zod-nest 1.10.0 → 1.12.0

package/README.md

@@ -23,7 +23,7 @@ For the long-form motivation, see [`docs/why-this-exists.md`](docs/why-this-exis
 - **OpenAPI 3.1 emission** — no post-processing, no spec downgrade, no leftover internal extension keys.
 - **`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.
+- **`@ZodResponse`** — stackable per status code; each entry is a DTO **or a raw Zod schema** (single, array `[Entry]`, or tuple `[A, B, …]`, mixable). A raw schema is normalised to an output DTO internally, so a `z.discriminatedUnion` / `z.union` / `z.intersection` that can't be wrapped in `createZodDto` (TS2509) drops straight into a response. 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.
@@ -186,6 +186,8 @@ The decorator set: `@ZodBody`, `@ZodQuery`, `@ZodHeaders`, `@ZodCookies`. All ar
 
 See [`docs/recipes/intersection-with-union.md`](docs/recipes/intersection-with-union.md) for the full pattern.
 
+Named query objects (both `@Query() dto` and `@ZodQuery`) expand to one parameter per field by default. Pass `applyZodNest(raw, { app, queryParamStyle: 'ref' })` — or `@ZodQuery(schema, { ref: true })` per handler — to instead emit a single schema-based query parameter that `$ref`s the shared component. Same wire format; see [`docs/swagger-integration.md → Query parameter style`](docs/swagger-integration.md#query-parameter-style).
+
 ### 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.
@@ -471,7 +473,7 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 
 **DTO** — [`docs/dto.md`](docs/dto.md)
 
-- `createZodDto(schema, options?)`, `isZodDto(value)`, `ZodDto<TSchema>`, `Io`
+- `createZodDto(schema, options?)`, `isZodDto(value)`, `isZodSchema(value)`, `ZodDto<TSchema>`, `Io`
 
 **Validation** — [`docs/validation-pipe.md`](docs/validation-pipe.md)
 
@@ -479,7 +481,7 @@ 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`
+- `@ZodResponse({ status?, type, description?, passthroughOnError?, contentType?, stream? })` (`type` is a DTO or raw schema, or an array/tuple of either), `ZodSerializerInterceptor`, `ZodSerializationException`, `defaultStatusFor`, `resolveEffectiveStatus`, `ResponseStatusInput`, `ResponseStatusWildcard`, `ResponseVariant`, `ZodResponseEntry`, `ZodResponseType`, `ZOD_RESPONSES_METADATA_KEY`
 
 **Parameter decorators for raw schemas** — [`docs/recipes/intersection-with-union.md`](docs/recipes/intersection-with-union.md)
 

package/dist/index.d.mts

@@ -225,6 +225,16 @@ declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
  * NestJS exposes via `ArgumentMetadata`.
  */
 declare const isZodDto: (value: unknown) => value is ZodDto;
+/**
+ * Runtime guard: is `value` a Zod schema (any `z.*` type)?
+ *
+ * Used by `@ZodResponse` to accept a raw schema in place of a DTO — including
+ * `z.discriminatedUnion` / `z.union` / `z.intersection`, which can't be wrapped
+ * with `createZodDto` (their `z.infer` is a union, so `class … extends
+ * createZodDto(schema)` fails to typecheck with TS2509). `instanceof z.ZodType`
+ * holds for every schema built through the same `zod` module instance.
+ */
+declare const isZodSchema: (value: unknown) => value is z.ZodType;
 
 /**
  * Default exception thrown by `ZodSerializerInterceptor` in strict mode
@@ -477,18 +487,28 @@ declare class ZodValidationPipe implements PipeTransform {
 }
 
 /**
- * Accepted shapes for `@ZodResponse({ type })`:
- * - `Dto` → validates as `Dto.schema` (single-DTO response).
- * - `[Dto]` (length 1) → validates as `z.array(Dto.schema)`; matches Nest's
+ * One entry in `@ZodResponse({ type })` — either a zod-nest DTO or a raw Zod
+ * schema. A raw schema is normalised internally to `createZodDto(schema).Output`
+ * (output IO, since a response body is output-only), so schemas that can't be
+ * wrapped with `createZodDto` — `z.discriminatedUnion` / `z.union` /
+ * `z.intersection`, whose `z.infer` is a union and so trip TS2509 in an
+ * `extends` clause — can be passed straight to a response. See `toResponseDto`.
+ */
+type ZodResponseEntry = ZodDto | z.ZodType;
+/**
+ * Accepted shapes for `@ZodResponse({ type })`. Each slot is a `ZodResponseEntry`
+ * (DTO or raw schema), and the two may be mixed within an array:
+ * - `Dto` / `Schema` → validates as the entry's schema (single response).
+ * - `[Entry]` (length 1) → validates as `z.array(entry.schema)`; matches Nest's
  *   `@ApiResponse({ isArray: true })` convention without minting a separate
  *   `*sDto` id.
  * - `[A, B, ...]` (length ≥ 2) → validates as `z.tuple([A.schema, B.schema, ...])`;
  *   surfaces as an OpenAPI 3.1 `prefixItems` tuple via `applyZodNest`.
  *
- * Empty arrays and non-DTO elements throw `TypeError` at decoration time
- * so typos surface at module load, not the first request.
+ * Empty arrays and entries that are neither a DTO nor a schema throw `TypeError`
+ * at decoration time so typos surface at module load, not the first request.
  */
-type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+type ZodResponseType = ZodResponseEntry | readonly [ZodResponseEntry, ...ZodResponseEntry[]];
 /**
  * Accepted shapes for `@ZodResponse({ status })`:
  * - `number` — exact match against `response.statusCode` (most common case).
@@ -596,12 +616,34 @@ interface ZodQueryOptions {
     readonly id?: string;
     /** Registry to register into. Defaults to `defaultRegistry`. */
     readonly registry?: ZodNestRegistry;
+    /**
+     * Override how this query DTO is represented in the OpenAPI doc, taking
+     * precedence over `applyZodNest`'s `queryParamStyle`:
+     *
+     * - `true` — one single schema-based query parameter that `$ref`s the DTO's
+     *   `components.schemas` entry (`style: 'form'`, `explode: true`).
+     * - `false` — one parameter per top-level property.
+     * - unset — follow the global `queryParamStyle` preference (default `'expand'`).
+     *
+     * Ref mode needs a named schema to reference: `ref: true` on an anonymous
+     * schema (no `.meta({ id })` and no `id` option) throws `ZodNestError`.
+     */
+    readonly ref?: boolean;
 }
 /**
- * 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.
+ * Method-level decorator describing a `@Query()` object schema as OpenAPI
+ * query parameters.
+ *
+ * When the schema is named (`.meta({ id })` or the `id` option), the decorator
+ * registers it and emits a single deferred marker, leaving the expand-vs-`$ref`
+ * decision to `applyZodNest` — so an unset `ref` follows the global
+ * `queryParamStyle` preference, `ref: true` collapses to one `$ref` query
+ * parameter, and `ref: false` expands per property. This mirrors the
+ * `@Query() dto` (`createZodDto`) path, which flows through the same marker.
+ *
+ * When the schema is anonymous, there is no component to reference, so the
+ * decorator expands one `@ApiQuery` per property immediately (and rejects
+ * `ref: true`).
  *
  * The user remains responsible for binding the actual query values to the
  * handler, typically via `@Query(new ZodValidationPipe(schema)) q: z.infer<typeof schema>`.
@@ -700,6 +742,21 @@ declare class ZodNestModule {
     static forRoot(options?: ZodNestModuleOptions): DynamicModule;
 }
 
+/**
+ * How a named `@Query()` / `@ZodQuery` DTO is represented in the OpenAPI doc:
+ *
+ * - `'expand'` (default) — one parameter per top-level property of the DTO
+ *   schema, each inlined or `$ref`'d independently.
+ * - `'ref'` — a single schema-based query parameter that references the DTO's
+ *   `components.schemas` entry (`style: 'form'`, `explode: true`,
+ *   `schema: { $ref }`). The wire format is identical to `'expand'`; only the
+ *   document representation collapses to the shared component.
+ *
+ * Query-only: path / header / cookie markers always expand regardless of this
+ * setting, since the form-exploded-object pattern is a query serialization.
+ */
+type QueryParamStyle = 'expand' | 'ref';
+
 interface ApplyZodNestOptions {
     /**
      * The NestJS app instance. Required so `applyZodNest` can walk controllers
@@ -721,6 +778,20 @@ interface ApplyZodNestOptions {
      * Set to `false` to emit `{}` for those instead.
      */
     strict?: boolean;
+    /**
+     * How named `@Query()` / `@ZodQuery` DTOs are represented in the document
+     * (default `'expand'`):
+     *
+     * - `'expand'` — one query parameter per top-level property of the DTO.
+     * - `'ref'` — a single schema-based query parameter referencing the DTO's
+     *   `components.schemas` entry (`style: 'form'`, `explode: true`). The wire
+     *   format is unchanged; only the spec representation collapses to the
+     *   shared component. Note: Swagger UI renders the two forms differently.
+     *
+     * Query-only — path / header / cookie DTOs always expand. A per-handler
+     * `@ZodQuery({ ref })` override takes precedence over this preference.
+     */
+    queryParamStyle?: QueryParamStyle;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -732,9 +803,11 @@ interface ApplyZodNestOptions {
  *   keyed by the marker's `dtoId` (renaming as needed).
  * - Every `@Query()` / `@Param()` / `@Headers()` / `@Cookie()` marker
  *   parameter is expanded into one parameter per top-level property of the
- *   DTO's schema (`expandParamMarkers`). The synthetic `components.schemas.Object`
- *   that `@nestjs/swagger` materialises for the marker placeholder is pruned
- *   when it has no remaining referrers.
+ *   DTO's schema (`expandParamMarkers`) — except `@Query()` DTOs under
+ *   `queryParamStyle: 'ref'` (or a `@ZodQuery({ ref: true })` override), which
+ *   collapse to a single `$ref` schema-based query parameter. The synthetic
+ *   `components.schemas.Object` that `@nestjs/swagger` materialises for the
+ *   marker placeholder is pruned when it has no remaining referrers.
  * - The I/O suffix truth table is applied — equal input/output bodies collapse
  *   to one `components.schemas[id]`; divergent bodies split as
  *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
@@ -775,4 +848,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, DEFAULT_STREAM_CONTENT_TYPES, 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 };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, DEFAULT_STREAM_CONTENT_TYPES, 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 ZodResponseEntry, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, isZodSchema, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -225,6 +225,16 @@ declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
  * NestJS exposes via `ArgumentMetadata`.
  */
 declare const isZodDto: (value: unknown) => value is ZodDto;
+/**
+ * Runtime guard: is `value` a Zod schema (any `z.*` type)?
+ *
+ * Used by `@ZodResponse` to accept a raw schema in place of a DTO — including
+ * `z.discriminatedUnion` / `z.union` / `z.intersection`, which can't be wrapped
+ * with `createZodDto` (their `z.infer` is a union, so `class … extends
+ * createZodDto(schema)` fails to typecheck with TS2509). `instanceof z.ZodType`
+ * holds for every schema built through the same `zod` module instance.
+ */
+declare const isZodSchema: (value: unknown) => value is z.ZodType;
 
 /**
  * Default exception thrown by `ZodSerializerInterceptor` in strict mode
@@ -477,18 +487,28 @@ declare class ZodValidationPipe implements PipeTransform {
 }
 
 /**
- * Accepted shapes for `@ZodResponse({ type })`:
- * - `Dto` → validates as `Dto.schema` (single-DTO response).
- * - `[Dto]` (length 1) → validates as `z.array(Dto.schema)`; matches Nest's
+ * One entry in `@ZodResponse({ type })` — either a zod-nest DTO or a raw Zod
+ * schema. A raw schema is normalised internally to `createZodDto(schema).Output`
+ * (output IO, since a response body is output-only), so schemas that can't be
+ * wrapped with `createZodDto` — `z.discriminatedUnion` / `z.union` /
+ * `z.intersection`, whose `z.infer` is a union and so trip TS2509 in an
+ * `extends` clause — can be passed straight to a response. See `toResponseDto`.
+ */
+type ZodResponseEntry = ZodDto | z.ZodType;
+/**
+ * Accepted shapes for `@ZodResponse({ type })`. Each slot is a `ZodResponseEntry`
+ * (DTO or raw schema), and the two may be mixed within an array:
+ * - `Dto` / `Schema` → validates as the entry's schema (single response).
+ * - `[Entry]` (length 1) → validates as `z.array(entry.schema)`; matches Nest's
  *   `@ApiResponse({ isArray: true })` convention without minting a separate
  *   `*sDto` id.
  * - `[A, B, ...]` (length ≥ 2) → validates as `z.tuple([A.schema, B.schema, ...])`;
  *   surfaces as an OpenAPI 3.1 `prefixItems` tuple via `applyZodNest`.
  *
- * Empty arrays and non-DTO elements throw `TypeError` at decoration time
- * so typos surface at module load, not the first request.
+ * Empty arrays and entries that are neither a DTO nor a schema throw `TypeError`
+ * at decoration time so typos surface at module load, not the first request.
  */
-type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+type ZodResponseType = ZodResponseEntry | readonly [ZodResponseEntry, ...ZodResponseEntry[]];
 /**
  * Accepted shapes for `@ZodResponse({ status })`:
  * - `number` — exact match against `response.statusCode` (most common case).
@@ -596,12 +616,34 @@ interface ZodQueryOptions {
     readonly id?: string;
     /** Registry to register into. Defaults to `defaultRegistry`. */
     readonly registry?: ZodNestRegistry;
+    /**
+     * Override how this query DTO is represented in the OpenAPI doc, taking
+     * precedence over `applyZodNest`'s `queryParamStyle`:
+     *
+     * - `true` — one single schema-based query parameter that `$ref`s the DTO's
+     *   `components.schemas` entry (`style: 'form'`, `explode: true`).
+     * - `false` — one parameter per top-level property.
+     * - unset — follow the global `queryParamStyle` preference (default `'expand'`).
+     *
+     * Ref mode needs a named schema to reference: `ref: true` on an anonymous
+     * schema (no `.meta({ id })` and no `id` option) throws `ZodNestError`.
+     */
+    readonly ref?: boolean;
 }
 /**
- * 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.
+ * Method-level decorator describing a `@Query()` object schema as OpenAPI
+ * query parameters.
+ *
+ * When the schema is named (`.meta({ id })` or the `id` option), the decorator
+ * registers it and emits a single deferred marker, leaving the expand-vs-`$ref`
+ * decision to `applyZodNest` — so an unset `ref` follows the global
+ * `queryParamStyle` preference, `ref: true` collapses to one `$ref` query
+ * parameter, and `ref: false` expands per property. This mirrors the
+ * `@Query() dto` (`createZodDto`) path, which flows through the same marker.
+ *
+ * When the schema is anonymous, there is no component to reference, so the
+ * decorator expands one `@ApiQuery` per property immediately (and rejects
+ * `ref: true`).
  *
  * The user remains responsible for binding the actual query values to the
  * handler, typically via `@Query(new ZodValidationPipe(schema)) q: z.infer<typeof schema>`.
@@ -700,6 +742,21 @@ declare class ZodNestModule {
     static forRoot(options?: ZodNestModuleOptions): DynamicModule;
 }
 
+/**
+ * How a named `@Query()` / `@ZodQuery` DTO is represented in the OpenAPI doc:
+ *
+ * - `'expand'` (default) — one parameter per top-level property of the DTO
+ *   schema, each inlined or `$ref`'d independently.
+ * - `'ref'` — a single schema-based query parameter that references the DTO's
+ *   `components.schemas` entry (`style: 'form'`, `explode: true`,
+ *   `schema: { $ref }`). The wire format is identical to `'expand'`; only the
+ *   document representation collapses to the shared component.
+ *
+ * Query-only: path / header / cookie markers always expand regardless of this
+ * setting, since the form-exploded-object pattern is a query serialization.
+ */
+type QueryParamStyle = 'expand' | 'ref';
+
 interface ApplyZodNestOptions {
     /**
      * The NestJS app instance. Required so `applyZodNest` can walk controllers
@@ -721,6 +778,20 @@ interface ApplyZodNestOptions {
      * Set to `false` to emit `{}` for those instead.
      */
     strict?: boolean;
+    /**
+     * How named `@Query()` / `@ZodQuery` DTOs are represented in the document
+     * (default `'expand'`):
+     *
+     * - `'expand'` — one query parameter per top-level property of the DTO.
+     * - `'ref'` — a single schema-based query parameter referencing the DTO's
+     *   `components.schemas` entry (`style: 'form'`, `explode: true`). The wire
+     *   format is unchanged; only the spec representation collapses to the
+     *   shared component. Note: Swagger UI renders the two forms differently.
+     *
+     * Query-only — path / header / cookie DTOs always expand. A per-handler
+     * `@ZodQuery({ ref })` override takes precedence over this preference.
+     */
+    queryParamStyle?: QueryParamStyle;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -732,9 +803,11 @@ interface ApplyZodNestOptions {
  *   keyed by the marker's `dtoId` (renaming as needed).
  * - Every `@Query()` / `@Param()` / `@Headers()` / `@Cookie()` marker
  *   parameter is expanded into one parameter per top-level property of the
- *   DTO's schema (`expandParamMarkers`). The synthetic `components.schemas.Object`
- *   that `@nestjs/swagger` materialises for the marker placeholder is pruned
- *   when it has no remaining referrers.
+ *   DTO's schema (`expandParamMarkers`) — except `@Query()` DTOs under
+ *   `queryParamStyle: 'ref'` (or a `@ZodQuery({ ref: true })` override), which
+ *   collapse to a single `$ref` schema-based query parameter. The synthetic
+ *   `components.schemas.Object` that `@nestjs/swagger` materialises for the
+ *   marker placeholder is pruned when it has no remaining referrers.
  * - The I/O suffix truth table is applied — equal input/output bodies collapse
  *   to one `components.schemas[id]`; divergent bodies split as
  *   `id` (input) + `idOutput` (output), with response-side refs rewritten.
@@ -775,4 +848,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, DEFAULT_STREAM_CONTENT_TYPES, 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 };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, DEFAULT_STREAM_CONTENT_TYPES, 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 ZodResponseEntry, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, isZodSchema, makeZodDtoMarker, overrideJSONSchema, registerSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.js

@@ -585,6 +585,10 @@ var buildSiblingClass = /* @__PURE__ */ __name((parent, schema) => {
       };
     }
   };
