zod-nest 1.6.1 → 1.7.0

package/README.md

@@ -24,6 +24,7 @@ For the long-form motivation, see [`docs/why-this-exists.md`](docs/why-this-exis
 - **`createZodDto`** — class wrapper around a Zod schema with introspectable `schema`, `id`, `io`, and a sibling `Output` class when input/output diverge.
 - **`ZodValidationPipe`** — auto-detects DTO from handler-arg metatype, accepts an explicit DTO or raw Zod schema, customizable exception factory.
 - **`@ZodResponse`** — stackable per status code, accepts a single DTO, an array (`[Dto]`), or a tuple (`[A, B, …]`). No internal `@HttpCode` — caller controls status.
+- **`@ZodBody` / `@ZodQuery` / `@ZodHeaders` / `@ZodCookies`** — method-level decorators that wire OpenAPI docs for schemas whose `z.infer<>` is a union (intersection-of-union, discriminated unions, etc.) — the ones that can't be wrapped in `createZodDto` because TS refuses unions as class bases (TS2509). Schema validation stays via `@Body(new ZodValidationPipe(schema))`; the type at the handler arg stays `z.infer<>`.
 - **`ZodSerializerInterceptor`** — response validation with a `passthroughOnError` escape hatch for untrusted upstream shapes.
 - **`applyZodNest`** — one call after `SwaggerModule.createDocument(...)` replaces the entire `cleanupOpenApiDoc` ritual.
 - **`ZodNestModule.forRoot`** — global pipe + interceptor + logging configuration in one place; optional (everything works standalone).
@@ -149,6 +150,37 @@ The class returned by `createZodDto(schema)` carries `schema`, `id`, `io: 'input
 
 See [`docs/dto.md`](docs/dto.md) for the full surface.
 
+### Schemas that don't fit a class
+
+A schema whose `z.infer<>` is a TypeScript union — `z.union`, `z.discriminatedUnion`, or `z.intersection(obj, union)` — can't be used as a class base because TS rejects unions as constructor return types (TS2509: *Base constructor return type ... is not an object type*). For these, skip `createZodDto` and pair the raw schema with parameter-level decorators that handle OpenAPI emission directly:
+
+```ts
+const IntersectionWithUnion = z
+  .intersection(
+    z.union([z.object({ a: z.string() }), z.object({ b: z.string() })]),
+    z.union([z.object({ c: z.string() }), z.object({ d: z.string() })]),
+  )
+  .meta({ id: 'IntersectionWithUnion' });
+
+type IntersectionWithUnionType = z.infer<typeof IntersectionWithUnion>;
+
+@Controller()
+export class Controller {
+  @Post()
+  @ZodBody(IntersectionWithUnion)
+  async post(
+    @Body(new ZodValidationPipe(IntersectionWithUnion))
+    body: IntersectionWithUnionType,
+  ): Promise<IntersectionWithUnionType> {
+    return body;
+  }
+}
+```
+
+The decorator set: `@ZodBody`, `@ZodQuery`, `@ZodHeaders`, `@ZodCookies`. All are method-level. They register the schema in the registry (so it lands in `components.schemas` when named) and apply the matching OpenAPI parameter metadata — `@ZodBody` writes the request body's `$ref`/inline schema; `@ZodQuery` / `@ZodHeaders` / `@ZodCookies` expand a `z.object` into one OpenAPI parameter per property. Validation stays manual via `@Body(new ZodValidationPipe(schema))` so the handler arg keeps its precise `z.infer<>` type.
+
+See [`docs/recipes/intersection-with-union.md`](docs/recipes/intersection-with-union.md) for the full pattern.
+
 ### I/O suffix rules
 
 If a schema's input and output JSON Schemas are byte-equal (the common case), the OpenAPI doc emits a single `components.schemas[Id]`. If they differ (e.g. a `transform`, a `pipe`, an `.optional().default(x)` field), the doc emits two: `Id` for input, `IdOutput` for output. Response refs are rewritten to `IdOutput` automatically.
@@ -424,6 +456,9 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 **Response** — [`docs/responses.md`](docs/responses.md)
 - `@ZodResponse({ status?, type, description?, passthroughOnError? })`, `ZodSerializerInterceptor`, `ZodSerializationException`, `defaultStatusFor`, `resolveEffectiveStatus`, `ResponseStatusInput`, `ResponseStatusWildcard`, `ResponseVariant`, `ZOD_RESPONSES_METADATA_KEY`
 
+**Parameter decorators for raw schemas** — [`docs/recipes/intersection-with-union.md`](docs/recipes/intersection-with-union.md)
+- `@ZodBody(schema, options?)`, `@ZodQuery(schema, options?)`, `@ZodHeaders(schema, options?)`, `@ZodCookies(schema, options?)`, `ZodBodyOptions`, `ZodQueryOptions`, `ZodHeadersOptions`, `ZodCookiesOptions`
+
 **Document** — [`docs/swagger-integration.md`](docs/swagger-integration.md)
 - `applyZodNest(rawDoc, options)`, `ApplyZodNestOptions`, `ZodNestDocumentError`
 

package/dist/index.d.mts

@@ -487,6 +487,92 @@ interface ZodResponseOptions {
  */
 declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
 
+interface ZodBodyOptions {
+    /** Forces this id, overriding any `.meta({ id })` already on the schema. */
+    readonly id?: string;
+    /** Registry to register 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;
+}
+/**
+ * Method-level decorator that wires the OpenAPI `requestBody` for a handler
+ * whose body schema doesn't fit a `createZodDto` class — typically a
+ * `z.intersection` that contains a `z.union`, a `z.discriminatedUnion`, or
+ * any schema whose `z.infer<>` is a TypeScript union (which TS refuses as a
+ * class base with TS2509).
+ *
+ * Pair with `@Body(new ZodValidationPipe(schema))` at the parameter to keep
+ * the handler arg precisely typed as `z.infer<typeof schema>`:
+ *
+ * ```ts
+ * @Post()
+ * @ZodBody(IntersectionWithUnion)
+ * async post(
+ *   @Body(new ZodValidationPipe(IntersectionWithUnion))
+ *   body: z.infer<typeof IntersectionWithUnion>,
+ * ) {}
+ * ```
+ *
+ * The schema is registered in the registry when it has an id (via
+ * `.meta({ id })` or `options.id`) so its body is emitted into
+ * `components.schemas`. Anonymous schemas are inlined into the operation.
+ */
+declare const ZodBody: (schema: z.ZodType, options?: ZodBodyOptions) => MethodDecorator;
+
+interface ZodQueryOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * `@ApiQuery` entry per property. Each property's schema is independently
+ * resolved — named properties (`.meta({ id })`) become `$ref`s,
+ * anonymous properties inline.
+ *
+ * The user remains responsible for binding the actual query values to the
+ * handler, typically via `@Query(new ZodValidationPipe(schema)) q: z.infer<typeof schema>`.
+ */
+declare const ZodQuery: (schema: z.ZodType, options?: ZodQueryOptions) => MethodDecorator;
+
+interface ZodHeadersOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * header-parameter entry per property. Required-ness derives from each
+ * property's Zod optionality.
+ *
+ * Writes directly to the `swagger/apiParameters` metadata key the explorer
+ * reads. We bypass `@ApiHeader` because it injects a default `type: 'string'`
+ * onto the schema (`api-header.decorator.js`), which pollutes our `$ref`
+ * objects and inline JSON Schemas. The raw-metadata path keeps our schema
+ * bodies intact.
+ */
+declare const ZodHeaders: (schema: z.ZodType, options?: ZodHeadersOptions) => MethodDecorator;
+
+interface ZodCookiesOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * cookie-parameter entry per property in the OpenAPI operation. There is no
+ * `@ApiCookie` decorator in `@nestjs/swagger`, so we write directly to the
+ * `swagger/apiParameters` metadata key the explorer reads — the same key
+ * `@ApiQuery` / `@ApiParam` / `@ApiHeader` populate via their helper.
+ */
+declare const ZodCookies: (schema: z.ZodType, options?: ZodCookiesOptions) => MethodDecorator;
+
 declare class ZodSerializerInterceptor implements NestInterceptor {
     private readonly reflector;
     private readonly logOutputFailure;
@@ -619,4 +705,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, ZodBody, type ZodBodyOptions, ZodCookies, type ZodCookiesOptions, type ZodDto, type ZodDtoMarker, ZodHeaders, type ZodHeadersOptions, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodQuery, type ZodQueryOptions, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -487,6 +487,92 @@ interface ZodResponseOptions {
  */
 declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
 
+interface ZodBodyOptions {
+    /** Forces this id, overriding any `.meta({ id })` already on the schema. */
+    readonly id?: string;
+    /** Registry to register 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;
+}
+/**
+ * Method-level decorator that wires the OpenAPI `requestBody` for a handler
+ * whose body schema doesn't fit a `createZodDto` class — typically a
+ * `z.intersection` that contains a `z.union`, a `z.discriminatedUnion`, or
+ * any schema whose `z.infer<>` is a TypeScript union (which TS refuses as a
+ * class base with TS2509).
+ *
+ * Pair with `@Body(new ZodValidationPipe(schema))` at the parameter to keep
+ * the handler arg precisely typed as `z.infer<typeof schema>`:
+ *
+ * ```ts
+ * @Post()
+ * @ZodBody(IntersectionWithUnion)
+ * async post(
+ *   @Body(new ZodValidationPipe(IntersectionWithUnion))
+ *   body: z.infer<typeof IntersectionWithUnion>,
+ * ) {}
+ * ```
+ *
+ * The schema is registered in the registry when it has an id (via
+ * `.meta({ id })` or `options.id`) so its body is emitted into
+ * `components.schemas`. Anonymous schemas are inlined into the operation.
+ */
+declare const ZodBody: (schema: z.ZodType, options?: ZodBodyOptions) => MethodDecorator;
+
+interface ZodQueryOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * `@ApiQuery` entry per property. Each property's schema is independently
+ * resolved — named properties (`.meta({ id })`) become `$ref`s,
+ * anonymous properties inline.
+ *
+ * The user remains responsible for binding the actual query values to the
+ * handler, typically via `@Query(new ZodValidationPipe(schema)) q: z.infer<typeof schema>`.
+ */
+declare const ZodQuery: (schema: z.ZodType, options?: ZodQueryOptions) => MethodDecorator;
+
+interface ZodHeadersOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * header-parameter entry per property. Required-ness derives from each
+ * property's Zod optionality.
+ *
+ * Writes directly to the `swagger/apiParameters` metadata key the explorer
+ * reads. We bypass `@ApiHeader` because it injects a default `type: 'string'`
+ * onto the schema (`api-header.decorator.js`), which pollutes our `$ref`
+ * objects and inline JSON Schemas. The raw-metadata path keeps our schema
+ * bodies intact.
+ */
+declare const ZodHeaders: (schema: z.ZodType, options?: ZodHeadersOptions) => MethodDecorator;
+
+interface ZodCookiesOptions {
+    /** Forces this id on the root schema, overriding any `.meta({ id })`. */
+    readonly id?: string;
+    /** Registry to register into. Defaults to `defaultRegistry`. */
+    readonly registry?: ZodNestRegistry;
+}
+/**
+ * Method-level decorator that expands a `z.object` schema into one
+ * cookie-parameter entry per property in the OpenAPI operation. There is no
+ * `@ApiCookie` decorator in `@nestjs/swagger`, so we write directly to the
+ * `swagger/apiParameters` metadata key the explorer reads — the same key
+ * `@ApiQuery` / `@ApiParam` / `@ApiHeader` populate via their helper.
+ */
+declare const ZodCookies: (schema: z.ZodType, options?: ZodCookiesOptions) => MethodDecorator;
+
 declare class ZodSerializerInterceptor implements NestInterceptor {
     private readonly reflector;
     private readonly logOutputFailure;
@@ -619,4 +705,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type RegisterSchemaOptions, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, ZodBody, type ZodBodyOptions, ZodCookies, type ZodCookiesOptions, type ZodDto, type ZodDtoMarker, ZodHeaders, type ZodHeadersOptions, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodQuery, type ZodQueryOptions, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.js

@@ -1129,6 +1129,144 @@ var ZodResponse = /* @__PURE__ */ __name((opts) => {
     });
   };
 }, "ZodResponse");
+
+// src/decorators/internal/zod-schema-ref.ts
+var resolveSchemaRef = /* @__PURE__ */ __name((schema, options) => {
+  const registry = options?.registry ?? defaultRegistry;
+  const id = registerSchema(schema, registry, {
+    id: options?.id
+  });
+  if (id !== void 0) {
+    return {
+      kind: "ref",
+      ref: {
+        $ref: `#/components/schemas/${id}`
+      }
+    };
+  }
+  for (const [child, childId] of discoverDependents(schema)) {
+    registry.register(child, childId);
+  }
+  const { schema: body } = toOpenApi(schema, {
+    io: "input",
+    registry
+  });
+  return {
+    kind: "inline",
+    schema: body
+  };
+}, "resolveSchemaRef");
+
+// src/decorators/zod-body.decorator.ts
+var ZodBody = /* @__PURE__ */ __name((schema, options) => {
+  const resolution = resolveSchemaRef(schema, {
+    id: options?.id,
+    registry: options?.registry
+  });
+  const apiBodySchema = resolution.kind === "ref" ? resolution.ref : resolution.schema;
+  return swagger.ApiBody({
+    schema: apiBodySchema,
+    ...options?.description !== void 0 ? {
+      description: options.description
+    } : {},
+    required: options?.required ?? true
+  });
+}, "ZodBody");
+
+// src/decorators/internal/zod-param-expand.ts
+var isZodObject = /* @__PURE__ */ __name((schema) => schema._zod.def.type === "object", "isZodObject");
+var expandObjectSchema = /* @__PURE__ */ __name((schema, options) => {
+  if (!isZodObject(schema)) {
+    throw new ZodNestError(`${options.decoratorName} requires a \`z.object({...})\` schema (got \`${schema._zod.def.type}\`). Each property of the object becomes one OpenAPI parameter. For non-object body shapes (intersections, unions, primitives), use \`@ZodBody\` instead.`);
+  }
+  const registry = options.registry ?? defaultRegistry;
+  registerSchema(schema, registry, {
+    id: options.id
+  });
+  const result = [];
+  for (const [name, propSchema] of Object.entries(schema.shape)) {
+    const resolution = resolveSchemaRef(propSchema, {
+      registry
+    });
+    const required = options.forceRequired === true || !isOptionalProp(propSchema);
+    result.push({
+      name,
+      required,
+      resolution
+    });
+  }
+  return result;
+}, "expandObjectSchema");
+var paramSchemaBody = /* @__PURE__ */ __name((resolution) => resolution.kind === "ref" ? resolution.ref : resolution.schema, "paramSchemaBody");
+
+// src/decorators/zod-query.decorator.ts
+var ZodQuery = /* @__PURE__ */ __name((schema, options) => {
+  const expanded = expandObjectSchema(schema, {
+    id: options?.id,
+    registry: options?.registry,
+    decoratorName: "@ZodQuery"
+  });
+  return common.applyDecorators(...expanded.map(({ name, required, resolution }) => swagger.ApiQuery({
+    name,
+    schema: paramSchemaBody(resolution),
+    required
+  })));
+}, "ZodQuery");
+
+// src/decorators/internal/constants.ts
+var API_PARAMETERS_KEY = "swagger/apiParameters";
+
+// src/decorators/zod-headers.decorator.ts
+var ZodHeaders = /* @__PURE__ */ __name((schema, options) => {
+  const expanded = expandObjectSchema(schema, {
+    id: options?.id,
+    registry: options?.registry,
+    decoratorName: "@ZodHeaders"
+  });
+  const newEntries = expanded.map(({ name, required, resolution }) => ({
+    name,
+    in: "header",
+    required,
+    schema: paramSchemaBody(resolution)
+  }));
+  return (_target, _propertyKey, descriptor) => {
+    const handler = descriptor.value;
+    if (typeof handler !== "function") {
+      throw new TypeError("[zod-nest] @ZodHeaders can only be applied to methods.");
+    }
+    const existing = Reflect.getMetadata(API_PARAMETERS_KEY, handler) ?? [];
+    Reflect.defineMetadata(API_PARAMETERS_KEY, [
+      ...existing,
+      ...newEntries
+    ], handler);
+  };
+}, "ZodHeaders");
+
+// src/decorators/zod-cookies.decorator.ts
+var ZodCookies = /* @__PURE__ */ __name((schema, options) => {
+  const expanded = expandObjectSchema(schema, {
+    id: options?.id,
+    registry: options?.registry,
+    decoratorName: "@ZodCookies"
+  });
+  const newEntries = expanded.map(({ name, required, resolution }) => ({
+    name,
+    in: "cookie",
+    required,
+    schema: paramSchemaBody(resolution)
+  }));
+  return (_target, _propertyKey, descriptor) => {
+    const handler = descriptor.value;
+    if (typeof handler !== "function") {
+      throw new TypeError("[zod-nest] @ZodCookies can only be applied to methods.");
+    }
+    const existing = Reflect.getMetadata(API_PARAMETERS_KEY, handler) ?? [];
+    Reflect.defineMetadata(API_PARAMETERS_KEY, [
+      ...existing,
+      ...newEntries
+    ], handler);
+  };
+}, "ZodCookies");
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -1322,9 +1460,10 @@ var forEachOperation = /* @__PURE__ */ __name((doc, fn) => {
 
 // src/document/collect-usage.ts
 var isPlainRecord2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
-var collectUsage = /* @__PURE__ */ __name((doc, app) => {
+var collectUsage = /* @__PURE__ */ __name((doc, app, registry) => {
   const classToDtoId = buildClassToDtoIdMap(doc);
-  const inputExposedIds = collectInputExposedIds(doc, classToDtoId);
+  const knownIds = new Set(registry.ids());
+  const inputExposedIds = collectInputExposedIds(doc, classToDtoId, knownIds);
   const outputExposedIds = collectOutputExposedIds(app);
   return {
     inputExposedIds,
@@ -1359,7 +1498,7 @@ var readMarker = /* @__PURE__ */ __name((schema) => {
     dtoId: marker.dtoId
   };
 }, "readMarker");
-var collectInputExposedIds = /* @__PURE__ */ __name((doc, classToDtoId) => {
+var collectInputExposedIds = /* @__PURE__ */ __name((doc, classToDtoId, knownIds) => {
   const ids = /* @__PURE__ */ new Set();
   const paths = doc.paths ?? {};
   for (const pathItem of Object.values(paths)) {
@@ -1367,7 +1506,7 @@ var collectInputExposedIds = /* @__PURE__ */ __name((doc, classToDtoId) => {
       continue;
     }
     for (const operation of operationsOf(pathItem)) {
-      collectRefsFromOperation(operation, classToDtoId, ids);
+      collectRefsFromOperation(operation, classToDtoId, knownIds, ids);
     }
   }
   return ids;
@@ -1382,9 +1521,9 @@ var operationsOf = /* @__PURE__ */ __name((pathItem) => {
   }
   return out;
 }, "operationsOf");
-var collectRefsFromOperation = /* @__PURE__ */ __name((operation, classToDtoId, ids) => {
+var collectRefsFromOperation = /* @__PURE__ */ __name((operation, classToDtoId, knownIds, ids) => {
   if (isPlainRecord2(operation.requestBody)) {
-    collectRefsFromContent(operation.requestBody.content, classToDtoId, ids);
+    collectRefsFromContent(operation.requestBody.content, classToDtoId, knownIds, ids);
   }
   const parameters = operation.parameters;
   if (Array.isArray(parameters)) {
@@ -1392,7 +1531,7 @@ var collectRefsFromOperation = /* @__PURE__ */ __name((operation, classToDtoId,
       if (!isPlainRecord2(param)) {
         continue;
       }
-      collectRefFromSchema(param.schema, classToDtoId, ids);
+      collectRefFromSchema(param.schema, classToDtoId, knownIds, ids);
       collectIdFromMarkerParam(param, ids);
     }
   }
@@ -1407,7 +1546,7 @@ var collectIdFromMarkerParam = /* @__PURE__ */ __name((param, ids) => {
   }
   ids.add(dtoId);
 }, "collectIdFromMarkerParam");
-var collectRefsFromContent = /* @__PURE__ */ __name((content, classToDtoId, ids) => {
+var collectRefsFromContent = /* @__PURE__ */ __name((content, classToDtoId, knownIds, ids) => {
   if (!isPlainRecord2(content)) {
     return;
   }
@@ -1415,10 +1554,10 @@ var collectRefsFromContent = /* @__PURE__ */ __name((content, classToDtoId, ids)
     if (!isPlainRecord2(mediaType)) {
       continue;
     }
-    collectRefFromSchema(mediaType.schema, classToDtoId, ids);
+    collectRefFromSchema(mediaType.schema, classToDtoId, knownIds, ids);
   }
 }, "collectRefsFromContent");
-var collectRefFromSchema = /* @__PURE__ */ __name((schema, classToDtoId, ids) => {
+var collectRefFromSchema = /* @__PURE__ */ __name((schema, classToDtoId, knownIds, ids) => {
   if (!isPlainRecord2(schema)) {
     return;
   }
@@ -1427,9 +1566,13 @@ var collectRefFromSchema = /* @__PURE__ */ __name((schema, classToDtoId, ids) =>
     return;
   }
   const className = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
-  const dtoId = classToDtoId.get(className);
-  if (dtoId !== void 0) {
-    ids.add(dtoId);
+  const renamed = classToDtoId.get(className);
+  if (renamed !== void 0) {
+    ids.add(renamed);
+    return;
+  }
+  if (knownIds.has(className)) {
+    ids.add(className);
   }
 }, "collectRefFromSchema");
 var collectOutputExposedIds = /* @__PURE__ */ __name((app) => {
@@ -1913,7 +2056,7 @@ var stripMarkerFromSchema = /* @__PURE__ */ __name((schema) => {
 var OPENAPI_VERSION = "3.1.0";
 var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
   const registry = opts.registry ?? defaultRegistry;
-  const collected = collectUsage(doc, opts.app);
+  const collected = collectUsage(doc, opts.app, registry);
   const { inputSchemas, outputSchemas } = bulkEmit({
     registry,
     override: opts.override,
@@ -1955,10 +2098,14 @@ exports.ZOD_NEST_ERROR_DUPLICATE_ID = ZOD_NEST_ERROR_DUPLICATE_ID;
 exports.ZOD_NEST_ERROR_EXTENSION = ZOD_NEST_ERROR_EXTENSION;
 exports.ZOD_NEST_OPTIONS = ZOD_NEST_OPTIONS;
 exports.ZOD_RESPONSES_METADATA_KEY = ZOD_RESPONSES_METADATA_KEY;
+exports.ZodBody = ZodBody;
+exports.ZodCookies = ZodCookies;
+exports.ZodHeaders = ZodHeaders;
 exports.ZodNestDocumentError = ZodNestDocumentError;
 exports.ZodNestError = ZodNestError;
 exports.ZodNestModule = ZodNestModule;
 exports.ZodNestUnrepresentableError = ZodNestUnrepresentableError;
+exports.ZodQuery = ZodQuery;
 exports.ZodResponse = ZodResponse;
 exports.ZodSerializationException = ZodSerializationException;
 exports.ZodValidationException = ZodValidationException;