zod-nest 2.1.5 → 3.0.1

package/README.md

@@ -245,20 +245,11 @@ The id is what appears as the `components.schemas` key in the OpenAPI document a
 
 ```ts
 // Preferred — on the schema, via Zod's metadata
-const userSchema = z
-  .object({
-    /* ... */
-  })
-  .meta({ id: 'User' });
+const userSchema = z.object({/* ... */}).meta({ id: 'User' });
 class UserDto extends createZodDto(userSchema) {}
 
 // Also valid — passed through createZodDto's options
-class UserDto extends createZodDto(
-  z.object({
-    /* ... */
-  }),
-  { id: 'User' },
-) {}
+class UserDto extends createZodDto(z.object({/* ... */}), { id: 'User' }) {}
 ```
 
 Both produce the same OpenAPI output. `.meta({ id })` is preferred when the schema is hoisted into its own `const`, because the id stays with the schema — composition (`extend(parent, ...)`), shared input/output via `.meta({ id })` on the same schema reference, and any non-DTO use of the schema all pick up the same id without an extra hop through `createZodDto`'s options. Use the `createZodDto(schema, { id })` form when you don't own the schema (e.g. it comes from a third-party module) or when defining a small DTO with an inline schema, where chaining `.meta()` on the inline expression hurts readability.
@@ -525,7 +516,9 @@ See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-ove
 
 ## Compatibility matrix
 
-`zod-nest` declares explicit min + max peer-dep ranges in `package.json`: `zod >=4.4.0 <5.0.0`, `@nestjs/common >=11.0.1 <12.0.0`, `@nestjs/core >=11.0.1 <12.0.0`, `@nestjs/swagger >=11.0.0 <12.0.0`, `rxjs >=7.6.0 <8.0.0`, `reflect-metadata >=0.2.0 <0.3.0`, Node `>=22`. CI validates those claims by running the full test suite against the cells below; a red cell is a real blocker. Upper bounds are deliberate — a new peer major has to land in a real PR with a `/check-upstream-updates` audit before consumers can install it against this library.
+`zod-nest` declares explicit min + max peer-dep ranges in `package.json`: `zod >=4.4.0 <5.0.0`, `@nestjs/common >=11.0.1 <13.0.0`, `@nestjs/core >=11.0.1 <13.0.0`, `@nestjs/swagger >=11.0.0 <13.0.0`, `rxjs >=7.6.0 <8.0.0`, `reflect-metadata >=0.2.0 <0.3.0`, Node `>=22.12`. CI validates those claims by running the full test suite against the cells below; a red cell is a real blocker. Upper bounds are deliberate — a new peer major has to land in a real PR with a `/check-upstream-updates` audit before consumers can install it against this library.
+
+NestJS 11 and 12 are both supported. The Node floor is `>=22.12` rather than `>=22` because NestJS 12 ships as ESM: a CommonJS app doing `require('zod-nest')` reaches `require('@nestjs/common')`, and unflagged `require(esm)` only landed in Node 22.12.0.
 
 | Cell                      | `zod`  | `@nestjs/common` | `@nestjs/core` | `@nestjs/swagger` | `rxjs` | `reflect-metadata` |
 | ------------------------- | ------ | ---------------- | -------------- | ----------------- | ------ | ------------------ |
@@ -533,13 +526,14 @@ See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-ove
 | `zod-latest`              | latest | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | 0.2.0              |
 | `zod-4.5`                 | 4.5.4  | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | 0.2.0              |
 | `nest-latest`             | 4.4.0  | latest           | latest         | latest            | 7.6.0  | 0.2.0              |
+| `nest12`                  | 4.4.0  | 12.0.1           | 12.0.1         | 12.0.1            | 7.6.0  | 0.2.0              |
 | `rxjs-latest`             | 4.4.0  | 11.0.1           | 11.0.1         | 11.0.0            | latest | 0.2.0              |
 | `reflect-metadata-latest` | 4.4.0  | 11.0.1           | 11.0.1         | 11.0.0            | 7.6.0  | latest             |
 | `all-latest`              | latest | latest           | latest         | latest            | latest | latest             |
 
 One emission difference is visible across the supported `zod` range: from 4.5, a union of primitives — including `.nullable()` — emits `{ "type": ["string", "null"] }` where 4.4 emitted `{ "anyOf": [{ "type": "string" }, { "type": "null" }] }`. Both are valid OpenAPI 3.1 and validate identically; only the spelling changes. Everything else — `$ref` layout, composition `allOf`, input/output siblings, `paths` — is byte-identical across 4.4 and 4.5.
 
