zod-nest 0.13.0 → 1.1.0

package/README.md

@@ -431,7 +431,7 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 - `ZodNestModule.forRoot(options?)`, `ZodNestModuleOptions`, `DEFAULT_REDACT_KEYS`, `DEFAULT_MAX_LOGGED_VALUE_BYTES`, `ZOD_NEST_OPTIONS`
 
 **Schema engine** — single-schema mode and extension points
-- `toOpenApi(schema, opts)`, `createRegistry()`, `defaultRegistry`, `ZodNestRegistry`, `Override`, `OverrideContext`, `overrideJSONSchema(schema, fragment)`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
+- `toOpenApi(schema, opts)`, `createRegistry()`, `defaultRegistry`, `ZodNestRegistry`, `Override`, `OverrideContext`, `overrideJSONSchema(schema, fragment | { input?, output? })`, `OverrideJSONSchemaArg`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
 
 ## Documentation
 
@@ -450,16 +450,18 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 
 ## Compatibility matrix
 
-`zod-nest` declares broad peer-dep ranges in `package.json`: `zod >= 4.4.0`, `@nestjs/common >= 10`, `@nestjs/core >= 10`, `@nestjs/swagger >= 8`, `rxjs >= 7`, Node `>= 22`. CI validates those claims by running the full test suite against the cells below; a red cell is a real blocker.
+`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.1.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.
 
-| Cell | `zod` | `@nestjs/common` | `@nestjs/core` | `@nestjs/swagger` |
-|---|---|---|---|---|
-| `floor` | 4.4.0 | 10.0.0 | 10.0.0 | 8.0.0 |
-| `zod-latest` | latest | 10.0.0 | 10.0.0 | 8.0.0 |
-| `nest-latest` | 4.4.0 | latest | latest | latest |
-| `all-latest` | latest | latest | latest | latest |
+| Cell | `zod` | `@nestjs/common` | `@nestjs/core` | `@nestjs/swagger` | `rxjs` | `reflect-metadata` |
+|---|---|---|---|---|---|---|
+| `floor` | 4.4.0 | 11.0.1 | 11.0.1 | 11.0.0 | 7.1.0 | 0.2.0 |
+| `zod-latest` | latest | 11.0.1 | 11.0.1 | 11.0.0 | 7.1.0 | 0.2.0 |
+| `nest-latest` | 4.4.0 | latest | latest | latest | 7.1.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.1.0 | latest |
+| `all-latest` | latest | latest | latest | latest | latest | latest |
 
-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 + rxjs are not currently matrixed (Node floor `22` is enforced by `engines`; rxjs has been stable enough not to need cells yet).
+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`.
 
 ## Migration from `nestjs-zod`
 

package/dist/index.d.mts

@@ -79,27 +79,50 @@ declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P,
  */
 declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
+/**
+ * Argument shape for {@link overrideJSONSchema}. Two forms:
+ *
+ * - A raw `SchemaObject` — applied to both input and output emission.
+ * - A `{ input?, output? }` wrapper — distinct fragments per emission side,
+ *   for coercion shapes where input and output diverge (e.g.
+ *   `z.union([z.array(item), item.transform((v) => [v])])` accepts
+ *   `T | T[]` on input but always emits `T[]` on output).
+ *
+ * The wrapper form is detected by the presence of an `input` or `output`
+ * key. Neither is a JSON Schema / OpenAPI 3.1 keyword, so the discriminator
+ * is unambiguous in practice.
+ */
+type OverrideJSONSchemaArg = SchemaObject | {
+    input?: SchemaObject;
+    output?: SchemaObject;
+};
 /**
  * Register a fixed JSON Schema fragment for a specific Zod schema instance.
  *
  * Designed for shapes JSON Schema can't model directly — `z.custom<T>()` and
  * `z.instanceof(...)` (e.g. multipart `File` fields) — which Zod emits as `{}`,
- * tripping `ZodNestUnrepresentableError` in strict mode. After registration
- * the engine writes the supplied fragment in-place wherever that schema
- * instance is emitted (single-schema `toOpenApi`, bulk emission, nested
- * inside `z.object({...})`, anywhere).
+ * tripping `ZodNestUnrepresentableError` in strict mode. Also useful for
+ * coercion shapes where input and output diverge (`singleOrArray`-style
+ * helpers).
  *
- * Idempotent: subsequent calls for the same schema overwrite the prior
- * registration (last-write-wins).
+ * Two call shapes:
  *
- * @example
- *   const FileSchema = z.instanceof(File);
- *   overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ * ```ts
+ * // 1. Single fragment — applied verbatim to both input and output emission.
+ * overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ *
+ * // 2. Divergent fragments — separate fragments per emission side. Omit a
+ * //    side to leave Zod's default emission untouched on that side.
+ * overrideJSONSchema(arrayOrItem, {
+ *   input:  { anyOf: [arrFrag, itemFrag] },
+ *   output: arrFrag,
+ * });
+ * ```
  *
- *   class UploadDto extends createZodDto(z.object({ file: FileSchema })) {}
- *   // OpenAPI doc emits `properties.file = { type: 'string', format: 'binary' }`
+ * Idempotent: subsequent calls for the same schema overwrite the prior
+ * registration (last-write-wins).
  */
