zod-nest 3.6.0 → 3.7.0

package/README.md

@@ -42,7 +42,7 @@ A short list of behavioural differences you'll hit on day one. Full migration ta
 - **Multi-status `@ZodResponse`** — stack the decorator per status code. In `nestjs-zod`, multi-status required mixing `@ZodSerializerDto` with hand-rolled `@ApiResponse({ status: ... })` calls.
 - **No internal `@HttpCode`** — `@ZodResponse` does **not** call `@HttpCode` under the hood. Status resolution precedence: `@ZodResponse({ status })` → `@HttpCode(...)` on the handler → method default (`POST → 201`, others → `200`). The caller controls `201` vs `200` vs `204` via standard NestJS decorators. `status` accepts numeric codes plus the OpenAPI 3.1 range keys (`'1XX'`…`'5XX'`) and `'default'` (sugar for the resolved method default).
 - **I/O suffix only when needed** — `<Id>Output` is only emitted when the input and output JSON Schemas actually differ. `nestjs-zod` always emitted `_Output`.
-- **OpenAPI 3.1 and 3.2** — no `3.0` fallback. Pick with `DocumentBuilder.setOpenAPIVersion('3.2.0')`; 3.2 is what makes `QUERY` and WebDAV routes conformant, and what lets a streamed response say `itemSchema` instead of overstating the whole body. `$ref`s emit to the final location; `cleanupOpenApiDoc` is unnecessary.
+- **OpenAPI 3.1 and 3.2** — no `3.0` fallback. Pick with `DocumentBuilder.setOpenAPIVersion('3.2.0')`; 3.2 is what makes `QUERY` and WebDAV routes conformant, what lets a streamed response say `itemSchema` instead of overstating the whole body, what emits Response Object `summary`, and what collapses a named query DTO to `in: querystring`. `$ref`s emit to the final location; `cleanupOpenApiDoc` is unnecessary.
 - **Validation-failure logging out of the box** — `nestjs-zod` has none.
 - **Customizable serialization exception** — both `ZodValidationPipe` and `ZodSerializerInterceptor` accept a factory. `nestjs-zod` only customized the input side.
 - **DTO discriminator** — `Symbol.for('zod-nest.dto')` (cross-realm safe), not `MyDto.isZodDto`.
