npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@zodios/core

v10.9.6

Published

Typescript API client with autocompletion and zod validations

Downloads

443,776

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 or auth automatic injection

  • all 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", // 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` :

  • 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

  • [x] 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

  • [x] 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

  • [x] 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

  • [x] 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

  • [x] 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 !

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