V11 Roadmap Ideas

[ecyrbe]

Here is a discussion to share ideas for zodios V11.

As a reminder, Zodios scope is REST APIs, so we will not consider notifications, real time communication, RPC, Next RSC or Remix loader/actions type safety features (these would be completely distinct projects)

• Zod / Io-Ts Validation :
  • By using the TypeProvider pattern we can now make zodios validation agnostic.
  • Implement at least ZodTypeProvider and IoTsTypeProvider since they both support input and output type inferrence
  • openapi generation will only be compatible with zod though
  • Not a breaking change so no codemod needed
• MonoRepo:
  • Zodios will become a really large project so maybe migrate to turbo repo + pnpm
  • not a breaking change
• Transform:
  • By default, activate transforms on backend and disable on frontend (today it's the opposite), would make server transform code simpler since with this option we could make any transforms activated not just zod defaults.
  • Rationale being that transformation can be viewed as business code that should be kept on backend
  • breaking change => codemod to keep current defaults by setting them explicitly
• Axios:
  • Move Axios client to it's own package @zodios/axios and keep @zodios/core with only common types and helpers
  • Move plugins to @zodios/axios-plugins
  • breaking change => easy to do a codemod for this
• Fetch:
  • Create a new Fetch client with almost the same features as axios, but without axios dependency @zodios/fetch
  • Today we have fetch support with a plugin for axios instance (zodios maintains it's own axios network adapter for fetch). But since axios interceptors are not used by zodios plugins, we can make fetch implementation lighter than axios instance.
  • Create plugins package @zodios/fetch-plugins
  • Not sure it's doable without a lot of effort to keep it in sync/compatible with axios client
  • new feature, so no codemod needed
• React/Solid:
  • make ZodiosHooks independant of Zodios client instance (axios, fetch)
  • not a breaking change, so no codemod needed
• Client Request Config
  • uniform Query/Mutation with body sent on the config and not as a standalone object. This would allow to not do client.deleteUser(undefined, { params: { id: 1 } }) but simply client.deleteUser({ params: { id: 1 } })
  • breaking change, so a codemod would be needed, but might be difficult to implement
• Mock/Tests:
  • if we implement an abstraction layer for client instance, relying on moxios to mock APIs response will likely not work for fetch implementation.
  • create a @zodios/testing package that work for both axios/fetch clients
  • new feature, so no breaking change (no codemod needed)

In the works (not really tied to v11) :

• @zodios/fastify alternative to @zodios/express
• @zodios/vue add vue adapter for @tanstack/vue-query

Progress implementation in v11 branch

[thelinuxlich]

Since it's a major version, maybe think about standardizing the POST/GET method signatures with a single object parameter?

[ecyrbe]

You mean body sent with config like params and queries ?

[thelinuxlich]

yeah

[ecyrbe]

Added!

[Talent30]

Yes Fetch!

[astahmer]

looks promising ! 👏

regarding the axios-like fetch implementation, a few have been made already, I'm not sure if they have 100% feature parity with axios tho but if not using them directly I guess this could serve as inspiration:

• https://github.com/developit/redaxios
• https://github.com/ladjs/frisbee
• https://github.com/posva/mande

there are probably more that I don't know of

[andreas-soroko]

just an idea:

What about normalized cache (optional)?

[ecyrbe]

Could you elaborate ? Explain what you have in mind? Because in the context of REST APIs cache normalisation can have many different meanings.

[andreas-soroko]

sorry for the late answer.

i mean "we" have already great libraries like react-query but they (in my opinion) have a lack of great offline support.

imagine you are getting the same entity over different endpoints (simple example: list endpoint (paged) and by id endpoint, more complex: nested data)

in react query you will now have a key like ['todos', {page: 1, items: 10}] and ['todos', 'byId', <id>]
if you now update id: 753 it can be easily made for ['todos', 'byId', <id>] but for the paging endpoint, you have to search the whole pages in the cache to find the one specific item to update that (maybe i miss here something but..).

with a normalised cached in front, we could update just the item by id and the list resource would also update.

i think theoretically it should be possible because you have already schemes which shows the relation between the types, maybe this can be used to detect references between the types.
one difficult part could be, to detect the unique id for a type.

i hope this was not too confusing

[astahmer]

imo this is probably out-of-scope for both react-query & zodios, even tho I agree this could be nice to have a wrapper or something that takes cares of this

for offline-support you might want to check kikko, which use in-memory sqlite (in a browser's worker) and persists to IndexedDB

[ecyrbe]

Thank you, and also sorry for the delayed answer.

This type of normalized caching would need some sort of schema relationship declaration for it to work. Just declaring schema for individual endpoint would not do the job.

Declaring schema relationships would certainly need some sort of zod extension magic, since zod does not have this hability.
Another thing that would be missing is for react-query to have a way to declare a relationship from an object to cache key.
This way react-query would know how to split the results in their object and adress them by a normalized key.

So there are a lot missing pieces today to allow normalized caching with react-query. It was simply not designed for it. So for zodios to have normalized caching i think we would need to :

• change zodios api declaration to hint how data schemas are related to each other
• create a concurrent library to react-query that uses a normalized cache (like https://www.npmjs.com/package/normalized-cache)

For the moment i don't think i'm ready for such a task for v11. But any proposal implementation would be welcomed.

[ecyrbe]

You can check progress in this branch

[rmvn27]

Would love to see "go to definition" working for the aliases. So I could go from the client to my api definition. This would probably mean that the api needs to be defined as an object rather than an array.

[rmvn27]

I've tried to create a prototype but I don't think that it's possible. I actually got the "go to definition" feature to work by creating another type of ZodiosInstance, which would create it's aliases from the object. The ZodiosClass would have to transform the api when it is defined as an object.

The problem was the type conversion from an object type to a tuple, which is necessary for deriving the actual api type. You can't just map the values of the object to a tuple. There is a really hacky way, where you get the union of all object values and convert that union to a tuple, but even this method didn't work for me.

[ecyrbe]

Thank you for taking a look.

[thelinuxlich]

Unfortunately, this means an helper that does runtime transformation, and i think typescript will not be able to connect the dots to make "go to definition" work. But maybe i'm wrong. Need some POC to check.

tRPC has "go to definition", I don't think it does runtime transformation

[ecyrbe]

Yes, but it's because their alias is not inside an array and their alias is mandatory in an object format. That was the point @r0m4n27 .

[rmvn27]

Yeah I know. But for this feature to work you have to provide the object (or at least it's type) to the ZodiosConstructor.
This could be theoretically done by creating another overload to the ZodiosConstructor, which would make the new feature optional. The object values with their aliases could be transformed to the array, but as I said you can't create a tuple type
from the object.

[ecyrbe]

If you want to test the new type provider, you can play with it with the rc-0 release: https://github.com/ecyrbe/zodios/releases/tag/v11.0.0-rc.0 available on npm

To install a beta version, you need to install it explicitly :

npm i @zodios/core@11.0.0-rc.0

[ecyrbe]

A quick update for everyone, beta packages are available for :

• zodios/core
• zodios/axios
• zodios/fetch.
• zodios/testing

What's missing is react/solid and express/openapi packages for v11.

Everything is in a monorepo now. So the old repositories will be removed 3 month after release.
v11 should be out for christmas. That's the goal anyway. If not should be at the beginning of january.

[ecyrbe]

of course updated documentation is also missing. that will be the last thing i'll do before release.

[QzCurious]

Feature request

As @zodios/react will be independent from Zodios, I thought the config of @zodios/react MIGHT only extends config @zodios/core on type level (so @zodios/core will not have immutable flag).
If so, I wish to have a method to modify queryKey of @zodios/react at endpoint level (and even modify queryKey on invoking level).
It would be like

{ modifyQueryKey: (queryKeyByZodiosReact: QueryKey) => QueryKey }

My usecase is to prepend a user identifier like

{ modifyQueryKey: (queryKeyByZodiosReact: QueryKey) => [getAuthToken(), ...queryKeyByZodiosReact] }

so a user won't see data other user's data after switching to a different account. This is the suggest way to queryKey by SWR.

[ecyrbe]

I think there are better ways to handle this:

• Refresh the page on logout
• Clear the cache on logout
  Or am i missing something here ?

[QzCurious]

I'm currently clear cache on logout. Because I don't want my state be cleared out. In particular, I need my dialog remain open.

For a page mixed with login only data and public data, a clear cache would than not only blanks(*) login only data but also public data. Another way is to invalidate all cache. But disabled query would not refetch and still loaded with old cache that associates to previous user.

blanks(*): A component loaded with api data, and some action clears the api data (local state for the section). The component is now blank. The clear action blanks the component.

[ecyrbe]

I still don't understand. If your user reload the page himself, your page will be blank if that's how your app handle state... Also i don't see how application state (dialog being open) has anything to do with server state ( user cached data)

[ecyrbe]

Anyway, here how you can do it to clear the cache per user basis:

• declare a ZodiosHooks for public data
• declare a ZodiosHooks for user data

Call queryClient.removeQueries or queryClient.resetQueries with a predicate filter that removes only user data.

[QzCurious]

Cool, I didn't realize that I can have two distinct ZodiosHooks with different prefix key. It's a great idea for me.
Still, I'll re-evaluate my code structure. Thanks for your feedback.

[ivan-kleshnin]

I've noticed that a server response is not parsed by Zod, only typed. Or maybe it's configured in a way to preserve unknown keys.
Zod 2/3, by default, drops unknown keys: colinhacks/zod#106

// ^ response: z.object({name: z.string()})
// ...
const result = {name: "foo", junk: "bar"}
return res.status(200).json(result) // will ensure a correct TS type but response will contain both `name` and `junk` keys

One thing that might be useful for is to drop extra fields coming from a database. It's not the most effective way of doing that, but it can be quite beneficial while developing and even later in dev mode – to be sure your code is correctly typed. So an option to enable response parsing/validation is worth considering IMO.

[dejay-at-upstart]

I would love to see Zodios Client be augmented to support better customization. Right now, Zodios Client seems very brittle when trying to implement any logic at all that is non-standard. Some of this brittleness is due to Axios, some is due to Zod, some is due to TypeScript, and some is due to the relatively weak way that Zodios Client supports middleware.

Any plans to improve this for v11?

UPDATE: clarified that I'm referring to Zodios Client above, although to be honest, I don't know what the difference is between Zodios Client and Zodios Server, since I haven't used server.

[tomer555]

hey @ecyrbe is there any timeline for releasing v11? maybe it's worth releasing an update of what is left for that release. maybe I can assist or other ppl as well

[ecyrbe]

It's almost finished.
I wand to release it by the end of next week.
I need to update to use react query v5.
And it should be good to go.
Some features will not be part of the initial release:

• batch calls
• server side support for other validation libs than zod

Help is welcomed for updating documentation.
Maybe in switching docs from docusaurus to rspress to have multi version docs out of the box.

[Julien-R44]

Hey! I am working on a Zodios adapter for AdonisJS 6.
The current implementation works great and is super cool. So yeah, I'm already sold on Zodios and first of all, great job on that library dude 👏

just wanted to ask two questions:

• Does V11 already support solid and vue hooks? Looking at the branch, I think not, but I prefer to ask in case I missed something
• About support for multiple validation libraries: In AdonisJS, we use VineJS by default. So it's important for us to be able to change the default validator. I just wanted to share this library: https://github.com/decs/typeschema which seems to easily allow the possibility of supporting multiple validation libraries using a small abstraction
  ( just noticed you was a contributor on typeschema ahahah forget about that, sorry 😅😅 )

happy to contribute in any forms ( thinking especially about vue hooks ), but I think for the time being, it's going to be quite complicated as i guess there's a lot moving parts before the official release of V11. but let me know if there's anything I can do before that

[Talent30]

@ecyrbe

[Farnsi]

Add more Options for OpenApi-Documentation, e.g. extend Zod with https://github.com/asteasolutions/zod-to-openapi or https://github.com/anatine/zod-plugins
So we can add examples, etc.

[toteto]

#417 (comment)

☝️ relevant for anyone migrating v10->v11

[toteto]

Update: such a shame that such great work got completely abandoned by the maintainer and no guidance nor effort to let the community continue the support for it. For the time being, moving my app to ts-rest. Hope that one day v11 receives stable release and community support.