Zod Http Schemas

zod-http-schemas brings together the best parts of http-schemas and zod into one library that:

• Declares the 'shape' of an HTTP API both at compile time and at runtime.
• Supports transformations and refinements.

At compile time it statically checks:

• HTTP requests in the client code
• Route handlers in the server code against the declared schema, ensuring usage errors are caught early.

At runtime, zod-http-schemas:

• validates that response and request payloads match the declared schema
• Trims response payloads of any excess properties, preventing information leaks

Use a shared schema for both client and server side code as a single source of truth, ensuring the client and server always agree on the API.

zod-http-schemas uses the zod library for specifying and enforcing schema types.

Installation

npm install zod-http-schemas

Example Shared Code (use in both client and server)

1import {createHttpSchema} from 'zod-http-schemas';
2import * as z from 'zod';
3
4// Declare the http schema to be used by both client and server
5export const apiSchema = createHttpSchema({
6    'POST /sum': {
7        requestBody: z.array(z.number()),
8        responseBody: z.number(),
9    },
10    'GET /greet/:name': {
11        responseBody: z.string(),
12    },
13});

Example Client-Side Code

1import {createHttpClient} from 'zod-http-schemas/client';
2import {apiSchema} from '<path-to-shared-schema>';
3
4// Create a strongly-typed http client. These are cheap to create - it's fine to have many of them.
5const client = createHttpClient(apiSchema, {baseURL: '/api'});
6
7// Some valid request examples
8let res1 = client.post('/sum', {body: [1, 2]});                 // res1: Promise<number>
9let res2 = client.get('/greet/:name', {params: {name: 'Bob'}}); // res2: Promise<string>
10
11// Some invalid request examples
12let res3 = client.get('/sum', {body: [1, 2]});                  // tsc build error & runtime error
13let res4 = client.post('/sum', {body: 'foo'});                  // tsc build error & runtime error
14let res5 = client.post('/blah');                                // tsc build error & runtime error

Client-side implementation

zod-http-schemas uses Axios under the hood. Use the same config options with createHttpClient as you would with Axios.

However zod-http-schemas uses its own default validateStatus option that will only reject status codes >= 500. This lets you include common error responses in your schema, without losing typing.

For example, for a post endpoint you might specify

1export const apiSchema = createHttpSchema({
2    'POST /article': {
3        requestBody: NewArticle,
4        responseBody: z.union([Article, MyGenericApiErrorType]),
5    },
6});

Now your clientside code might have a type-guard function that asserts:

1import {AxiosResponse} from "axios";
2
3export const isNotErrorResponse = <T, E>(
4    response: AxiosResponse<T> | AxiosResponse<MyGenericApiErrorType>
5): response is AxiosResponse<T> => {
6    return response.status < 400;
7};

and used as such:

1const result = await apiClient.post('/article', {body: {title: 'Hello world'}});
2if (isNotErrorResponse(result)) {
3    // result is AxiosResponse<Article> in here
4    console.log(result.body);
5} else {
6    // Some error occured, so result is typed AxiosResponse<MyGenericApiErrorType>
7    console.error(result.body.myGenericErrorProperty)
8}

Example Server-Side Code

1import * as express from 'express';
2import {createRequestHandler, decorateExpressRouter} from 'http-schemas/server';
3import {apiSchema} from '<path-to-shared-schema>';
4
5// Create a strongly-typed express router.
6const apiRouter = decorateExpressRouter({schema: apiSchema});
7
8// Create a normal express app and mount the strongly-typed router.
9const app = express();
10app.use(express.json()); // it's a normal express app; mount whatever middleware you want
11app.use('/api', apiRouter); // `apiRouter` is just middleware; mount it wherever you want
12
13// Add a request handler directly to the router
14apiRouter.post('/sum', (req, res) => {
15    let result = req.body.reduce((sum, n) => sum + n, 0);
16    res.send(result);
17});
18
19// Declare a request handler separately, then add it to the router
20const greetHandler = createRequestHandler(apiSchema, 'GET', '/greet/:name', (req, res) => {
21    res.send(`Hello, ${req.params.name}!`);
22});
23apiRouter.get('/greet/:name', greetHandler);
24
25// Some invalid route handler examples
26apiRouter.post('/blah', (req, res) => {/*...*/});           // tsc build error & runtime error
27apiRouter.post('/sum', (req, res) => { req.body.foo[0] });  // tsc build error & runtime error
28apiRouter.post('/sum', (req, res) => { res.send('foo') });  // tsc build error & runtime error
29
30app.listen(8000);

Full production-like webserver demo

The best way to see http-schemas in action is to see it in a real demonstration with documentation. Take a look at http-schemas-webserver-demo, read the docs, run it and play with it yourself.