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

``bash
> npm install @zodios/express
`

or

`bash
> 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) :

`typescript
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) :

`typescript
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) :
`typescript
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.

`typescript
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.

`typescript
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()`