gem-hunter
Language: TypeScript
typescript http client and server with zod validation
Zodios is a typescript api client and an optional api server with auto-completion features backed by axios and zod and express
Documentation
It's an axios compatible API client and an optional expressJS compatible API server with the following features:
fetch adapter or auth automatic injection@tanstack/query wrappers for react and solid (vue, svelte, etc, soon)Table of contents:
> npm install @zodios/coreor
> yarn add @zodios/core> npm install @zodios/core @zodios/expressor
> yarn add @zodios/core @zodios/expressFor an almost complete example on how to use zodios and how to split your APIs declarations, take a look at dev.to example.
Here is an example of API declaration with Zodios.
import { Zodios } from "@zodios/core"; import { z } from "zod"; const apiClient = new Zodios( "https://jsonplaceholder.typicode.com", // API definition [ { method: "get", path: "/users/:id", // auto detect :id and ask for it in apiClient get params alias: "getUser", // optional alias to call this endpoint with it description: "Get a user", response: z.object({ id: z.number(), name: z.string(), }), }, ], );
Calling this API is now easy and has builtin autocomplete features :
// typed auto-complete path auto-complete params // ▼ ▼ ▼ const user = await apiClient.get("/users/:id", { params: { id: 7 } }); console.log(user);
It should output
{ id: 7, name: 'Kurtis Weissnat' }
You can also use aliases :
// typed alias auto-complete params // ▼ ▼ ▼ const user = await apiClient.getUser({ params: { id: 7 } }); console.log(user);
type ZodiosEndpointDescriptions = Array<{ method: 'get'|'post'|'put'|'patch'|'delete'; path: string; // example: /posts/:postId/comments/:commentId alias?: string; // example: getPostComments immutable?: boolean; // flag a post request as immutable to allow it to be cached with react-query description?: string; requestFormat?: 'json'|'form-data'|'form-url'|'binary'|'text'; // default to json if not set parameters?: Array<{ name: string; description?: string; type: 'Path'|'Query'|'Body'|'Header'; schema: ZodSchema; // you can use zod `transform` to transform the value of the parameter before sending it to the server }>; response: ZodSchema; // you can use zod `transform` to transform the value of the response before returning it status?: number; // default to 200, you can use this to override the sucess status code of the response (only usefull for openapi and express) responseDescription?: string; // optional response description of the endpoint errors?: Array<{ status: number | 'default'; description?: string; schema: ZodSchema; // transformations are not supported on error schemas }>; }>;
Check out the full documentation or following shortcuts.
for Zod/Io-Ts` :
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)
You have other ideas ? Let me know !
Zodios even when working in pure Javascript is better suited to be working with Typescript Language Server to handle autocompletion. So you should at least use the one provided by your IDE (vscode integrates a typescript language server) However, we will only support fixing bugs related to typings for versions of Typescript Language v4.5 Earlier versions should work, but do not have TS tail recusion optimisation that impact the size of the API you can declare.
Also note that Zodios do not embed any dependency. It's your Job to install the peer dependencies you need.
Internally Zodios uses these libraries on all platforms :