Express Zod API

Start your API server with I/O schema validation and custom middlewares in minutes.

1. Overview
2. How it works
3. Quick start — Fast Track
4. Basic features
   1. Routing including static file serving
   2. Middlewares
   3. Options
   4. Using native express middlewares
   5. Refinements
   6. Transformations
   7. Top level transformations and mapping
   8. Dealing with dates
   9. Cross-Origin Resource Sharing (CORS)
   10. Enabling HTTPS
   11. Customizing logger
   12. Child logger
   13. Profiling
   14. Enabling compression
5. Advanced features
   1. Customizing input sources
   2. Headers as input source
   3. Response customization
   4. Empty response
   5. Error handling
   6. Production mode
   7. Non-object response including file downloads
   8. HTML Forms (URL encoded)
   9. File uploads
   10. Connect to your own express app
   11. Testing endpoints
   12. Testing middlewares
6. Special needs
   1. Different responses for different status codes
   2. Array response for migrating legacy APIs
   3. Accepting raw data
   4. Graceful shutdown
   5. Subscriptions
7. Integration and Documentation
   1. Zod Plugin
   2. Generating a Frontend Client
   3. Creating a documentation
   4. Tagging the endpoints
   5. Deprecated schemas and routes
   6. Customizable brands handling
8. Caveats
   1. Coercive schema of Zod
   2. Excessive properties in endpoint output
9. Your input to my output

You can find the release notes and migration guides in Changelog.

Overview

I made this framework because of the often repetitive tasks of starting a web server APIs with the need to validate input data. It integrates and provides the capabilities of popular web server, logging, validation and documenting solutions. Therefore, many basic tasks can be accomplished faster and easier, in particular:

• You can describe web server routes as a hierarchical object.
• You can keep the endpoint's input and output type declarations right next to its handler.
• All input and output data types are validated, so it ensures you won't have an empty string, null or undefined where you expect a number.
• Variables within an endpoint handler have types according to the declared schema, so your IDE and Typescript will provide you with necessary hints to focus on bringing your vision to life.
• All of your endpoints can respond in a consistent way.
• The expected endpoint input and response types can be exported to the frontend, so you don't get confused about the field names when you implement the client for your API.
• You can generate your API documentation in OpenAPI 3.1 and JSON Schema compatible format.

Contributors

These people contributed to the improvement of the framework by reporting bugs, making changes and suggesting ideas:

How it works

Concept

The API operates object schemas for input and output validation. The object being validated is the combination of certain request properties. It is available to the endpoint handler as the input parameter. Middlewares have access to all request properties, they can provide endpoints with options. The object returned by the endpoint handler is called output. It goes to the ResultHandler which is responsible for transmitting consistent responses containing the output or possible error. Much can be customized to fit your needs.

Technologies

• Typescript first.
• Web server — Express.js v5.
• Schema validation — Zod 3.x including Zod Plugin.
• Supports any logger having info(), debug(), error() and warn() methods;
  • Built-in console logger with colorful and pretty inspections by default.
• Generators:
  • Documentation — OpenAPI 3.1 (former Swagger);
  • Client side types — inspired by zod-to-ts.
• File uploads — Express-FileUpload (based on Busboy).

Quick start

Installation

Install the framework, its peer dependencies and type assistance packages using your favorite package manager.

1# example for yarn:
2yarn add express-zod-api express zod@3 typescript http-errors
3yarn add -D @types/express @types/node @types/http-errors

Ensure having the following options in your tsconfig.json file in order to make it work as expected:

1{
2  "compilerOptions": {
3    "strict": true,
4    "skipLibCheck": true
5  }
6}

Set up config

Create a minimal configuration. See all available options in sources.

1import { createConfig } from "express-zod-api";
2
3const config = createConfig({
4  http: {
5    listen: 8090, // port, UNIX socket or options
6  },
7  cors: true,
8});

Create an endpoints factory

In the basic case, you can just import and use the default factory. See also Middlewares and Response customization.

1import { defaultEndpointsFactory } from "express-zod-api";

Create your first endpoint

The endpoint responds with "Hello, World" or "Hello, {name}" if the name is supplied within GET request payload.

1import { z } from "zod";
2
3const helloWorldEndpoint = defaultEndpointsFactory.build({
4  // method: "get" (default) or array ["get", "post", ...]
5  input: z.object({
6    name: z.string().optional(),
7  }),
8  output: z.object({
9    greetings: z.string(),
10  }),
11  handler: async ({ input: { name }, options, logger }) => {
12    logger.debug("Options:", options); // middlewares provide options
13    return { greetings: `Hello, ${name || "World"}. Happy coding!` };
14  },
15});

Set up routing

Connect your endpoint to the /v1/hello route:

1import { Routing } from "express-zod-api";
2
3const routing: Routing = {
4  v1: {
5    hello: helloWorldEndpoint,
6  },
7};

Create your server

See the complete implementation example.

1import { createServer } from "express-zod-api";
2
3createServer(config, routing);

Try it

Start your application and execute the following command:

1curl -L -X GET 'localhost:8090/v1/hello?name=Rick'

You should receive the following response:

1{ "status": "success", "data": { "greetings": "Hello, Rick. Happy coding!" } }

Basic features

Routing

The framework offers flexible ways to define your routes, supporting both nested and flat syntaxes, dynamic path parameters, method-based routing, and static file serving. This example brings together all supported routing styles in one place, illustrating how you can structure your API using whichever method best fits your application’s architecture — or even mix them seamlessly.

