zod-nest 3.0.2 → 3.2.0

package/dist/param-decorators-CX1cUqfY.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { Z as ZodNestRegistry } from './registry-C9xStKa6.js';
+import * as _nestjs_common from '@nestjs/common';
+
+/**
+ * Where the multipart parser puts uploaded files. Multer leaves them on the
+ * request (`req.file` / `req.files`) with only text fields in `req.body`;
+ * `@fastify/multipart` with `attachFieldsToBody: true` puts everything in
+ * `req.body`.
+ */
+declare const MultipartFilesIn: {
+    readonly Request: "request";
+    readonly Body: "body";
+};
+type MultipartFilesIn = (typeof MultipartFilesIn)[keyof typeof MultipartFilesIn];
+/** Shape accepted by `@ZodMultipart` — one Zod schema per form field. */
+type MultipartShape = Readonly<Record<string, z.ZodType>>;
+
+declare const MULTIPART_CONTENT_TYPE = "multipart/form-data";
+/**
+ * Body declaration accepted by `@ZodMultipart`: a flat shape record, or any
+ * Zod schema. A record is the common case; a schema covers named bodies
+ * (`.meta({ id })` → `$ref`) and composites an object literal can't express.
+ */
+type MultipartBody = MultipartShape | z.ZodType;
+interface ZodMultipartOptions {
+    /**
+     * Where the parser puts uploaded files. Defaults to the platform entry
+     * point's convention — `'request'` from `zod-nest/express`, `'body'` from
+     * `zod-nest/fastify`.
+     */
+    readonly filesIn?: MultipartFilesIn;
+    /**
+     * Forces this id, overriding any `.meta({ id })` on the schema. A named body
+     * is emitted as a `$ref` to `components.schemas`, which keeps a stable name
+     * for client generators — at the cost of Swagger UI's `try-it-out` form,
+     * which doesn't follow `$ref` for `multipart/form-data`.
+     */
+    readonly id?: string;
+    /**
+     * Merge an intersection / union of `z.object` arms into one flat inline
+     * object. Needed for composite bodies whose `try-it-out` form must render.
+     * All merged properties become optional. See `@ZodBody`'s `flatten`.
+     */
+    readonly flatten?: boolean;
+    /** Registry to register named descendants into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+    /** OpenAPI `description` for the request body. */
+    readonly description?: string;
+    /** Whether the body is required. Defaults to `true`. */
+    readonly required?: boolean;
+}
+
+interface BaseFileOptions {
+    /**
+     * Registry id for the schema. Set it to get a reusable
+     * `components.schemas` entry that every field `$ref`s, instead of the
+     * fragment being inlined at each use site. There is no `title` counterpart
+     * — `overrideJSONSchema` replaces the emitted body and does not carry
+     * `title` into it, so one would have no effect.
+     */
+    readonly id?: string;
+    /** Allowed MIME types, matched case-insensitively against the client-supplied value. */
+    readonly mimeTypes?: readonly string[];
+    /** Allowed filename extensions, with or without a leading dot. */
+    readonly extensions?: readonly string[];
+    /** OpenAPI `description` for the emitted binary property. */
+    readonly description?: string;
+    /** Overrides the `contentMediaType` derived from a single-entry `mimeTypes`. */
+    readonly contentMediaType?: string;
+}
+
+/**
+ * Validates `req.file` against the named property of the `@ZodMultipart`
+ * shape. The name selects a schema; it never searches the request. Match it
+ * to your `FileInterceptor('<name>')` field name, as with plain Nest.
+ */
+declare const ZodUploadedFile: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>>)[]) => ParameterDecorator;
+/**
+ * Validates `req.files` against the named property of the `@ZodMultipart`
+ * shape, or against an object of every declared file property when called
+ * with no name — the record shape `FileFieldsInterceptor` produces.
+ */
+declare const ZodUploadedFiles: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/**
+ * Validates `req.body` against the `@ZodMultipart` shape — the text fields
+ * only under `filesIn: 'request'` (multer keeps files off the body), the
+ * whole shape under `filesIn: 'body'`.
+ */
+declare const ZodMultipartBody: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+export { type BaseFileOptions as B, MULTIPART_CONTENT_TYPE as M, ZodMultipartBody as Z, type MultipartBody as a, type MultipartShape as b, type ZodMultipartOptions as c, ZodUploadedFile as d, ZodUploadedFiles as e };

