zhttp

A small library that brings zod, express, and static-path together to create type safe HTTP endpoints for clients and servers.

• Reference
  • endpoint
  • createRouter
  • fetchJson
  • createClient

Getting Started

Install zhttp and its peer dependencies.

npm i @danprince/zhttp express @types/express zod static-path

• static-path requires typescript@^4.1 (for template literal types)
• zod requires you to run TypeScript in strict mode.

Example

Define your endpoints somewhere that both your client and server can import from.

// shared/endpoints.ts
import { endpoint } from "@danprince/zhttp";
import { z } from "zod";
import { path } from "path";

export let sendMessage = endpoint({
  // static-path definition
  path: path("/message/:to"),

  // "post" | "get" | "patch" | "put" | "delete" | "head"
  method: "post",

  // zod request body schema
  request: z.object({
    subject: z.string(),
    text: z.string(),
  }),

  // zod response body schema
  response: z.object({
    status: z.union([
      z.literal("success"),
      z.literal("pending"),
      z.literal("failure"),
    ]),
  }),
});

Then create corresponding server side route handlers.

// server/routes.ts
import { createRouter } from "@danprince/zhttp/express";
import { sendMessage } from "../shared/endpoints";

let router = createRouter();

router.use(sendMessage, async (req, res) => {
  // Type safe access from req.body
  let { subject, text } = req.body;

  // ...

  // Type safe res.body methods
  res.json({ status: "success" });
});

// router.routes() is an Express.Router

And finally, the client side.

// client/index.ts
import { fetchJson } from "@danprince/zhttp/fetch";
import { sendMessage } from "../shared/endpoints";

let res = await fetchJson(sendMessage, {
  params: { to: "howard" },
  body: {
    subject: "Hello!",
    text: "This is a message",
  },
});

// Type safe response
res.status