-declare const overrideJSONSchema: (schema: z.ZodType, jsonSchema: SchemaObject) => void;
+declare const overrideJSONSchema: (schema: z.ZodType, arg: OverrideJSONSchemaArg) => void;
 
 interface ToOpenApiOptions {
     io: 'input' | 'output';
@@ -549,4 +572,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -79,27 +79,50 @@ declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P,
  */
 declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
+/**
+ * Argument shape for {@link overrideJSONSchema}. Two forms:
+ *
+ * - A raw `SchemaObject` — applied to both input and output emission.
+ * - A `{ input?, output? }` wrapper — distinct fragments per emission side,
+ *   for coercion shapes where input and output diverge (e.g.
+ *   `z.union([z.array(item), item.transform((v) => [v])])` accepts
+ *   `T | T[]` on input but always emits `T[]` on output).
+ *
+ * The wrapper form is detected by the presence of an `input` or `output`
+ * key. Neither is a JSON Schema / OpenAPI 3.1 keyword, so the discriminator
+ * is unambiguous in practice.
+ */
+type OverrideJSONSchemaArg = SchemaObject | {
+    input?: SchemaObject;
+    output?: SchemaObject;
+};
 /**
  * Register a fixed JSON Schema fragment for a specific Zod schema instance.
  *
  * Designed for shapes JSON Schema can't model directly — `z.custom<T>()` and
  * `z.instanceof(...)` (e.g. multipart `File` fields) — which Zod emits as `{}`,
- * tripping `ZodNestUnrepresentableError` in strict mode. After registration
- * the engine writes the supplied fragment in-place wherever that schema
- * instance is emitted (single-schema `toOpenApi`, bulk emission, nested
- * inside `z.object({...})`, anywhere).
+ * tripping `ZodNestUnrepresentableError` in strict mode. Also useful for
+ * coercion shapes where input and output diverge (`singleOrArray`-style
+ * helpers).
  *
- * Idempotent: subsequent calls for the same schema overwrite the prior
- * registration (last-write-wins).
+ * Two call shapes:
  *
- * @example
- *   const FileSchema = z.instanceof(File);
- *   overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ * ```ts
+ * // 1. Single fragment — applied verbatim to both input and output emission.
+ * overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ *
+ * // 2. Divergent fragments — separate fragments per emission side. Omit a
+ * //    side to leave Zod's default emission untouched on that side.
+ * overrideJSONSchema(arrayOrItem, {
+ *   input:  { anyOf: [arrFrag, itemFrag] },
+ *   output: arrFrag,
+ * });
+ * ```
  *
- *   class UploadDto extends createZodDto(z.object({ file: FileSchema })) {}
- *   // OpenAPI doc emits `properties.file = { type: 'string', format: 'binary' }`
+ * Idempotent: subsequent calls for the same schema overwrite the prior
+ * registration (last-write-wins).
  */
-declare const overrideJSONSchema: (schema: z.ZodType, jsonSchema: SchemaObject) => void;
+declare const overrideJSONSchema: (schema: z.ZodType, arg: OverrideJSONSchemaArg) => void;
 
 interface ToOpenApiOptions {
     io: 'input' | 'output';
@@ -549,4 +572,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type OverrideJSONSchemaArg, type ResponseStatusInput, type ResponseStatusWildcard, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, overrideJSONSchema, resolveEffectiveStatus, toOpenApi };

package/dist/index.js

@@ -106,19 +106,36 @@ var createCompositionOverride = /* @__PURE__ */ __name((opts) => {
 
 // src/schema/custom-override.ts
 var customOverrideMap = /* @__PURE__ */ new WeakMap();
-var overrideJSONSchema = /* @__PURE__ */ __name((schema, jsonSchema) => {
-  customOverrideMap.set(schema, jsonSchema);
-}, "overrideJSONSchema");
-var customOverride = /* @__PURE__ */ __name(({ zodSchema, jsonSchema }) => {
-  const fragment = customOverrideMap.get(zodSchema);
-  if (fragment === void 0) {
+var isWrapper = /* @__PURE__ */ __name((arg) => "input" in arg || "output" in arg, "isWrapper");
+var overrideJSONSchema = /* @__PURE__ */ __name((schema, arg) => {
+  if (isWrapper(arg)) {
+    customOverrideMap.set(schema, {
+      input: arg.input,
+      output: arg.output
+    });
     return;
   }
-  for (const key of Object.keys(jsonSchema)) {
-    Reflect.deleteProperty(jsonSchema, key);
-  }
-  Object.assign(jsonSchema, fragment);
-}, "customOverride");
+  customOverrideMap.set(schema, {
+    input: arg,
+    output: arg
+  });
+}, "overrideJSONSchema");
+var createCustomOverride = /* @__PURE__ */ __name((io) => {
+  return ({ zodSchema, jsonSchema }) => {
+    const record = customOverrideMap.get(zodSchema);
+    if (record === void 0) {
+      return;
+    }
+    const fragment = record[io];
+    if (fragment === void 0) {
+      return;
+    }
+    for (const key of Object.keys(jsonSchema)) {
+      Reflect.deleteProperty(jsonSchema, key);
+    }
+    Object.assign(jsonSchema, fragment);
+  };
+}, "createCustomOverride");
 
 // src/schema/errors.ts
 var ZodNestError = class extends Error {
@@ -248,6 +265,7 @@ var buildToJsonSchemaOptions = /* @__PURE__ */ __name((params) => {
     buildRef: params.uri ?? DEFAULT_BUILD_REF,
     registry: params.registry
   });
+  const customOverride = createCustomOverride(params.io);
   const merged = combine(primitiveOverride, compositionOverride, customOverride, params.override);
   const unrepresentableHits = [];
   const wrapped = /* @__PURE__ */ __name((ctx) => {