package/dist/param-decorators-DbgygRVn.d.mts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { Z as ZodNestRegistry } from './registry-C9xStKa6.mjs';
+import * as _nestjs_common from '@nestjs/common';
+
+/**
+ * Where the multipart parser puts uploaded files. Multer leaves them on the
+ * request (`req.file` / `req.files`) with only text fields in `req.body`;
+ * `@fastify/multipart` with `attachFieldsToBody: true` puts everything in
+ * `req.body`.
+ */
+declare const MultipartFilesIn: {
+    readonly Request: "request";
+    readonly Body: "body";
+};
+type MultipartFilesIn = (typeof MultipartFilesIn)[keyof typeof MultipartFilesIn];
+/** Shape accepted by `@ZodMultipart` — one Zod schema per form field. */
+type MultipartShape = Readonly<Record<string, z.ZodType>>;
+
+declare const MULTIPART_CONTENT_TYPE = "multipart/form-data";
+/**
+ * Body declaration accepted by `@ZodMultipart`: a flat shape record, or any
+ * Zod schema. A record is the common case; a schema covers named bodies
+ * (`.meta({ id })` → `$ref`) and composites an object literal can't express.
+ */
+type MultipartBody = MultipartShape | z.ZodType;
+interface ZodMultipartOptions {
+    /**
+     * Where the parser puts uploaded files. Defaults to the platform entry
+     * point's convention — `'request'` from `zod-nest/express`, `'body'` from
+     * `zod-nest/fastify`.
+     */
+    readonly filesIn?: MultipartFilesIn;
+    /**
+     * Forces this id, overriding any `.meta({ id })` on the schema. A named body
+     * is emitted as a `$ref` to `components.schemas`, which keeps a stable name
+     * for client generators — at the cost of Swagger UI's `try-it-out` form,
+     * which doesn't follow `$ref` for `multipart/form-data`.
+     */
+    readonly id?: string;
+    /**
+     * Merge an intersection / union of `z.object` arms into one flat inline
+     * object. Needed for composite bodies whose `try-it-out` form must render.
+     * All merged properties become optional. See `@ZodBody`'s `flatten`.
+     */
+    readonly flatten?: boolean;
+    /** Registry to register named descendants into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+    /** OpenAPI `description` for the request body. */
+    readonly description?: string;
+    /** Whether the body is required. Defaults to `true`. */
+    readonly required?: boolean;
+}
+
+interface BaseFileOptions {
+    /**
+     * Registry id for the schema. Set it to get a reusable
+     * `components.schemas` entry that every field `$ref`s, instead of the
+     * fragment being inlined at each use site. There is no `title` counterpart
+     * — `overrideJSONSchema` replaces the emitted body and does not carry
+     * `title` into it, so one would have no effect.
+     */
+    readonly id?: string;
+    /** Allowed MIME types, matched case-insensitively against the client-supplied value. */
+    readonly mimeTypes?: readonly string[];
+    /** Allowed filename extensions, with or without a leading dot. */
+    readonly extensions?: readonly string[];
+    /** OpenAPI `description` for the emitted binary property. */
+    readonly description?: string;
+    /** Overrides the `contentMediaType` derived from a single-entry `mimeTypes`. */
+    readonly contentMediaType?: string;
+}
+
+/**
+ * Validates `req.file` against the named property of the `@ZodMultipart`
+ * shape. The name selects a schema; it never searches the request. Match it
+ * to your `FileInterceptor('<name>')` field name, as with plain Nest.
+ */
+declare const ZodUploadedFile: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>>)[]) => ParameterDecorator;
+/**
+ * Validates `req.files` against the named property of the `@ZodMultipart`
+ * shape, or against an object of every declared file property when called
+ * with no name — the record shape `FileFieldsInterceptor` produces.
+ */
+declare const ZodUploadedFiles: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/**
+ * Validates `req.body` against the `@ZodMultipart` shape — the text fields
+ * only under `filesIn: 'request'` (multer keeps files off the body), the
+ * whole shape under `filesIn: 'body'`.
+ */
+declare const ZodMultipartBody: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+export { type BaseFileOptions as B, MULTIPART_CONTENT_TYPE as M, ZodMultipartBody as Z, type MultipartBody as a, type MultipartShape as b, type ZodMultipartOptions as c, ZodUploadedFile as d, ZodUploadedFiles as e };

