zod-nest 1.3.1 → 1.5.0

package/README.md

@@ -433,6 +433,14 @@ A compact, link-out index. Type signatures and detailed semantics live in the co
 **Schema engine** — single-schema mode and extension points
 - `toOpenApi(schema, opts)`, `createRegistry()`, `defaultRegistry`, `ZodNestRegistry`, `Override`, `OverrideContext`, `overrideJSONSchema(schema, fragment | { input?, output? })`, `OverrideJSONSchemaArg`, `ZodNestError`, `ZodNestUnrepresentableError`, `extend`, `getLineage`, `LineageEntry`
 
+**Helpers** (subpath: `zod-nest/helpers`) — common JSON Schema fragments + presets for assembling overrides
+- **Fragment catalog** (frozen consts): `dateTimeFragment`, `dateFragment`, `timeFragment`, `uuidFragment`, `emailFragment`, `uriFragment`, `hostnameFragment`, `ipv4Fragment`, `ipv6Fragment`, `binaryFragment`, `byteFragment`, `int32Fragment`, `int64Fragment`, `floatFragment`, `doubleFragment`, `opaqueFragment`
+- **Sugar functions**: `binary(opts?)`, `opaque(opts?)`
+- **Type-strict composition**: `enrich(base, extras)` — extras are typed per fragment family
+- **Pre-registered Zod schemas**: `FileSchema`, `BlobSchema`, `BufferSchema` (all `z.instanceof(...)` + `binaryFragment`)
+
+See [`docs/recipes/custom-openapi-overrides.md`](docs/recipes/custom-openapi-overrides.md) for the full catalog and usage patterns.
+
 ## Documentation
 
 | Topic | Doc |

package/dist/helpers/index.d.mts

