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

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) => {