-Cell definitions live in [`.github/compat-matrix.json`](.github/compat-matrix.json). The CI workflow ([`.github/workflows/compat-matrix.yml`](.github/workflows/compat-matrix.yml)) runs on every push to `main` and weekly on Monday — when a cell fails, the workflow opens (or comments on) a GitHub issue labelled `compat-matrix-failure` so the regression is tracked outside the Actions UI. Editing the JSON is the formal way to extend or shrink supported ranges. Node is not matrixed — the `>=22` floor is enforced by `engines`.
+Cell definitions live in [`.github/compat-matrix.json`](.github/compat-matrix.json). The CI workflow ([`.github/workflows/compat-matrix.yml`](.github/workflows/compat-matrix.yml)) runs on every push to `main` and weekly on Monday — when a cell fails, the workflow opens (or comments on) a GitHub issue labelled `compat-matrix-failure` so the regression is tracked outside the Actions UI. Editing the JSON is the formal way to extend or shrink supported ranges. Node is not matrixed — the `>=22.12` floor is enforced by `engines`. Cells that move NestJS also pin `@nestjs/platform-express` and `@nestjs/testing` to the same major (omitted from the table above for width) — both peer-require matching `@nestjs/common` + `@nestjs/core` majors, so moving the others without them just produces a peer conflict.
 
 ## Migration from `nestjs-zod`
 

package/dist/index.d.mts

@@ -895,9 +895,11 @@ type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDA
  * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
  * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
  *
- * `AMBIGUOUS_RENAME`: two distinct DTO classes target the same registry id
- * with differing bodies — the rename pass can't write `components.schemas[id]`
- * unambiguously.
+ * `AMBIGUOUS_RENAME`: two distinct bodies target one `components.schemas[id]`.
+ * `details.preexisting` distinguishes the causes — `true` means the key was
+ * already populated before zod-nest emitted anything (on NestJS 12+, usually
+ * the native Standard Schema path emitting the component itself); `false`
+ * means two registered ids collided on one key.
  *
  * `DANGLING_REF`: a `$ref` in the doc points at a `components.schemas` key
  * that no longer exists after `applyZodNest`. Usually means a marker was

package/dist/index.d.ts

@@ -895,9 +895,11 @@ type ZodNestDocumentErrorCode = 'AMBIGUOUS_RENAME' | 'DANGLING_REF' | 'UNEXPANDA
  * Thrown by `applyZodNest` when the doc cannot be processed cleanly. Surfaces
  * at doc-build time so typos / mis-registrations fail in CI, not at runtime.
  *
- * `AMBIGUOUS_RENAME`: two distinct DTO classes target the same registry id
- * with differing bodies — the rename pass can't write `components.schemas[id]`
- * unambiguously.
+ * `AMBIGUOUS_RENAME`: two distinct bodies target one `components.schemas[id]`.
+ * `details.preexisting` distinguishes the causes — `true` means the key was
+ * already populated before zod-nest emitted anything (on NestJS 12+, usually
+ * the native Standard Schema path emitting the component itself); `false`
+ * means two registered ids collided on one key.
  *
  * `DANGLING_REF`: a `$ref` in the doc points at a `components.schemas` key
  * that no longer exists after `applyZodNest`. Usually means a marker was

package/dist/index.js

