Intro

Create fully inferred typesafe express endpoints using zod schemas

https://user-images.githubusercontent.com/55771765/217964766-edb63238-7079-442f-86ba-8ce94bf1382a.mp4

How to Install

$ yarn add zod-express-endpoint

# or

$ npm i zod-express-endpoint

Basic usage

1import express, { json } from "express";
2import { z } from "zod";
3import { TypeSafeEndpoint } from "zod-express-endpoint";
4
5const server = express();
6
7server.use(json());
8
9const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
10
11server.post(
12  "/api",
13  endpoint.create(
14    {
15      bodySchema: z.object({ message: z.string() }),
16      responseSchema: z.object({ message: z.string() }),
17    },
18    async (req, _res, send) => {
19      const { message } = req.body;
20
21      return send(200, { message });
22    }
23  )
24);

Options

1const endpoint = new TypeSafeEndpoint({
2  zodErrorMode: "always",
3  customUnexpectedError: "Oh no",
4});

Syntax	Type	Required	Description
zodErrorMode	ZodErrorMode	true	Endpoint will trigger zod errors in production, development or both
customUnexpectedError	String	false	Error Message when some unexpected error happens

1type ZodErrorMode = "production" | "development" | "always";

Typing Body Params

1import { TypeSafeEndpoint } from "zod-express-endpoint";
2
3const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
4
5const exampleEndpoint = endpoint.create(
6  {
7    bodySchema: z.object({ message: z.string() }),
8    responseSchema: z.object({ message: z.string() }),
9  },
10  async (req, _res, send) => {
11    const { message } = req.body;
12
13    return send(200, { message });
14  }
15);

Typing Path Params

1import { TypeSafeEndpoint } from "zod-express-endpoint";
2
3const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
4
5const exampleEndpoint = endpoint.create(
6  {
7    paramsSchema: z.object({ message: z.string() }),
8    responseSchema: z.object({ message: z.string() }),
9  },
10  async (req, _res, send) => {
11    const { message } = req.params;
12
13    return send(200, { message });
14  }
15);

Typing Query Params

1import { TypeSafeEndpoint } from "zod-express-endpoint";
2
3const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
4
5const exampleEndpoint = endpoint.create(
6  {
7    querySchema: z.object({ message: z.string() }),
8    responseSchema: z.object({ message: z.string() }),
9  },
10  async (req, _res, send) => {
11    const { message } = req.query;
12
13    return send(200, { message });
14  }
15);

Typing Endpoint Return

1import { TypeSafeEndpoint } from "zod-express-endpoint";
2
3const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
4
5const exampleEndpoint = endpoint.create(
6  {
7    responseSchema: z.object({ message: z.string() }),
8  },
9  async (req, _res, send) => {
10    return send(200, { message: "Hello there" });
11  }
12);

Emitting Custom Errors

1import { TypeSafeEndpoint, EndpointError } from "zod-express-endpoint";
2
3const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
4
5const exampleEndpoint = endpoint.create(
6  {
7    responseSchema: z.object({ message: z.string() }),
8  },
9  async (req, _res, send) => {
10    return send(400, { error: 'Error' });
11  }
12);
13
14# or
15
16import { TypeSafeEndpoint, EndpointError } from "zod-express-endpoint";
17
18const endpoint = new TypeSafeEndpoint({ zodErrorMode: "always" });
19
20const exampleEndpoint = endpoint.create(
21  {
22    responseSchema: z.object({ message: z.string() }),
23  },
24  async (req, _res, send) => {
25    throw new EndpointError("Error");
26  }
27);