zod-nest 1.11.0 → 2.0.0

package/README.md

@@ -130,7 +130,7 @@ async function bootstrap() {
     app,
     new DocumentBuilder().setTitle('Users').setVersion('1').build(),
   );
-  const doc = applyZodNest(raw, { app });
+  const doc = applyZodNest(raw);
   SwaggerModule.setup('docs', app, doc);
 
   await app.listen(3000);
@@ -151,7 +151,7 @@ Every DTO is one Zod schema wrapped in a class. The class exists so NestJS' intr
 
 The class returned by `createZodDto(schema)` carries `schema`, `id`, `io: 'input'`, and a lazy `Output` sibling. `parse` / `safeParse` are static methods on the class. The class is tagged with `Symbol.for('zod-nest.dto')` so `ZodValidationPipe` and `ZodSerializerInterceptor` can discriminate it from plain constructors. The id comes from `schema.meta({ id })` when present (preferred) or from the second-argument options.
 
-**Naming is exposing.** Every schema put through `registerSchema()` — directly, or transitively via `createZodDto` / `@ZodBody` / `extend` / descendant discovery — lands in `components.schemas` when `applyZodNest` runs, regardless of whether any `$ref` in the doc points at it. If you give a schema `.meta({ id })`, you're declaring it documented. Anonymous schemas without an id stay inlined where used.
+**Exposure is reachability-scoped.** A schema lands in `components.schemas` when an endpoint in the document references it — directly or transitively through a `$ref` (response inner deps included), or as a query/param/header/cookie DTO captured via its marker. A registered schema that no endpoint reaches is pruned; force it in with `{ expose: true }`. Anonymous schemas without an id stay inlined where used. This keeps several Swagger documents that share one registry from each carrying the whole catalog.
 
 See [`docs/dto.md`](docs/dto.md) for the full surface.
 