@@ -186,7 +186,7 @@ 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).
+Named query objects (both `@Query() dto` and `@ZodQuery`) collapse to a single `in: querystring` parameter under OpenAPI 3.2 — the field 3.2 added for exactly this — and expand to one parameter per field under 3.1. Nothing changes on the wire either way. The deprecated `queryParamStyle` / `@ZodQuery({ ref })` flags override the default; see [`docs/swagger-integration.md → Query parameter style`](docs/swagger-integration.md#query-parameter-style).
 
 ### I/O suffix rules
 

package/dist/index.d.mts

@@ -603,16 +603,19 @@ interface ZodQueryOptions {
     /** 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`:
+     * Override how this query DTO is represented, taking precedence over
+     * `applyZodNest`'s `queryParamStyle` and the target version:
      *
-     * - `true` — one single schema-based query parameter that `$ref`s the DTO's
-     *   `components.schemas` entry (`style: 'form'`, `explode: true`).
+     * - `true` — collapse to one parameter carrying the whole schema
+     *   (`in: 'querystring'` under 3.2, `style: 'form'` under 3.1).
      * - `false` — one parameter per top-level property.
-     * - unset — follow the global `queryParamStyle` preference (default `'expand'`).
+     * - unset — follow `queryParamStyle`, then the version (3.2 collapses).
      *
-     * Ref mode needs a named schema to reference: `ref: true` on an anonymous
+     * Collapsing needs a named schema to reference: `ref: true` on an anonymous
      * schema (no `.meta({ id })` and no `id` option) throws `ZodNestError`.
+     *
+     * @deprecated Removed in the next major, where 3.1 always expands and 3.2
+     * always collapses. Under 3.2 an explicit value warns.
      */
     readonly ref?: boolean;
 }
@@ -731,15 +734,14 @@ declare class ZodNestModule {
 /**
  * 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.
+ * - `'expand'` — one parameter per top-level property of the DTO schema.
+ * - `'ref'` — collapse to a single parameter carrying the whole schema.
+ *
+ * Query-only: path / header / cookie markers always expand, since collapsing
+ * an object into one parameter is a query serialization.
  *
- * Query-only: path / header / cookie markers always expand regardless of this
- * setting, since the form-exploded-object pattern is a query serialization.
+ * @deprecated Removed in the next major. 3.2 collapses named query DTOs to
+ * `in: 'querystring'` by default, which is what this option approximated.
  */
 type QueryParamStyle = 'expand' | 'ref';
 
@@ -759,17 +761,17 @@ interface ApplyZodNestOptions {
      */
     strict?: boolean;
     /**
-     * How named `@Query()` / `@ZodQuery` DTOs are represented in the document
-     * (default `'expand'`):
+     * Overrides the version-derived default for named `@Query()` / `@ZodQuery`
+     * DTOs: `'expand'` for one parameter per property, `'ref'` to collapse to a
+     * single parameter carrying the whole schema.
      *
-     * - `'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.
+     * Left unset, 3.2 collapses (as `in: 'querystring'`) and 3.1 expands.
+     * Query-only — path / header / cookie DTOs always expand — and a per-handler
+     * `@ZodQuery({ ref })` takes precedence.
      *
-     * Query-only — path / header / cookie DTOs always expand. A per-handler
-     * `@ZodQuery({ ref })` override takes precedence over this preference.
+     * @deprecated Removed in the next major, where 3.1 always expands and 3.2
+     * always collapses. This option existed because 3.1 could not express a
+     * whole-query-string schema; 3.2's `querystring` can.
      */
     queryParamStyle?: QueryParamStyle;
     /**
@@ -795,9 +797,9 @@ 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`) — except `@Query()` DTOs under
- *   `queryParamStyle: 'ref'` (or a `@ZodQuery({ ref: true })` override), which
- *   collapse to a single `$ref` schema-based query parameter. The synthetic
+ *   DTO's schema (`expandParamMarkers`) — except named `@Query()` DTOs under
+ *   3.2, which collapse to a single `in: 'querystring'` parameter, and their
+ *   3.1 equivalent under `queryParamStyle: 'ref'`. 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
@@ -822,6 +824,9 @@ interface ApplyZodNestOptions {
  *   so a streamed body documents one item rather than the whole sequence.
  * - Response Object `summary` survives only under 3.2; emitting 3.1 drops each
  *   one with a warning naming the operation, since 3.1 forbids the field.
+ * - Under 3.2 a named query DTO collapses to `in: 'querystring'`, degrading to
+ *   per-property expansion (with a warning) where that version's coexistence
+ *   rules forbid it — a sibling `in: 'query'` parameter, or a second candidate.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.d.ts

@@ -603,16 +603,19 @@ interface ZodQueryOptions {
     /** 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`:
+     * Override how this query DTO is represented, taking precedence over
+     * `applyZodNest`'s `queryParamStyle` and the target version:
      *
-     * - `true` — one single schema-based query parameter that `$ref`s the DTO's
-     *   `components.schemas` entry (`style: 'form'`, `explode: true`).
+     * - `true` — collapse to one parameter carrying the whole schema
+     *   (`in: 'querystring'` under 3.2, `style: 'form'` under 3.1).
      * - `false` — one parameter per top-level property.
-     * - unset — follow the global `queryParamStyle` preference (default `'expand'`).
+     * - unset — follow `queryParamStyle`, then the version (3.2 collapses).
      *
-     * Ref mode needs a named schema to reference: `ref: true` on an anonymous
+     * Collapsing needs a named schema to reference: `ref: true` on an anonymous
      * schema (no `.meta({ id })` and no `id` option) throws `ZodNestError`.
+     *
+     * @deprecated Removed in the next major, where 3.1 always expands and 3.2
+     * always collapses. Under 3.2 an explicit value warns.
      */
     readonly ref?: boolean;
 }
@@ -731,15 +734,14 @@ declare class ZodNestModule {
 /**
  * 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.
+ * - `'expand'` — one parameter per top-level property of the DTO schema.
+ * - `'ref'` — collapse to a single parameter carrying the whole schema.
+ *
+ * Query-only: path / header / cookie markers always expand, since collapsing
+ * an object into one parameter is a query serialization.
  *
- * Query-only: path / header / cookie markers always expand regardless of this
- * setting, since the form-exploded-object pattern is a query serialization.
+ * @deprecated Removed in the next major. 3.2 collapses named query DTOs to
+ * `in: 'querystring'` by default, which is what this option approximated.
  */
 type QueryParamStyle = 'expand' | 'ref';
 
@@ -759,17 +761,17 @@ interface ApplyZodNestOptions {
      */
     strict?: boolean;
     /**
-     * How named `@Query()` / `@ZodQuery` DTOs are represented in the document
-     * (default `'expand'`):
+     * Overrides the version-derived default for named `@Query()` / `@ZodQuery`
+     * DTOs: `'expand'` for one parameter per property, `'ref'` to collapse to a
+     * single parameter carrying the whole schema.
      *
-     * - `'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.
+     * Left unset, 3.2 collapses (as `in: 'querystring'`) and 3.1 expands.
+     * Query-only — path / header / cookie DTOs always expand — and a per-handler
+     * `@ZodQuery({ ref })` takes precedence.
      *
-     * Query-only — path / header / cookie DTOs always expand. A per-handler
-     * `@ZodQuery({ ref })` override takes precedence over this preference.
+     * @deprecated Removed in the next major, where 3.1 always expands and 3.2
+     * always collapses. This option existed because 3.1 could not express a
+     * whole-query-string schema; 3.2's `querystring` can.
      */
     queryParamStyle?: QueryParamStyle;
     /**
@@ -795,9 +797,9 @@ 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`) — except `@Query()` DTOs under
- *   `queryParamStyle: 'ref'` (or a `@ZodQuery({ ref: true })` override), which
- *   collapse to a single `$ref` schema-based query parameter. The synthetic
+ *   DTO's schema (`expandParamMarkers`) — except named `@Query()` DTOs under
+ *   3.2, which collapse to a single `in: 'querystring'` parameter, and their
+ *   3.1 equivalent under `queryParamStyle: 'ref'`. 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
@@ -822,6 +824,9 @@ interface ApplyZodNestOptions {
  *   so a streamed body documents one item rather than the whole sequence.
  * - Response Object `summary` survives only under 3.2; emitting 3.1 drops each
  *   one with a warning naming the operation, since 3.1 forbids the field.
+ * - Under 3.2 a named query DTO collapses to `in: 'querystring'`, degrading to
+ *   per-property expansion (with a warning) where that version's coexistence
+ *   rules forbid it — a sibling `in: 'query'` parameter, or a second candidate.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.js

@@ -1430,35 +1430,104 @@ var hintFor = /* @__PURE__ */ chunkEV5I5HGT_js.__name((ref, collected) => {
   return "no DTO with this id was registered \u2014 check for a meta.id typo or a DTO used without createZodDto";
 }, "hintFor");
 
-// src/document/expand-param-markers.ts
+// src/document/querystring-param.ts
+var QUERYSTRING_MEDIA_TYPE = "application/x-www-form-urlencoded";
 var isPlainRecord3 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var buildQuerystringParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
+  const { dtoId, body } = params;
+  const required = isPlainRecord3(body) && Array.isArray(body.required) && body.required.length > 0;
+  return {
+    name: dtoId,
+    in: "querystring",
+    required,
+    content: {
+      [QUERYSTRING_MEDIA_TYPE]: {
+        schema: {
+          $ref: `${chunkJ2MGUXBB_js.COMPONENTS_SCHEMAS_PREFIX}${dtoId}`
+        }
+      }
+    }
+  };
+}, "buildQuerystringParam");
+var hasQueryConflict = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
+  const { parameters, pathItemParameters, candidateCount } = params;
+  if (candidateCount > 1) {
+    return true;
+  }
+  return containsQueryParam(parameters) || containsQueryParam(pathItemParameters);
+}, "hasQueryConflict");
+var conflictingQueryNames = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, pathItemParameters) => [
+  ...queryNamesOf(parameters),
+  ...queryNamesOf(pathItemParameters)
+], "conflictingQueryNames");
+var containsQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters) => Array.isArray(parameters) && parameters.some(isPlainQueryParam), "containsQueryParam");
+var queryNamesOf = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters) => {
+  if (!Array.isArray(parameters)) {
+    return [];
+  }
+  const names = [];
+  for (const param of parameters) {
+    if (!isPlainQueryParam(param)) {
+      continue;
+    }
+    names.push(typeof param.name === "string" ? param.name : "<unnamed>");
+  }
+  return names;
+}, "queryNamesOf");
+var isPlainQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((param) => isPlainRecord3(param) && param.in === "query" && param.__zodNestDto !== true, "isPlainQueryParam");
+
+// src/document/expand-param-markers.ts
+var isPlainRecord4 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var expandParamMarkers = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
-  const { doc, inputSchemas, outputSchemas } = params;
-  const queryParamStyle = params.queryParamStyle ?? "expand";
+  const { doc, inputSchemas, outputSchemas, queryParamStyle } = params;
+  const emitThirtyTwo = params.emitThirtyTwo ?? false;
   const schemas = doc.components?.schemas;
   const componentIds = schemas !== null && typeof schemas === "object" ? new Set(Object.keys(schemas)) : /* @__PURE__ */ new Set();