+  Object.defineProperty(SiblingClass, "name", {
+    get: /* @__PURE__ */ __name(() => parent.id, "get"),
+    configurable: true
+  });
   return SiblingClass;
 }, "buildSiblingClass");
 var resolveOutput = /* @__PURE__ */ __name((parent, schema) => {
@@ -658,9 +662,8 @@ var createZodDto = /* @__PURE__ */ __name((schema, options) => {
   };
   return ZodDtoBase;
 }, "createZodDto");
-
-// src/dto/predicates.ts
 var isZodDto = /* @__PURE__ */ __name((value) => typeof value === "function" && value[ZOD_DTO_SYMBOL] === true, "isZodDto");
+var isZodSchema = /* @__PURE__ */ __name((value) => value instanceof zod.z.ZodType, "isZodSchema");
 var ZodSerializationException = class extends common.InternalServerErrorException {
   static {
     __name(this, "ZodSerializationException");
@@ -948,8 +951,8 @@ function _ts_param(paramIndex, decorator) {
   };
 }
 __name(_ts_param, "_ts_param");
-var isZodSchema = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && "_zod" in value, "isZodSchema");
-var isOptionsObject = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !isZodSchema(value), "isOptionsObject");
+var isZodSchema2 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && "_zod" in value, "isZodSchema");
+var isOptionsObject = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !isZodSchema2(value), "isOptionsObject");
 var defaultExceptionFactory = /* @__PURE__ */ __name((zodError, argMetadata) => new ZodValidationException(zodError, argMetadata), "defaultExceptionFactory");
 exports.ZodValidationPipe = class _ZodValidationPipe {
   static {
@@ -1018,7 +1021,7 @@ exports.ZodValidationPipe = class _ZodValidationPipe {
         dtoName: arg.name
       };
     }
-    if (isZodSchema(arg)) {
+    if (isZodSchema2(arg)) {
       return {
         schema: arg,
         factory: void 0,
@@ -1086,6 +1089,48 @@ var appendResponseVariant = /* @__PURE__ */ __name((handler, variant) => {
     ...existing
   ], handler);
 }, "appendResponseVariant");
+
+// src/response/normalize-type.ts
+var responseDtoCache = /* @__PURE__ */ new WeakMap();
+var anonResponseSchemaCounter = 0;
+var warnedOnAnonymousResponseSchema = false;
+var warnAnonymousOnce = /* @__PURE__ */ __name((fallbackId) => {
+  if (warnedOnAnonymousResponseSchema) {
+    return;
+  }
+  warnedOnAnonymousResponseSchema = true;
+  console.warn(`[zod-nest] @ZodResponse received a raw Zod schema with no \`.meta({ id })\`. It will appear in components.schemas as "${fallbackId}". Add \`schema.meta({ id: 'Foo' })\` to control the OpenAPI component name.`);
+}, "warnAnonymousOnce");
+var schemaToOutputDto = /* @__PURE__ */ __name((schema) => {
+  const cached = responseDtoCache.get(schema);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const namedId = registerSchema(schema);
+  if (namedId !== void 0) {
+    const dto2 = createZodDto(schema).Output;
+    responseDtoCache.set(schema, dto2);
+    return dto2;
+  }
+  anonResponseSchemaCounter += 1;
+  const fallbackId = `_AnonZodResponseSchema_${anonResponseSchemaCounter}`;
+  warnAnonymousOnce(fallbackId);
+  const dto = createZodDto(schema, {
+    id: fallbackId
+  }).Output;
+  responseDtoCache.set(schema, dto);
+  return dto;
+}, "schemaToOutputDto");
+var toResponseDto = /* @__PURE__ */ __name((entry, index) => {
+  if (isZodDto(entry)) {
+    return entry;
+  }
+  if (isZodSchema(entry)) {
+    return schemaToOutputDto(entry);
+  }
+  const where = index === void 0 ? "@ZodResponse({ type })" : `@ZodResponse({ type }) element [${index}]`;
+  throw new TypeError(`[zod-nest] ${where} must be a zod-nest DTO class (from createZodDto), a Zod schema, or a non-empty array of those.`);
+}, "toResponseDto");
 var extractDescriptionFields = /* @__PURE__ */ __name((desc) => {
   if (desc === void 0) {
     return {};
@@ -1188,13 +1233,10 @@ var applySwaggerResponseDecorator = /* @__PURE__ */ __name((variant, effectiveSt
 }, "applySwaggerResponseDecorator");
 
 // src/decorators/zod-response.decorator.ts
-var buildArrayKind = /* @__PURE__ */ __name((dtos) => {
-  for (const [index, element] of dtos.entries()) {
-    if (!isZodDto(element)) {
-      throw new TypeError(`[zod-nest] @ZodResponse({ type }) element [${index}] is not a zod-nest DTO (class returned by createZodDto). Wrap raw schemas with createZodDto first.`);
-    }
-  }
-  const [head, ...rest] = dtos;
+var buildArrayKind = /* @__PURE__ */ __name((entries) => {
+  const [headEntry, ...restEntries] = entries;
+  const head = toResponseDto(headEntry, 0);
+  const rest = restEntries.map((entry, index) => toResponseDto(entry, index + 1));
   if (rest.length === 0) {
     return {
       kind: "array",
@@ -1210,24 +1252,25 @@ var buildArrayKind = /* @__PURE__ */ __name((dtos) => {
   ];
   return {
     kind: "tuple",
-    dto: dtos,
+    dto: [
+      head,
+      ...rest
+    ],
     validationSchema: zod.z.tuple(tupleSchemas)
   };
 }, "buildArrayKind");
 var buildKind = /* @__PURE__ */ __name((type) => {
   if (Array.isArray(type)) {
     if (type.length === 0) {
-      throw new TypeError("[zod-nest] @ZodResponse({ type: [] }) is invalid \u2014 provide at least one DTO.");
+      throw new TypeError("[zod-nest] @ZodResponse({ type: [] }) is invalid \u2014 provide at least one DTO or schema.");
     }
     return buildArrayKind(type);
   }
-  if (!isZodDto(type)) {
-    throw new TypeError("[zod-nest] @ZodResponse({ type }) must be a zod-nest DTO class (from createZodDto) or an array of such classes.");
-  }
+  const dto = toResponseDto(type);
   return {
     kind: "single",
-    dto: type,
-    validationSchema: type.schema
+    dto,
+    validationSchema: dto.schema
   };
 }, "buildKind");
 var normaliseStatus = /* @__PURE__ */ __name((status) => {
@@ -1429,10 +1472,51 @@ var resolveBodySchema = /* @__PURE__ */ __name((schema, options) => {
   });
   return resolution.kind === "ref" ? resolution.ref : resolution.schema;
 }, "resolveBodySchema");
+
+// src/decorators/internal/query-marker.ts
+var API_PARAMETERS_METADATA_KEY = "swagger/apiParameters";
+var appendQueryMarker = /* @__PURE__ */ __name((dtoId, ref) => (_target, _propertyKey, descriptor) => {
+  const method = descriptor.value;
+  if (typeof method !== "function") {
+    return descriptor;
+  }
+  const marker = {
+    name: dtoId,
+    in: "query",
+    __zodNestDto: true,
+    dtoId,
+    io: "input"
+  };
+  if (ref !== void 0) {
+    marker.ref = ref;
+  }
+  const existing = Reflect.getMetadata(API_PARAMETERS_METADATA_KEY, method);
+  const params = Array.isArray(existing) ? existing : [];
+  Reflect.defineMetadata(API_PARAMETERS_METADATA_KEY, [
+    ...params,
+    marker
+  ], method);
+  return descriptor;
+}, "appendQueryMarker");
+
+// src/decorators/zod-query.decorator.ts
 var ZodQuery = /* @__PURE__ */ __name((schema, options) => {
+  if (!isZodObject(schema)) {
+    throw new ZodNestError(`@ZodQuery 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;
+  const id = registerSchema(schema, registry, {
+    id: options?.id
+  });
+  if (id !== void 0) {
+    return appendQueryMarker(id, options?.ref);
+  }
+  if (options?.ref === true) {
+    throw new ZodNestError(`@ZodQuery({ ref: true }) requires a named schema \u2014 there is no component to \`$ref\`. Name the schema via \`.meta({ id: 'Foo' })\` or pass the \`id\` option, or drop \`ref\` to expand per property.`);
+  }
   const expanded = expandObjectSchema(schema, {
     id: options?.id,
-    registry: options?.registry,
+    registry,
     decoratorName: "@ZodQuery"
   });
   return common.applyDecorators(...expanded.map(({ name, required, resolution }) => swagger.ApiQuery({
@@ -1516,10 +1600,10 @@ __name(_ts_param2, "_ts_param");
 var defaultSerializationFactory = /* @__PURE__ */ __name((err, ctx) => new ZodSerializationException(err, ctx), "defaultSerializationFactory");
 var formatDtoLabel = /* @__PURE__ */ __name((variant) => {
   if (variant.kind === "single") {
-    return variant.dto.name;
+    return variant.dto.id;
   }
   const dtos = variant.dto;
-  return `[${dtos.map((d) => d.name).join(", ")}]`;
+  return `[${dtos.map((d) => d.id).join(", ")}]`;
 }, "formatDtoLabel");
 var formatHandlerLabel = /* @__PURE__ */ __name((context) => `${context.getClass().name}.${context.getHandler().name}`, "formatHandlerLabel");
 var matchesWildcard = /* @__PURE__ */ __name((wildcard, status) => wildcard.charCodeAt(0) - 48 === Math.floor(status / 100), "matchesWildcard");
@@ -1938,13 +2022,21 @@ var hintFor = /* @__PURE__ */ __name((ref, collected) => {
 var isPlainRecord3 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var expandParamMarkers = /* @__PURE__ */ __name((params) => {
   const { doc, inputSchemas, outputSchemas } = params;
+  const queryParamStyle = params.queryParamStyle ?? "expand";
+  const schemas = doc.components?.schemas;
+  const componentIds = schemas !== null && typeof schemas === "object" ? new Set(Object.keys(schemas)) : /* @__PURE__ */ new Set();
   let expandedAny = false;
   forEachOperation(doc, (op) => {
     const parameters = op.parameters;
     if (!Array.isArray(parameters)) {
       return;
     }
-    const next = expandParameterList(parameters, inputSchemas, outputSchemas);
+    const next = expandParameterList(parameters, {
+      inputSchemas,
+      outputSchemas,
+      queryParamStyle,
+      componentIds
+    });
     if (next !== parameters) {
       op.parameters = next;
       expandedAny = true;
@@ -1954,7 +2046,7 @@ var expandParamMarkers = /* @__PURE__ */ __name((params) => {
     pruneOrphanObjectSchema(doc);
   }
 }, "expandParamMarkers");
-var expandParameterList = /* @__PURE__ */ __name((parameters, inputSchemas, outputSchemas) => {
+var expandParameterList = /* @__PURE__ */ __name((parameters, context) => {
   let result;
   for (let i = 0; i < parameters.length; i++) {
     const param = parameters[i];
@@ -1966,12 +2058,34 @@ var expandParameterList = /* @__PURE__ */ __name((parameters, inputSchemas, outp
     if (result === void 0) {
       result = parameters.slice(0, i);
     }
-    const map = marker.io === "output" ? outputSchemas : inputSchemas;
+    const map = marker.io === "output" ? context.outputSchemas : context.inputSchemas;
     const body = map.get(marker.dtoId);
-    result.push(...expandOne(marker, body));
+    result.push(...resolveMarker(marker, body, context));
   }
   return result ?? parameters;
 }, "expandParameterList");
+var resolveMarker = /* @__PURE__ */ __name((marker, body, context) => {
+  const useRef = marker.ref ?? context.queryParamStyle === "ref";
+  if (marker.in === "query" && useRef && context.componentIds.has(marker.dtoId)) {
+    return [
+      buildRefQueryParam(marker, body)
+    ];
+  }
+  return expandOne(marker, body);
+}, "resolveMarker");
+var buildRefQueryParam = /* @__PURE__ */ __name((marker, body) => {
+  const required = isPlainRecord3(body) && Array.isArray(body.required) && body.required.length > 0;
+  return {
+    name: marker.dtoId,
+    in: "query",
+    required,
+    style: "form",
+    explode: true,
+    schema: {
+      $ref: `${COMPONENTS_SCHEMAS_PREFIX}${marker.dtoId}`
+    }
+  };
+}, "buildRefQueryParam");
 var readMarker2 = /* @__PURE__ */ __name((value) => {
   if (!isPlainRecord3(value)) {
     return void 0;
@@ -1988,6 +2102,9 @@ var readMarker2 = /* @__PURE__ */ __name((value) => {
   if (typeof value.in !== "string" || value.in === "") {
     return void 0;
   }
+  if (value.ref !== void 0 && typeof value.ref !== "boolean") {
+    return void 0;
+  }
   return value;
 }, "readMarker");
 var expandOne = /* @__PURE__ */ __name((marker, body) => {
@@ -2326,7 +2443,8 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
   expandParamMarkers({
     doc,
     inputSchemas,
-    outputSchemas
+    outputSchemas,
+    queryParamStyle: opts.queryParamStyle
   });
   rewriteRefs2({
     doc,
@@ -2372,6 +2490,7 @@ exports.extend = extend;
 exports.getLineage = getLineage;
 exports.isZodDto = isZodDto;
 exports.isZodDtoMarker = isZodDtoMarker;
+exports.isZodSchema = isZodSchema;
 exports.makeZodDtoMarker = makeZodDtoMarker;
 exports.overrideJSONSchema = overrideJSONSchema;
 exports.registerSchema = registerSchema;