Home

Awesome

<h1 align="center">Zodios</h1> <p align="center"> <a href="https://github.com/ecyrbe/zodios"> <img align="center" src="https://raw.githubusercontent.com/ecyrbe/zodios/main/docs/logo.svg" width="128px" alt="Zodios logo"> </a> </p> <p align="center"> Zodios is a typescript api client and an optional api server with auto-completion features backed by <a href="https://axios-http.com" >axios</a> and <a href="https://github.com/colinhacks/zod">zod</a> and <a href="https://expressjs.com/">express</a> <br/> <a href="https://www.zodios.org/">Documentation</a> </p> <p align="center"> <a href="https://www.npmjs.com/package/@zodios/core"> <img src="https://img.shields.io/npm/v/@zodios/core.svg" alt="langue typescript"> </a> <a href="https://www.npmjs.com/package/@zodios/core"> <img alt="npm" src="https://img.shields.io/npm/dw/@zodios/core"> </a> <a href="https://github.com/ecyrbe/zodios/blob/main/LICENSE"> <img alt="GitHub" src="https://img.shields.io/github/license/ecyrbe/zodios"> </a> <img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/ecyrbe/zodios/ci.yml?branch=main"> </p> <p align="center"> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/core?label=%40zodios%2Fcore"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/fetch?label=%40zodios%2Ffetch"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/axios?label=%40zodios%2Faxios"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/react?label=%40zodios%2Freact"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/express?label=%40zodios%2Fexpress"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/openapi?label=%40zodios%2Fopenapi"/> <img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/@zodios/testing?label=%40zodios%2Ftesting"/> </p>

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:

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", // 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);

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

Roadmap for v11

for Zod/Io-Ts` :

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 :