1import { Routing, DependsOnMethod, ServeStatic } from "express-zod-api";
2
3const routing: Routing = {
4  // flax syntax — /v1/users
5  "/v1/users": listUsersEndpoint,
6  // nested syntax
7  v1: {
8    // the way to have both — /v1/path and /v1/path/subpath
9    path: endpointA.nest({
10      subpath: endpointB,
11    }),
12    // path parameters — /v1/user/:id
13    user: {
14      ":id": getUserEndpoint,
15    },
16    // mixed syntax with explicit method — /v1/user/:id
17    "delete /user/:id": deleteUserEndpoint,
18    // method-based routing — /v1/account
19    account: new DependsOnMethod({
20      get: endpointA,
21      delete: endpointA,
22      post: endpointB,
23      patch: endpointB,
24    }),
25  },
26  // static file serving — /public serves files from ./assets
27  public: new ServeStatic("assets", {
28    /** @see https://expressjs.com/en/5x/api.html#express.static */
29    dotfiles: "deny",
30    index: false,
31    redirect: false,
32  }),
33};

Same Endpoint can be reused on different routes or handle multiple methods if needed. Path parameters (the :id above) should be declared in the endpoint’s input schema. Properties assigned with Endpoint can explicitly declare a method. When the method is not specified, the one(s) supported by the Endpoint applied (or get as a fallback).

Middlewares

Middleware can authenticate using input or request headers, and can provide endpoint handlers with options. Inputs of middlewares are also available to endpoint handlers within input.

Here is an example of the authentication middleware, that checks a key from input and token from headers:

1import { z } from "zod";
2import createHttpError from "http-errors";
3import { Middleware } from "express-zod-api";
4
5const authMiddleware = new Middleware({
6  security: {
7    // this information is optional and used for generating documentation
8    and: [
9      { type: "input", name: "key" },
10      { type: "header", name: "token" },
11    ],
12  },
13  input: z.object({
14    key: z.string().min(1),
15  }),
16  handler: async ({ input: { key }, request, logger }) => {
17    logger.debug("Checking the key and token");
18    const user = await db.Users.findOne({ key });
19    if (!user) throw createHttpError(401, "Invalid key");
20    if (request.headers.token !== user.token)
21      throw createHttpError(401, "Invalid token");
22    return { user }; // provides endpoints with options.user
23  },
24});

By using .addMiddleware() method before .build() you can connect it to the endpoint:

1const yourEndpoint = defaultEndpointsFactory
2  .addMiddleware(authMiddleware)
3  .build({
4    handler: async ({ options: { user } }) => {
5      // user is the one returned by authMiddleware
6    }, // ...
7  });

You can create a new factory by connecting as many middlewares as you want — they will be executed in the specified order for all the endpoints produced on that factory. You may also use a shorter inline syntax within the .addMiddleware() method, and have access to the output of the previously executed middlewares in chain as options:

1import { defaultEndpointsFactory } from "express-zod-api";
2
3const factory = defaultEndpointsFactory
4  .addMiddleware(authMiddleware) // add Middleware instance or use shorter syntax:
5  .addMiddleware({
6    handler: async ({ options: { user } }) => ({}), // user from authMiddleware
7  });

Options

In case you'd like to provide your endpoints with options that do not depend on Request, like non-persistent connection to a database, consider shorthand method addOptions. For static options consider reusing const across your files.

1import { readFile } from "node:fs/promises";
2import { defaultEndpointsFactory } from "express-zod-api";
3
4const endpointsFactory = defaultEndpointsFactory.addOptions(async () => {
5  // caution: new connection on every request:
6  const db = mongoose.connect("mongodb://connection.string");
7  const privateKey = await readFile("private-key.pem", "utf-8");
8  return { db, privateKey };
9});

Notice on resources cleanup: If necessary, you can release resources at the end of the request processing in a custom Result Handler:

1import { ResultHandler } from "express-zod-api";
2
3const resultHandlerWithCleanup = new ResultHandler({
4  handler: ({ options }) => {
5    // necessary to check for certain option presence:
6    if ("db" in options && options.db) {
7      options.db.connection.close(); // sample cleanup
8    }
9  },
10});

Using native express middlewares

There are two ways of connecting the native express middlewares depending on their nature and your objective.

In case it's a middleware establishing and serving its own routes, or somehow globally modifying the behaviour, or being an additional request parser (like cookie-parser), use the beforeRouting option. However, it might be better to avoid cors here — the framework handles it on its own.

1import { createConfig } from "express-zod-api";
2import ui from "swagger-ui-express";
3
4const config = createConfig({
5  beforeRouting: ({ app, getLogger }) => {
6    const logger = getLogger();
7    logger.info("Serving the API documentation at https://example.com/docs");
8    app.use("/docs", ui.serve, ui.setup(documentation));
9    app.use("/custom", (req, res, next) => {
10      const childLogger = getLogger(req); // if childLoggerProvider is configured
11    });
12  },
13});

In case you need a special processing of request, or to modify the response for selected endpoints, use the method addExpressMiddleware() of EndpointsFactory (or its alias use()). The method has two optional features: a provider of options and an error transformer for adjusting the response status code.