+  if (queryParamStyle !== void 0 && emitThirtyTwo) {
+    warnDeprecatedQueryParamStyle();
+  }
+  const context = {
+    inputSchemas,
+    outputSchemas,
+    queryParamStyle,
+    emitThirtyTwo,
+    componentIds
+  };
   let expandedAny = false;
-  forEachOperation(doc, (op) => {
-    const parameters = op.parameters;
-    if (!Array.isArray(parameters)) {
-      return;
+  for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+    if (!isPlainRecord4(pathItem)) {
+      continue;
     }
-    const next = expandParameterList(parameters, {
-      inputSchemas,
-      outputSchemas,
-      queryParamStyle,
-      componentIds
-    });
-    if (next !== parameters) {
-      op.parameters = next;
-      expandedAny = true;
+    for (const { method, operation } of operationEntriesOfPathItem(pathItem)) {
+      const parameters = operation.parameters;
+      if (!Array.isArray(parameters)) {
+        continue;
+      }
+      const next = expandParameterList(parameters, context, {
+        path,
+        method,
+        pathItemParameters: pathItem.parameters
+      });
+      if (next !== parameters) {
+        operation.parameters = next;
+        expandedAny = true;
+      }
     }
-  });
+  }
   if (expandedAny) {
     pruneOrphanObjectSchema(doc);
   }
 }, "expandParamMarkers");