package/dist/registry-C9xStKa6.d.mts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+/**
+ * Per-registration flags carried alongside the id.
+ *
+ * - `expose` — force the id into the emitted document even when no endpoint
+ *   references it. The author deliberately wants it in `components.schemas`
+ *   (e.g. for out-of-band client codegen). Default exposure is otherwise
+ *   reachability-scoped, so an unreferenced schema is pruned unless flagged.
+ * - `anonymous` — the id is a synthetic placeholder for a schema with no
+ *   resolvable id (passed inline to `@ZodResponse` / `@ZodBody`). It exists
+ *   only to carry the body through bulk emission under the document's
+ *   `strict` / `override` options; `inlineAnonymousBodies` later inlines the
+ *   body at each `$ref` site and prunes the component, so the synthetic id
+ *   never reaches the final document.
+ *
+ * Both flags are sticky — once set for an id they stay set, so a later plain
+ * `register` of the same id (e.g. the idempotent re-register inside
+ * `createZodDto`) doesn't clear them.
+ */
+interface RegisterFlags {
+    readonly expose?: boolean;
+    readonly anonymous?: boolean;
+}
+interface ZodNestRegistry {
+    readonly zodRegistry: typeof z.globalRegistry;
+    register(schema: z.ZodType, id: string, flags?: RegisterFlags): void;
+    hasCollision(id: string): boolean;
+    getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
+    /**
+     * Snapshot of every id registered through this `ZodNestRegistry`. The
+     * underlying Zod registry is `z.globalRegistry`, which may hold third-party
+     * entries — bulk emission filters its output against this snapshot to keep
+     * only zod-nest-known ids.
+     *
+     * Includes ids discovered transitively via `.meta({ id })` on descendants
+     * of explicitly-registered schemas.
+     */
+    ids(): readonly string[];
+    /** Ids registered with `{ expose: true }` — exposed regardless of usage. */
+    forceExposedIds(): readonly string[];
+    /** Ids registered with `{ anonymous: true }` — inlined + pruned by `applyZodNest`. */
+    anonymousIds(): readonly string[];
+}
+declare const createRegistry: () => ZodNestRegistry;
+/** Process-wide default registry, used when no explicit `options.registry` is passed. */
+declare const defaultRegistry: ZodNestRegistry;
+interface RegisterSchemaOptions {
+    /** Forces this id, overriding any `.meta({ id })` already on the schema. */
+    readonly id?: string;
+    /**
+     * Force the schema into the emitted document even when no endpoint
+     * references it. Default exposure is reachability-scoped — see
+     * {@link RegisterFlags.expose}.
+     */
+    readonly expose?: boolean;
+    /**
+     * Mark the resolved id as a synthetic anonymous placeholder — inlined and
+     * pruned by `applyZodNest`. See {@link RegisterFlags.anonymous}.
+     */
+    readonly anonymous?: boolean;
+}
+/**
+ * Register a schema with the given registry, resolving its id from (in order):
+ * an explicit `options.id`, then `.meta({ id })` on the schema. Returns the
+ * resolved id, or `undefined` when neither source yields one (the call is then
+ * a no-op — callers with their own fallback path handle that case).
+ *
+ * Shared by `createZodDto` and `extend` so a schema named via `.meta({ id })`
+ * gets its body emitted into `components.schemas` even when it never flows
+ * through `createZodDto` (e.g. used only as an `extend()` parent — Zod's
+ * `.extend()` produces a flat object, so the parent isn't a transitive
+ * descendant of the child and would otherwise be missed by `discoverDependents`).
+ *
+ * Idempotent — `registry.register` already deduplicates repeat calls.
+ */
+declare const registerSchema: (schema: z.ZodType, registry?: ZodNestRegistry, options?: RegisterSchemaOptions) => string | undefined;
+
+export { type RegisterFlags as R, type ZodNestRegistry as Z, type RegisterSchemaOptions as a, createRegistry as c, defaultRegistry as d, registerSchema as r };