1import { defaultEndpointsFactory } from "express-zod-api";
2import createHttpError from "http-errors";
3import { auth } from "express-oauth2-jwt-bearer";
4
5const factory = defaultEndpointsFactory.use(auth(), {
6  provider: (req) => ({ auth: req.auth }), // optional, can be async
7  transformer: (err) => createHttpError(401, err.message), // optional
8});

Refinements

You can implement additional validations within schemas using refinements. Validation errors are reported in a response with a status code 400.

1import { z } from "zod";
2import { Middleware } from "express-zod-api";
3
4const nicknameConstraintMiddleware = new Middleware({
5  input: z.object({
6    nickname: z
7      .string()
8      .min(1)
9      .refine(
10        (nick) => !/^\d.*$/.test(nick),
11        "Nickname cannot start with a digit",
12      ),
13  }),
14  // ...,
15});

By the way, you can also refine the whole I/O object, for example in case you need a complex validation of its props.

1const endpoint = endpointsFactory.build({
2  input: z
3    .object({
4      email: z.string().email().optional(),
5      id: z.string().optional(),
6      otherThing: z.string().optional(),
7    })
8    .refine(
9      (inputs) => Object.keys(inputs).length >= 1,
10      "Please provide at least one property",
11    ),
12  // ...,
13});

Transformations

Since parameters of GET requests come in the form of strings, there is often a need to transform them into numbers or arrays of numbers.

1import { z } from "zod";
2
3const getUserEndpoint = endpointsFactory.build({
4  input: z.object({
5    id: z.string().transform((id) => parseInt(id, 10)),
6    ids: z
7      .string()
8      .transform((ids) => ids.split(",").map((id) => parseInt(id, 10))),
9  }),
10  handler: async ({ input: { id, ids }, logger }) => {
11    logger.debug("id", id); // type: number
12    logger.debug("ids", ids); // type: number[]
13  },
14});

Top level transformations and mapping

For some APIs it may be important that public interfaces such as query parameters use snake case, while the implementation itself requires camel case for internal naming. In order to facilitate interoperability between the different naming standards you can .transform() the entire input schema into another object using a well-typed mapping library, such as camelize-ts. However, that approach would not be enough for the output schema if you're also aiming to generate a valid documentation, because the transformations themselves do not contain schemas. Addressing this case, the framework offers the .remap() method of the object schema, a part of the Zod plugin, which under the hood, in addition to the transformation, also .pipe() the transformed object into a new object schema. Here is a recommended solution: it is important to use shallow transformations only.

1import camelize from "camelize-ts";
2import snakify from "snakify-ts";
3import { z } from "zod";
4
5const endpoint = endpointsFactory.build({
6  input: z
7    .object({ user_id: z.string() })
8    .transform((inputs) => camelize(inputs, /* shallow: */ true)),
9  output: z
10    .object({ userName: z.string() })
11    .remap((outputs) => snakify(outputs, /* shallow: */ true)),
12  handler: async ({ input: { userId }, logger }) => {
13    logger.debug("user_id became userId", userId);
14    return { userName: "Agneta" }; // becomes "user_name" in response
15  },
16});

The .remap() method can also accept an object with an explicitly defined naming of your choice. The original keys missing in that object remain unchanged (partial mapping).

1z.object({ user_name: z.string(), id: z.number() }).remap({
2  user_name: "weHAVEreallyWEIRDnamingSTANDARDS", // "id" remains intact
3});

Dealing with dates

Dates in Javascript are one of the most troublesome entities. In addition, Date cannot be passed directly in JSON format. Therefore, attempting to return Date from the endpoint handler results in it being converted to an ISO string in actual response by calling toJSON(), which in turn calls toISOString(). It is also impossible to transmit the Date in its original form to your endpoints within JSON. Therefore, there is confusion with original method z.date() that should not be used within IO schemas of your API.

In order to solve this problem, the framework provides two custom methods for dealing with dates: ez.dateIn() and ez.dateOut() for using within input and output schemas accordingly.

ez.dateIn() is a transforming schema that accepts an ISO string representation of a Date, validates it, and provides your endpoint handler or middleware with a Date. It supports the following formats:

12021-12-31T23:59:59.000Z
22021-12-31T23:59:59Z
32021-12-31T23:59:59
42021-12-31

ez.dateOut(), on the contrary, accepts a Date and provides ResultHandler with a string representation in ISO format for the response transmission. Consider the following simplified example for better understanding:

1import { z } from "zod";
2import { ez, defaultEndpointsFactory } from "express-zod-api";
3
4const updateUserEndpoint = defaultEndpointsFactory.build({
5  method: "post",
6  input: z.object({
7    userId: z.string(),
8    birthday: ez.dateIn(), // string -> Date in handler
9  }),
10  output: z.object({
11    createdAt: ez.dateOut(), // Date -> string in response
12  }),
13  handler: async ({ input }) => ({
14    createdAt: new Date("2022-01-22"), // 2022-01-22T00:00:00.000Z
15  }),
16});

Cross-Origin Resource Sharing

You can enable your API for other domains using the corresponding configuration option cors. It's not optional to draw your attention to making the appropriate decision, however, it's enabled in the Quick start example above, assuming that in most cases you will want to enable this feature. See MDN article for more information.

In addition to being a boolean, cors can also be assigned a function that overrides default CORS headers. That function has several parameters and can be asynchronous.