@@ -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, { 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.
@@ -375,7 +377,7 @@ Use this sparingly — it bypasses the contract you declared. Logging at `warn`
 import { applyZodNest } from 'zod-nest';
 
 const raw = SwaggerModule.createDocument(app, config);
-const doc = applyZodNest(raw, { app });
+const doc = applyZodNest(raw);
 SwaggerModule.setup('docs', app, doc);
 ```
 
@@ -540,7 +542,7 @@ Cell definitions live in [`.github/compat-matrix.json`](.github/compat-matrix.js
 
 If you're coming from `nestjs-zod`, the headline changes are:
 
-- Replace `cleanupOpenApiDoc(SwaggerModule.createDocument(app, config))` with `applyZodNest(SwaggerModule.createDocument(app, config), { app })`.
+- Replace `cleanupOpenApiDoc(SwaggerModule.createDocument(app, config))` with `applyZodNest(SwaggerModule.createDocument(app, config))`.
 - Replace `@ApiOkResponse({ type: Dto }) + @ZodSerializerDto(Dto)` pairs with `@ZodResponse({ type: Dto })`.
 - Drop `class-validator` / `class-transformer` if they were installed only for `nestjs-zod` interop.
 - Check any `MyDto.isZodDto` reflection — the discriminator is now `Symbol.for('zod-nest.dto') in MyDto`.

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { S as SchemaObject } from './openapi.types-CFBG3Zz9.mjs';
 import { $ZodTypes } from 'zod/v4/core';
-import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule, INestApplication } from '@nestjs/common';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
 import { OpenAPIObject } from '@nestjs/swagger';
@@ -27,9 +27,31 @@ interface OverrideContext {
 }
 type Override = (ctx: OverrideContext) => void;
 
+/**
+ * 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): void;
+    register(schema: z.ZodType, id: string, flags?: RegisterFlags): void;
     hasCollision(id: string): boolean;
     getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
     /**
@@ -42,6 +64,10 @@ interface ZodNestRegistry {
      * 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. */
@@ -49,6 +75,17 @@ 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):
@@ -175,6 +212,14 @@ interface CreateZodDtoOptions {
     id?: string;
     /** Registry to register this DTO's schema into. Defaults to `defaultRegistry`. */
     registry?: ZodNestRegistry;
+    /**
+     * Force this DTO's schema into the emitted document even when no endpoint
+     * references it. Exposure is otherwise reachability-scoped — a registered
+     * schema that no exposed endpoint reaches is pruned. Set `true` to keep an
+     * intentionally-documented schema (e.g. for out-of-band client codegen).
+     * Defaults to `false`.
+     */
+    expose?: boolean;
 }
 /**
  * The class type returned by `createZodDto`. Instance type infers to the
@@ -616,12 +661,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>`.
@@ -720,13 +787,22 @@ 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
-     * via `DiscoveryService` to pick up `@ZodResponse` output-side DTO usage —
-     * `@nestjs/swagger` is currently anemic on response shapes.
-     */
-    app: INestApplication;
     /**
      * `ZodNestRegistry` instance that holds the zod-nest DTOs. Defaults to
      * `defaultRegistry` (the process-wide singleton populated by `createZodDto`).
@@ -741,6 +817,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
@@ -752,23 +842,29 @@ 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.
+ * - Anonymous body/response schemas (no `.meta({ id })`) are inlined at their
+ *   `$ref` sites and their synthetic components pruned (`inlineAnonymousBodies`).
+ * - Only schemas reachable from this document's endpoints (plus their
+ *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
+ *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
+ *   several documents sharing one registry each carry only what they use.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the
  *   `DocumentBuilder` configuration on the caller side.
  *
  * Composable with other doc-transform passes — apply other mutations before
- * or after this function. The `app` argument is required because the
- * output-side DTO usage lives on controller-method metadata that the doc
- * doesn't surface; `DiscoveryService` resolves it.
+ * or after this function.
  */
-declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
+declare const applyZodNest: (doc: OpenAPIObject, opts?: ApplyZodNestOptions) => OpenAPIObject;
 
 type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDABLE_PARAM_DTO';
 /**
@@ -795,4 +891,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 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 };
+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 RegisterFlags, 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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { S as SchemaObject } from './openapi.types-CFBG3Zz9.js';
 import { $ZodTypes } from 'zod/v4/core';
-import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule, INestApplication } from '@nestjs/common';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
 import { OpenAPIObject } from '@nestjs/swagger';
@@ -27,9 +27,31 @@ interface OverrideContext {
 }
 type Override = (ctx: OverrideContext) => void;
 
+/**
+ * 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): void;
+    register(schema: z.ZodType, id: string, flags?: RegisterFlags): void;
     hasCollision(id: string): boolean;
     getCollisions(): ReadonlyMap<string, ReadonlySet<z.ZodType>>;
     /**
@@ -42,6 +64,10 @@ interface ZodNestRegistry {
      * 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. */
@@ -49,6 +75,17 @@ 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):
@@ -175,6 +212,14 @@ interface CreateZodDtoOptions {
     id?: string;
     /** Registry to register this DTO's schema into. Defaults to `defaultRegistry`. */
     registry?: ZodNestRegistry;
+    /**
+     * Force this DTO's schema into the emitted document even when no endpoint
+     * references it. Exposure is otherwise reachability-scoped — a registered
+     * schema that no exposed endpoint reaches is pruned. Set `true` to keep an
+     * intentionally-documented schema (e.g. for out-of-band client codegen).
+     * Defaults to `false`.
+     */
+    expose?: boolean;
 }
 /**
  * The class type returned by `createZodDto`. Instance type infers to the
@@ -616,12 +661,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>`.
@@ -720,13 +787,22 @@ 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
-     * via `DiscoveryService` to pick up `@ZodResponse` output-side DTO usage —
-     * `@nestjs/swagger` is currently anemic on response shapes.
-     */
-    app: INestApplication;
     /**
      * `ZodNestRegistry` instance that holds the zod-nest DTOs. Defaults to
      * `defaultRegistry` (the process-wide singleton populated by `createZodDto`).
@@ -741,6 +817,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
@@ -752,23 +842,29 @@ 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.
+ * - Anonymous body/response schemas (no `.meta({ id })`) are inlined at their
+ *   `$ref` sites and their synthetic components pruned (`inlineAnonymousBodies`).
+ * - Only schemas reachable from this document's endpoints (plus their
+ *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
+ *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
+ *   several documents sharing one registry each carry only what they use.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the
  *   `DocumentBuilder` configuration on the caller side.
  *
  * Composable with other doc-transform passes — apply other mutations before
- * or after this function. The `app` argument is required because the
- * output-side DTO usage lives on controller-method metadata that the doc
- * doesn't surface; `DiscoveryService` resolves it.
+ * or after this function.
  */
-declare const applyZodNest: (doc: OpenAPIObject, opts: ApplyZodNestOptions) => OpenAPIObject;
+declare const applyZodNest: (doc: OpenAPIObject, opts?: ApplyZodNestOptions) => OpenAPIObject;
 
 type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDABLE_PARAM_DTO';
 /**
@@ -795,4 +891,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 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 };
+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 RegisterFlags, 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 };