zod-nest 1.11.0 → 1.12.0

package/README.md

@@ -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.

package/dist/index.d.mts

@@ -616,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>`.
@@ -720,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
@@ -741,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
@@ -752,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.

package/dist/index.d.ts

@@ -616,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>`.
@@ -720,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
@@ -741,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
@@ -752,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.

package/dist/index.js

@@ -1472,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({
@@ -1981,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;
@@ -1997,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];
@@ -2009,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;
@@ -2031,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) => {
@@ -2369,7 +2443,8 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts) => {
   expandParamMarkers({
     doc,
     inputSchemas,
-    outputSchemas
+    outputSchemas,
+    queryParamStyle: opts.queryParamStyle
   });
   rewriteRefs2({
     doc,