1import { createConfig } from "express-zod-api";
2
3const config = createConfig({
4  cors: ({ defaultHeaders, request, endpoint, logger }) => ({
5    ...defaultHeaders,
6    "Access-Control-Max-Age": "5000",
7  }),
8});

Please note: If you only want to send specific headers on requests to a specific endpoint, consider the Middlewares or response customization approach.

Enabling HTTPS

The modern API standard often assumes the use of a secure data transfer protocol, confirmed by a TLS certificate, also often called an SSL certificate in habit. This way you can additionally (or solely) configure and run the HTTPS server:

1import { createConfig, createServer } from "express-zod-api";
2
3const config = createConfig({
4  https: {
5    options: {
6      cert: fs.readFileSync("fullchain.pem", "utf-8"),
7      key: fs.readFileSync("privkey.pem", "utf-8"),
8    },
9    listen: 443, // port, UNIX socket or options
10  }, // ... cors, logger, etc
11});
12
13// 'await' is only needed if you're going to use the returned entities.
14// For top level CJS you can wrap you code with (async () => { ... })()
15const { app, servers, logger } = await createServer(config, routing);

Ensure having @types/node package installed. At least you need to specify the port (usually it is 443) or UNIX socket, certificate and the key, issued by the certifying authority. For example, you can acquire a free TLS certificate for your API at Let's Encrypt.

Customizing logger

A simple built-in console logger is used by default with the following options that you can configure:

1import { createConfig } from "express-zod-api";
2const config = createConfig({
3  logger: {
4    level: "debug", // or "warn" in production mode
5    color: undefined, // detects automatically, boolean
6    depth: 2, // controls how deeply entities should be inspected
7  },
8});

You can also replace it with a one having at least the following methods: info(), debug(), error() and warn(). Winston and Pino support is well known. Here is an example configuring pino logger with pino-pretty extension:

1import pino, { Logger } from "pino";
2import { createConfig } from "express-zod-api";
3
4const logger = pino({
5  transport: {
6    target: "pino-pretty",
7    options: { colorize: true },
8  },
9});
10const config = createConfig({ logger });
11
12// Setting the type of logger used
13declare module "express-zod-api" {
14  interface LoggerOverrides extends Logger {}
15}

Child logger

In case you need a dedicated logger for each request (for example, equipped with a request ID), you can specify the childLoggerProvider option in your configuration. The function accepts the initially defined logger and the request, it can also be asynchronous. The child logger returned by that function will replace the logger in all handlers. You can use the .child() method of the built-in logger or install a custom logger instead.

1import { createConfig, BuiltinLogger } from "express-zod-api";
2import { randomUUID } from "node:crypto";
3
4// This enables the .child() method on "logger":
5declare module "express-zod-api" {
6  interface LoggerOverrides extends BuiltinLogger {}
7}
8
9const config = createConfig({
10  childLoggerProvider: ({ parent, request }) =>
11    parent.child({ requestId: randomUUID() }), // accessible at logger.ctx.requestId later
12});

Profiling

For debugging and performance testing purposes the framework offers a simple .profile() method on the built-in logger. It starts a timer when you call it and measures the duration in adaptive units (from picoseconds to minutes) until you invoke the returned callback. The default severity of those measurements is debug.

1import { createConfig, BuiltinLogger } from "express-zod-api";
2
3// This enables the .profile() method on built-in logger:
4declare module "express-zod-api" {
5  interface LoggerOverrides extends BuiltinLogger {}
6}
7
8// Inside a handler of Endpoint, Middleware or ResultHandler:
9const done = logger.profile("expensive operation");
10doExpensiveOperation();
11done(); // debug: expensive operation '555 milliseconds'

You can also customize the profiler with your own formatter, chosen severity or even performance assessment function:

1logger.profile({
2  message: "expensive operation",
3  severity: (ms) => (ms > 500 ? "error" : "info"), // assess immediately
4  formatter: (ms) => `${ms.toFixed(2)}ms`, // custom format
5});
6doExpensiveOperation();
7done(); // error: expensive operation '555.55ms'

Enabling compression

According to Express.js best practices guide it might be a good idea to enable GZIP and Brotli compression for your API responses.

Install compression and @types/compression, and enable or configure compression:

1import { createConfig } from "express-zod-api";
2
3const config = createConfig({
4  /** @link https://www.npmjs.com/package/compression#options */
5  compression: { threshold: "1kb" }, // or true
6});

In order to receive a compressed response the client should include the following header in the request: Accept-Encoding: br, gzip, deflate. Only responses with compressible content types are subject to compression.

Advanced features

Customizing input sources

You can customize the list of request properties that are combined into input that is being validated and available to your endpoints and middlewares. The order here matters: each next item in the array has a higher priority than its previous sibling. The following arrangement is default:

1import { createConfig } from "express-zod-api";
2
3createConfig({
4  inputSources: {
5    get: ["query", "params"],
6    post: ["body", "params", "files"],
7    put: ["body", "params"],
8    patch: ["body", "params"],
9    delete: ["query", "params"],
10  }, // ...
11});

Headers as input source

In a similar way you can enable request headers as the input source. This is an opt-in feature. Please note:

• consider giving headers the lowest priority among other inputSources to avoid overwrites;
• consider handling headers in Middleware and declaring them within security property to improve Documentation;
• the request headers acquired that way are always lowercase when describing their validation schemas.

