Zodios Express

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

https://user-images.githubusercontent.com/633115/185851987-554f5686-cb78-4096-8ff5-c8d61b645608.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

1> npm install @zodios/express

or

1> 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) :

1import { makeApi } from "@zodios/core";
2import { z } from "zod";
3
4const userApi = makeApi([
5  {
6    method: "get",
7    path: "/users/:id", // auto detect :id and ask for it in apiClient get params
8    alias: "getUser", // optionnal alias to call this endpoint with it
9    description: "Get a user",
10    response: z.object({
11      id: z.number(),
12      name: z.string(),
13    }),
14  },
15]);

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

1import { Zodios } from "@zodios/core";
2import { userApi } from "../../common/api";
3
4const apiClient = new Zodios(
5  "https://jsonplaceholder.typicode.com",
6  userApi
7);
8
9//   typed                     alias   auto-complete params
10//     ▼                        ▼                   ▼
11const user = await apiClient.getUser({ params: { id: 1 } });

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

1import { zodiosApp } from "@zodios/express";
2import { userApi } from "../../common/api";
3
4// just an express adapter that is aware of  your api, app is just an express app with type annotations and validation middlewares
5const app = zodiosApp(userApi);
6
7//  auto-complete path  fully typed and validated input params (body, query, path, header)
8//          ▼           ▼    ▼
9app.get("/users/:id", (req, res) => {
10  // res.json is typed thanks to zod
11  res.json({
12    //   auto-complete req.params.id
13    //              ▼
14    id: req.params.id,
15    name: "John Doe",
16  });
17})
18
19app.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.

1import { zodiosApp, zodiosRouter } from "@zodios/express";
2
3const app = zodiosApp(); // just an axpess app with type annotations
4const userRouter = zodiosRouter(userApi); // just an express router with type annotations and validation middlewares
5const adminRouter = zodiosRouter(adminApi); // just an express router with type annotations and validation middlewares
6
7const app.use(userRouter,adminRouter);
8
9app.listen(3000);

Error Handling

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

1import { makeApi } from "@zodios/core";
2import { zodiosApp } from "@zodios/express";
3import { z } from "zod";
4
5const userApi = makeApi([
6  {
7    method: "get",
8    path: "/users/:id", // auto detect :id and ask for it in apiClient get params
9    alias: "getUser", // optionnal alias to call this endpoint with it
10    description: "Get a user",
11    response: z.object({
12      id: z.number(),
13      name: z.string(),
14    }),
15    errors: [
16      {
17        status: 404,
18        response: z.object({
19          code: z.string(),
20          message: z.string(),
21          id: z.number(),
22        }),
23      }, {
24        status: 'default', // default status code will be used if error is not 404
25        response: z.object({
26          code: z.string(),
27          message: z.string(),
28        }),
29      },
30    ],
31  },
32]);
33
34const app = zodiosApp(userApi);
35app.get("/users/:id", (req, res) => {
36  try {
37    const id = +req.params.id;
38    const user = service.findUser(id);
39    if(!user) {
40      // match error 404 schema with auto-completion
41      res.status(404).json({
42        code: "USER_NOT_FOUND",
43        message: "User not found",
44        id, // compile time error if you forget to add id
45      });
46    } else {
47      // match response schema with auto-completion
48      res.json(user);
49    }
50  } catch(err) {
51    // match default error schema with auto-completion
52    res.status(500).json({
53      code: "INTERNAL_ERROR",
54      message: "Internal error",
55    });
56  }
57})
58
59app.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()