zod-nest 3.2.6 → 3.4.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,11 @@ 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.
+ * - Targeting 3.2 additionally moves `search` / WebDAV operations under
+ *   `additionalOperations`, the only place that version accepts them.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.d.ts

@@ -807,9 +807,11 @@ 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.
+ * - Targeting 3.2 additionally moves `search` / WebDAV operations under
+ *   `additionalOperations`, the only place that version accepts them.
  *
  * Composable with other doc-transform passes — apply other mutations before
  * or after this function.

package/dist/index.js

@@ -1041,6 +1041,101 @@ var ZodNestModule = class _ZodNestModule {
     };
   }
 };
+
+// src/document/http-methods.ts
+var OPENAPI_OPERATION_KEYS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+  "query"
+];
+var EXTENSION_OPERATION_KEYS = [
+  "search",
+  "propfind",
+  "proppatch",
+  "mkcol",
+  "copy",
+  "move",
+  "lock",
+  "unlock"
+];
+var HTTP_METHODS = [
+  ...OPENAPI_OPERATION_KEYS,
+  ...EXTENSION_OPERATION_KEYS
+];
+var ADDITIONAL_OPERATIONS_KEY = "additionalOperations";
+var isRecord = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object", "isRecord");
+var operationsOfPathItem = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => {
+  const operations = [];
+  for (const method of HTTP_METHODS) {
+    const operation = pathItem[method];
+    if (isRecord(operation)) {
+      operations.push(operation);
+    }
+  }
+  const additional = pathItem[ADDITIONAL_OPERATIONS_KEY];
+  if (isRecord(additional)) {
+    for (const operation of Object.values(additional)) {
+      if (isRecord(operation)) {
+        operations.push(operation);
+      }
+    }
+  }
+  return operations;
+}, "operationsOfPathItem");
+var forEachOperation = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, fn) => {
+  const paths = doc.paths;
+  if (!isRecord(paths)) {
+    return;
+  }
+  for (const pathItem of Object.values(paths)) {
+    if (!isRecord(pathItem)) {
+      continue;
+    }
+    for (const operation of operationsOfPathItem(pathItem)) {
+      fn(operation);
+    }
+  }
+}, "forEachOperation");
+
+// src/document/additional-operations.ts
+var isRecord2 = /* @__PURE__ */ chunkEV5I5HGT_js.__name((value) => value !== null && typeof value === "object", "isRecord");
+var relocateExtensionOperations = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc) => {
+  const paths = doc.paths;
+  if (!isRecord2(paths)) {
+    return;
+  }
+  for (const pathItem of Object.values(paths)) {
+    if (!isRecord2(pathItem)) {
+      continue;
+    }
+    relocateInPathItem(pathItem);
+  }
+}, "relocateExtensionOperations");
+var relocateInPathItem = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => {
+  const relocated = {};
+  for (const method of EXTENSION_OPERATION_KEYS) {
+    const operation = pathItem[method];
+    if (!isRecord2(operation)) {
+      continue;
+    }
+    relocated[method.toUpperCase()] = operation;
+    delete pathItem[method];
+  }
+  if (Object.keys(relocated).length === 0) {
+    return;
+  }
+  const existing = pathItem[ADDITIONAL_OPERATIONS_KEY];
+  pathItem[ADDITIONAL_OPERATIONS_KEY] = isRecord2(existing) ? {
+    ...relocated,
+    ...existing
+  } : relocated;
+}, "relocateInPathItem");
 var URI = /* @__PURE__ */ chunkEV5I5HGT_js.__name((id) => `#/components/schemas/${id}`, "URI");
 var bulkEmit = /* @__PURE__ */ chunkEV5I5HGT_js.__name((opts) => {
   const knownIds = new Set(opts.registry.ids());
@@ -1080,46 +1175,6 @@ var runPass = /* @__PURE__ */ chunkEV5I5HGT_js.__name((opts, io, knownIds) => {
   return filtered;
 }, "runPass");
 
-// src/document/http-methods.ts
-var HTTP_METHODS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace",
-  "query",
-  "search",
-  "propfind",
-  "proppatch",
-  "mkcol",
-  "copy",
-  "move",
-  "lock",
-  "unlock"
-];
-var forEachOperation = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, fn) => {
-  const paths = doc.paths;
-  if (paths === null || typeof paths !== "object") {
-    return;
-  }
-  for (const pathItem of Object.values(paths)) {
-    if (pathItem === null || typeof pathItem !== "object") {
-      continue;
-    }
-    const pathRecord = pathItem;
-    for (const method of HTTP_METHODS) {
-      const op = pathRecord[method];
-      if (op === null || typeof op !== "object") {
-        continue;
-      }
-      fn(op);
-    }
-  }
-}, "forEachOperation");
-
 // src/document/walk-refs.ts
 var walkRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((node, visit) => {
   if (node === null || typeof node !== "object") {
@@ -1192,22 +1247,12 @@ var collectInputExposedIds = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, class
     if (!isPlainRecord2(pathItem)) {
       continue;
     }
-    for (const operation of operationsOf(pathItem)) {
+    for (const operation of operationsOfPathItem(pathItem)) {
       collectRefsFromOperation(operation, classToDtoId, knownIds, ids);
     }
   }
   return ids;
 }, "collectInputExposedIds");
-var operationsOf = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem) => {
-  const out = [];
-  for (const method of HTTP_METHODS) {
-    const op = pathItem[method];
-    if (isPlainRecord2(op)) {
-      out.push(op);
-    }
-  }
-  return out;
-}, "operationsOf");
 var collectRefsFromOperation = /* @__PURE__ */ chunkEV5I5HGT_js.__name((operation, classToDtoId, knownIds, ids) => {
   if (isPlainRecord2(operation.requestBody)) {
     collectRefsFromContent(operation.requestBody.content, classToDtoId, knownIds, ids);
@@ -1269,7 +1314,7 @@ var collectOutputExposedIds = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, clas
     if (!isPlainRecord2(pathItem)) {
       continue;
     }
-    for (const operation of operationsOf(pathItem)) {
+    for (const operation of operationsOfPathItem(pathItem)) {
       collectRefsFromResponses(operation.responses, classToDtoId, knownIds, ids);
     }
   }
@@ -1728,6 +1773,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;
@@ -1797,11 +1861,7 @@ var rewriteRefs = /* @__PURE__ */ chunkEV5I5HGT_js.__name((params) => {
   }
 }, "rewriteRefs");
 var rewriteResponseSubtree = /* @__PURE__ */ chunkEV5I5HGT_js.__name((pathItem, divergentOutputIds) => {
-  for (const method of HTTP_METHODS) {
-    const op = pathItem[method];
-    if (op === null || typeof op !== "object") {
-      continue;
-    }
+  for (const op of operationsOfPathItem(pathItem)) {
     const responses = op.responses;
     if (responses === null || typeof responses !== "object") {
       continue;
@@ -1880,7 +1940,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 +1980,11 @@ var applyZodNest = /* @__PURE__ */ chunkEV5I5HGT_js.__name((doc, opts = {}) => {
     doc,
     collected: extended
   });
-  doc.openapi = OPENAPI_VERSION;
+  const openApiVersion = resolveOpenApiVersion(doc);
+  if (openApiVersion.startsWith("3.2.")) {
+    relocateExtensionOperations(doc);
+  }
+  doc.openapi = openApiVersion;
   return doc;
 }, "applyZodNest");