1import { createConfig, Middleware } from "express-zod-api";
2import { z } from "zod";
3
4createConfig({
5  inputSources: {
6    get: ["headers", "query"], // headers have lowest priority
7  }, // ...
8});
9
10new Middleware({
11  security: { type: "header", name: "token" }, // recommended
12  input: z.object({ token: z.string() }),
13});
14
15factory.build({
16  input: z.object({
17    "x-request-id": z.string(), // this one is from request.headers
18    id: z.string(), // this one is from request.query
19  }), // ...
20});

Response customization

ResultHandler is responsible for transmitting consistent responses containing the endpoint output or an error. The defaultResultHandler sets the HTTP status code and ensures the following type of the response:

1type DefaultResponse<OUT> =
2  | { status: "success"; data: OUT } // Positive response
3  | { status: "error"; error: { message: string } }; // or Negative response

You can create your own result handler by using this example as a template:

1import { z } from "zod";
2import {
3  ResultHandler,
4  ensureHttpError,
5  getMessageFromError,
6} from "express-zod-api";
7
8const yourResultHandler = new ResultHandler({
9  positive: (data) => ({
10    schema: z.object({ data }),
11    mimeType: "application/json", // optinal or array
12  }),
13  negative: z.object({ error: z.string() }),
14  handler: ({ error, input, output, request, response, logger }) => {
15    if (error) {
16      const { statusCode } = ensureHttpError(error);
17      const message = getMessageFromError(error);
18      return void response.status(statusCode).json({ error: message });
19    }
20    response.status(200).json({ data: output });
21  },
22});

See also Different responses for different status codes.

After creating your custom ResultHandler you can use it as an argument for EndpointsFactory instance creation:

1import { EndpointsFactory } from "express-zod-api";
2
3const endpointsFactory = new EndpointsFactory(yourResultHandler);

Empty response

For some REST APIs, empty responses are typical: with status code 204 (No Content) and redirects (302). In order to describe it set the mimeType to null and schema to z.never():

1const resultHandler = new ResultHandler({
2  positive: { statusCode: 204, mimeType: null, schema: z.never() },
3  negative: { statusCode: 404, mimeType: null, schema: z.never() },
4});

Error handling

All runtime errors are handled by a ResultHandler. The default is defaultResultHandler. Using ensureHttpError() it normalizes errors into consistent HTTP responses with sensible status codes. Errors can originate from three layers:

• Endpoint execution (including attached Middleware):
  • Handled by a ResultHandler used by EndpointsFactory (defaultEndpointsFactory uses defaultResultHandler);
  • InputValidationError: request violates input schema, the default status code is 400;
  • OutputValidationError: handler violates output schema, the default status code is 500;
  • HttpError: can be thrown in handlers with help of createHttpError(), its .statusCode is used for response;
  • For other errors the default status code is 500;
• Routing, parsing and upload issues:
  • Handled by ResultHandler configured as errorHandler (the defaults is defaultResultHandler);
  • Parsing errors: passed through as-is (typically HttpError with 4XX code used for response by default);
  • Routing errors: 404 or 405, based on wrongMethodBehavior configuration;
  • Upload issues: thrown only if upload.limitError is configured (HttpError::statusCode can be used for response);
  • For other errors the default status code is 500;
• ResultHandler failures:
  • Handled by LastResortHandler with status code 500 and a plain text response.

You can customize it by passing a custom ResultHandler to EndpointsFactory and by configuring errorHandler.

Production mode

Consider enabling production mode by setting NODE_ENV environment variable to production for your deployment:

• Express activates some performance optimizations;
• Self-diagnosis for potential problems is disabled to ensure faster startup;
• The defaultResultHandler, defaultEndpointsFactory and LastResortHandler generalize server-side error messages in negative responses in order to improve the security of your API by not disclosing the exact causes of errors:
  • Throwing errors that have or imply 5XX status codes become just Internal Server Error message in response;
  • You can control that behavior by throwing errors using createHttpError() and using its expose option:

1import createHttpError from "http-errors";
2// NODE_ENV=production
3// Throwing HttpError from Endpoint or Middleware that is using defaultResultHandler or defaultEndpointsFactory:
4createHttpError(401, "Token expired"); // —> "Token expired"
5createHttpError(401, "Token expired", { expose: false }); // —> "Unauthorized"
6createHttpError(500, "Something is broken"); // —> "Internal Server Error"
7createHttpError(501, "We didn't make it yet", { expose: true }); // —> "We didn't make it yet"

Non-object response

Thus, you can configure non-object responses too, for example, to send an image file.

You can find two approaches to EndpointsFactory and ResultHandler implementation in this example. One of them implements file streaming, in this case the endpoint just has to provide the filename. The response schema generally may be just z.string(), but I made more specific ez.file() that also supports ez.file("binary") and ez.file("base64") variants which are reflected in the generated documentation.

1const fileStreamingEndpointsFactory = new EndpointsFactory(
2  new ResultHandler({
3    positive: { schema: ez.file("buffer"), mimeType: "image/*" },
4    negative: { schema: z.string(), mimeType: "text/plain" },
5    handler: ({ response, error, output }) => {
6      if (error) return void response.status(400).send(error.message);
7      if ("filename" in output)
8        fs.createReadStream(output.filename).pipe(
9          response.type(output.filename),
10        );
11      else response.status(400).send("Filename is missing");
12    },
13  }),
14);

