zod-nest 0.12.0 → 1.0.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`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
+- `toOpenApi(schema, opts)`, `createRegistry()`, `defaultRegistry`, `ZodNestRegistry`, `Override`, `OverrideContext`, `overrideJSONSchema(schema, fragment)`, `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,6 +79,28 @@ declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P,
  */
 declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
+/**
+ * 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).
+ *
+ * Idempotent: subsequent calls for the same schema overwrite the prior
+ * registration (last-write-wins).
+ *
+ * @example
+ *   const FileSchema = z.instanceof(File);
+ *   overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ *
+ *   class UploadDto extends createZodDto(z.object({ file: FileSchema })) {}
+ *   // OpenAPI doc emits `properties.file = { type: 'string', format: 'binary' }`
+ */
+declare const overrideJSONSchema: (schema: z.ZodType, jsonSchema: SchemaObject) => void;
+
 interface ToOpenApiOptions {
     io: 'input' | 'output';
     registry: ZodNestRegistry;
@@ -527,4 +549,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, 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 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,6 +79,28 @@ declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P,
  */
 declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
 
+/**
+ * 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).
+ *
+ * Idempotent: subsequent calls for the same schema overwrite the prior
+ * registration (last-write-wins).
+ *
+ * @example
+ *   const FileSchema = z.instanceof(File);
+ *   overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });
+ *
+ *   class UploadDto extends createZodDto(z.object({ file: FileSchema })) {}
+ *   // OpenAPI doc emits `properties.file = { type: 'string', format: 'binary' }`
+ */
+declare const overrideJSONSchema: (schema: z.ZodType, jsonSchema: SchemaObject) => void;
+
 interface ToOpenApiOptions {
     io: 'input' | 'output';
     registry: ZodNestRegistry;
@@ -527,4 +549,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, 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 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

@@ -104,6 +104,22 @@ var createCompositionOverride = /* @__PURE__ */ __name((opts) => {
   };
 }, "createCompositionOverride");
 
+// 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) {
+    return;
+  }
+  for (const key of Object.keys(jsonSchema)) {
+    Reflect.deleteProperty(jsonSchema, key);
+  }
+  Object.assign(jsonSchema, fragment);
+}, "customOverride");
+
 // src/schema/errors.ts
 var ZodNestError = class extends Error {
   static {
@@ -232,7 +248,7 @@ var buildToJsonSchemaOptions = /* @__PURE__ */ __name((params) => {
     buildRef: params.uri ?? DEFAULT_BUILD_REF,
     registry: params.registry
   });
-  const merged = combine(primitiveOverride, compositionOverride, params.override);
+  const merged = combine(primitiveOverride, compositionOverride, customOverride, params.override);
   const unrepresentableHits = [];
   const wrapped = /* @__PURE__ */ __name((ctx) => {
     merged(ctx);
@@ -1482,6 +1498,7 @@ exports.getLineage = getLineage;
 exports.isZodDto = isZodDto;
 exports.isZodDtoMarker = isZodDtoMarker;
 exports.makeZodDtoMarker = makeZodDtoMarker;
+exports.overrideJSONSchema = overrideJSONSchema;
 exports.resolveEffectiveStatus = resolveEffectiveStatus;
 exports.toOpenApi = toOpenApi;
 //# sourceMappingURL=index.js.map