@zodios/fetch
v11.0.0-beta.19
Published
Typescript API client with fetch
Downloads
70
Maintainers
Readme
https://user-images.githubusercontent.com/633115/185851987-554f5686-cb78-4096-8ff5-c8d61b645608.mp4
What is it ?
It's an axios compatible API client and an optional expressJS compatible API server with the following features:
really simple centralized API declaration
typescript autocompletion in your favorite IDE for URL and parameters
typescript response types
parameters and responses schema thanks to zod
response schema validation
powerfull plugins like
fetch
adapter orauth
automatic injectionall axios features available
@tanstack/query
wrappers for react and solid (vue, svelte, etc, soon)all expressJS features available (middlewares, etc.)
Table of contents:
Install
Client and api definitions :
> npm install @zodios/core
or
> yarn add @zodios/core
Server :
> npm install @zodios/core @zodios/express
or
> yarn add @zodios/core @zodios/express
How to use it on client side ?
For an almost complete example on how to use zodios and how to split your APIs declarations, take a look at dev.to example.
Declare your API with zodios
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", // optionnal 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);
API definition format
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
}>;
}>;
Full documentation
Check out the full documentation or following shortcuts.
Ecosystem
- openapi-zod-client: generate a zodios client from an openapi specification
- @zodios/express: full end to end type safety like tRPC, but for REST APIs
- @zodios/plugins : some plugins for zodios
- @zodios/react : a react-query wrapper for zodios
- @zodios/solid : a solid-query wrapper for zodios
Roadmap
The following will need investigation to check if it's doable :
- implement
@zodios/nestjs
to define your API endpoints with nestjs and share it with your frontend (like tRPC) - generate openAPI json from your API endpoints
You have other ideas ? Let me know !
Dependencies
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 :
- zod
- axios