express-zod-routes 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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

@@ -0,0 +1,126 @@
+# express-zod-routes
+
+[![CI](https://github.com/adriangrahldev/express-zod-routes/actions/workflows/ci.yml/badge.svg)](https://github.com/adriangrahldev/express-zod-routes/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/express-zod-routes.svg)](https://www.npmjs.com/package/express-zod-routes)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Express middleware** that validates `body`, `query`, and `params` with **[Zod](https://zod.dev)**. On success, parsed values land on **`req.validated`**. On failure, the client gets a **consistent JSON 400** (or your chosen status) without calling `next`.
+
+Built for **MERN / TypeScript** stacks: one source of truth for validation, no duplicate DTO logic.
+
+## Install
+
+```bash
+npm install express-zod-routes
+```
+
+Peer dependencies:
+
+- `express` `^4.18.0 || ^5.0.0`
+- `zod` `^3.22.0`
+
+## Quick start
+
+```ts
+import express from 'express';
+import { z } from 'zod';
+import { validate } from 'express-zod-routes';
+
+const app = express();
+app.use(express.json());
+
+app.post(
+  '/users',
+  validate({
+    body: z.object({
+      name: z.string().min(1),
+      email: z.string().email(),
+    }),
+  }),
+  (req, res) => {
+    // req.validated.body is parsed & typed with InferValidated (see below)
+    res.status(201).json(req.validated!.body);
+  }
+);
+```
+
+## API
+
+### `validate(schemas)` · `createValidator(schemas)`
+
+Same function; `createValidator` is an alias.
+
+| Option         | Type      | Description                                       |
+| -------------- | --------- | ------------------------------------------------- |
+| `body`         | `ZodType` | Validates `req.body` (use after `express.json()`) |
+| `query`        | `ZodType` | Validates `req.query` (strings → use `z.coerce`)  |
+| `params`       | `ZodType` | Validates `req.params`                            |
+| `statusCode`   | `number`  | Default `400`                                     |
+| `errorMessage` | `string`  | Default `"Validation failed"`                     |
+
+At least one of `body`, `query`, or `params` is required.
+
+### `req.validated`
+
+After the middleware runs successfully, `req.validated` contains only the keys you validated (merged if you stack multiple validators on the same route — usually one per route is enough).
+
+Importing the package augments Express’s `Request` so `validated` is recognized by TypeScript.
+
+### Typing handlers with `InferValidated`
+
+```ts
+import type { Request } from 'express';
+import { validate, type InferValidated } from 'express-zod-routes';
+
+const schemas = {
+  body: z.object({ email: z.string().email() }),
+} as const;
+
+app.post(
+  '/',
+  validate(schemas),
+  (req: Request & { validated: InferValidated<typeof schemas> }, res) => {
+    req.validated.body.email;
+    res.sendStatus(204);
+  }
+);
+```
+
+### Error response shape
+
+```json
+{
+  "error": "Validation failed",
+  "issues": [{ "path": "email", "message": "Invalid email", "code": "invalid_string" }]
+}
+```
+
+### `mapZodErrorToResponse(err, message?)`
+
+Use in your own error middleware if you reuse the same JSON shape.
+
+## Query & params tips
+
+- **Query** values are strings (or arrays) from Express. Use `z.coerce.number()`, `z.enum()`, etc.
+- **Params** are strings; use `z.string().uuid()`, regex, or transforms as needed.
+
+## Comparison
+
+| Approach              | express-zod-routes       |
+| --------------------- | ------------------------ |
+| Manual `if` + res 400 | Centralized Zod + format |
+| Only body validation  | body + query + params    |
+
+Other great options exist (`express-zod-api`, custom Zod wrappers). This package stays small: one middleware, `req.validated`, stable errors.
+
+## Example project
+
+See [`examples/basic-express`](examples/basic-express).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT © see [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,75 @@
+'use strict';
+
+// src/constants.ts
+var DEFAULT_VALIDATION_ERROR_MESSAGE = "Validation failed";
+var DEFAULT_VALIDATION_STATUS = 400;
+
+// src/middleware/error-mapper.ts
+function issuePath(issue) {
+  return issue.path.map(String).join(".") || "(root)";
+}
+function mapZodErrorToResponse(err, message = DEFAULT_VALIDATION_ERROR_MESSAGE) {
+  return {
+    error: message,
+    issues: err.issues.map((issue) => ({
+      path: issuePath(issue),
+      message: issue.message,
+      code: issue.code
+    }))
+  };
+}
+
+// src/middleware/validate.ts
+function parseSegment(schema, raw, errorMessage, statusCode, res) {
+  const result = schema.safeParse(raw);
+  if (result.success) {
+    return { ok: true, data: result.data };
+  }
+  res.status(statusCode).json(mapZodErrorToResponse(result.error, errorMessage));
+  return { ok: false };
+}
+function validate(schemas) {
+  const keys = ["body", "query", "params"];
+  const hasAny = keys.some((k) => schemas[k] !== void 0);
+  if (!hasAny) {
+    throw new Error(
+      "express-zod-routes: validate() requires at least one of body, query, or params"
+    );
+  }
+  const statusCode = schemas.statusCode ?? DEFAULT_VALIDATION_STATUS;
+  const errorMessage = schemas.errorMessage ?? DEFAULT_VALIDATION_ERROR_MESSAGE;
+  return (req, res, next) => {
+    try {
+      const prev = req.validated ?? {};
+      const nextValidated = { ...prev };
+      if (schemas.body) {
+        const out = parseSegment(schemas.body, req.body, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.body = out.data;
+      }
+      if (schemas.query) {
+        const out = parseSegment(schemas.query, req.query, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.query = out.data;
+      }
+      if (schemas.params) {
+        const out = parseSegment(schemas.params, req.params, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.params = out.data;
+      }
+      req.validated = nextValidated;
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+var createValidator = validate;
+
+exports.DEFAULT_VALIDATION_ERROR_MESSAGE = DEFAULT_VALIDATION_ERROR_MESSAGE;
+exports.DEFAULT_VALIDATION_STATUS = DEFAULT_VALIDATION_STATUS;
+exports.createValidator = createValidator;
+exports.mapZodErrorToResponse = mapZodErrorToResponse;
+exports.validate = validate;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/middleware/error-mapper.ts","../src/middleware/validate.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/** Default message for validation error responses */\nexport const DEFAULT_VALIDATION_ERROR_MESSAGE = 'Validation failed' as const;\n\n/** Default HTTP status when validation fails */\nexport const DEFAULT_VALIDATION_STATUS = 400 as const;\n","import type { ZodError, ZodIssue } from 'zod';\nimport { DEFAULT_VALIDATION_ERROR_MESSAGE } from '../constants.js';\n\n/** One validation issue in the API response */\nexport interface ValidationIssue {\n  /** Dot-separated path (e.g. `user.email`) */\n  path: string;\n  message: string;\n  code: ZodIssue['code'];\n}\n\n/** Stable JSON body for HTTP 400 validation errors */\nexport interface ValidationErrorBody {\n  error: string;\n  issues: ValidationIssue[];\n}\n\nfunction issuePath(issue: ZodIssue): string {\n  return issue.path.map(String).join('.') || '(root)';\n}\n\n/**\n * Maps a Zod error to the package’s standard error payload (for custom error middleware).\n */\nexport function mapZodErrorToResponse(\n  err: ZodError,\n  message: string = DEFAULT_VALIDATION_ERROR_MESSAGE\n): ValidationErrorBody {\n  return {\n    error: message,\n    issues: err.issues.map((issue) => ({\n      path: issuePath(issue),\n      message: issue.message,\n      code: issue.code,\n    })),\n  };\n}\n","import type { NextFunction, Request, RequestHandler, Response } from 'express';\nimport type { ZodTypeAny } from 'zod';\nimport { DEFAULT_VALIDATION_ERROR_MESSAGE, DEFAULT_VALIDATION_STATUS } from '../constants.js';\nimport type { ValidationSchemas } from '../types/schemas.js';\nimport { mapZodErrorToResponse } from './error-mapper.js';\n\nexport interface ValidateOptions extends ValidationSchemas {\n  /** HTTP status when validation fails (default: 400) */\n  statusCode?: number;\n  /** Override default error message in JSON body */\n  errorMessage?: string;\n}\n\nfunction parseSegment(\n  schema: ZodTypeAny,\n  raw: unknown,\n  errorMessage: string,\n  statusCode: number,\n  res: Response\n): { ok: true; data: unknown } | { ok: false } {\n  const result = schema.safeParse(raw);\n  if (result.success) {\n    return { ok: true, data: result.data };\n  }\n  res.status(statusCode).json(mapZodErrorToResponse(result.error, errorMessage));\n  return { ok: false };\n}\n\n/**\n * Express middleware: validates `body`, `query`, and/or `params` with Zod.\n * On success, merges results into `req.validated`. On failure, sends JSON 400 and does not call `next`.\n *\n * @example\n * ```ts\n * app.post(\n *   '/users',\n *   express.json(),\n *   validate({ body: z.object({ name: z.string().min(1) }) }),\n *   (req, res) => res.json(req.validated!.body)\n * );\n * ```\n */\nexport function validate(schemas: ValidateOptions): RequestHandler {\n  const keys = ['body', 'query', 'params'] as const;\n  const hasAny = keys.some((k) => schemas[k] !== undefined);\n  if (!hasAny) {\n    throw new Error(\n      'express-zod-routes: validate() requires at least one of body, query, or params'\n    );\n  }\n\n  const statusCode = schemas.statusCode ?? DEFAULT_VALIDATION_STATUS;\n  const errorMessage = schemas.errorMessage ?? DEFAULT_VALIDATION_ERROR_MESSAGE;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    try {\n      const prev = req.validated ?? {};\n      const nextValidated: NonNullable<Request['validated']> = { ...prev };\n\n      if (schemas.body) {\n        const out = parseSegment(schemas.body, req.body, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.body = out.data;\n      }\n      if (schemas.query) {\n        const out = parseSegment(schemas.query, req.query, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.query = out.data;\n      }\n      if (schemas.params) {\n        const out = parseSegment(schemas.params, req.params, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.params = out.data;\n      }\n\n      req.validated = nextValidated;\n      next();\n    } catch (e) {\n      next(e);\n    }\n  };\n}\n\n/** Alias for {@link validate} */\nexport const createValidator = validate;\n"]}

package/dist/index.d.cts

@@ -0,0 +1,99 @@
+import { RequestHandler } from 'express';
+import { z, ZodIssue, ZodError } from 'zod';
+
+/**
+ * Augments Express `Request` with `validated` when you import `express-zod-routes`.
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * Parsed values after {@link validate}. Only keys you passed schemas for are set.
+             */
+            validated?: {
+                body?: unknown;
+                query?: unknown;
+                params?: unknown;
+            };
+        }
+    }
+}
+
+/** Schemas you can pass to {@link validate} */
+interface ValidationSchemas {
+    body?: z.ZodTypeAny;
+    query?: z.ZodTypeAny;
+    params?: z.ZodTypeAny;
+}
+type Empty = Record<never, never>;
+/**
+ * Shape of `req.validated` inferred from the schemas passed to {@link validate}.
+ *
+ * @example
+ * ```ts
+ * const schemas = { body: z.object({ email: z.string().email() }) };
+ * app.post(
+ *   '/',
+ *   validate(schemas),
+ *   (req: Request & { validated: InferValidated<typeof schemas> }, res) => {
+ *     req.validated.body.email;
+ *   }
+ * );
+ * ```
+ */
+type InferValidated<S extends ValidationSchemas> = (S['body'] extends z.ZodTypeAny ? {
+    body: z.infer<NonNullable<S['body']>>;
+} : Empty) & (S['query'] extends z.ZodTypeAny ? {
+    query: z.infer<NonNullable<S['query']>>;
+} : Empty) & (S['params'] extends z.ZodTypeAny ? {
+    params: z.infer<NonNullable<S['params']>>;
+} : Empty);
+
+interface ValidateOptions extends ValidationSchemas {
+    /** HTTP status when validation fails (default: 400) */
+    statusCode?: number;
+    /** Override default error message in JSON body */
+    errorMessage?: string;
+}
+/**
+ * Express middleware: validates `body`, `query`, and/or `params` with Zod.
+ * On success, merges results into `req.validated`. On failure, sends JSON 400 and does not call `next`.
+ *
+ * @example
+ * ```ts
+ * app.post(
+ *   '/users',
+ *   express.json(),
+ *   validate({ body: z.object({ name: z.string().min(1) }) }),
+ *   (req, res) => res.json(req.validated!.body)
+ * );
+ * ```
+ */
+declare function validate(schemas: ValidateOptions): RequestHandler;
+/** Alias for {@link validate} */
+declare const createValidator: typeof validate;
+
+/** One validation issue in the API response */
+interface ValidationIssue {
+    /** Dot-separated path (e.g. `user.email`) */
+    path: string;
+    message: string;
+    code: ZodIssue['code'];
+}
+/** Stable JSON body for HTTP 400 validation errors */
+interface ValidationErrorBody {
+    error: string;
+    issues: ValidationIssue[];
+}
+/**
+ * Maps a Zod error to the package’s standard error payload (for custom error middleware).
+ */
+declare function mapZodErrorToResponse(err: ZodError, message?: string): ValidationErrorBody;
+
+/** Default message for validation error responses */
+declare const DEFAULT_VALIDATION_ERROR_MESSAGE: "Validation failed";
+/** Default HTTP status when validation fails */
+declare const DEFAULT_VALIDATION_STATUS: 400;
+
+export { DEFAULT_VALIDATION_ERROR_MESSAGE, DEFAULT_VALIDATION_STATUS, type InferValidated, type ValidateOptions, type ValidationErrorBody, type ValidationIssue, type ValidationSchemas, createValidator, mapZodErrorToResponse, validate };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { RequestHandler } from 'express';
+import { z, ZodIssue, ZodError } from 'zod';
+
+/**
+ * Augments Express `Request` with `validated` when you import `express-zod-routes`.
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * Parsed values after {@link validate}. Only keys you passed schemas for are set.
+             */
+            validated?: {
+                body?: unknown;
+                query?: unknown;
+                params?: unknown;
+            };
+        }
+    }
+}
+
+/** Schemas you can pass to {@link validate} */
+interface ValidationSchemas {
+    body?: z.ZodTypeAny;
+    query?: z.ZodTypeAny;
+    params?: z.ZodTypeAny;
+}
+type Empty = Record<never, never>;
+/**
+ * Shape of `req.validated` inferred from the schemas passed to {@link validate}.
+ *
+ * @example
+ * ```ts
+ * const schemas = { body: z.object({ email: z.string().email() }) };
+ * app.post(
+ *   '/',
+ *   validate(schemas),
+ *   (req: Request & { validated: InferValidated<typeof schemas> }, res) => {
+ *     req.validated.body.email;
+ *   }
+ * );
+ * ```
+ */
+type InferValidated<S extends ValidationSchemas> = (S['body'] extends z.ZodTypeAny ? {
+    body: z.infer<NonNullable<S['body']>>;
+} : Empty) & (S['query'] extends z.ZodTypeAny ? {
+    query: z.infer<NonNullable<S['query']>>;
+} : Empty) & (S['params'] extends z.ZodTypeAny ? {
+    params: z.infer<NonNullable<S['params']>>;
+} : Empty);
+
+interface ValidateOptions extends ValidationSchemas {
+    /** HTTP status when validation fails (default: 400) */
+    statusCode?: number;
+    /** Override default error message in JSON body */
+    errorMessage?: string;
+}
+/**
+ * Express middleware: validates `body`, `query`, and/or `params` with Zod.
+ * On success, merges results into `req.validated`. On failure, sends JSON 400 and does not call `next`.
+ *
+ * @example
+ * ```ts
+ * app.post(
+ *   '/users',
+ *   express.json(),
+ *   validate({ body: z.object({ name: z.string().min(1) }) }),
+ *   (req, res) => res.json(req.validated!.body)
+ * );
+ * ```
+ */
+declare function validate(schemas: ValidateOptions): RequestHandler;
+/** Alias for {@link validate} */
+declare const createValidator: typeof validate;
+
+/** One validation issue in the API response */
+interface ValidationIssue {
+    /** Dot-separated path (e.g. `user.email`) */
+    path: string;
+    message: string;
+    code: ZodIssue['code'];
+}
+/** Stable JSON body for HTTP 400 validation errors */
+interface ValidationErrorBody {
+    error: string;
+    issues: ValidationIssue[];
+}
+/**
+ * Maps a Zod error to the package’s standard error payload (for custom error middleware).
+ */
+declare function mapZodErrorToResponse(err: ZodError, message?: string): ValidationErrorBody;
+
+/** Default message for validation error responses */
+declare const DEFAULT_VALIDATION_ERROR_MESSAGE: "Validation failed";
+/** Default HTTP status when validation fails */
+declare const DEFAULT_VALIDATION_STATUS: 400;
+
+export { DEFAULT_VALIDATION_ERROR_MESSAGE, DEFAULT_VALIDATION_STATUS, type InferValidated, type ValidateOptions, type ValidationErrorBody, type ValidationIssue, type ValidationSchemas, createValidator, mapZodErrorToResponse, validate };

package/dist/index.js

@@ -0,0 +1,69 @@
+// src/constants.ts
+var DEFAULT_VALIDATION_ERROR_MESSAGE = "Validation failed";
+var DEFAULT_VALIDATION_STATUS = 400;
+
+// src/middleware/error-mapper.ts
+function issuePath(issue) {
+  return issue.path.map(String).join(".") || "(root)";
+}
+function mapZodErrorToResponse(err, message = DEFAULT_VALIDATION_ERROR_MESSAGE) {
+  return {
+    error: message,
+    issues: err.issues.map((issue) => ({
+      path: issuePath(issue),
+      message: issue.message,
+      code: issue.code
+    }))
+  };
+}
+
+// src/middleware/validate.ts
+function parseSegment(schema, raw, errorMessage, statusCode, res) {
+  const result = schema.safeParse(raw);
+  if (result.success) {
+    return { ok: true, data: result.data };
+  }
+  res.status(statusCode).json(mapZodErrorToResponse(result.error, errorMessage));
+  return { ok: false };
+}
+function validate(schemas) {
+  const keys = ["body", "query", "params"];
+  const hasAny = keys.some((k) => schemas[k] !== void 0);
+  if (!hasAny) {
+    throw new Error(
+      "express-zod-routes: validate() requires at least one of body, query, or params"
+    );
+  }
+  const statusCode = schemas.statusCode ?? DEFAULT_VALIDATION_STATUS;
+  const errorMessage = schemas.errorMessage ?? DEFAULT_VALIDATION_ERROR_MESSAGE;
+  return (req, res, next) => {
+    try {
+      const prev = req.validated ?? {};
+      const nextValidated = { ...prev };
+      if (schemas.body) {
+        const out = parseSegment(schemas.body, req.body, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.body = out.data;
+      }
+      if (schemas.query) {
+        const out = parseSegment(schemas.query, req.query, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.query = out.data;
+      }
+      if (schemas.params) {
+        const out = parseSegment(schemas.params, req.params, errorMessage, statusCode, res);
+        if (!out.ok) return;
+        nextValidated.params = out.data;
+      }
+      req.validated = nextValidated;
+      next();
+    } catch (e) {
+      next(e);
+    }
+  };
+}
+var createValidator = validate;
+
+export { DEFAULT_VALIDATION_ERROR_MESSAGE, DEFAULT_VALIDATION_STATUS, createValidator, mapZodErrorToResponse, validate };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/middleware/error-mapper.ts","../src/middleware/validate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** Default message for validation error responses */\nexport const DEFAULT_VALIDATION_ERROR_MESSAGE = 'Validation failed' as const;\n\n/** Default HTTP status when validation fails */\nexport const DEFAULT_VALIDATION_STATUS = 400 as const;\n","import type { ZodError, ZodIssue } from 'zod';\nimport { DEFAULT_VALIDATION_ERROR_MESSAGE } from '../constants.js';\n\n/** One validation issue in the API response */\nexport interface ValidationIssue {\n  /** Dot-separated path (e.g. `user.email`) */\n  path: string;\n  message: string;\n  code: ZodIssue['code'];\n}\n\n/** Stable JSON body for HTTP 400 validation errors */\nexport interface ValidationErrorBody {\n  error: string;\n  issues: ValidationIssue[];\n}\n\nfunction issuePath(issue: ZodIssue): string {\n  return issue.path.map(String).join('.') || '(root)';\n}\n\n/**\n * Maps a Zod error to the package’s standard error payload (for custom error middleware).\n */\nexport function mapZodErrorToResponse(\n  err: ZodError,\n  message: string = DEFAULT_VALIDATION_ERROR_MESSAGE\n): ValidationErrorBody {\n  return {\n    error: message,\n    issues: err.issues.map((issue) => ({\n      path: issuePath(issue),\n      message: issue.message,\n      code: issue.code,\n    })),\n  };\n}\n","import type { NextFunction, Request, RequestHandler, Response } from 'express';\nimport type { ZodTypeAny } from 'zod';\nimport { DEFAULT_VALIDATION_ERROR_MESSAGE, DEFAULT_VALIDATION_STATUS } from '../constants.js';\nimport type { ValidationSchemas } from '../types/schemas.js';\nimport { mapZodErrorToResponse } from './error-mapper.js';\n\nexport interface ValidateOptions extends ValidationSchemas {\n  /** HTTP status when validation fails (default: 400) */\n  statusCode?: number;\n  /** Override default error message in JSON body */\n  errorMessage?: string;\n}\n\nfunction parseSegment(\n  schema: ZodTypeAny,\n  raw: unknown,\n  errorMessage: string,\n  statusCode: number,\n  res: Response\n): { ok: true; data: unknown } | { ok: false } {\n  const result = schema.safeParse(raw);\n  if (result.success) {\n    return { ok: true, data: result.data };\n  }\n  res.status(statusCode).json(mapZodErrorToResponse(result.error, errorMessage));\n  return { ok: false };\n}\n\n/**\n * Express middleware: validates `body`, `query`, and/or `params` with Zod.\n * On success, merges results into `req.validated`. On failure, sends JSON 400 and does not call `next`.\n *\n * @example\n * ```ts\n * app.post(\n *   '/users',\n *   express.json(),\n *   validate({ body: z.object({ name: z.string().min(1) }) }),\n *   (req, res) => res.json(req.validated!.body)\n * );\n * ```\n */\nexport function validate(schemas: ValidateOptions): RequestHandler {\n  const keys = ['body', 'query', 'params'] as const;\n  const hasAny = keys.some((k) => schemas[k] !== undefined);\n  if (!hasAny) {\n    throw new Error(\n      'express-zod-routes: validate() requires at least one of body, query, or params'\n    );\n  }\n\n  const statusCode = schemas.statusCode ?? DEFAULT_VALIDATION_STATUS;\n  const errorMessage = schemas.errorMessage ?? DEFAULT_VALIDATION_ERROR_MESSAGE;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    try {\n      const prev = req.validated ?? {};\n      const nextValidated: NonNullable<Request['validated']> = { ...prev };\n\n      if (schemas.body) {\n        const out = parseSegment(schemas.body, req.body, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.body = out.data;\n      }\n      if (schemas.query) {\n        const out = parseSegment(schemas.query, req.query, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.query = out.data;\n      }\n      if (schemas.params) {\n        const out = parseSegment(schemas.params, req.params, errorMessage, statusCode, res);\n        if (!out.ok) return;\n        nextValidated.params = out.data;\n      }\n\n      req.validated = nextValidated;\n      next();\n    } catch (e) {\n      next(e);\n    }\n  };\n}\n\n/** Alias for {@link validate} */\nexport const createValidator = validate;\n"]}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "express-zod-routes",
+  "version": "1.0.0",
+  "description": "Express middleware to validate body, query, and params with Zod — typed req.validated and consistent 400 errors",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./src/global-augment.ts"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "express",
+    "zod",
+    "validation",
+    "middleware",
+    "typescript",
+    "mern"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:adriangrahldev/express-zod-routes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adriangrahldev/express-zod-routes/issues"
+  },
+  "homepage": "https://github.com/adriangrahldev/express-zod-routes#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@types/supertest": "^6.0.2",
+    "@eslint/js": "^9.16.0",
+    "eslint": "^9.16.0",
+    "express": "^4.21.0",
+    "prettier": "^3.4.2",
+    "supertest": "^7.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.1"
+  }
+}