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
import { endpoint, path } from "zod-endpoint/spec";
// Define the endpoint specification
const getPostsEndpoint = endpoint({
// Specify the HTTP method
method: "get",
// Define the path /posts/:id through a type-safe fluent builder
path: path()
.literal("posts")
.placeholder("id", z.string())
.build(),
// Define the shape of parsed Query parameters
query: z.object({
include: z.string().optional(),
tag: z.string(),
}),
// Define the shape of data returned by service
result: z.object({
id: z.string(),
tags: z.array(z.string()),
name: z.string(),
}),
});Server
While implementing the server, we can bridge this specification to an endpoint which implements our service.
import express from "express";
import { bridge } from "zod-endpoint/server";
const app = express();
// Bridge the endpoint spec to a service which is independent
// of http
bridge(getPostsEndpoint)
.through({
// We receive a zod type that can be used to parse
// the incoming request.
//
// We augment this type with transformations to generate the
// input our service expects.
inputType: (it) =>
it.transform((it) => ({
id: it.params.id,
tag: it.query.tag,
})),
// Zod-type to transform the service output
// to http output
outputType: (it) => it,
})
// Implementation of our service
//
// Note that this service implementation does not receive
// request/response object and is http independent.
.toService(async ({ id, tag }) => {
// Dummy implementation.
// In a real application we will most likely fetch this data
// from some data store
const tags: string[] = [];
if (tag) tags.push(tag);
return {
id,
tags,
name: "Test Post",
};
})
// Attach our middleware to express router
.attach(app);
const server = app.listen(3000);Client
We can also create a client from this spec
import { request } from "zod-endpoint/client";
const getPost = request(getPostsEndpoint);
const resp = await getPost({
params: {
id: "1",
},
query: {
tag: "foo",
}
});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.