zod-nest 3.5.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

@@ -300,10 +300,12 @@ type ResponseStatusWildcard = '1XX' | '2XX' | '3XX' | '4XX' | '5XX';
  * Description payload accepted by `@ZodResponse(...)` and passed through to
  * `applyZodNest`'s `@ApiResponse(...)` emitter. String form is shorthand for
  * `{ description }`; the object form lets users declare OpenAPI response
- * `headers` / `links` alongside the description.
+ * `summary` / `headers` / `links` alongside the description.
  */
 type ZodResponseDescription = string | {
     description: string;
+    /** 3.2-only. `applyZodNest` drops it, with a warning, when emitting 3.1. */
+    summary?: string;
     headers?: Record<string, unknown>;
     links?: Record<string, unknown>;
 };
@@ -601,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;
 }
@@ -729,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';
 
@@ -757,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;
     /**
@@ -793,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
@@ -818,6 +822,11 @@ interface ApplyZodNestOptions {
  *   `additionalOperations`, the only place that version accepts them, and
  *   rewrites `schema` to `itemSchema` on sequential media types (SSE, NDJSON, …)
  *   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

@@ -300,10 +300,12 @@ type ResponseStatusWildcard = '1XX' | '2XX' | '3XX' | '4XX' | '5XX';
  * Description payload accepted by `@ZodResponse(...)` and passed through to
  * `applyZodNest`'s `@ApiResponse(...)` emitter. String form is shorthand for
  * `{ description }`; the object form lets users declare OpenAPI response
- * `headers` / `links` alongside the description.
+ * `summary` / `headers` / `links` alongside the description.
  */
 type ZodResponseDescription = string | {
     description: string;
+    /** 3.2-only. `applyZodNest` drops it, with a warning, when emitting 3.1. */
+    summary?: string;
     headers?: Record<string, unknown>;
     links?: Record<string, unknown>;
 };
@@ -601,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;
 }
@@ -729,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';
 
@@ -757,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;
     /**
@@ -793,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
@@ -818,6 +822,11 @@ interface ApplyZodNestOptions {
  *   `additionalOperations`, the only place that version accepts them, and
  *   rewrites `schema` to `itemSchema` on sequential media types (SSE, NDJSON, …)
  *   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.