-var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context) => {
+var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context, scope) => {
+  const candidateCount = countCollapseCandidates(parameters, context);
+  const collapseBlocked = context.emitThirtyTwo && candidateCount > 0 && hasQueryConflict({
+    parameters,
+    pathItemParameters: scope.pathItemParameters,
+    candidateCount
+  });
+  if (collapseBlocked) {
+    warnQuerystringDegraded(scope, parameters, candidateCount);
+  }
   let result;
   for (let i = 0; i < parameters.length; i++) {
     const param = parameters[i];
@@ -1472,21 +1541,51 @@ var expandParameterList = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, c
     }
     const map = marker.io === "output" ? context.outputSchemas : context.inputSchemas;
     const body = map.get(marker.dtoId);
-    result.push(...resolveMarker(marker, body, context));
+    result.push(...resolveMarker(marker, body, context, collapseBlocked));
   }
   return result ?? parameters;
 }, "expandParameterList");
-var resolveMarker = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body, context) => {
-  const useRef = marker.ref ?? context.queryParamStyle === "ref";
-  if (marker.in === "query" && useRef && context.componentIds.has(marker.dtoId)) {
+var wouldCollapse = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, context) => marker.in === "query" && prefersCollapse(marker, context) && context.componentIds.has(marker.dtoId), "wouldCollapse");
+var prefersCollapse = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, context) => {
+  if (marker.ref !== void 0) {
+    return marker.ref;
+  }
+  if (context.queryParamStyle !== void 0) {
+    return context.queryParamStyle === "ref";
+  }
+  return context.emitThirtyTwo;
+}, "prefersCollapse");
+var countCollapseCandidates = /* @__PURE__ */ chunkEV5I5HGT_js.__name((parameters, context) => {
+  let count = 0;
+  for (const param of parameters) {
+    const marker = readMarker2(param);
+    if (marker !== void 0 && wouldCollapse(marker, context)) {
+      count += 1;
+    }
+  }
+  return count;
+}, "countCollapseCandidates");
+var resolveMarker = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body, context, collapseBlocked) => {
+  if (marker.ref !== void 0 && context.emitThirtyTwo) {
+    warnDeprecatedRefOption(marker.dtoId);
+  }
+  if (collapseBlocked || !wouldCollapse(marker, context)) {
+    return expandOne(marker, body);
+  }
+  if (context.emitThirtyTwo) {
     return [
-      buildRefQueryParam(marker, body)
+      buildQuerystringParam({
+        dtoId: marker.dtoId,
+        body
+      })
     ];
   }
-  return expandOne(marker, body);
+  return [
+    buildRefQueryParam(marker, body)
+  ];
 }, "resolveMarker");
 var buildRefQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
