🛡️ Express Zod Safe

Express Zod Safe is a strict, typesafe middleware designed for Node.js applications, leveraging the robustness of Zod schemas to validate incoming request bodies, parameters, and queries. This package seamlessly integrates with Express.js (or similar frameworks) to provide developers with a typesafe, declarative approach to ensure data integrity and prevent invalid or malicious data from affecting their applications.

This package was inspired by Aquila169's zod-express-middleware package, and is intended to be a more robust and typesafe alternative.

🔒 Features

• Typesafe: Built with TypeScript, offering complete typesafe interfaces that enrich your development experience.
• Zod Integration: Utilises Zod schemas for comprehensive and customisable request validation.
• Middleware Flexibility: Easily integrates with Express.js middleware stack, ensuring a smooth validation process without compromising performance.
• Parameter & Query Validation: Validates not just request bodies but also URL parameters and query strings, covering all facets of incoming data.
• Error Handling: Provides detailed, developer-friendly error responses to aid in debugging and informing API consumers.
• Simple & Intuitive: Designed to be easy to use and understand, with a declarative API that is both concise and powerful.

⬇️ Install

Install this package using your package manager of choice.

1npm i express-zod-safe

zod, express and @types/express are peer dependencies and must be installed separately. This means you can bring your own version of these packages, and this package will not force you to use a specific version.

1npm i zod express && npm i -D @types/express

🛠️ Usage

1import express from 'express';
2import validate from 'express-zod-safe';
3import { z } from 'zod';
4 
5const app = express();
6 
7// Define your Zod schemas
8const params = {
9  userId: z.string().uuid(),
10};
11const query = {
12  age: z.coerce.number().optional(), // Given all query params and url params are strings, this will coerce the value to a number.
13};
14const body = {
15  name: z.string(),
16  email: z.string().email(),
17};
18 
19// Use the validate middleware in your route
20app.post('/user/:userId', validate({ params, query, body }), (req, res) => {
21  // Your route logic here
22  res.send('User data is valid!');
23});
24
25app.listen(3000, () => console.log('Server running on port 3000'));

Note: The validate middleware must be used after any other middleware that parses/modifies the request body, such as express.json() or express.urlencoded().

📦 Custom Error Handling

By default, the validate middleware will send a 400 Bad Request response with a JSON body containing the error message. However, you can provide your own error handling function to customise the error response.

1// ... extending the previous example
2
3const handler = (errors, req, res, next) => {
4  res.status(400).json({
5    message: 'Invalid request data',
6    errors: errors.map((error) => error.message),
7  });
8};
9
10// Use the validate middleware in your route
11app.post('/user/:userId', validate({ handler, params, query, body }), (req, res) => {
12  // Your route logic here
13  res.send('User data is valid!');
14});

⚠️ Usage with Additional Middleware

When using express-zod-safe with other middleware, it is important not to explicitly type the Request parameter in the middleware, as this will override the inferred type that express-zod-safe generates from your validation schemas. The best way to do this is to instead type your other middleware (or cast them) to WeakRequestHandler, a weakly typed version of the RequestHandler type from express.

1import validate, { type WeakRequestHandler } from 'express-zod-safe';
2
3// Use the RequestHandler type, instead of explicitly typing (req: Request, res: Response, next: NextFunction)
4const authenticate: WeakRequestHandler = (req, res, next) => {
5  // ... perform user authentication
6
7  next();
8};
9
10app.post('/user/:userId', authenticate, validate({ params, query, body }), (req, res) => {
11  // Your validation typing will work as expected here
12});
13

If you do not control the middleware, such as when you import it from another library, you can instead cast the middleware to WeakRequestHandler.

1// For one off cases...
2app.post('/user/:userId', authenticate as WeakRequestHandler, validate({ params, query, body }), (req, res) => {
3  // Your validation typing will work as expected here
4});
5
6// For a middleware with a lot of use, aliasing the middleware...
7const auth = authenticate as WeakRequestHandler;
8app.post('/user/:userId', auth, validate({ params, query, body }), (req, res) => {
9  // Your validation typing will work as expected here
10});

⚠️ URL Parameters & Query Strings Coercion

As mentioned in the example above, all URL parameters and query strings are parsed as strings. This means that if you have a URL parameter or query string that is expected to be a number, you must use the z.coerce.number() method to coerce the value to a number. This is because Zod will not coerce the value for you, and will instead throw an error if the value is not a string.

1const params = {
2  userId: z.coerce.number(),
3};
4
5app.get('/user/:userId', validate({ params }), (req, res) => {
6  // req.params.userId -> number
7});

⚠️ Missing Validation Schemas

If you do not provide a validation schema for a particular request component (e.g. params, query, or body), then that component will be assumed to be empty. This means that requests with non-empty components will be rejected, and requests with empty components will be accepted. The types on the req object will also reflect this, and will be an empty object {} if the component is not provided.

1const body = {
2  name: z.string(),
3  email: z.string().email(),
4};
5
6app.post('/user', validate({ body }), (req, res) => {
7  // req.body.name -> string
8  // req.body.email -> string
9  // req.params.age -> Property 'age' does not exist on type '{}'
10  // req.query.age -> Property 'age' does not exist on type '{}'
11});

This behaviour is intentional and ensures that you do not try to access or use a property that does not exist on the req object. If you'd prefer to allow any property for any given request component, you can do so by setting a loose validation schema with z.any().

1const body = {
2  name: z.string(),
3  email: z.string().email(),
4};
5
6const params = z.any()
7
8app.post('/user', validate({ body, params }), (req, res) => {
9  // req.body.name -> string
10  // req.body.email -> string
11  // req.params.age -> any
12  // req.query.age -> Property 'age' does not exist on type '{}'
13});

⭐️ Show your support

Give a ⭐️ on GitHub if this project helped you!

📝 License

Copyright © AngaBlue.
This project is MIT licensed.