README.md

Zodios Express

Zodios express is a typescript end to end typesafe adapter for express using zod

zodios.mp4

What is it ?

It's an express adapter for zodios that helps you type your express routes.

• really simple centralized API declaration
• router endpoints autocompletion
• typescript autocompletion for query, path, header and body input parameters (req is fully typed)
• typescript autocompletion for response body (res.json())
• input validation thanks to zod
• openapi specification generation out of the box (using swagger)
• end to end typesafe APIs (a la tRPC when using both @zodios/express and @zodios/core)

Table of contents:

• What is it ?
• Install
• How to use it ?
  • zodiosApp : Declare your API for fullstack end to end type safety
  • zodiosRouter : Split your application with multiple routers
  • Error Handling
• Roadmap

Install

> npm install @zodios/express

or

> yarn add @zodios/express

How to use it ?

For an almost complete example on how to use zodios and how to split your APIs declarations, take a look at dev.to example.

zodiosApp : Declare your API for fullstack end to end type safety

Here is an example of API declaration with Zodios.

in a common directory (ex: src/common/api.ts) :

import { makeApi } from "@zodios/core";
import { z } from "zod";

const userApi = makeApi([
  {
    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(),
    }),
  },
]);

in your frontend (ex: src/client/api.ts) :

import { Zodios } from "@zodios/core";
import { userApi } from "../../common/api";

const apiClient = new Zodios(
  "https://jsonplaceholder.typicode.com",
  userApi
);

//   typed                     alias   auto-complete params
//     ▼                        ▼                   ▼
const user = await apiClient.getUser({ params: { id: 1 } });

in your backend (ex: src/server/router.ts) :

import { zodiosApp } from "@zodios/express";
import { userApi } from "../../common/api";

// just an express adapter that is aware of  your api, app is just an express app with type annotations and validation middlewares
const app = zodiosApp(userApi);

//  auto-complete path  fully typed and validated input params (body, query, path, header)
//          ▼           ▼    ▼
app.get("/users/:id", (req, res) => {
  // res.json is typed thanks to zod
  res.json({
    //   auto-complete req.params.id
    //              ▼
    id: req.params.id,
    name: "John Doe",
  });
})

app.listen(3000);

zodiosRouter : Split your application with multiple routers

When organizing your express application, you usually want to split your API declarations into separate Routers. You can use the zodiosRouter to do that with a zodiosApp without APIs attached.

import { zodiosApp, zodiosRouter } from "@zodios/express";

const app = zodiosApp(); // just an axpess app with type annotations
const userRouter = zodiosRouter(userApi); // just an express router with type annotations and validation middlewares
const adminRouter = zodiosRouter(adminApi); // just an express router with type annotations and validation middlewares

const app.use(userRouter,adminRouter);

app.listen(3000);

Error Handling

Zodios express can infer the status code to match your API error response and also have your errors correctly typed.

import { makeApi } from "@zodios/core";
import { zodiosApp } from "@zodios/express";
import { z } from "zod";

const userApi = makeApi([
  {
    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(),
    }),
    errors: [
      {
        status: 404,
        response: z.object({
          code: z.string(),
          message: z.string(),
          id: z.number(),
        }),
      }, {
        status: 'default', // default status code will be used if error is not 404
        response: z.object({
          code: z.string(),
          message: z.string(),
        }),
      },
    ],
  },
]);

const app = zodiosApp(userApi);
app.get("/users/:id", (req, res) => {
  try {
    const id = +req.params.id;
    const user = service.findUser(id);
    if(!user) {
      // match error 404 schema with auto-completion
      res.status(404).json({
        code: "USER_NOT_FOUND",
        message: "User not found",
        id, // compile time error if you forget to add id
      });
    } else {
      // match response schema with auto-completion
      res.json(user);
    }
  } catch(err) {
    // match default error schema with auto-completion
    res.status(500).json({
      code: "INTERNAL_ERROR",
      message: "Internal error",
    });
  }
})

app.listen(3000);

Roadmap

• [] add support for swagger/openapi generation
• [] add utilities to combine api declarations to match the express router api
• [] add autocompletion for express app.name()