Zod Express validator

This package provides a set of usefull Express tools for REST request validation with zod (body, parameters and query) based on Matt Pocock's (💜) solution.

Installation

As simple as:

1npm i @zodyac/express
2
3pnpm add @zodyac/express
4
5yarn add @zodyac/express
6
7bun add @zodyac/express

Usage

Validating body

Define your request body schema:

1import { z } from "zod";
2
3const zBody = z.object({
4  // ... your zod schema
5});

Create an endpoint using CheckBody function:

1const my_endpoint = CheckBody(zBody, (req, res) => {
2  const body = req.body;
3  // ... the rest of your code
4});

Validating parameters

You can also parse your request parameters using CheckParams:

1const my_endpoint = CheckParams(zParams, (req, res) => {
2  const params = req.params;
3  // ... the rest of your code
4});

Validating query parameters

And query parameters using CheckQuery:

1const my_endpoint = CheckQuery(zQuery, (req, res) => {
2  const query = req.query;
3  // ... the rest of your code
4});

As you can see, req.body, req.params and req.query are inferring types from your zod schema.

Please remember that Express params and query parameters are always strings. If you want to parse them to other types, you have to do it manually.

Validating all at once

But what if... We want to validate all of them at once? No problem, just use Check:

1const my_endpoint = Check(
2  {
3    body: zBody,
4    params: zParams,
5    query: zQuery,
6  },
7  (req, res) => {
8    const body = req.body;
9    const params = req.params;
10    const query = req.query;
11    // ... the rest of your code
12  }
13);

Error handling

If validation fails, Check, CheckBody, CheckParams and CheckQuery will automatically send 406 response with error message. If you want to handle errors yourself, you can use ValidationOptions:

1const my_error_handler: ze.ValidationOptions = {
2  errorCode: 400, // default is 406 (Not Acceptable)
3  errorHandler: (req, res, error) => {
4    // error is zod Error
5    const error_message = error.errors[0].message;
6    // ... your error handling code
7  },
8};
9
10const my_endpoint = Check(
11  {
12    body: zBody,
13    params: zParams,
14    query: zQuery,
15  },
16  (req, res) => {
17    const body = req.body;
18    const params = req.params;
19    const query = req.query;
20    // ... the rest of your code
21  },
22  my_error_handler
23);

ValidationOptions interface:

1type ErrorHandler = (req: Request, res: Response, error: z.ZodError) => void;
2
3interface ValidationOptions {
4  errorCode?: number;
5  errorHandler?: ErrorHandler;
6}

Middleware

If you prefer to validate your requests aside from your endpoints logic, you can use zem.Body, zem.Params, zem.Query or zem.Check middleware:

1import { zem } from "@zodyac/express";
2
3const my_endpoint = (req: Request, res: Response) => {
4  const body = req.body;
5  const params = req.params;
6  const query = req.query;
7  // ... the rest of your code
8};
9
10app.post("/my_endpoint", zem.Body(zBody), my_endpoint);
11app.get("/my_endpoint/:id", zem.Params(zParams), my_endpoint);
12app.get("/my_endpoint", zem.Query(zQuery), my_endpoint);
13
14app.put(
15  "/my_endpoint",
16  zem.Check({
17    body: zBody,
18    params: zParams,
19    query: zQuery,
20  }),
21  my_endpoint
22);

In this case your req.body, req.params and req.query will be any. If you want to use types, you have to specify them manually or use CheckBody, CheckParams, CheckQuery or Check.

Experimental: decorators

You can also use decorators to validate your requests. Just add @ValidateBody, @ValidateParams, @ValidateQuery or @Validate to your endpoint function:

1export class Example {
2  @ValidateBody(zBody)
3  public static my_endpoint(req: Request, res: Response) {
4    const body = req.body as z.infer<typeof zBody>;
5    // ... the rest of your code
6  }
7}

Due to the limitations of TypeScript decorators, you have to specify the type of req.body manually.

Contributing

Feel free to open issues and pull requests! Here's a quick guide to get you started:

• Fork the repository
• Install linter and formatter for VSCode: Biome
• Install dependencies: npm i
• Make changes
• Run tests: npm test (not implemented yet)
• Run linter: npm run lint (fix with npm run lint:fix)
• Commit and push your changes
• Open a pull request

License

MIT