@@ -0,0 +1,167 @@
+import { S as SchemaObject } from '../openapi.types-CFBG3Zz9.mjs';
+import * as buffer from 'buffer';
+import { z } from 'zod';
+import 'zod/v4/core';
+
+/**
+ * Common JSON Schema fragment catalog — reusable building blocks for assembling
+ * fragments by hand: alongside `z.custom<T>()`, in `overrideJSONSchema` calls,
+ * in custom override callbacks, in tests that build expected fragments.
+ *
+ * The catalog overlaps with what Zod constructs already emit (`z.uuid()` →
+ * `uuidFragment` shape, `z.email()` → `emailFragment` shape, etc.) — the
+ * helpers don't *replace* those Zod constructs; they're a parallel catalog
+ * for programmatic fragment assembly.
+ *
+ * Each fragment is `as const satisfies SchemaObject` so its literal type
+ * powers the dispatch in {@link enrich} — passing wrong-family options
+ * fails at compile time.
+ */
+declare const dateTimeFragment: {
+    readonly type: "string";
+    readonly format: "date-time";
+};
+declare const dateFragment: {
+    readonly type: "string";
+    readonly format: "date";
+};
+declare const timeFragment: {
+    readonly type: "string";
+    readonly format: "time";
+};
+declare const uuidFragment: {
+    readonly type: "string";
+    readonly format: "uuid";
+};
+declare const emailFragment: {
+    readonly type: "string";
+    readonly format: "email";
+};
+declare const uriFragment: {
+    readonly type: "string";
+    readonly format: "uri";
+};
+declare const hostnameFragment: {
+    readonly type: "string";
+    readonly format: "hostname";
+};
+declare const ipv4Fragment: {
+    readonly type: "string";
+    readonly format: "ipv4";
+};
+declare const ipv6Fragment: {
+    readonly type: "string";
+    readonly format: "ipv6";
+};
+declare const binaryFragment: {
+    readonly type: "string";
+    readonly format: "binary";
+};
+declare const byteFragment: {
+    readonly type: "string";
+    readonly format: "byte";
+};
+declare const int32Fragment: {
+    readonly type: "integer";
+    readonly format: "int32";
+};
+declare const int64Fragment: {
+    readonly type: "integer";
+    readonly format: "int64";
+};
+declare const floatFragment: {
+    readonly type: "number";
+    readonly format: "float";
+};
+declare const doubleFragment: {
+    readonly type: "number";
+    readonly format: "double";
+};
+declare const opaqueFragment: {
+    readonly type: "object";
+    readonly additionalProperties: true;
+};
+interface StringFormatOptions {
+    description?: string;
+    examples?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+interface BinaryFragmentOptions {
+    description?: string;
+    contentMediaType?: string;
+    contentEncoding?: string;
+}
+interface NumberFormatOptions {
+    description?: string;
+    examples?: number[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+}
+interface OpaqueFragmentOptions {
+    description?: string;
+}
+type OptionsFor<T> = T extends {
+    readonly format: 'binary';
+} ? BinaryFragmentOptions : T extends {
+    readonly format: 'date-time' | 'date' | 'time' | 'uuid' | 'email' | 'uri' | 'hostname' | 'ipv4' | 'ipv6' | 'byte';
+} ? StringFormatOptions : T extends {
+    readonly format: 'int32' | 'int64' | 'float' | 'double';
+} ? NumberFormatOptions : T extends {
+    readonly type: 'object';
+    readonly additionalProperties: true;
+} ? OpaqueFragmentOptions : never;
+/**
+ * Merge a catalog fragment with extras whose shape is dictated by the base
+ * fragment's family. Passing wrong-family extras (e.g. a `contentMediaType`
+ * onto `uuidFragment`) is a compile-time error.
+ *
+ * Returns a fresh `SchemaObject` — the original fragment is never mutated.
+ */
+declare const enrich: <T extends SchemaObject>(base: T, extras: OptionsFor<T>) => SchemaObject;
+/**
+ * Binary-content fragment with typed enrichment. Sugar for
+ * `enrich(binaryFragment, opts)` — exists because the `binary` option set
+ * (`contentMediaType` / `contentEncoding`) is nuanced enough to deserve a
+ * dedicated entry point and discoverable via auto-complete.
+ *
+ * @example
+ * overrideJSONSchema(z.instanceof(File), binary());
+ * overrideJSONSchema(z.instanceof(File), binary({ contentMediaType: 'application/pdf' }));
+ */
+declare const binary: (opts?: BinaryFragmentOptions) => SchemaObject;
+/**
+ * Opaque-object fragment with typed enrichment. Sugar for
+ * `enrich(opaqueFragment, opts)` — exists for parity with {@link binary}
+ * and because opaque passthrough payloads commonly carry a description
+ * explaining why the API doesn't introspect them.
+ *
+ * @example
+ * overrideJSONSchema(z.unknown(), opaque({ description: 'JWT passthrough' }));
+ */
+declare const opaque: (opts?: OpaqueFragmentOptions) => SchemaObject;
+
+/**
+ * Pre-registered Zod schemas for the common binary runtime types. Each
+ * schema is wired through `overrideJSONSchema` so it emits `binaryFragment`
+ * verbatim in OpenAPI — drop into a DTO without further setup.
+ *
+ * Node 22+ provides `File`, `Blob`, and `Buffer` as globals (zod-nest's
+ * `engines.node >=22`), so `z.instanceof(...)` at module load is safe.
+ *
+ * @example
+ * import { FileSchema } from 'zod-nest/helpers';
+ *
+ * class UploadDto extends createZodDto(
+ *   z.object({ file: FileSchema }),
+ * ) {}
+ */
+declare const FileSchema: z.ZodCustom<buffer.File, buffer.File>;
+declare const BlobSchema: z.ZodCustom<buffer.Blob, buffer.Blob>;
+declare const BufferSchema: z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
+
+export { type BinaryFragmentOptions, BlobSchema, BufferSchema, FileSchema, type NumberFormatOptions, type OpaqueFragmentOptions, type StringFormatOptions, binary, binaryFragment, byteFragment, dateFragment, dateTimeFragment, doubleFragment, emailFragment, enrich, floatFragment, hostnameFragment, int32Fragment, int64Fragment, ipv4Fragment, ipv6Fragment, opaque, opaqueFragment, timeFragment, uriFragment, uuidFragment };

package/dist/helpers/index.d.ts

@@ -0,0 +1,167 @@
+import { S as SchemaObject } from '../openapi.types-CFBG3Zz9.js';
+import * as buffer from 'buffer';
+import { z } from 'zod';
+import 'zod/v4/core';
+
+/**
+ * Common JSON Schema fragment catalog — reusable building blocks for assembling
+ * fragments by hand: alongside `z.custom<T>()`, in `overrideJSONSchema` calls,
+ * in custom override callbacks, in tests that build expected fragments.
+ *
+ * The catalog overlaps with what Zod constructs already emit (`z.uuid()` →
+ * `uuidFragment` shape, `z.email()` → `emailFragment` shape, etc.) — the
+ * helpers don't *replace* those Zod constructs; they're a parallel catalog
+ * for programmatic fragment assembly.
+ *
+ * Each fragment is `as const satisfies SchemaObject` so its literal type
+ * powers the dispatch in {@link enrich} — passing wrong-family options
+ * fails at compile time.
+ */
+declare const dateTimeFragment: {
+    readonly type: "string";
+    readonly format: "date-time";
+};
+declare const dateFragment: {
+    readonly type: "string";
+    readonly format: "date";
+};
+declare const timeFragment: {
+    readonly type: "string";
+    readonly format: "time";
+};
+declare const uuidFragment: {
+    readonly type: "string";
+    readonly format: "uuid";
+};
+declare const emailFragment: {
+    readonly type: "string";
+    readonly format: "email";
+};
+declare const uriFragment: {
+    readonly type: "string";
+    readonly format: "uri";
+};
+declare const hostnameFragment: {
+    readonly type: "string";
+    readonly format: "hostname";
+};
+declare const ipv4Fragment: {
+    readonly type: "string";
+    readonly format: "ipv4";
+};
+declare const ipv6Fragment: {
+    readonly type: "string";
+    readonly format: "ipv6";
+};
+declare const binaryFragment: {
+    readonly type: "string";
+    readonly format: "binary";
+};
+declare const byteFragment: {
+    readonly type: "string";
+    readonly format: "byte";
+};
+declare const int32Fragment: {
+    readonly type: "integer";
+    readonly format: "int32";
+};
+declare const int64Fragment: {
+    readonly type: "integer";
+    readonly format: "int64";
+};
+declare const floatFragment: {
+    readonly type: "number";
+    readonly format: "float";
+};
+declare const doubleFragment: {
+    readonly type: "number";
+    readonly format: "double";
+};
+declare const opaqueFragment: {
+    readonly type: "object";
+    readonly additionalProperties: true;
+};
+interface StringFormatOptions {
+    description?: string;
+    examples?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+interface BinaryFragmentOptions {
+    description?: string;
+    contentMediaType?: string;
+    contentEncoding?: string;
+}
+interface NumberFormatOptions {
+    description?: string;
+    examples?: number[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+}
+interface OpaqueFragmentOptions {
+    description?: string;
+}
+type OptionsFor<T> = T extends {
+    readonly format: 'binary';
+} ? BinaryFragmentOptions : T extends {
+    readonly format: 'date-time' | 'date' | 'time' | 'uuid' | 'email' | 'uri' | 'hostname' | 'ipv4' | 'ipv6' | 'byte';
+} ? StringFormatOptions : T extends {
+    readonly format: 'int32' | 'int64' | 'float' | 'double';
+} ? NumberFormatOptions : T extends {
+    readonly type: 'object';
+    readonly additionalProperties: true;
+} ? OpaqueFragmentOptions : never;
+/**
+ * Merge a catalog fragment with extras whose shape is dictated by the base
+ * fragment's family. Passing wrong-family extras (e.g. a `contentMediaType`
+ * onto `uuidFragment`) is a compile-time error.
+ *
+ * Returns a fresh `SchemaObject` — the original fragment is never mutated.
+ */
+declare const enrich: <T extends SchemaObject>(base: T, extras: OptionsFor<T>) => SchemaObject;
+/**
+ * Binary-content fragment with typed enrichment. Sugar for
+ * `enrich(binaryFragment, opts)` — exists because the `binary` option set
+ * (`contentMediaType` / `contentEncoding`) is nuanced enough to deserve a
+ * dedicated entry point and discoverable via auto-complete.
+ *
+ * @example
+ * overrideJSONSchema(z.instanceof(File), binary());
+ * overrideJSONSchema(z.instanceof(File), binary({ contentMediaType: 'application/pdf' }));
+ */
+declare const binary: (opts?: BinaryFragmentOptions) => SchemaObject;
+/**
+ * Opaque-object fragment with typed enrichment. Sugar for
+ * `enrich(opaqueFragment, opts)` — exists for parity with {@link binary}
+ * and because opaque passthrough payloads commonly carry a description
+ * explaining why the API doesn't introspect them.
+ *
+ * @example
+ * overrideJSONSchema(z.unknown(), opaque({ description: 'JWT passthrough' }));
+ */
+declare const opaque: (opts?: OpaqueFragmentOptions) => SchemaObject;
+
+/**
+ * Pre-registered Zod schemas for the common binary runtime types. Each
+ * schema is wired through `overrideJSONSchema` so it emits `binaryFragment`
+ * verbatim in OpenAPI — drop into a DTO without further setup.
+ *
+ * Node 22+ provides `File`, `Blob`, and `Buffer` as globals (zod-nest's
+ * `engines.node >=22`), so `z.instanceof(...)` at module load is safe.
+ *
+ * @example
+ * import { FileSchema } from 'zod-nest/helpers';
+ *
+ * class UploadDto extends createZodDto(
+ *   z.object({ file: FileSchema }),
+ * ) {}
+ */
+declare const FileSchema: z.ZodCustom<buffer.File, buffer.File>;
+declare const BlobSchema: z.ZodCustom<buffer.Blob, buffer.Blob>;
+declare const BufferSchema: z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
+
+export { type BinaryFragmentOptions, BlobSchema, BufferSchema, FileSchema, type NumberFormatOptions, type OpaqueFragmentOptions, type StringFormatOptions, binary, binaryFragment, byteFragment, dateFragment, dateTimeFragment, doubleFragment, emailFragment, enrich, floatFragment, hostnameFragment, int32Fragment, int64Fragment, ipv4Fragment, ipv6Fragment, opaque, opaqueFragment, timeFragment, uriFragment, uuidFragment };

package/dist/helpers/index.js

@@ -0,0 +1,126 @@
+'use strict';
+
+var zod = require('zod');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/helpers/fragments.ts
+var dateTimeFragment = {
+  type: "string",
+  format: "date-time"
+};
+var dateFragment = {
+  type: "string",
+  format: "date"
+};
+var timeFragment = {
+  type: "string",
+  format: "time"
+};
+var uuidFragment = {
+  type: "string",
+  format: "uuid"
+};
+var emailFragment = {
+  type: "string",
+  format: "email"
+};
+var uriFragment = {
+  type: "string",
+  format: "uri"
+};
+var hostnameFragment = {
+  type: "string",
+  format: "hostname"
+};
+var ipv4Fragment = {
+  type: "string",
+  format: "ipv4"
+};
+var ipv6Fragment = {
+  type: "string",
+  format: "ipv6"
+};
+var binaryFragment = {
+  type: "string",
+  format: "binary"
+};
+var byteFragment = {
+  type: "string",
+  format: "byte"
+};
+var int32Fragment = {
+  type: "integer",
+  format: "int32"
+};
+var int64Fragment = {
+  type: "integer",
+  format: "int64"
+};
+var floatFragment = {
+  type: "number",
+  format: "float"
+};
+var doubleFragment = {
+  type: "number",
+  format: "double"
+};
+var opaqueFragment = {
+  type: "object",
+  additionalProperties: true
+};
+var enrich = /* @__PURE__ */ __name((base, extras) => ({
+  ...base,
+  ...extras
+}), "enrich");
+var binary = /* @__PURE__ */ __name((opts) => ({
+  ...binaryFragment,
+  ...opts
+}), "binary");
+var opaque = /* @__PURE__ */ __name((opts) => ({
+  ...opaqueFragment,
+  ...opts
+}), "opaque");
+
+// src/schema/custom-override.ts
+var customOverrideMap = /* @__PURE__ */ new WeakMap();
+var isWrapper = /* @__PURE__ */ __name((arg) => "input" in arg || "output" in arg, "isWrapper");
+var overrideJSONSchema = /* @__PURE__ */ __name((schema, arg) => {
+  const overrideSchema = isWrapper(arg) ? arg : {
+    input: arg,
+    output: arg
+  };
+  customOverrideMap.set(schema, overrideSchema);
+  return schema;
+}, "overrideJSONSchema");
+
+// src/helpers/presets.ts
+var FileSchema = overrideJSONSchema(zod.z.instanceof(File), binaryFragment);
+var BlobSchema = overrideJSONSchema(zod.z.instanceof(Blob), binaryFragment);
+var BufferSchema = overrideJSONSchema(zod.z.instanceof(Buffer), binaryFragment);
+
+exports.BlobSchema = BlobSchema;
+exports.BufferSchema = BufferSchema;
+exports.FileSchema = FileSchema;
+exports.binary = binary;
+exports.binaryFragment = binaryFragment;
+exports.byteFragment = byteFragment;
+exports.dateFragment = dateFragment;
+exports.dateTimeFragment = dateTimeFragment;
+exports.doubleFragment = doubleFragment;
+exports.emailFragment = emailFragment;
+exports.enrich = enrich;
+exports.floatFragment = floatFragment;
+exports.hostnameFragment = hostnameFragment;
+exports.int32Fragment = int32Fragment;
+exports.int64Fragment = int64Fragment;
+exports.ipv4Fragment = ipv4Fragment;
+exports.ipv6Fragment = ipv6Fragment;
+exports.opaque = opaque;
+exports.opaqueFragment = opaqueFragment;
+exports.timeFragment = timeFragment;
+exports.uriFragment = uriFragment;
+exports.uuidFragment = uuidFragment;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/helpers/fragments.ts","../../src/schema/custom-override.ts","../../src/helpers/presets.ts"],"names":["dateTimeFragment","type","format","dateFragment","timeFragment","uuidFragment","emailFragment","uriFragment","hostnameFragment","ipv4Fragment","ipv6Fragment","binaryFragment","byteFragment","int32Fragment","int64Fragment","floatFragment","doubleFragment","opaqueFragment","additionalProperties","enrich","base","extras","binary","opts","opaque","customOverrideMap","WeakMap","isWrapper","arg","overrideJSONSchema","schema","overrideSchema","input","output","set","FileSchema","z","instanceof","File","BlobSchema","Blob","BufferSchema","Buffer"],"mappings":"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","file":"index.js","sourcesContent":["import type { SchemaObject } from '../schema/openapi.types.js';\n\n/**\n * Common JSON Schema fragment catalog — reusable building blocks for assembling\n * fragments by hand: alongside `z.custom<T>()`, in `overrideJSONSchema` calls,\n * in custom override callbacks, in tests that build expected fragments.\n *\n * The catalog overlaps with what Zod constructs already emit (`z.uuid()` →\n * `uuidFragment` shape, `z.email()` → `emailFragment` shape, etc.) — the\n * helpers don't *replace* those Zod constructs; they're a parallel catalog\n * for programmatic fragment assembly.\n *\n * Each fragment is `as const satisfies SchemaObject` so its literal type\n * powers the dispatch in {@link enrich} — passing wrong-family options\n * fails at compile time.\n */\n\n// ---------------------------------------------------------------------------\n// Layer 1 — Fragment catalog\n// ---------------------------------------------------------------------------\n\n// String formats (RFC-defined)\nexport const dateTimeFragment = {\n  type: 'string',\n  format: 'date-time',\n} as const satisfies SchemaObject;\nexport const dateFragment = { type: 'string', format: 'date' } as const satisfies SchemaObject;\nexport const timeFragment = { type: 'string', format: 'time' } as const satisfies SchemaObject;\nexport const uuidFragment = { type: 'string', format: 'uuid' } as const satisfies SchemaObject;\nexport const emailFragment = { type: 'string', format: 'email' } as const satisfies SchemaObject;\nexport const uriFragment = { type: 'string', format: 'uri' } as const satisfies SchemaObject;\nexport const hostnameFragment = {\n  type: 'string',\n  format: 'hostname',\n} as const satisfies SchemaObject;\nexport const ipv4Fragment = { type: 'string', format: 'ipv4' } as const satisfies SchemaObject;\nexport const ipv6Fragment = { type: 'string', format: 'ipv6' } as const satisfies SchemaObject;\n\n// Binary / encoded payloads\nexport const binaryFragment = { type: 'string', format: 'binary' } as const satisfies SchemaObject;\nexport const byteFragment = { type: 'string', format: 'byte' } as const satisfies SchemaObject;\n\n// Numeric formats (OpenAPI 3.1)\nexport const int32Fragment = { type: 'integer', format: 'int32' } as const satisfies SchemaObject;\nexport const int64Fragment = { type: 'integer', format: 'int64' } as const satisfies SchemaObject;\nexport const floatFragment = { type: 'number', format: 'float' } as const satisfies SchemaObject;\nexport const doubleFragment = { type: 'number', format: 'double' } as const satisfies SchemaObject;\n\n// Object passthrough\nexport const opaqueFragment = {\n  type: 'object',\n  additionalProperties: true,\n} as const satisfies SchemaObject;\n\n// ---------------------------------------------------------------------------\n// Layer 2 — Per-family option types\n// ---------------------------------------------------------------------------\n\nexport interface StringFormatOptions {\n  description?: string;\n  examples?: string[];\n  minLength?: number;\n  maxLength?: number;\n  pattern?: string;\n}\n\nexport interface BinaryFragmentOptions {\n  description?: string;\n  contentMediaType?: string;\n  contentEncoding?: string;\n}\n\nexport interface NumberFormatOptions {\n  description?: string;\n  examples?: number[];\n  minimum?: number;\n  maximum?: number;\n  exclusiveMinimum?: number;\n  exclusiveMaximum?: number;\n  multipleOf?: number;\n}\n\nexport interface OpaqueFragmentOptions {\n  description?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Layer 3 — Type-strict generic enrich\n// ---------------------------------------------------------------------------\n\n// `binary` discriminates before the generic string-format branch because its\n// option set diverges (contentMediaType / contentEncoding instead of length\n// constraints). Order matters here.\ntype OptionsFor<T> = T extends { readonly format: 'binary' }\n  ? BinaryFragmentOptions\n  : T extends {\n        readonly format:\n          | 'date-time'\n          | 'date'\n          | 'time'\n          | 'uuid'\n          | 'email'\n          | 'uri'\n          | 'hostname'\n          | 'ipv4'\n          | 'ipv6'\n          | 'byte';\n      }\n    ? StringFormatOptions\n    : T extends { readonly format: 'int32' | 'int64' | 'float' | 'double' }\n      ? NumberFormatOptions\n      : T extends { readonly type: 'object'; readonly additionalProperties: true }\n        ? OpaqueFragmentOptions\n        : never;\n\n/**\n * Merge a catalog fragment with extras whose shape is dictated by the base\n * fragment's family. Passing wrong-family extras (e.g. a `contentMediaType`\n * onto `uuidFragment`) is a compile-time error.\n *\n * Returns a fresh `SchemaObject` — the original fragment is never mutated.\n */\nexport const enrich = <T extends SchemaObject>(base: T, extras: OptionsFor<T>): SchemaObject => ({\n  ...base,\n  ...extras,\n});\n\n// ---------------------------------------------------------------------------\n// Layer 3b — Sugar functions\n// ---------------------------------------------------------------------------\n\n/**\n * Binary-content fragment with typed enrichment. Sugar for\n * `enrich(binaryFragment, opts)` — exists because the `binary` option set\n * (`contentMediaType` / `contentEncoding`) is nuanced enough to deserve a\n * dedicated entry point and discoverable via auto-complete.\n *\n * @example\n * overrideJSONSchema(z.instanceof(File), binary());\n * overrideJSONSchema(z.instanceof(File), binary({ contentMediaType: 'application/pdf' }));\n */\nexport const binary = (opts?: BinaryFragmentOptions): SchemaObject => ({\n  ...binaryFragment,\n  ...opts,\n});\n\n/**\n * Opaque-object fragment with typed enrichment. Sugar for\n * `enrich(opaqueFragment, opts)` — exists for parity with {@link binary}\n * and because opaque passthrough payloads commonly carry a description\n * explaining why the API doesn't introspect them.\n *\n * @example\n * overrideJSONSchema(z.unknown(), opaque({ description: 'JWT passthrough' }));\n */\nexport const opaque = (opts?: OpaqueFragmentOptions): SchemaObject => ({\n  ...opaqueFragment,\n  ...opts,\n});\n","import type { z } from 'zod';\nimport type { $ZodType } from 'zod/v4/core';\nimport type { SchemaObject } from './openapi.types.js';\nimport type { Override } from './override.js';\n\n/**\n * Argument shape for {@link overrideJSONSchema}. Two forms:\n *\n * - A raw `SchemaObject` — applied to both input and output emission.\n * - A `{ input?, output? }` wrapper — distinct fragments per emission side,\n *   for coercion shapes where input and output diverge (e.g.\n *   `z.union([z.array(item), item.transform((v) => [v])])` accepts\n *   `T | T[]` on input but always emits `T[]` on output).\n *\n * The wrapper form is detected by the presence of an `input` or `output`\n * key. Neither is a JSON Schema / OpenAPI 3.1 keyword, so the discriminator\n * is unambiguous in practice.\n */\nexport type OverrideJSONSchemaArg = SchemaObject | { input?: SchemaObject; output?: SchemaObject };\n\nexport interface StoredFragments {\n  input?: SchemaObject;\n  output?: SchemaObject;\n}\n\n/**\n * Per-instance JSON Schema registration store. Keyed by the Zod core type\n * (`$ZodType`) because that's what the override sees on `ctx.zodSchema`;\n * `z.ZodType` widens to `$ZodType` without a cast at the public API boundary.\n * Same WeakMap pattern as `composition.ts`'s `lineageMap`\n * (CLAUDE.md: \"transient, per-instance → WeakMap\").\n *\n * Value holds the per-direction fragments separately so the override factory\n * can pick the right one without surfacing `io` on `OverrideContext`.\n */\nconst customOverrideMap = new WeakMap<$ZodType, StoredFragments>();\n\nconst isWrapper = (\n  arg: OverrideJSONSchemaArg,\n): arg is { input?: SchemaObject; output?: SchemaObject } => 'input' in arg || 'output' in arg;\n\n/**\n * Register a fixed JSON Schema fragment for a specific Zod schema instance.\n *\n * Designed for shapes JSON Schema can't model directly — `z.custom<T>()` and\n * `z.instanceof(...)` (e.g. multipart `File` fields) — which Zod emits as `{}`,\n * tripping `ZodNestUnrepresentableError` in strict mode. Also useful for\n * coercion shapes where input and output diverge (`singleOrArray`-style\n * helpers).\n *\n * Two call shapes:\n *\n * ```ts\n * // 1. Single fragment — applied verbatim to both input and output emission.\n * overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });\n *\n * // 2. Divergent fragments — separate fragments per emission side. Omit a\n * //    side to leave Zod's default emission untouched on that side.\n * overrideJSONSchema(arrayOrItem, {\n *   input:  { anyOf: [arrFrag, itemFrag] },\n *   output: arrFrag,\n * });\n * ```\n *\n * Idempotent: subsequent calls for the same schema overwrite the prior\n * registration (last-write-wins).\n */\nexport const overrideJSONSchema = <T extends z.ZodType>(\n  schema: T,\n  arg: OverrideJSONSchemaArg,\n): T => {\n  const overrideSchema = isWrapper(arg) ? arg : { input: arg, output: arg };\n\n  customOverrideMap.set(schema, overrideSchema);\n\n  return schema;\n};\n\n/**\n * Read-only lookup into the registration store. Used by the engine to detect\n * when a pipe-typed schema covers its inner descent target with a relevant-io\n * fragment — see `buildToJsonSchemaOptions` in `engine.ts`. Returning a\n * possibly-`undefined` `StoredFragments` keeps the engine ignorant of the\n * underlying WeakMap.\n */\nexport const peekRegistration = (schema: $ZodType): StoredFragments | undefined =>\n  customOverrideMap.get(schema);\n\n/**\n * Internal override factory consulted by the engine. Closes over the current\n * emission direction so the lookup can pick the right registered fragment\n * without surfacing `io` on the `OverrideContext` public contract. Mirrors\n * `createCompositionOverride` at `engine.ts:98`.\n *\n * Mutates `ctx.jsonSchema` in-place (clears existing keys, then assigns the\n * fragment) because Zod's override pipeline doesn't propagate\n * `ctx.jsonSchema = newObj` reassignments — only mutations on the existing\n * object reach the caller (see `composition.ts` for the same constraint).\n *\n * No-ops if the schema isn't registered, or if the registered record has no\n * fragment for the current `io` direction.\n */\nexport const createCustomOverride = (io: 'input' | 'output'): Override => {\n  return ({ zodSchema, jsonSchema }) => {\n    const record = customOverrideMap.get(zodSchema);\n    if (record === undefined) {\n      return;\n    }\n    const fragment = record[io];\n    if (fragment === undefined) {\n      return;\n    }\n    for (const key of Object.keys(jsonSchema)) {\n      Reflect.deleteProperty(jsonSchema, key);\n    }\n    Object.assign(jsonSchema, fragment);\n  };\n};\n","import { z } from 'zod';\n\nimport { overrideJSONSchema } from '../schema/custom-override.js';\nimport { binaryFragment } from './fragments.js';\n\n/**\n * Pre-registered Zod schemas for the common binary runtime types. Each\n * schema is wired through `overrideJSONSchema` so it emits `binaryFragment`\n * verbatim in OpenAPI — drop into a DTO without further setup.\n *\n * Node 22+ provides `File`, `Blob`, and `Buffer` as globals (zod-nest's\n * `engines.node >=22`), so `z.instanceof(...)` at module load is safe.\n *\n * @example\n * import { FileSchema } from 'zod-nest/helpers';\n *\n * class UploadDto extends createZodDto(\n *   z.object({ file: FileSchema }),\n * ) {}\n */\n\nexport const FileSchema = overrideJSONSchema(z.instanceof(File), binaryFragment);\n\nexport const BlobSchema = overrideJSONSchema(z.instanceof(Blob), binaryFragment);\n\nexport const BufferSchema = overrideJSONSchema(z.instanceof(Buffer), binaryFragment);\n"]}

package/dist/helpers/index.mjs

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/helpers/fragments.ts
+var dateTimeFragment = {
+  type: "string",
+  format: "date-time"
+};
+var dateFragment = {
+  type: "string",
+  format: "date"
+};
+var timeFragment = {
+  type: "string",
+  format: "time"
+};
+var uuidFragment = {
+  type: "string",
+  format: "uuid"
+};
+var emailFragment = {
+  type: "string",
+  format: "email"
+};
+var uriFragment = {
+  type: "string",
+  format: "uri"
+};
+var hostnameFragment = {
+  type: "string",
+  format: "hostname"
+};
+var ipv4Fragment = {
+  type: "string",
+  format: "ipv4"
+};
+var ipv6Fragment = {
+  type: "string",
+  format: "ipv6"
+};
+var binaryFragment = {
+  type: "string",
+  format: "binary"
+};
+var byteFragment = {
+  type: "string",
+  format: "byte"
+};
+var int32Fragment = {
+  type: "integer",
+  format: "int32"
+};
+var int64Fragment = {
+  type: "integer",
+  format: "int64"
+};
+var floatFragment = {
+  type: "number",
+  format: "float"
+};
+var doubleFragment = {
+  type: "number",
+  format: "double"
+};
+var opaqueFragment = {
+  type: "object",
+  additionalProperties: true
+};
+var enrich = /* @__PURE__ */ __name((base, extras) => ({
+  ...base,
+  ...extras
+}), "enrich");
+var binary = /* @__PURE__ */ __name((opts) => ({
+  ...binaryFragment,
+  ...opts
+}), "binary");
+var opaque = /* @__PURE__ */ __name((opts) => ({
+  ...opaqueFragment,
+  ...opts
+}), "opaque");
+
+// src/schema/custom-override.ts
+var customOverrideMap = /* @__PURE__ */ new WeakMap();
+var isWrapper = /* @__PURE__ */ __name((arg) => "input" in arg || "output" in arg, "isWrapper");
+var overrideJSONSchema = /* @__PURE__ */ __name((schema, arg) => {
+  const overrideSchema = isWrapper(arg) ? arg : {
+    input: arg,
+    output: arg
+  };
+  customOverrideMap.set(schema, overrideSchema);
+  return schema;
+}, "overrideJSONSchema");
+
+// src/helpers/presets.ts
+var FileSchema = overrideJSONSchema(z.instanceof(File), binaryFragment);
+var BlobSchema = overrideJSONSchema(z.instanceof(Blob), binaryFragment);
+var BufferSchema = overrideJSONSchema(z.instanceof(Buffer), binaryFragment);
+
+export { BlobSchema, BufferSchema, FileSchema, binary, binaryFragment, byteFragment, dateFragment, dateTimeFragment, doubleFragment, emailFragment, enrich, floatFragment, hostnameFragment, int32Fragment, int64Fragment, ipv4Fragment, ipv6Fragment, opaque, opaqueFragment, timeFragment, uriFragment, uuidFragment };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/helpers/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/helpers/fragments.ts","../../src/schema/custom-override.ts","../../src/helpers/presets.ts"],"names":["dateTimeFragment","type","format","dateFragment","timeFragment","uuidFragment","emailFragment","uriFragment","hostnameFragment","ipv4Fragment","ipv6Fragment","binaryFragment","byteFragment","int32Fragment","int64Fragment","floatFragment","doubleFragment","opaqueFragment","additionalProperties","enrich","base","extras","binary","opts","opaque","customOverrideMap","WeakMap","isWrapper","arg","overrideJSONSchema","schema","overrideSchema","input","output","set","FileSchema","z","instanceof","File","BlobSchema","Blob","BufferSchema","Buffer"],"mappings":"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","file":"index.mjs","sourcesContent":["import type { SchemaObject } from '../schema/openapi.types.js';\n\n/**\n * Common JSON Schema fragment catalog — reusable building blocks for assembling\n * fragments by hand: alongside `z.custom<T>()`, in `overrideJSONSchema` calls,\n * in custom override callbacks, in tests that build expected fragments.\n *\n * The catalog overlaps with what Zod constructs already emit (`z.uuid()` →\n * `uuidFragment` shape, `z.email()` → `emailFragment` shape, etc.) — the\n * helpers don't *replace* those Zod constructs; they're a parallel catalog\n * for programmatic fragment assembly.\n *\n * Each fragment is `as const satisfies SchemaObject` so its literal type\n * powers the dispatch in {@link enrich} — passing wrong-family options\n * fails at compile time.\n */\n\n// ---------------------------------------------------------------------------\n// Layer 1 — Fragment catalog\n// ---------------------------------------------------------------------------\n\n// String formats (RFC-defined)\nexport const dateTimeFragment = {\n  type: 'string',\n  format: 'date-time',\n} as const satisfies SchemaObject;\nexport const dateFragment = { type: 'string', format: 'date' } as const satisfies SchemaObject;\nexport const timeFragment = { type: 'string', format: 'time' } as const satisfies SchemaObject;\nexport const uuidFragment = { type: 'string', format: 'uuid' } as const satisfies SchemaObject;\nexport const emailFragment = { type: 'string', format: 'email' } as const satisfies SchemaObject;\nexport const uriFragment = { type: 'string', format: 'uri' } as const satisfies SchemaObject;\nexport const hostnameFragment = {\n  type: 'string',\n  format: 'hostname',\n} as const satisfies SchemaObject;\nexport const ipv4Fragment = { type: 'string', format: 'ipv4' } as const satisfies SchemaObject;\nexport const ipv6Fragment = { type: 'string', format: 'ipv6' } as const satisfies SchemaObject;\n\n// Binary / encoded payloads\nexport const binaryFragment = { type: 'string', format: 'binary' } as const satisfies SchemaObject;\nexport const byteFragment = { type: 'string', format: 'byte' } as const satisfies SchemaObject;\n\n// Numeric formats (OpenAPI 3.1)\nexport const int32Fragment = { type: 'integer', format: 'int32' } as const satisfies SchemaObject;\nexport const int64Fragment = { type: 'integer', format: 'int64' } as const satisfies SchemaObject;\nexport const floatFragment = { type: 'number', format: 'float' } as const satisfies SchemaObject;\nexport const doubleFragment = { type: 'number', format: 'double' } as const satisfies SchemaObject;\n\n// Object passthrough\nexport const opaqueFragment = {\n  type: 'object',\n  additionalProperties: true,\n} as const satisfies SchemaObject;\n\n// ---------------------------------------------------------------------------\n// Layer 2 — Per-family option types\n// ---------------------------------------------------------------------------\n\nexport interface StringFormatOptions {\n  description?: string;\n  examples?: string[];\n  minLength?: number;\n  maxLength?: number;\n  pattern?: string;\n}\n\nexport interface BinaryFragmentOptions {\n  description?: string;\n  contentMediaType?: string;\n  contentEncoding?: string;\n}\n\nexport interface NumberFormatOptions {\n  description?: string;\n  examples?: number[];\n  minimum?: number;\n  maximum?: number;\n  exclusiveMinimum?: number;\n  exclusiveMaximum?: number;\n  multipleOf?: number;\n}\n\nexport interface OpaqueFragmentOptions {\n  description?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Layer 3 — Type-strict generic enrich\n// ---------------------------------------------------------------------------\n\n// `binary` discriminates before the generic string-format branch because its\n// option set diverges (contentMediaType / contentEncoding instead of length\n// constraints). Order matters here.\ntype OptionsFor<T> = T extends { readonly format: 'binary' }\n  ? BinaryFragmentOptions\n  : T extends {\n        readonly format:\n          | 'date-time'\n          | 'date'\n          | 'time'\n          | 'uuid'\n          | 'email'\n          | 'uri'\n          | 'hostname'\n          | 'ipv4'\n          | 'ipv6'\n          | 'byte';\n      }\n    ? StringFormatOptions\n    : T extends { readonly format: 'int32' | 'int64' | 'float' | 'double' }\n      ? NumberFormatOptions\n      : T extends { readonly type: 'object'; readonly additionalProperties: true }\n        ? OpaqueFragmentOptions\n        : never;\n\n/**\n * Merge a catalog fragment with extras whose shape is dictated by the base\n * fragment's family. Passing wrong-family extras (e.g. a `contentMediaType`\n * onto `uuidFragment`) is a compile-time error.\n *\n * Returns a fresh `SchemaObject` — the original fragment is never mutated.\n */\nexport const enrich = <T extends SchemaObject>(base: T, extras: OptionsFor<T>): SchemaObject => ({\n  ...base,\n  ...extras,\n});\n\n// ---------------------------------------------------------------------------\n// Layer 3b — Sugar functions\n// ---------------------------------------------------------------------------\n\n/**\n * Binary-content fragment with typed enrichment. Sugar for\n * `enrich(binaryFragment, opts)` — exists because the `binary` option set\n * (`contentMediaType` / `contentEncoding`) is nuanced enough to deserve a\n * dedicated entry point and discoverable via auto-complete.\n *\n * @example\n * overrideJSONSchema(z.instanceof(File), binary());\n * overrideJSONSchema(z.instanceof(File), binary({ contentMediaType: 'application/pdf' }));\n */\nexport const binary = (opts?: BinaryFragmentOptions): SchemaObject => ({\n  ...binaryFragment,\n  ...opts,\n});\n\n/**\n * Opaque-object fragment with typed enrichment. Sugar for\n * `enrich(opaqueFragment, opts)` — exists for parity with {@link binary}\n * and because opaque passthrough payloads commonly carry a description\n * explaining why the API doesn't introspect them.\n *\n * @example\n * overrideJSONSchema(z.unknown(), opaque({ description: 'JWT passthrough' }));\n */\nexport const opaque = (opts?: OpaqueFragmentOptions): SchemaObject => ({\n  ...opaqueFragment,\n  ...opts,\n});\n","import type { z } from 'zod';\nimport type { $ZodType } from 'zod/v4/core';\nimport type { SchemaObject } from './openapi.types.js';\nimport type { Override } from './override.js';\n\n/**\n * Argument shape for {@link overrideJSONSchema}. Two forms:\n *\n * - A raw `SchemaObject` — applied to both input and output emission.\n * - A `{ input?, output? }` wrapper — distinct fragments per emission side,\n *   for coercion shapes where input and output diverge (e.g.\n *   `z.union([z.array(item), item.transform((v) => [v])])` accepts\n *   `T | T[]` on input but always emits `T[]` on output).\n *\n * The wrapper form is detected by the presence of an `input` or `output`\n * key. Neither is a JSON Schema / OpenAPI 3.1 keyword, so the discriminator\n * is unambiguous in practice.\n */\nexport type OverrideJSONSchemaArg = SchemaObject | { input?: SchemaObject; output?: SchemaObject };\n\nexport interface StoredFragments {\n  input?: SchemaObject;\n  output?: SchemaObject;\n}\n\n/**\n * Per-instance JSON Schema registration store. Keyed by the Zod core type\n * (`$ZodType`) because that's what the override sees on `ctx.zodSchema`;\n * `z.ZodType` widens to `$ZodType` without a cast at the public API boundary.\n * Same WeakMap pattern as `composition.ts`'s `lineageMap`\n * (CLAUDE.md: \"transient, per-instance → WeakMap\").\n *\n * Value holds the per-direction fragments separately so the override factory\n * can pick the right one without surfacing `io` on `OverrideContext`.\n */\nconst customOverrideMap = new WeakMap<$ZodType, StoredFragments>();\n\nconst isWrapper = (\n  arg: OverrideJSONSchemaArg,\n): arg is { input?: SchemaObject; output?: SchemaObject } => 'input' in arg || 'output' in arg;\n\n/**\n * Register a fixed JSON Schema fragment for a specific Zod schema instance.\n *\n * Designed for shapes JSON Schema can't model directly — `z.custom<T>()` and\n * `z.instanceof(...)` (e.g. multipart `File` fields) — which Zod emits as `{}`,\n * tripping `ZodNestUnrepresentableError` in strict mode. Also useful for\n * coercion shapes where input and output diverge (`singleOrArray`-style\n * helpers).\n *\n * Two call shapes:\n *\n * ```ts\n * // 1. Single fragment — applied verbatim to both input and output emission.\n * overrideJSONSchema(FileSchema, { type: 'string', format: 'binary' });\n *\n * // 2. Divergent fragments — separate fragments per emission side. Omit a\n * //    side to leave Zod's default emission untouched on that side.\n * overrideJSONSchema(arrayOrItem, {\n *   input:  { anyOf: [arrFrag, itemFrag] },\n *   output: arrFrag,\n * });\n * ```\n *\n * Idempotent: subsequent calls for the same schema overwrite the prior\n * registration (last-write-wins).\n */\nexport const overrideJSONSchema = <T extends z.ZodType>(\n  schema: T,\n  arg: OverrideJSONSchemaArg,\n): T => {\n  const overrideSchema = isWrapper(arg) ? arg : { input: arg, output: arg };\n\n  customOverrideMap.set(schema, overrideSchema);\n\n  return schema;\n};\n\n/**\n * Read-only lookup into the registration store. Used by the engine to detect\n * when a pipe-typed schema covers its inner descent target with a relevant-io\n * fragment — see `buildToJsonSchemaOptions` in `engine.ts`. Returning a\n * possibly-`undefined` `StoredFragments` keeps the engine ignorant of the\n * underlying WeakMap.\n */\nexport const peekRegistration = (schema: $ZodType): StoredFragments | undefined =>\n  customOverrideMap.get(schema);\n\n/**\n * Internal override factory consulted by the engine. Closes over the current\n * emission direction so the lookup can pick the right registered fragment\n * without surfacing `io` on the `OverrideContext` public contract. Mirrors\n * `createCompositionOverride` at `engine.ts:98`.\n *\n * Mutates `ctx.jsonSchema` in-place (clears existing keys, then assigns the\n * fragment) because Zod's override pipeline doesn't propagate\n * `ctx.jsonSchema = newObj` reassignments — only mutations on the existing\n * object reach the caller (see `composition.ts` for the same constraint).\n *\n * No-ops if the schema isn't registered, or if the registered record has no\n * fragment for the current `io` direction.\n */\nexport const createCustomOverride = (io: 'input' | 'output'): Override => {\n  return ({ zodSchema, jsonSchema }) => {\n    const record = customOverrideMap.get(zodSchema);\n    if (record === undefined) {\n      return;\n    }\n    const fragment = record[io];\n    if (fragment === undefined) {\n      return;\n    }\n    for (const key of Object.keys(jsonSchema)) {\n      Reflect.deleteProperty(jsonSchema, key);\n    }\n    Object.assign(jsonSchema, fragment);\n  };\n};\n","import { z } from 'zod';\n\nimport { overrideJSONSchema } from '../schema/custom-override.js';\nimport { binaryFragment } from './fragments.js';\n\n/**\n * Pre-registered Zod schemas for the common binary runtime types. Each\n * schema is wired through `overrideJSONSchema` so it emits `binaryFragment`\n * verbatim in OpenAPI — drop into a DTO without further setup.\n *\n * Node 22+ provides `File`, `Blob`, and `Buffer` as globals (zod-nest's\n * `engines.node >=22`), so `z.instanceof(...)` at module load is safe.\n *\n * @example\n * import { FileSchema } from 'zod-nest/helpers';\n *\n * class UploadDto extends createZodDto(\n *   z.object({ file: FileSchema }),\n * ) {}\n */\n\nexport const FileSchema = overrideJSONSchema(z.instanceof(File), binaryFragment);\n\nexport const BlobSchema = overrideJSONSchema(z.instanceof(Blob), binaryFragment);\n\nexport const BufferSchema = overrideJSONSchema(z.instanceof(Buffer), binaryFragment);\n"]}