Zodios

Zodios is a typescript api client and an optional api server with auto-completion features backed by axios and zod and express
Documentation

zodios.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
bearer token injection and token renewal with simple token provider interface
all axios features available
all expressJS features available (middlewares, etc.)

Table of contents:

What is it ?
Install
- Client and api definitions :
- Server :
How to use it on client side ?
- Declare your API with zodios
- API definition format
Full documentation
Ecosystem
Roadmap
Dependencies

Install

Client and api definitions :

> npm install @zodios/core

> yarn add @zodios/core

Server :

> npm install @zodios/core @zodios/express

> 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
  description?: string;
  requestFormat?: 'json'|'form-data'|'form-url'|'binary'|'text'; // default to json if not set
  parameters?: Array<{
    name: string;
    description?: string;
    type: '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
  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

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 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

In addition, it also uses on NodeJS :

formdata-node
form-data-encoder

mbakoG90210 / zodiosAPIclientCreator