HTML Forms (URL encoded)

Use the proprietary schema ez.form() with an object shape or a custom z.object() with form fields in order to describe the input schema of an Endpoint. Requests to the Endpoint are parsed using the formParser config option, which is express.urlencoded() by default. The request content type should be application/x-www-form-urlencoded (default for HTML forms without uploads).

1import { defaultEndpointsFactory, ez } from "express-zod-api";
2import { z } from "zod";
3
4export const submitFeedbackEndpoint = defaultEndpointsFactory.build({
5  method: "post",
6  input: ez.form({
7    name: z.string().min(1),
8    email: z.string().email(),
9    message: z.string().min(1),
10  }),
11});

Hint: for unlisted extra fields use the following syntax: ez.form( z.object({}).passthrough() ).

File uploads

Install the following additional packages: express-fileupload and @types/express-fileupload, and enable or configure file uploads. Refer to documentation on available options. The limitHandler option is replaced by the limitError one. You can also connect an additional middleware for restricting the ability to upload using the beforeUpload option. So the configuration for the limited and restricted upload might look this way:

1import createHttpError from "http-errors";
2
3const config = createConfig({
4  upload: /* true or options: */ {
5    limits: { fileSize: 51200 }, // 50 KB
6    limitError: createHttpError(413, "The file is too large"), // handled by errorHandler in config
7    beforeUpload: ({ request, logger }) => {
8      if (!canUpload(request)) throw createHttpError(403, "Not authorized");
9    },
10    debug: true, // default
11  },
12});

Then use ez.upload() schema for a corresponding property. The request content type must be multipart/form-data:

1import { z } from "zod";
2import { ez, defaultEndpointsFactory } from "express-zod-api";
3
4const fileUploadEndpoint = defaultEndpointsFactory.build({
5  method: "post",
6  input: z.object({
7    avatar: ez.upload(), // <--
8  }),
9  output: z.object({}),
10  handler: async ({ input: { avatar } }) => {
11    // avatar: {name, mv(), mimetype, data, size, etc}
12    // avatar.truncated is true on failure when limitError option is not set
13  },
14});

You can still send other data and specify additional input parameters, including arrays and objects.

Connect to your own express app

If you already have your own configured express application, or you find the framework settings not enough, you can connect the endpoints to your app or any express router using the attachRouting() method:

1import express from "express";
2import { createConfig, attachRouting, Routing } from "express-zod-api";
3
4const app = express(); // or express.Router()
5const config = createConfig({ app /* cors, logger, ... */ });
6const routing: Routing = {}; // your endpoints go here
7
8const { notFoundHandler, logger } = attachRouting(config, routing);
9
10app.use(notFoundHandler); // optional
11app.listen();
12logger.info("Glory to science!");

Please note that in this case you probably need to parse request.body, call app.listen() and handle 404 errors yourself. In this regard attachRouting() provides you with notFoundHandler which you can optionally connect to your custom express app.

Besides that, if you're looking to include additional request parsers, or a middleware that establishes its own routes, then consider using the beforeRouting option in config instead.

Testing endpoints

The way to test endpoints is to mock the request, response, and logger objects, invoke the execute() method, and assert the expectations on status, headers and payload. The framework provides a special method testEndpoint that makes mocking easier. Under the hood, request and response object are mocked using the node-mocks-http library, therefore you can utilize its API for settings additional properties and asserting expectation using the provided getters, such as ._getStatusCode().

1import { testEndpoint } from "express-zod-api";
2
3test("should respond successfully", async () => {
4  const { responseMock, loggerMock } = await testEndpoint({
5    endpoint: yourEndpoint,
6    requestProps: {
7      method: "POST", // default: GET
8      body: {}, // incoming data as if after parsing (JSON)
9    }, // responseOptions, configProps, loggerProps
10  });
11  expect(loggerMock._getLogs().error).toHaveLength(0);
12  expect(responseMock._getStatusCode()).toBe(200);
13  expect(responseMock._getHeaders()).toHaveProperty("x-custom", "one"); // lower case!
14  expect(responseMock._getJSONData()).toEqual({ status: "success" });
15});

Testing middlewares

Middlewares can also be tested individually using the testMiddleware() method. You can also pass options collected from outputs of previous middlewares, if the one being tested somehow depends on them. Possible errors would be handled either by errorHandler configured within given configProps or defaultResultHandler.

1import { z } from "zod";
2import { Middleware, testMiddleware } from "express-zod-api";
3
4const middleware = new Middleware({
5  input: z.object({ test: z.string() }),
6  handler: async ({ options, input: { test } }) => ({
7    collectedOptions: Object.keys(options),
8    testLength: test.length,
9  }),
10});
11
12const { output, responseMock, loggerMock } = await testMiddleware({
13  middleware,
14  requestProps: { method: "POST", body: { test: "something" } },
15  options: { prev: "accumulated" }, // responseOptions, configProps, loggerProps
16});
17expect(loggerMock._getLogs().error).toHaveLength(0);
18expect(output).toEqual({ collectedOptions: ["prev"], testLength: 9 });

Special needs

Different responses for different status codes

In some special cases you may want the ResultHandler to respond slightly differently depending on the status code, for example if your API strictly follows REST standards. It may also be necessary to reflect this difference in the generated Documentation. For that purpose, the constructor of ResultHandler accepts flexible declaration of possible response schemas and their corresponding status codes.