@@ -1063,13 +1063,22 @@ var normalizeZodNestOptions = /* @__PURE__ */ __name((opts) => {
 // src/pipes/validation.pipe.ts
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate, "_ts_decorate");
-function _ts_metadata(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
 }
 __name(_ts_metadata, "_ts_metadata");
 function _ts_param(paramIndex, decorator) {
@@ -1728,13 +1737,22 @@ var ZodCookies = /* @__PURE__ */ __name((schema, options) => {
 }, "ZodCookies");
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata2(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+function _ts_metadata2(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
 }
 __name(_ts_metadata2, "_ts_metadata");
 function _ts_param2(paramIndex, decorator) {
@@ -2410,8 +2428,18 @@ var mergeSchemas = /* @__PURE__ */ __name((params) => {
     ...collected.inputExposedIds,
     ...collected.outputExposedIds
   ]);
+  const foreignKeys = collectForeignKeys(schemas);
   for (const id of exposedIds) {
-    applyTruthTable(schemas, id, collected.inputExposedIds.has(id), collected.outputExposedIds.has(id), inputSchemas.get(id), outputSchemas.get(id), divergentOutputIds);
+    applyTruthTable({
+      schemas,
+      id,
+      inputExposed: collected.inputExposedIds.has(id),
+      outputExposed: collected.outputExposedIds.has(id),
+      inputBody: inputSchemas.get(id),
+      outputBody: outputSchemas.get(id),
+      divergentOutputIds,
+      foreignKeys
+    });
   }
   for (const [className, dtoId] of collected.classToDtoId) {
     if (className === dtoId) {
@@ -2433,24 +2461,35 @@ var ensureComponentsSchemas = /* @__PURE__ */ __name((doc) => {
   components.schemas = schemas;
   return schemas;
 }, "ensureComponentsSchemas");
-var applyTruthTable = /* @__PURE__ */ __name((schemas, id, inputExposed, outputExposed, inputBody, outputBody, divergentOutputIds) => {
+var applyTruthTable = /* @__PURE__ */ __name((params) => {
+  const { schemas, id, inputExposed, outputExposed, inputBody, outputBody } = params;
+  const { divergentOutputIds, foreignKeys } = params;
   if (inputExposed && !outputExposed) {
-    writeOrThrowAmbiguous(schemas, id, inputBody);
+    writeOrThrowAmbiguous(schemas, id, inputBody, foreignKeys);
     return;
   }
   if (!inputExposed && outputExposed) {
-    writeOrThrowAmbiguous(schemas, id, outputBody);
+    writeOrThrowAmbiguous(schemas, id, outputBody, foreignKeys);
     return;
   }
   if (canonicalEqual(inputBody, outputBody)) {
-    writeOrThrowAmbiguous(schemas, id, inputBody);
+    writeOrThrowAmbiguous(schemas, id, inputBody, foreignKeys);
     return;
   }
-  writeOrThrowAmbiguous(schemas, id, inputBody);
-  writeOrThrowAmbiguous(schemas, `${id}${OUTPUT_SUFFIX}`, outputBody);
+  writeOrThrowAmbiguous(schemas, id, inputBody, foreignKeys);
+  writeOrThrowAmbiguous(schemas, `${id}${OUTPUT_SUFFIX}`, outputBody, foreignKeys);
   divergentOutputIds.add(id);
 }, "applyTruthTable");
-var writeOrThrowAmbiguous = /* @__PURE__ */ __name((schemas, key, body) => {
+var collectForeignKeys = /* @__PURE__ */ __name((schemas) => {
+  const foreign = /* @__PURE__ */ new Set();
+  for (const [key, body] of Object.entries(schemas)) {
+    if (!isMarkerPlaceholder(body)) {
+      foreign.add(key);
+    }
+  }
+  return foreign;
+}, "collectForeignKeys");
+var writeOrThrowAmbiguous = /* @__PURE__ */ __name((schemas, key, body, foreignKeys) => {
   if (body === void 0) {
     return;
   }
@@ -2459,10 +2498,18 @@ var writeOrThrowAmbiguous = /* @__PURE__ */ __name((schemas, key, body) => {
     schemas[key] = body;
     return;
   }
-  throw new ZodNestDocumentError("AMBIGUOUS_RENAME", `Two distinct schemas target \`components.schemas[${key}]\` with differing bodies \u2014 multiple createZodDto classes likely share the same dtoId. Set distinct \`options.id\` values, or align the class names so renames are unambiguous.`, {
-    key
+  const preexisting = foreignKeys.has(key);
+  throw new ZodNestDocumentError("AMBIGUOUS_RENAME", `Two distinct schemas target \`components.schemas[${key}]\` with differing bodies \u2014 ` + ambiguousRenameHint(key, preexisting), {
+    key,
+    preexisting
   });
 }, "writeOrThrowAmbiguous");
+var ambiguousRenameHint = /* @__PURE__ */ __name((key, preexisting) => {
+  if (preexisting) {
+    return `\`${key}\` was already populated before zod-nest emitted anything. On NestJS 12+ the usual cause is the native Standard Schema path \u2014 \`@Body({ schema })\`, \`@Query({ schema })\` or \`@ApiResponse({ standardSchema })\` \u2014 which makes @nestjs/swagger emit the component itself, in its OpenAPI 3.0 shape. Route the schema through \`createZodDto\` / \`@ZodBody\` / \`@ZodResponse\` instead, or drop \`applyZodNest\` and let Nest own the whole document. A hand-authored component or a doc pre-pass under the same name does this too.`;
+  }
+  return "Two registered ids resolved to the same key \u2014 most often an `<Id>Output` sibling from a diverging input/output schema colliding with a DTO explicitly registered as `<Id>Output`. Rename one of them, or set a distinct `options.id`.";
+}, "ambiguousRenameHint");
 var isMarkerPlaceholder = /* @__PURE__ */ __name((value) => {
   if (value === null || typeof value !== "object") {
     return false;