-  const required = isPlainRecord3(body) && Array.isArray(body.required) && body.required.length > 0;
+  const required = isPlainRecord4(body) && Array.isArray(body.required) && body.required.length > 0;
   return {
     name: marker.dtoId,
     in: "query",
@@ -1499,7 +1598,7 @@ var buildRefQueryParam = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body)
   };
 }, "buildRefQueryParam");
 var readMarker2 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => {
-  if (!isPlainRecord3(value)) {
+  if (!isPlainRecord4(value)) {
     return void 0;
   }
   if (value.__zodNestDto !== true) {
@@ -1520,7 +1619,7 @@ var readMarker2 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => {
   return value;
 }, "readMarker");
 var expandOne = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
-  if (!isPlainRecord3(body) || !isPlainRecord3(body.properties)) {
+  if (!isPlainRecord4(body) || !isPlainRecord4(body.properties)) {
     throw new ZodNestDocumentError("UNEXPANDABLE_PARAM_DTO", `Cannot expand \`@${capitalize(marker.in)}() x: ${marker.dtoId}\` \u2014 the DTO's schema is not an object with \`properties\`. Non-body parameter DTOs must be object schemas; arrays, unions, primitives, etc. cannot be split into individual parameters. Use \`@Body()\` for non-object DTOs, or restructure the schema as an object whose fields become the params.`, {
       dtoId: marker.dtoId,
       in: marker.in,
@@ -1531,7 +1630,7 @@ var expandOne = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, body) => {
   const requiredSet = collectRequired(body.required);
   const out = [];
   for (const [propName, propSchemaRaw] of Object.entries(properties)) {
-    if (!isPlainRecord3(propSchemaRaw)) {
+    if (!isPlainRecord4(propSchemaRaw)) {
       continue;
     }
     out.push(buildParameter(marker, propName, propSchemaRaw, requiredSet.has(propName)));
@@ -1564,6 +1663,22 @@ var buildParameter = /* @__PURE__ */ chunkEV5I5HGT_js.__name((marker, name, sche
   };
 }, "buildParameter");
 var capitalize = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value.charAt(0).toUpperCase() + value.slice(1), "capitalize");
+var warnQuerystringDegraded = /* @__PURE__ */ chunkEV5I5HGT_js.__name((scope, parameters, candidateCount) => {
+  console.warn(`[zod-nest] Expanded the query DTO on \`${scope.method.toUpperCase()} ${scope.path}\` per-property instead of emitting \`in: 'querystring'\`: ${degradeReason(scope, parameters, candidateCount)} The expanded form is spec-valid, so the document still ships.`);
+}, "warnQuerystringDegraded");
+var degradeReason = /* @__PURE__ */ chunkEV5I5HGT_js.__name((scope, parameters, candidateCount) => {
+  if (candidateCount > 1) {
+    return `OpenAPI 3.2 allows at most one \`querystring\` parameter per operation, and this one has ${candidateCount} query DTOs.`;
+  }
+  const names = conflictingQueryNames(parameters, scope.pathItemParameters);
+  return `OpenAPI 3.2 forbids a \`querystring\` parameter alongside \`in: 'query'\` parameters (${names.map((name) => `\`${name}\``).join(", ")}).`;
+}, "degradeReason");
+var warnDeprecatedQueryParamStyle = /* @__PURE__ */ chunkEV5I5HGT_js.__name(() => {
+  console.warn("[zod-nest] `queryParamStyle` is deprecated and will be removed in the next major: OpenAPI 3.2 emits `in: 'querystring'` for named query DTOs by default, which is what this option approximated. Drop it to take the default.");
+}, "warnDeprecatedQueryParamStyle");
+var warnDeprecatedRefOption = /* @__PURE__ */ chunkEV5I5HGT_js.__name((dtoId) => {
+  console.warn(`[zod-nest] \`@ZodQuery({ ref })\` on \`${dtoId}\` is deprecated and will be removed in the next major: OpenAPI 3.2 emits \`in: 'querystring'\` for named query DTOs by default. Drop the option to take the default.`);
+}, "warnDeprecatedRefOption");
 var pruneOrphanObjectSchema = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   const schemas = doc.components?.schemas;
   if (schemas === void 0 || !Object.prototype.hasOwnProperty.call(schemas, "Object")) {
@@ -1635,7 +1750,7 @@ var inlineAnonymousBodies = /* @__PURE__ */ chunkEV5I5HGT_js.__name(({ doc, regi
       `${anonId}${OUTPUT_SUFFIX}`
     ]) {
       const body = schemas[key];
-      if (isPlainRecord4(body)) {
+      if (isPlainRecord5(body)) {
         bodyByRef.set(`${chunkJ2MGUXBB_js.COMPONENTS_SCHEMAS_PREFIX}${key}`, body);
       }
     }
@@ -1661,7 +1776,7 @@ var refsWithin = /* @__PURE__ */ chunkEV5I5HGT_js.__name((schemas, bodyByRef) =>
   });
   return found;
 }, "refsWithin");
-var isPlainRecord4 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var isPlainRecord5 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var inlineRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, bodyByRef) => {
   if (Array.isArray(node)) {
     for (const item of node) {
@@ -1669,7 +1784,7 @@ var inlineRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, bodyByRef) => {
     }
     return;
   }
-  if (!isPlainRecord4(node)) {
+  if (!isPlainRecord5(node)) {
     return;
   }
   const ref = node.$ref;
@@ -1901,7 +2016,7 @@ var applyRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   }
   const titleById = /* @__PURE__ */ new Map();
   for (const [id, body] of Object.entries(schemas)) {
-    if (isPlainRecord5(body) && typeof body.title === "string" && body.title !== "") {
+    if (isPlainRecord6(body) && typeof body.title === "string" && body.title !== "") {
       titleById.set(id, body.title);
     }
   }
@@ -1911,7 +2026,7 @@ var applyRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   addRefTitles(doc.paths, titleById);
   addRefTitles(schemas, titleById);
 }, "applyRefTitles");
-var isPlainRecord5 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var isPlainRecord6 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
 var addRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, titleById) => {
   if (Array.isArray(node)) {
     for (const item of node) {
@@ -1919,7 +2034,7 @@ var addRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, titleById) =>
     }
     return;
   }
