zod-nest 3.2.6 → 3.3.0

package/README.md

@@ -1,19 +1,19 @@
 # zod-nest
 
-> Modern **Zod v4** ↔ **NestJS** ↔ **OpenAPI 3.1** integration.
+> Modern **Zod v4** ↔ **NestJS** ↔ **OpenAPI 3.1 / 3.2** integration.
 
 [![npm](https://img.shields.io/npm/v/zod-nest)](https://www.npmjs.com/package/zod-nest)
 [![CI](https://github.com/rodrigowbazevedo/zod-nest/actions/workflows/ci.yml/badge.svg)](https://github.com/rodrigowbazevedo/zod-nest/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/rodrigowbazevedo/zod-nest/branch/main/graph/badge.svg)](https://codecov.io/gh/rodrigowbazevedo/zod-nest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Define your DTOs once with Zod, get validated request bodies, validated response bodies, and a correct OpenAPI 3.1 document — without the dual-codepath, post-process, or `@ts-ignore` baggage that comes with bolting Zod onto class-validator-shaped tooling.
+Define your DTOs once with Zod, get validated request bodies, validated response bodies, and a correct OpenAPI 3.1 or 3.2 document — without the dual-codepath, post-process, or `@ts-ignore` baggage that comes with bolting Zod onto class-validator-shaped tooling.
 
 ## Why this exists
 
 `zod-nest` is a fresh take on the idea pioneered by [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod) — many thanks to that project and its maintainers; this library would not exist without it.
 
-The difference is that `zod-nest` is Zod v4 only and OpenAPI 3.1 only. It drops `class-validator` / `class-transformer` coexistence, drops Zod v3 codepaths, drops `cleanupOpenApiDoc` as a separate post-process, and drops the 20-odd `@ts-ignore`s that the dual-version approach required. The result is a smaller surface, fully type-safe end to end, with extension points where you actually need them — exception factories, response status resolution, custom emission overrides.
+The difference is that `zod-nest` is Zod v4 only and OpenAPI 3.1+ only (3.1 or 3.2; no 3.0). It drops `class-validator` / `class-transformer` coexistence, drops Zod v3 codepaths, drops `cleanupOpenApiDoc` as a separate post-process, and drops the 20-odd `@ts-ignore`s that the dual-version approach required. The result is a smaller surface, fully type-safe end to end, with extension points where you actually need them — exception factories, response status resolution, custom emission overrides.
 
 For the long-form motivation, see [`docs/why-this-exists.md`](docs/why-this-exists.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 only** — no `3.0` fallback. `$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` routes conformant. `$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`.

package/dist/index.d.mts

@@ -807,9 +807,9 @@ interface ApplyZodNestOptions {
  *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
  *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - 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.
+ * - `doc.openapi` is normalised to a version zod-nest emits — the one set via
+ *   `DocumentBuilder.setOpenAPIVersion()` when supported, else `'3.1.0'` with a
+ *   warning, so the version string always matches the emitted body.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.d.ts

@@ -807,9 +807,9 @@ interface ApplyZodNestOptions {
  *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
  *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - 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.
+ * - `doc.openapi` is normalised to a version zod-nest emits — the one set via
+ *   `DocumentBuilder.setOpenAPIVersion()` when supported, else `'3.1.0'` with a
+ *   warning, so the version string always matches the emitted body.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.js

@@ -1728,6 +1728,25 @@ var decorateIfPresent = /* @__PURE__ */ chunkEV5I5HGT_js.__name((schemas, key) =
   };
 }, "decorateIfPresent");
 
+// src/document/openapi-version.ts
+var SUPPORTED_OPENAPI_SERIES = [
+  "3.1",
+  "3.2"
+];
+var DEFAULT_OPENAPI_VERSION = "3.1.0";
+var SUPPORTED_VERSION_PATTERN = /^3\.[12]\.\d+(?:-.+)?$/;
+var resolveOpenApiVersion = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
+  const declared = doc.openapi;
+  if (typeof declared !== "string" || declared === "") {
+    return DEFAULT_OPENAPI_VERSION;
+  }
+  if (SUPPORTED_VERSION_PATTERN.test(declared)) {
+    return declared;
+  }
+  console.warn(`[zod-nest] Document declares OpenAPI \`${declared}\`, which zod-nest does not emit; emitting \`${DEFAULT_OPENAPI_VERSION}\` instead. Supported: ${SUPPORTED_OPENAPI_SERIES.map((series) => `${series}.x`).join(", ")}. Set one via \`DocumentBuilder.setOpenAPIVersion()\` to silence this.`);
+  return DEFAULT_OPENAPI_VERSION;
+}, "resolveOpenApiVersion");
+
 // src/document/ref-titles.ts
 var applyRefTitles = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
   const schemas = doc.components?.schemas;
@@ -1880,7 +1899,6 @@ var withForcedExposure = /* @__PURE__ */ chunkEV5I5HGT_js.__name((collected, reg
     classToDtoId: collected.classToDtoId
   };
 }, "withForcedExposure");
-var OPENAPI_VERSION = "3.1.0";
 var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
   const registry = opts.registry ?? chunkQ3SWJZBB_js.defaultRegistry;
   const collected = collectUsage(doc, registry);
@@ -1921,7 +1939,7 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     collected: extended
   });
-  doc.openapi = OPENAPI_VERSION;
+  doc.openapi = resolveOpenApiVersion(doc);
   return doc;
 }, "applyZodNest");