npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

zod-http-schemas

v2.0.5

Published

Zod Powered, strongly-typed HTTP schemas

Downloads

12,049

Readme

Zod Http Schemasnpm monthly downloads current version Commitizen friendly

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.