zod-express-validator

A package to validate Express request and response payloads using Zod.

Inspired by zod-express-middleware

Prerequisites

This package requires your project to have Express and Zod installed.
To add this package to your project you can use one of the following commands:

1npm install zod-express-validator
2yarn add zod-express-validator
3pnpm add zod-express-validator

Usage

This package has a single function that you use as an Express middleware in your handlers, you need to import it as the following:

1import { validate } from "zod-express-validator";

Then, in your handler you can use it as the following:

1const app = express();
2
3const bodySchema = z.object({
4  name: z.string().min(3).max(255),
5});
6
7const paramsSchema = z.object({
8  userId: z.coerce.number(),
9});
10
11const querySchema = z.object({
12  page: z.coerce.number().min(1).max(100),
13});
14
15const responseSchema = z.object({
16  success: z.boolean(),
17});
18
19app.post(
20  "/info/:userId",
21  validate(
22    {
23      body: bodySchema,
24      params: paramsSchema,
25      query: querySchema,
26      res: responseSchema,
27    },
28    ({ bodyError, paramsError, queryError }, res) => {
29      //This will be called if there is a validation error in the request.
30      //Get the first non-null error
31      const error = bodyError ?? paramsError ?? queryError;
32      return res.status(400).json({ error: error?.message });
33    }
34  ),
35  (req, res) => {
36    // Do something
37    const body = req.body; //body is now typed
38    const params = req.params; //params is now typed
39    const query = req.query; //query is now typeds
40
41    //Because we have a response schema, we will have type checking for the response
42    return res.status(200).json({ success: true });
43  }
44);

Note: You can skip any of the schemas if you don't want to validate it.
Important Note: For validation of params and query your must always use z.coerce to convert the values to the correct type

Usage with Controllers

1const app = express();
2
3const bodySchema = z.object({
4  name: z.string().min(3).max(255),
5});
6
7const paramsSchema = z.object({
8  userId: z.coerce.string().min(3).max(255),
9});
10
11const querySchema = z.object({
12  page: z.coerce.number().min(1).max(100),
13});
14
15const responseSchema = z.object({
16  success: z.boolean(),
17});
18
19const validator = validate(
20  {
21    body: bodySchema,
22    params: paramsSchema,
23    query: querySchema,
24    res: responseSchema,
25  },
26  ({ bodyError, paramsError, queryError }, res) => {
27    //This will be called if there is a validation error in the request.
28    //Get the first non-null error
29    const error = bodyError ?? paramsError ?? queryError;
30    return res.status(400).json({ error: error?.message });
31  }
32);
33
34type ValidatorType = typeof validator;
35
36const controller: ValidatorType = (req, res) => {
37  // Do something
38  const body = req.body; //body is now typed
39  const params = req.params; //params is now typed
40  const query = req.query; //query is now typeds
41
42  //Because we have a response schema, we will have type checking for the response
43  return res.status(200).json({ success: true });
44};
45
46app.post("/info/:userId", validator, controller);

Error Handling

If there is a validation error in the request, the error handler will be called with an object containing the errors for each of the request parts.
If you don't specify an error handler, the default error handler will be used, which will throw a RequestValidationError that contains the property errors with the validation error.

Typescript Support

This package fully supports Typescript, and will infer the types of your request and response payloads.

Versioning

This package uses SemVer for versioning.

Contributing & Issues

Feel free to open an issue or a pull request if you have any suggestions or if you found a bug.

License

This project is licensed under the MIT License - see the LICENSE file for details.