zod-http-schemas
v2.0.5
Published
Zod Powered, strongly-typed HTTP schemas
Downloads
12,180
Maintainers
Readme
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)
import {createHttpSchema} from 'zod-http-schemas';
import * as z from 'zod';
// Declare the http schema to be used by both client and server
export const apiSchema = createHttpSchema({
'POST /sum': {
requestBody: z.array(z.number()),
responseBody: z.number(),
},
'GET /greet/:name': {
responseBody: z.string(),
},
});
Example Client-Side Code
import {createHttpClient} from 'zod-http-schemas/client';
import {apiSchema} from '<path-to-shared-schema>';
// Create a strongly-typed http client. These are cheap to create - it's fine to have many of them.
const client = createHttpClient(apiSchema, {baseURL: '/api'});
// Some valid request examples
let res1 = client.post('/sum', {body: [1, 2]}); // res1: Promise<number>
let res2 = client.get('/greet/:name', {params: {name: 'Bob'}}); // res2: Promise<string>
// Some invalid request examples
let res3 = client.get('/sum', {body: [1, 2]}); // tsc build error & runtime error
let res4 = client.post('/sum', {body: 'foo'}); // tsc build error & runtime error
let 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
export const apiSchema = createHttpSchema({
'POST /article': {
requestBody: NewArticle,
responseBody: z.union([Article, MyGenericApiErrorType]),
},
});
Now your clientside code might have a type-guard function that asserts:
import {AxiosResponse} from "axios";
export const isNotErrorResponse = <T, E>(
response: AxiosResponse<T> | AxiosResponse<MyGenericApiErrorType>
): response is AxiosResponse<T> => {
return response.status < 400;
};
and used as such:
const result = await apiClient.post('/article', {body: {title: 'Hello world'}});
if (isNotErrorResponse(result)) {
// result is AxiosResponse<Article> in here
console.log(result.body);
} else {
// Some error occured, so result is typed AxiosResponse<MyGenericApiErrorType>
console.error(result.body.myGenericErrorProperty)
}
Example Server-Side Code
import * as express from 'express';
import {createRequestHandler, decorateExpressRouter} from 'http-schemas/server';
import {apiSchema} from '<path-to-shared-schema>';
// Create a strongly-typed express router.
const apiRouter = decorateExpressRouter({schema: apiSchema});
// Create a normal express app and mount the strongly-typed router.
const app = express();
app.use(express.json()); // it's a normal express app; mount whatever middleware you want
app.use('/api', apiRouter); // `apiRouter` is just middleware; mount it wherever you want
// Add a request handler directly to the router
apiRouter.post('/sum', (req, res) => {
let result = req.body.reduce((sum, n) => sum + n, 0);
res.send(result);
});
// Declare a request handler separately, then add it to the router
const greetHandler = createRequestHandler(apiSchema, 'GET', '/greet/:name', (req, res) => {
res.send(`Hello, ${req.params.name}!`);
});
apiRouter.get('/greet/:name', greetHandler);
// Some invalid route handler examples
apiRouter.post('/blah', (req, res) => {/*...*/}); // tsc build error & runtime error
apiRouter.post('/sum', (req, res) => { req.body.foo[0] }); // tsc build error & runtime error
apiRouter.post('/sum', (req, res) => { res.send('foo') }); // tsc build error & runtime error
app.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.