express-zod-safe 1.4.0 → 1.5.1

package/LICENSE

@@ -1,165 +1,21 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+MIT License
+
+Copyright (c) 2025 AngaBlue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,13 @@
 <h1 align="center">🛡️ Express Zod Safe</h1>
 <p align="center">
-    <a href="https://www.npmjs.com/package/express-zod-safe" target="_blank">
-  <img alt="GitHub tag (latest by date)" src="https://img.shields.io/github/v/tag/AngaBlue/express-zod-safe?label=Version">
+  <a href="https://www.npmjs.com/package/express-zod-safe" target="_blank">
+    <img alt="Downloads" src="https://img.shields.io/npm/dm/express-zod-safe.svg?color=blue&?label=Downloads">
   </a>
-  <a href="https://github.com/AngaBlue/express-zod-safe/blob/master/LICENSE" target="_blank">
-    <img alt="License: LGPL--3.0--or--later" src="https://img.shields.io/github/license/AngaBlue/express-zod-safe?color=green" />
+  <a href="https://www.npmjs.com/package/express-zod-safe" target="_blank">
+    <img alt="Version" src="https://img.shields.io/npm/v/express-zod-safe.svg?label=Version">
+  </a>
+  <a href="https://github.com/AngaBlue/exe/blob/master/LICENSE" target="_blank">
+    <img alt="License: MIT" src="https://img.shields.io/npm/l/express-zod-safe?color=green?label=Licence" />
   </a>
 </p>
 
@@ -15,7 +18,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**: 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.
@@ -68,7 +71,7 @@ app.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 customize the error response.
+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.
 
 ```ts
 // ... extending the previous example
@@ -87,6 +90,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 +138,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 +149,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
 
@@ -126,4 +179,4 @@ Give a ⭐️ on GitHub if this project helped you!
 ## 📝 License
 
 Copyright © [AngaBlue](https://github.com/AngaBlue).<br />
-This project is [LGPL--3.0--or--later](https://github.com/AngaBlue/express-zod-safe/blob/master/LICENSE) licensed.
+This project is [MIT](https://github.com/AngaBlue/express-zod-safe/blob/master/LICENSE) licensed.

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

@@ -11,6 +11,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 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'];

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.4.0",
+  "version": "1.5.1",
   "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"
@@ -15,8 +17,12 @@
     "guard",
     "typesafe"
   ],
-  "author": "AngaBlue <contact@anga.blue>",
-  "license": "LGPL-3.0-or-later",
+  "author": {
+    "name": "AngaBlue",
+    "email": "contact@anga.blue",
+    "url": "https://anga.blue"
+  },
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/AngaBlue/express-zod-safe/issues"
   },
@@ -36,7 +42,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"
   }
 }