1import { ResultHandler } from "express-zod-api";
2
3new ResultHandler({
4  positive: (data) => ({
5    statusCode: [201, 202], // created or will be created
6    schema: z.object({ status: z.literal("created"), data }),
7  }),
8  negative: [
9    {
10      statusCode: 409, // conflict: entity already exists
11      schema: z.object({ status: z.literal("exists"), id: z.number().int() }),
12    },
13    {
14      statusCode: [400, 500], // validation or internal error
15      schema: z.object({ status: z.literal("error"), reason: z.string() }),
16    },
17  ],
18  handler: ({ error, response, output }) => {
19    // your implementation here
20  },
21});

Array response

Please avoid doing this in new projects: responding with array is a bad practice keeping your endpoints from evolving in backward compatible way (without making breaking changes). Nevertheless, for the purpose of easier migration of legacy APIs to this framework consider using arrayResultHandler or arrayEndpointsFactory instead of default ones, or implement your own ones in a similar way. The arrayResultHandler expects your endpoint to have items property in the output object schema. The array assigned to that property is used as the response. This approach also supports examples, as well as documentation and client generation. Check out the example endpoint for more details.

Accepting raw data

Some APIs may require an endpoint to be able to accept and process raw data, such as streaming or uploading a binary file as an entire body of request. Use the proprietary ez.raw() schema as the input schema of your endpoint. The default parser in this case is express.raw(). You can customize it by assigning the rawParser option in config. The raw data is placed into request.body.raw property, having type Buffer.

1import { defaultEndpointsFactory, ez } from "express-zod-api";
2
3const rawAcceptingEndpoint = defaultEndpointsFactory.build({
4  method: "post",
5  input: ez.raw({
6    /* the place for additional inputs, like route params, if needed */
7  }),
8  output: z.object({ length: z.number().int().nonnegative() }),
9  handler: async ({ input: { raw } }) => ({
10    length: raw.length, // raw is Buffer
11  }),
12});

Graceful shutdown

You can enable and configure a special request monitoring that, if it receives a signal to terminate a process, will first put the server into a mode that rejects new requests, attempt to complete started requests within the specified time, and then forcefully stop the server and terminate the process.

1import { createConfig } from "express-zod-api";
2
3createConfig({
4  gracefulShutdown: {
5    timeout: 1000,
6    events: ["SIGINT", "SIGTERM"],
7  },
8});

Subscriptions

If you want the user of a client application to be able to subscribe to subsequent updates initiated by the server, consider Server-Sent Events (SSE) feature. Client application can subscribe to the event stream using EventSource class instance or the instance of the generated Subscription class. The following example demonstrates the implementation emitting the time event each second.

1import { z } from "zod";
2import { EventStreamFactory } from "express-zod-api";
3import { setTimeout } from "node:timers/promises";
4
5const subscriptionEndpoint = new EventStreamFactory({
6  time: z.number().int().positive(),
7}).buildVoid({
8  input: z.object({}), // optional input schema
9  handler: async ({ options: { emit, isClosed } }) => {
10    while (!isClosed()) {
11      emit("time", Date.now());
12      await setTimeout(1000);
13    }
14  },
15});

If you need more capabilities, such as bidirectional event sending, I have developed an additional websocket operating framework, Zod Sockets, which has similar principles and capabilities.

Integration and Documentation

Zod Plugin

Express Zod API acts as a plugin for Zod, extending its functionality once you import anything from express-zod-api:

• Adds .example() method to all Zod schemas for storing examples and reflecting them in the generated documentation;
• Adds .deprecated() method to all schemas for marking properties and request parameters as deprecated;
• Adds .label() method to ZodDefault for replacing the default value in documentation with a label;
• Adds .remap() method to ZodObject for renaming object properties in a suitable way for making documentation;
• Alters the .brand() method on all Zod schemas by making the assigned brand available in runtime.

Generating a Frontend Client

You can generate a Typescript file containing the IO types of your API and a client for it. Consider installing prettier and using the async printFormatted() method.

1import { Integration } from "express-zod-api";
2
3const client = new Integration({
4  routing,
5  variant: "client", // <— optional, see also "types" for a DIY solution
6  optionalPropStyle: { withQuestionMark: true, withUndefined: true }, // optional
7});
8
9const prettierFormattedTypescriptCode = await client.printFormatted(); // or just .print() for unformatted

Alternatively, you can supply your own format function into that method or use a regular print() method instead. The generated client is flexibly configurable on the frontend side for using a custom implementation function that makes requests using the libraries and methods of your choice. The default implementation uses fetch. The client asserts the type of request parameters and response. Consuming the generated client requires Typescript version 4.1+.

1import { Client, Implementation, Subscription } from "./client.ts"; // the generated file
2
3const client = new Client(/* optional custom Implementation */);
4client.provide("get /v1/user/retrieve", { id: "10" });
5client.provide("post /v1/user/:id", { id: "10" }); // it also substitues path params
6new Subscription("get /v1/events/stream", {}).on("time", (time) => {}); // Server-sent events (SSE)

Creating a documentation

You can generate the specification of your API and write it to a .yaml file, that can be used as the documentation:

1import { Documentation } from "express-zod-api";
2
3const yamlString = new Documentation({
4  routing, // the same routing and config that you use to start the server
5  config,
6  version: "1.2.3",
7  title: "Example API",
8  serverUrl: "https://example.com",
9  composition: "inline", // optional, or "components" for keeping schemas in a separate dedicated section using refs
10  // descriptions: { positiveResponse, negativeResponse, requestParameter, requestBody }, // check out these features
11  // numericRange: null, // to disable printing min/max values for z.number() based on JS engine limits
12}).getSpecAsYaml();

You can add descriptions and examples to your endpoints, their I/O schemas and their properties. It will be included into the generated documentation of your API. Consider the following example:

1import { defaultEndpointsFactory } from "express-zod-api";
2
3const exampleEndpoint = defaultEndpointsFactory.build({
4  shortDescription: "Retrieves the user.", // <—— this becomes the summary line
5  description: "The detailed explanaition on what this endpoint does.",
6  input: z.object({
7    id: z.number().describe("the ID of the user").example(123),
8  }),
9  // ..., similarly for output and middlewares
10});

See the example of the generated documentation here

Tagging the endpoints

When generating documentation, you may find it necessary to classify endpoints into groups. The possibility of tagging endpoints is available for that purpose. In order to establish the constraints on tags across all the endpoints, they should be declared as keys of TagOverrides interface. Consider the following example:

1import { defaultEndpointsFactory, Documentation } from "express-zod-api";
2
3// Add similar declaration once, somewhere in your code, preferably near config
4declare module "express-zod-api" {
5  interface TagOverrides {
6    users: unknown;
7    files: unknown;
8    subscriptions: unknown;
9  }
10}
11
12// Use the declared tags for endpoints
13const exampleEndpoint = defaultEndpointsFactory.build({
14  tag: "users", // or array ["users", "files"]
15});
16
17// Add extended description of the tags to Documentation (optional)
18new Documentation({
19  tags: {
20    users: "All about users",
21    files: { description: "All about files", url: "https://example.com" },
22  },
23});

Deprecated schemas and routes

As your API evolves, you may need to mark some parameters or routes as deprecated before deleting them. For this purpose, the .deprecated() method is available on each schema, Endpoint and DependsOnMethod, it's immutable. You can also deprecate all routes the Endpoint assigned to by setting EndpointsFactory::build({ deprecated: true }).

1import { Routing, DependsOnMethod } from "express-zod-api";
2import { z } from "zod";
3
4const someEndpoint = factory.build({
5  deprecated: true, // deprecates all routes the endpoint assigned to
6  input: z.object({
7    prop: z.string().deprecated(), // deprecates the property or a path parameter
8  }),
9});
10
11const routing: Routing = {
12  v1: oldEndpoint.deprecated(), // deprecates the /v1 path
13  v2: new DependsOnMethod({ get: oldEndpoint }).deprecated(), // deprecates the /v2 path
14  v3: someEndpoint, // the path is assigned with initially deprecated endpoint (also deprecated)
15};

Customizable brands handling

You can customize handling rules for your schemas in Documentation and Integration. Use the .brand() method on your schema to make it special and distinguishable for the framework in runtime. Using symbols is recommended for branding. After that utilize the brandHandling feature of both constructors to declare your custom implementation. In case you need to reuse a handling rule for multiple brands, use the exposed types Depicter and Producer.

1import ts from "typescript";
2import { z } from "zod";
3import {
4  Documentation,
5  Integration,
6  Depicter,
7  Producer,
8} from "express-zod-api";
9
10const myBrand = Symbol("MamaToldMeImSpecial"); // I recommend to use symbols for this purpose
11const myBrandedSchema = z.string().brand(myBrand);
12
13const ruleForDocs: Depicter = (
14  schema: typeof myBrandedSchema, // you should assign type yourself
15  { next, path, method, isResponse }, // handle a nested schema using next()
16) => {
17  const defaultDepiction = next(schema.unwrap()); // { type: string }
18  return { summary: "Special type of data" };
19};
20
21const ruleForClient: Producer = (
22  schema: typeof myBrandedSchema, // you should assign type yourself
23  { next, isResponse }, // handle a nested schema using next()
24) => ts.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
25
26new Documentation({
27  brandHandling: { [myBrand]: ruleForDocs },
28});
29
30new Integration({
31  brandHandling: { [myBrand]: ruleForClient },
32});

Caveats

There are some well-known issues and limitations, or third party bugs that cannot be fixed in the usual way, but you should be aware of them.

Coercive schema of Zod

Despite being supported by the framework, z.coerce.* schema does not work intuitively. Please be aware that z.coerce.number() and z.number({ coerce: true }) (being typed not well) still will NOT allow you to assign anything but number. Moreover, coercive schemas are not fail-safe and their methods .isOptional() and .isNullable() are buggy. If possible, try to avoid using this type of schema. This issue will NOT be fixed in Zod version 3.x.

Excessive properties in endpoint output

The schema validator removes excessive properties by default. However, Typescript does not yet display errors in this case during development. You can achieve this verification by assigning the output schema to a constant and reusing it in forced type of the output:

1import { z } from "zod";
2
3const output = z.object({
4  anything: z.number(),
5});
6
7endpointsFactory.build({
8  output,
9  handler: async (): Promise<z.input<typeof output>> => ({
10    anything: 123,
11    excessive: "something", // error TS2322, ok!
12  }),
13});

Your input to my output

If you have a question or idea, or you found a bug, or vulnerability, or security issue, or want to make a PR: please refer to Contributing Guidelines.