package/dist/registry-C9xStKa6.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+/**
+ * Per-registration flags carried alongside the id.
+ *
+ * - `expose` — force the id into the emitted document even when no endpoint
+ *   references it. The author deliberately wants it in `components.schemas`
+ *   (e.g. for out-of-band client codegen). Default exposure is otherwise
+ *   reachability-scoped, so an unreferenced schema is pruned unless flagged.
+ * - `anonymous` — the id is a synthetic placeholder for a schema with no
+ *   resolvable id (passed inline to `@ZodResponse` / `@ZodBody`). It exists
+ *   only to carry the body through bulk emission under the document's
+ *   `strict` / `override` options; `inlineAnonymousBodies` later inlines the
+ *   body at each `$ref` site and prunes the component, so the synthetic id
+ *   never reaches the final document.
+ *
+ * Both flags are sticky — once set for an id they stay set, so a later plain
+ * `register` of the same id (e.g. the idempotent re-register inside
+ * `createZodDto`) doesn't clear them.
+ */
+interface RegisterFlags {
+    readonly expose?: boolean;
+    readonly anonymous?: boolean;
+}
+interface ZodNestRegistry {
+    readonly zodRegistry: typeof z.globalRegistry;
+    register(schema: z.ZodType, id: string, flags?: RegisterFlags): void;
+    hasCollision(id: string): boolean;
+    getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
+    /**
+     * Snapshot of every id registered through this `ZodNestRegistry`. The
+     * underlying Zod registry is `z.globalRegistry`, which may hold third-party
+     * entries — bulk emission filters its output against this snapshot to keep
+     * only zod-nest-known ids.
+     *
+     * Includes ids discovered transitively via `.meta({ id })` on descendants
+     * of explicitly-registered schemas.
+     */
+    ids(): readonly string[];
+    /** Ids registered with `{ expose: true }` — exposed regardless of usage. */
+    forceExposedIds(): readonly string[];
+    /** Ids registered with `{ anonymous: true }` — inlined + pruned by `applyZodNest`. */
+    anonymousIds(): readonly string[];
+}
+declare const createRegistry: () => ZodNestRegistry;
+/** Process-wide default registry, used when no explicit `options.registry` is passed. */
+declare const defaultRegistry: ZodNestRegistry;
+interface RegisterSchemaOptions {
+    /** Forces this id, overriding any `.meta({ id })` already on the schema. */
+    readonly id?: string;
+    /**
+     * Force the schema into the emitted document even when no endpoint
+     * references it. Default exposure is reachability-scoped — see
+     * {@link RegisterFlags.expose}.
+     */
+    readonly expose?: boolean;
+    /**
+     * Mark the resolved id as a synthetic anonymous placeholder — inlined and
+     * pruned by `applyZodNest`. See {@link RegisterFlags.anonymous}.
+     */
+    readonly anonymous?: boolean;
+}
+/**
+ * Register a schema with the given registry, resolving its id from (in order):
+ * an explicit `options.id`, then `.meta({ id })` on the schema. Returns the
+ * resolved id, or `undefined` when neither source yields one (the call is then
+ * a no-op — callers with their own fallback path handle that case).
+ *
+ * Shared by `createZodDto` and `extend` so a schema named via `.meta({ id })`
+ * gets its body emitted into `components.schemas` even when it never flows
+ * through `createZodDto` (e.g. used only as an `extend()` parent — Zod's
+ * `.extend()` produces a flat object, so the parent isn't a transitive
+ * descendant of the child and would otherwise be missed by `discoverDependents`).
+ *
+ * Idempotent — `registry.register` already deduplicates repeat calls.
+ */
+declare const registerSchema: (schema: z.ZodType, registry?: ZodNestRegistry, options?: RegisterSchemaOptions) => string | undefined;
+
+export { type RegisterFlags as R, type ZodNestRegistry as Z, type RegisterSchemaOptions as a, createRegistry as c, defaultRegistry as d, registerSchema as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-nest",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "Modern Zod v4-only NestJS + OpenAPI 3.1 integration. Successor to nestjs-zod.",
   "license": "MIT",
   "author": "Rodrigo Azevedo",
@@ -49,6 +49,26 @@
         "default": "./dist/helpers/index.js"
       }
     },
+    "./express": {
+      "import": {
+        "types": "./dist/express/index.d.mts",
+        "default": "./dist/express/index.mjs"
+      },
+      "require": {
+        "types": "./dist/express/index.d.ts",
+        "default": "./dist/express/index.js"
+      }
+    },
+    "./fastify": {
+      "import": {
+        "types": "./dist/fastify/index.d.mts",
+        "default": "./dist/fastify/index.mjs"
+      },
+      "require": {
+        "types": "./dist/fastify/index.d.ts",
+        "default": "./dist/fastify/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -95,6 +115,7 @@
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
     "@swc/core": "^1.16.1",
+    "@types/multer": "2.2.0",
     "@types/node": "^24.13.3",
     "@types/supertest": "^7.2.1",
     "@types/swagger2openapi": "^7.0.4",