express-zod-safe 1.3.3 → 1.5.0

package/README.md

@@ -15,7 +15,7 @@ _This package was inspired by Aquila169's [zod-express-middleware](https://githu
 ## 🔒 Features
 
  - **Typesafe**: Built with TypeScript, offering complete typesafe interfaces that enrich your development experience.
- - **Zod Integration**: Utilizes Zod schemas for comprehensive and customizable request validation.
+ - **Zod Integration**: Utilizes 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.
@@ -87,6 +87,40 @@ app.post('/user/:userId', validate({ handler, params, query, body }), (req, res)
 });
 ```
 
+### ⚠️ 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`.
+
+```ts
+import validate, { type WeakRequestHandler } from 'express-zod-safe';
+
+// Use the RequestHandler type, instead of explicitly typing (req: Request, res: Response, next: NextFunction)
+const authenticate: WeakRequestHandler = (req, res, next) => {
+  // ... perform user authentication
+
+  next();
+};
+
+app.post('/user/:userId', authenticate, validate({ params, query, body }), (req, res) => {
+  // Your validation typing will work as expected here
+});
+
+```
+
+If you do not control the middleware, such as when you import it from another library, you can instead cast the middleware to `WeakRequestHandler`.
+
+```ts
+// For one off cases...
+app.post('/user/:userId', authenticate as WeakRequestHandler, validate({ params, query, body }), (req, res) => {
+  // Your validation typing will work as expected here
+});
+
+// For a middleware with a lot of use, aliasing the middleware...
+const auth = authenticate as WeakRequestHandler;
+app.post('/user/:userId', auth, validate({ params, query, body }), (req, res) => {
+  // Your validation typing will work as expected here
+});
+```
+
 ### ⚠️ 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.
 