-  if (!isPlainRecord5(node)) {
+  if (!isPlainRecord6(node)) {
     return;
   }
   const ref = node.$ref;
@@ -2067,6 +2182,8 @@ var withForcedExposure = /* @__PURE__ */ chunkEV5I5HGT_js.__name((collected, reg
 }, "withForcedExposure");
 var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
   const registry = opts.registry ?? chunkJ2MGUXBB_js.defaultRegistry;
+  const openApiVersion = resolveOpenApiVersion(doc);
+  const emitThirtyTwo = openApiVersion.startsWith("3.2.");
   const collected = collectUsage(doc, registry);
   const exposed = withForcedExposure(collected, registry);
   const { inputSchemas, outputSchemas } = bulkEmit({
@@ -2086,7 +2203,8 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     inputSchemas,
     outputSchemas,
-    queryParamStyle: opts.queryParamStyle
+    queryParamStyle: opts.queryParamStyle,
+    emitThirtyTwo
   });
   rewriteRefs({
     doc,
@@ -2105,8 +2223,6 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     collected: extended
   });
-  const openApiVersion = resolveOpenApiVersion(doc);
-  const emitThirtyTwo = openApiVersion.startsWith("3.2.");
   if (emitThirtyTwo) {
     relocateExtensionOperations(doc);
   }