zod-endpoint

Extremely lightweight zod and express integration enabling type-safe HTTP endpoints.

Both express and zod are unopinionated micro libraries - and we inherit and embrace the flexibility of both.

Usage

zod-endpoint can be used client-side or server-side (or both).

It is easy to incrementally adopt in your project if you are already using express (server-side) or axios (client-side).

Specification

First step is to define a specification of an endpoint

1import { endpoint, path } from "zod-endpoint/spec";
2
3// Define the endpoint specification
4const getPostsEndpoint = endpoint({
5
6    // Specify the HTTP method
7    method: "get",
8
9    // Define the path /posts/:id through a type-safe fluent builder
10    path: path()
11        .literal("posts")
12        .placeholder("id", z.string())
13        .build(),
14
15    // Define the shape of parsed Query parameters
16    query: z.object({
17        include: z.string().optional(),
18        tag: z.string(),
19    }),
20
21    // Define the shape of data returned by service
22    result: z.object({
23        id: z.string(),
24        tags: z.array(z.string()),
25        name: z.string(),
26    }),
27});

Server

While implementing the server, we can bridge this specification to an endpoint which implements our service.

1import express from "express";
2import { bridge } from "zod-endpoint/server";
3
4const app = express();
5
6// Bridge the endpoint spec to a service which is independent
7// of http
8bridge(getPostsEndpoint)
9.through({
10    // We receive a zod type that can be used to parse 
11    // the incoming request. 
12    //
13    // We augment this type with transformations to generate the
14    // input our service expects.
15    inputType: (it) =>
16        it.transform((it) => ({
17            id: it.params.id,
18            tag: it.query.tag,
19        })),
20
21    // Zod-type to transform the service output
22    // to http output
23    outputType: (it) => it,
24})
25
26    // Implementation of our service
27    //
28    // Note that this service implementation does not receive
29    // request/response object and is http independent.
30    .toService(async ({ id, tag }) => {
31
32        // Dummy implementation.
33        // In a real application we will most likely fetch this data
34        // from some data store
35        const tags: string[] = [];
36        if (tag) tags.push(tag);
37        return {
38            id,
39            tags,
40            name: "Test Post",
41        };
42    })
43
44    // Attach our middleware to express router
45    .attach(app);
46
47const server = app.listen(3000);

Client

We can also create a client from this spec

1import { request } from "zod-endpoint/client";
2
3const getPost = request(getPostsEndpoint);
4
5const resp = await getPost({
6    params: {
7        id: "1",
8    },
9    query: {
10        tag: "foo",
11    }
12});

Note that we don't have to implement both the Server & Client implementations.

So we can still use zod-endpoint if either our server or client is not in our control. However using it in both client and server provides us end-to-end type-safety without needing to redeclare any types or needing any code-generation.

We are also able to implement any HTTP API - zod-endpoint is unassuming and does not restrict us to implement some custom protocol with adhoc limitations.

We also don't necessarily need to accept or return JSON - it is perfectly fine to use this for applications that return HTML or binary content.