@@ -101,7 +135,7 @@ app.get('/user/:userId', validate({ params }), (req, res) => {
 ```
 
 ### ⚠️ 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 `undefined` if the component is not provided.
+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.
 
 ```ts
 const body = {
@@ -112,12 +146,28 @@ const body = {
 app.post('/user', validate({ body }), (req, res) => {
   // req.body.name -> string
   // req.body.email -> string
-  // req.params.age -> undefined
-  // req.query.age -> undefined
+  // req.params.age -> Property 'age' does not exist on type '{}'
+  // req.query.age -> Property 'age' does not exist on type '{}'
 });
 ```
 
-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.
+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()`.
+
+```ts
+const body = {
+  name: z.string(),
+  email: z.string().email(),
+};
+
+const params = z.any()
+
+app.post('/user', validate({ body, params }), (req, res) => {
+  // req.body.name -> string
+  // req.body.email -> string
+  // req.params.age -> any
+  // req.query.age -> Property 'age' does not exist on type '{}'
+});
+```
 
 ## ⭐️ Show your support
 

package/dist/{index.js → cjs/index.js}

@@ -1,7 +1,18 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validate;
 const express_1 = __importDefault(require("express"));
 const zod_1 = require("zod");
 const types = ['query', 'params', 'body'];
@@ -12,7 +23,7 @@ const emptyObjectSchema = zod_1.z.object({}).strict();
  * @returns Whether the provided schema is a ZodSchema.
  */
 function isZodSchema(schema) {
-    return !!schema && typeof schema.safeParse === 'function';
+    return !!schema && typeof schema.safeParseAsync === 'function';
 }
 // Override express@^5 request.query getter to provider setter
 const descriptor = Object.getOwnPropertyDescriptor(express_1.default.request, 'query');
@@ -77,12 +88,12 @@ function validate(schemas) {
         query: isZodSchema(schemas.query) ? schemas.query : zod_1.z.object((_b = schemas.query) !== null && _b !== void 0 ? _b : {}).strict(),
         body: isZodSchema(schemas.body) ? schemas.body : zod_1.z.object((_c = schemas.body) !== null && _c !== void 0 ? _c : {}).strict()
     };
-    return (req, res, next) => {
+    return (req, res, next) => __awaiter(this, void 0, void 0, function* () {
         var _a;
         const errors = [];
         // Validate all types (params, query, body)
         for (const type of types) {
-            const parsed = validation[type].safeParse((_a = req[type]) !== null && _a !== void 0 ? _a : {});
+            const parsed = yield validation[type].safeParseAsync((_a = req[type]) !== null && _a !== void 0 ? _a : {});
             if (parsed.success)
                 req[type] = parsed.data;
             else
@@ -97,6 +108,6 @@ function validate(schemas) {
             return;
         }
         return next();
-    };
+    });
 }
 module.exports = validate;

package/dist/{index.d.ts → esm/index.d.ts}

@@ -2,7 +2,7 @@ import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import { type ZodError, type ZodRawShape, type ZodTypeAny, z } from 'zod';
 declare const types: readonly ["query", "params", "body"];
 declare const emptyObjectSchema: z.ZodObject<{}, "strict", ZodTypeAny, {}, {}>;
-type Empty = typeof emptyObjectSchema;
+export type EmptyValidationSchema = typeof emptyObjectSchema;
 /**
  * Generates a middleware function for Express.js that validates request params, query, and body.
  * This function uses Zod schemas to perform validation against the provided schema definitions.
@@ -41,7 +41,7 @@ type Empty = typeof emptyObjectSchema;
  *
  * app.listen(3000, () => console.log('Server running on port 3000'));
  */
-declare function validate<TParams extends Validation = Empty, TQuery extends Validation = Empty, TBody extends Validation = Empty>(schemas: ExtendedValidationSchemas<TParams, TQuery, TBody>): RequestHandler<ZodOutput<TParams>, any, ZodOutput<TBody>, ZodOutput<TQuery>>;
+export default function validate<TParams extends ValidationSchema = EmptyValidationSchema, TQuery extends ValidationSchema = EmptyValidationSchema, TBody extends ValidationSchema = EmptyValidationSchema>(schemas: CompleteValidationSchema<TParams, TQuery, TBody>): RequestHandler<ZodOutput<TParams>, any, ZodOutput<TBody>, ZodOutput<TQuery>>;
 /**
  * Describes the types of data that can be validated: 'query', 'params', or 'body'.
  */
@@ -50,25 +50,19 @@ type DataType = (typeof types)[number];
  * Defines the structure of an error item, containing the type of validation that failed (params, query, or body)
  * and the associated ZodError.
  */
-interface ErrorListItem {
+export interface ErrorListItem {
     type: DataType;
     errors: ZodError;
 }
 /**
- * Represents a QueryString object parsed by the qs library.
+ * Represents an Express.js error request handler where the params, query and body are of unknown type as validation failed.
  */
-interface ParsedQs {
-    [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[];
-}
-/**
- * Represents an Express.js error request handler.
- */
-type ErrorRequestHandler<P = Record<string, string>, ResBody = any, ReqBody = any, ReqQuery = ParsedQs, LocalsObj extends Record<string, any> = Record<string, any>> = (err: ErrorListItem[], req: Request<P, ResBody, ReqBody, ReqQuery, LocalsObj>, res: Response<ResBody, LocalsObj>, next: NextFunction) => void | Promise<void>;
+export type ErrorRequestHandler<P = unknown, ResBody = any, ReqBody = unknown, ReqQuery = unknown, LocalsObj extends Record<string, any> = Record<string, any>> = (err: ErrorListItem[], req: Request<P, ResBody, ReqBody, ReqQuery, LocalsObj>, res: Response<ResBody, LocalsObj>, next: NextFunction) => void | Promise<void>;
 /**
  * Represents a generic type for route validation, which can be applied to params, query, or body.
  * Each key-value pair represents a field and its corresponding Zod validation schema.
  */
-type Validation = ZodTypeAny | ZodRawShape;
+export type ValidationSchema = ZodTypeAny | ZodRawShape;
 /**
  * Defines the structure for the schemas provided to the validate middleware.
  * Each property corresponds to a different part of the request (params, query, body)
@@ -78,7 +72,7 @@ type Validation = ZodTypeAny | ZodRawShape;
  * @template TQuery - Type definition for query schema.
  * @template TBody - Type definition for body schema.
  */
-interface ExtendedValidationSchemas<TParams, TQuery, TBody> {
+export interface CompleteValidationSchema<TParams extends ValidationSchema = EmptyValidationSchema, TQuery extends ValidationSchema = EmptyValidationSchema, TBody extends ValidationSchema = EmptyValidationSchema> {
     handler?: ErrorRequestHandler;
     params?: TParams;
     query?: TQuery;
@@ -91,5 +85,9 @@ interface ExtendedValidationSchemas<TParams, TQuery, TBody> {
  *
  * @template T - The validation type (params, query, or body).
  */
-type ZodOutput<T extends Validation> = T extends ZodRawShape ? z.ZodObject<T>['_output'] : T['_output'];
-export = validate;
+export type ZodOutput<T extends ValidationSchema> = T extends ZodRawShape ? z.ZodObject<T>['_output'] : T['_output'];
+/**
+ * A utility type to ensure other middleware types don't conflict with the validate middleware.
+ */
+export type WeakRequestHandler = RequestHandler<unknown, unknown, unknown, Record<string, unknown>>;
+export {};

package/dist/esm/index.js

@@ -0,0 +1,95 @@
+import express from 'express';
+import { z } from 'zod';
+const types = ['query', 'params', 'body'];
+const emptyObjectSchema = z.object({}).strict();
+/**
+ * A ZodSchema type guard.
+ * @param schema The Zod schema to check.
+ * @returns Whether the provided schema is a ZodSchema.
+ */
+function isZodSchema(schema) {
+    return !!schema && typeof schema.safeParseAsync === 'function';
+}
+// Override express@^5 request.query getter to provider setter
+const descriptor = Object.getOwnPropertyDescriptor(express.request, 'query');
+if (descriptor) {
+    Object.defineProperty(express.request, 'query', {
+        get() {
+            if (this._query)
+                return this._query;
+            return descriptor?.get?.call(this);
+        },
+        set(query) {
+            this._query = query;
+        },
+        configurable: true,
+        enumerable: true
+    });
+}
+/**
+ * Generates a middleware function for Express.js that validates request params, query, and body.
+ * This function uses Zod schemas to perform validation against the provided schema definitions.
+ *
+ * @param schemas - An object containing Zod schemas for params, query, and body.  Optional handler for custom error handling.
+ * @returns An Express.js middleware function that validates the request based on the provided schemas.
+ *          It attaches validated data to the request object and sends error details if validation fails.
+ * @template TParams - Type definition for params schema.
+ * @template TQuery - Type definition for query schema.
+ * @template TBody - Type definition for body schema.
+ * @example
+ * // Example usage in an Express.js route
+ * import express from 'express';
+ * import validate from 'express-zod-safe';
+ * import { z } from 'zod';
+ *
+ * const app = express();
+ *
+ * // Define your Zod schemas
+ * const params = {
+ *   userId: z.string().uuid(),
+ * };
+ * const query = {
+ *   age: z.coerce.number().optional(),
+ * };
+ * const body = {
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * };
+ *
+ * // Use the validate middleware in your route
+ * app.post('/user/:userId', validate({ params, query, body }), (req, res) => {
+ *   // Your route logic here
+ *   res.send('User data is valid!');
+ * });
+ *
+ * app.listen(3000, () => console.log('Server running on port 3000'));
+ */
+export default function validate(schemas) {
+    // Create validation objects for each type
+    const validation = {
+        params: isZodSchema(schemas.params) ? schemas.params : z.object(schemas.params ?? {}).strict(),
+        query: isZodSchema(schemas.query) ? schemas.query : z.object(schemas.query ?? {}).strict(),
+        body: isZodSchema(schemas.body) ? schemas.body : z.object(schemas.body ?? {}).strict()
+    };
+    return async (req, res, next) => {
+        const errors = [];
+        // Validate all types (params, query, body)
+        for (const type of types) {
+            const parsed = await validation[type].safeParseAsync(req[type] ?? {});
+            if (parsed.success)
+                req[type] = parsed.data;
+            else
+                errors.push({ type, errors: parsed.error });
+        }
+        // Return all errors if there are any
+        if (errors.length > 0) {
+            // If a custom error handler is provided, use it
+            if (schemas.handler)
+                return schemas.handler(errors, req, res, next);
+            res.status(400).send(errors.map(error => ({ type: error.type, errors: error.errors })));
+            return;
+        }
+        return next();
+    };
+}
+module.exports = validate;

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "express-zod-safe",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "description": "TypeScript-friendly middleware designed for Express applications, leveraging the robustness of Zod schemas to validate incoming request bodies, parameters, and queries.",
-  "main": "dist/index.js",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AngaBlue/express-zod-safe.git"
@@ -36,7 +38,7 @@
   },
   "scripts": {
     "clean": "rimraf dist",
-    "build": "pnpm run clean && tsc",
-    "lint": "biome check --fix --error-on-warnings"
+    "build": "pnpm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",
+    "lint": "biome check --fix"
   }
 }