@kubb/plugin-zod 5.1.0 → 5.1.1

package/dist/index.d.ts

@@ -73,14 +73,18 @@ type PrinterZodOptions = {
    */
   cyclicSchemas?: ReadonlySet<string>;
   /**
-   * Print direction for `dateType: 'date'` fields (`Date` in TypeScript):
-   * - `'output'` (default): decode the wire `string` into a `Date` (response bodies).
-   * - `'input'`: encode a `Date` back into the wire `string` (request bodies/params).
+   * Which way a node converts between its wire type and its runtime type:
+   * - `'decode'` (default): wire into runtime, used by response schemas.
+   * - `'encode'`: runtime back to wire, used by request bodies and parameters.
    *
-   * Diverging the directions requires the generator to emit an `${name}InputSchema`
-   * variant for each date-bearing component.
+   * Named for the conversion rather than the slot, since Zod's own `z.input` and `z.output`
+   * describe a different axis and read inverted here: the `'decode'` schema is the one whose
+   * `z.input` is the wire type.
+   *
+   * A handler returning different output per direction makes the generator emit an
+   * `${name}InputSchema` variant for that component.
    */
-  direction?: 'input' | 'output';
+  direction?: 'encode' | 'decode';
   /**
    * Custom handler map for node type overrides.
    */
@@ -351,6 +355,9 @@ type Options = OutputOptions & {
    * validate with `z.coerce.date()` instead of the string-to-Date codec. Fields
    * kept as ISO strings (`z.iso.date()`, `z.iso.datetime()`) are never coerced.
    *
+   * `bigint` fields (`format: int64`) always coerce, regardless of this option:
+   * `JSON.parse` hands back a `number`, which a plain `z.bigint()` rejects.
+   *
    * @default false
    * @see https://zod.dev/?id=coercion-for-primitives
    */
@@ -391,6 +398,11 @@ type Options = OutputOptions & {
   /**
    * Replace the Zod handler for a specific schema type (`'integer'`, `'date'`, ...).
    * When `mini: true`, overrides target the Zod Mini printer instead.
+   *
+   * A handler that returns a different expression per `this.options.direction` declares a two-way
+   * conversion, such as a `time` field carried as an ISO string but modeled as a
+   * `Temporal.PlainTime`. The generator then emits an `${name}InputSchema` variant for request
+   * bodies to resolve to, `$ref` included. Ignore `direction` and only the printed output changes.
    */
   printer?: {
     nodes?: PrinterZodNodes | PrinterZodMiniNodes;

package/dist/index.js

@@ -779,68 +779,6 @@ function shouldCoerce(coercion, type) {
 	return !!coercion[type];
 }
 /**
-* Registered codecs, checked in order.
-*/
-const codecs = [{
-	matches(node) {
-		return node.type === "date" && node.representation === "date";
-	},
-	decode(node) {
-		return node.format === "date" ? "z.iso.date().transform((value) => new Date(value))" : "z.iso.datetime().transform((value) => new Date(value))";
-	},
-	encode(node) {
-		return node.format === "date" ? "z.date().transform((value) => value.toISOString().slice(0, 10))" : "z.date().transform((value) => value.toISOString())";
-	}
-}];
-/**
-* Returns the codec for this node, or `undefined` when the node needs no
-* encode/decode (its wire and runtime types match).
-*/
-function getCodec(node) {
-	if (!node) return void 0;
-	return codecs.find((codec) => codec.matches(node));
-}
-/**
-* Returns `true` when the node itself is encoded/decoded by a codec.
-*/
-function hasCodec(node) {
-	return getCodec(node) !== void 0;
-}
-/**
-* Returns `true` when the schema transitively contains a codec node —
-* a value whose runtime type differs from its wire type (see {@link hasCodec}),
-* so it must be decoded (response) or encoded (request) at the validation boundary.
-* `$ref`s are followed via their resolved schema; a `seen` set guards cycles.
-*/
-function containsCodec(node, seen = /* @__PURE__ */ new Set()) {
-	if (!node) return false;
-	if (hasCodec(node)) return true;
-	if (node.type === "ref") {
-		if (!node.ref) return false;
-		const refName = extractRefName(node.ref);
-		if (refName) {
-			if (seen.has(refName)) return false;
-			seen.add(refName);
-		}
-		const resolved = syncSchemaRef(node);
-		if (resolved.type === "ref") return false;
-		return containsCodec(resolved, seen);
-	}
-	const children = [];
-	if ("properties" in node && node.properties) children.push(...node.properties.map((prop) => prop.schema));
-	if ("items" in node && node.items) children.push(...node.items);
-	if ("members" in node && node.members) children.push(...node.members);
-	if ("additionalProperties" in node && node.additionalProperties && node.additionalProperties !== true) children.push(node.additionalProperties);
-	return children.some((child) => containsCodec(child, seen));
-}
-/**
-* Collects the names of `$ref` schemas that transitively contain a codec, so the generator can route
-* them to their input (encode) variant.
-*/
-function collectCodecRefNames(node) {
-	return ast.collectSync(node, { schema: (n) => n.type === "ref" && n.ref && containsCodec(n) ? ast.resolveRefName(n) ?? void 0 : void 0 });
-}
-/**
 * Whether the node is a plain inline object whose shape can be lifted into an `.extend({ … })`
 * argument. A catchall, `patternProperties`, or a nullable/optional wrapper cannot, so those stay
 * on `.and(…)`.
@@ -1153,6 +1091,168 @@ function buildZodObjectShape(ctx, node) {
 	}));
 }
 /**
+* Types the direction probe skips. They delegate to their children rather than reading
+* `direction` themselves, so {@link containsDirectionalNode} walks into the children instead.
+*/
+const CONTAINER_TYPES = /* @__PURE__ */ new Set([
+	"object",
+	"array",
+	"tuple",
+	"union",
+	"intersection",
+	"ref"
+]);
+/**
+* Runs the node's effective handler (a `printer.nodes` override, else the built-in) once per
+* direction and reports whether the two disagree. That difference is what makes a component
+* need an `${name}InputSchema` variant.
+*/
+function variesByDirection({ node, printerOptions }) {
+	if (CONTAINER_TYPES.has(node.type)) return false;
+	const handler = printerOptions.nodes?.[node.type] ?? scalarNodes[node.type];
+	if (!handler) return false;
+	const call = (direction) => {
+		const context = {
+			options: {
+				...printerOptions,
+				direction
+			},
+			transform: () => null,
+			base: () => null
+		};
+		return handler.call(context, node);
+	};
+	return call("decode") !== call("encode");
+}
+/**
+* Whether the schema transitively contains a node that prints differently per direction, so it
+* must decode on responses and encode on requests. Follows `$ref`s through their resolved
+* schema, with `seen` guarding cycles.
+*/
+function containsDirectionalNode({ node, printerOptions, seen = /* @__PURE__ */ new Set() }) {
+	if (!node) return false;
+	if (node.type === "ref") {
+		if (!node.ref) return false;
+		const refName = extractRefName(node.ref);
+		if (refName) {
+			if (seen.has(refName)) return false;
+			seen.add(refName);
+		}
+		const resolved = syncSchemaRef(node);
+		if (resolved.type === "ref") return false;
+		return containsDirectionalNode({
+			node: resolved,
+			printerOptions,
+			seen
+		});
+	}
+	if (variesByDirection({
+		node,
+		printerOptions
+	})) return true;
+	const children = [];
+	if ("properties" in node && node.properties) children.push(...node.properties.map((prop) => prop.schema));
+	if ("items" in node && node.items) children.push(...node.items);
+	if ("members" in node && node.members) children.push(...node.members);
+	if ("additionalProperties" in node && node.additionalProperties && node.additionalProperties !== true) children.push(node.additionalProperties);
+	return children.some((child) => containsDirectionalNode({
+		node: child,
+		printerOptions,
+		seen
+	}));
+}
+/**
+* Names of the `$ref` schemas the generator should route to their input (encode) variant.
+*/
+function collectDirectionalRefNames({ node, printerOptions }) {
+	return ast.collectSync(node, { schema: (n) => n.type === "ref" && n.ref && containsDirectionalNode({
+		node: n,
+		printerOptions
+	}) ? ast.resolveRefName(n) ?? void 0 : void 0 });
+}
+/**
+* Handlers that never recurse into children, so {@link variesByDirection} can call one directly
+* to probe both directions without building a printer.
+*
+* `date` is the built-in two-way conversion, decoding `string → Date` on responses and encoding
+* back on requests, keeping `date` and `date-time` precision apart. Only `representation: 'date'`
+* fields convert; ISO-string fields print `z.iso.date()` either way. A `printer.nodes.date`
+* override replaces the whole handler, direction branch included.
+*/
+const scalarNodes = {
+	any: () => "z.any()",
+	unknown: () => "z.unknown()",
+	void: () => "z.void()",
+	never: () => "z.never()",
+	boolean: () => "z.boolean()",
+	null: () => "z.null()",
+	string(node) {
+		const base = shouldCoerce(this.options.coercion, "strings") ? "z.coerce.string()" : "z.string()";
+		const pattern = node.pattern ?? integerFormatPattern(node.format);
+		return `${base}${lengthConstraints({
+			...node,
+			pattern,
+			regexType: this.options.regexType
+		})}`;
+	},
+	number(node) {
+		return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number()" : "z.number()"}${numberConstraints(node)}`;
+	},
+	integer(node) {
+		return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number().int()" : "z.int()"}${numberConstraints(node)}`;
+	},
+	bigint() {
+		return "z.coerce.bigint()";
+	},
+	date(node) {
+		if (node.representation !== "date") return "z.iso.date()";
+		if (this.options.direction === "encode") return node.format === "date" ? "z.date().transform((value) => value.toISOString().slice(0, 10))" : "z.date().transform((value) => value.toISOString())";
+		const decoded = node.format === "date" ? "z.iso.date().transform((value) => new Date(value))" : "z.iso.datetime().transform((value) => new Date(value))";
+		return shouldCoerce(this.options.coercion, "dates") ? "z.coerce.date()" : decoded;
+	},
+	datetime(node) {
+		const offset = node.offset || this.options.dateType === "stringOffset";
+		const local = node.local || this.options.dateType === "stringLocal";
+		if (offset) return "z.iso.datetime({ offset: true })";
+		if (local) return "z.iso.datetime({ local: true })";
+		return "z.iso.datetime()";
+	},
+	time(node) {
+		if (node.representation === "string") return "z.iso.time()";
+		return shouldCoerce(this.options.coercion, "dates") ? "z.coerce.date()" : "z.date()";
+	},
+	uuid(node) {
+		return `${this.options.guidType === "guid" ? "z.guid()" : "z.uuid()"}${lengthConstraints({
+			...node,
+			regexType: this.options.regexType
+		})}`;
+	},
+	email(node) {
+		return `z.email()${lengthConstraints({
+			...node,
+			regexType: this.options.regexType
+		})}`;
+	},
+	url(node) {
+		return `z.url()${lengthConstraints({
+			...node,
+			regexType: this.options.regexType
+		})}`;
+	},
+	ipv4: () => "z.ipv4()",
+	ipv6: () => "z.ipv6()",
+	blob: () => "z.instanceof(File)",
+	enum(node) {
+		const nonNullValues = (node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []).filter((v) => v !== null);
+		if (node.namedEnumValues?.length) {
+			const literals = nonNullValues.map((v) => `z.literal(${formatLiteral(v)})`);
+			if (literals.length === 1) return literals[0];
+			return `z.union([${literals.join(", ")}])`;
+		}
+		return buildEnum(nonNullValues);
+	}
+};
+/**
 * Zod v4 printer built with `definePrinter`.
 *
 * Converts a `SchemaNode` AST into a Zod v4 code string using the chainable API
@@ -1170,84 +1270,15 @@ const printerZod = ast.createPrinter((options) => {
 		name: "zod",
 		options,
 		nodes: {
-			any: () => "z.any()",
-			unknown: () => "z.unknown()",
-			void: () => "z.void()",
-			never: () => "z.never()",
-			boolean: () => "z.boolean()",
-			null: () => "z.null()",
-			string(node) {
-				const base = shouldCoerce(this.options.coercion, "strings") ? "z.coerce.string()" : "z.string()";
-				const pattern = node.pattern ?? integerFormatPattern(node.format);
-				return `${base}${lengthConstraints({
-					...node,
-					pattern,
-					regexType: this.options.regexType
-				})}`;
-			},
-			number(node) {
-				return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number()" : "z.number()"}${numberConstraints(node)}`;
-			},
-			integer(node) {
-				return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number().int()" : "z.int()"}${numberConstraints(node)}`;
-			},
-			bigint() {
-				return shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.bigint()" : "z.bigint()";
-			},
-			date(node) {
-				const codec = getCodec(node);
-				if (codec) {
-					if (this.options.direction === "input") return codec.encode(node);
-					return shouldCoerce(this.options.coercion, "dates") ? "z.coerce.date()" : codec.decode(node);
-				}
-				return "z.iso.date()";
-			},
-			datetime(node) {
-				const offset = node.offset || this.options.dateType === "stringOffset";
-				const local = node.local || this.options.dateType === "stringLocal";
-				if (offset) return "z.iso.datetime({ offset: true })";
-				if (local) return "z.iso.datetime({ local: true })";
-				return "z.iso.datetime()";
-			},
-			time(node) {
-				if (node.representation === "string") return "z.iso.time()";
-				return shouldCoerce(this.options.coercion, "dates") ? "z.coerce.date()" : "z.date()";
-			},
-			uuid(node) {
-				return `${this.options.guidType === "guid" ? "z.guid()" : "z.uuid()"}${lengthConstraints({
-					...node,
-					regexType: this.options.regexType
-				})}`;
-			},
-			email(node) {
-				return `z.email()${lengthConstraints({
-					...node,
-					regexType: this.options.regexType
-				})}`;
-			},
-			url(node) {
-				return `z.url()${lengthConstraints({
-					...node,
-					regexType: this.options.regexType
-				})}`;
-			},
-			ipv4: () => "z.ipv4()",
-			ipv6: () => "z.ipv6()",
-			blob: () => "z.instanceof(File)",
-			enum(node) {
-				const nonNullValues = (node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []).filter((v) => v !== null);
-				if (node.namedEnumValues?.length) {
-					const literals = nonNullValues.map((v) => `z.literal(${formatLiteral(v)})`);
-					if (literals.length === 1) return literals[0];
-					return `z.union([${literals.join(", ")}])`;
-				}
-				return buildEnum(nonNullValues);
-			},
+			...scalarNodes,
 			ref(node) {
 				if (!node.name) return null;
 				const refName = ast.resolveRefName(node);
 				if (!refName) return null;
-				const useInputVariant = node.ref != null && this.options.direction === "input" && containsCodec(node);
+				const useInputVariant = node.ref != null && this.options.direction === "encode" && containsDirectionalNode({
+					node,
+					printerOptions: this.options
+				});
 				const resolvedName = node.ref ? useInputVariant ? this.options.resolver?.schema.inputName(refName) ?? refName : this.options.resolver?.name(refName) ?? refName : node.name;
 				if (node.ref && this.options.cyclicSchemas?.has(refName)) return `z.lazy(() => ${resolvedName})`;
 				return resolvedName;
@@ -1431,7 +1462,7 @@ const printerZodMini = ast.createPrinter((options) => {
 				return `z.int()${numberChecksMini(node)}`;
 			},
 			bigint(node) {
-				return `z.bigint()${numberChecksMini(node)}`;
+				return `z.coerce.bigint()${numberChecksMini(node)}`;
 			},
 			date(node) {
 				if (node.representation === "string") return "z.iso.date()";
@@ -1574,29 +1605,28 @@ const printerZodMini = ast.createPrinter((options) => {
 const zodPrinterCache = /* @__PURE__ */ new WeakMap();
 const zodMiniPrinterCache = /* @__PURE__ */ new WeakMap();
 /**
-* Returns the cached `output`/`input` direction printers for a resolver, building them on
-* first use. The `input` printer encodes `Date → string` for request bodies, and `output` decodes
-* `string → Date` for responses. Schemas without `dateType: 'date'` fields print identically.
+* Cached printer per direction for a resolver, built on first use. Schemas holding nothing that
+* converts print the same either way.
 */
 function getStdPrinters(resolver, params) {
 	const cached = zodPrinterCache.get(resolver);
 	if (cached && cached.coercion === params.coercion && cached.guidType === params.guidType && cached.regexType === params.regexType && cached.dateType === params.dateType && cached.nodes === params.nodes) return {
-		output: cached.output,
-		input: cached.input
+		decode: cached.decode,
+		encode: cached.encode
 	};
-	const output = printerZod({
+	const decode = printerZod({
 		...params,
 		resolver,
-		direction: "output"
+		direction: "decode"
 	});
-	const input = printerZod({
+	const encode = printerZod({
 		...params,
 		resolver,
-		direction: "input"
+		direction: "encode"
 	});
 	zodPrinterCache.set(resolver, {
-		output,
-		input,
+		decode,
+		encode,
 		coercion: params.coercion,
 		guidType: params.guidType,
 		regexType: params.regexType,
@@ -1604,8 +1634,8 @@ function getStdPrinters(resolver, params) {
 		nodes: params.nodes
 	});
 	return {
-		output,
-		input
+		decode,
+		encode
 	};
 }
 function getMiniPrinter(resolver, params) {
@@ -1639,15 +1669,30 @@ const zodGenerator = defineGenerator({
 		if (!node.name) return;
 		const isZodImport = ZOD_NAMESPACE_IMPORTS.has(importPath);
 		const cyclicSchemas = new Set(ctx.meta.circularNames);
-		const hasCodec = !mini && containsCodec(node);
-		const codecRefNames = new Set(hasCodec ? collectCodecRefNames(node) : []);
+		const printerOptions = {
+			coercion,
+			guidType,
+			regexType,
+			dateType,
+			resolver,
+			cyclicSchemas,
+			nodes: printer?.nodes
+		};
+		const hasDirectionalNode = !mini && containsDirectionalNode({
+			node,
+			printerOptions
+		});
+		const directionalRefNames = new Set(hasDirectionalNode ? collectDirectionalRefNames({
+			node,
+			printerOptions
+		}) : []);
 		const importEntries = resolver.imports({
 			node,
 			root,
 			output,
 			group: group ?? void 0
 		});
-		const inputImportEntries = hasCodec ? [...codecRefNames].map((schemaName) => ({
+		const inputImportEntries = hasDirectionalNode ? [...directionalRefNames].map((schemaName) => ({
 			name: [resolver.schema.inputName(schemaName)],
 			path: resolver.file({
 				name: schemaName,
@@ -1688,7 +1733,7 @@ const zodGenerator = defineGenerator({
 			regexType,
 			cyclicSchemas,
 			nodes: printer?.nodes
-		}) : stdPrinters.output;
+		}) : stdPrinters.decode;
 		return /* @__PURE__ */ jsxs(File, {
 			baseName: meta.file.baseName,
 			path: meta.file.path,
@@ -1731,10 +1776,10 @@ const zodGenerator = defineGenerator({
 					inferTypeName,
 					cyclic: cyclicSchemas.has(node.name)
 				}),
-				hasCodec && stdPrinters && /* @__PURE__ */ jsx(Zod, {
+				hasDirectionalNode && stdPrinters && /* @__PURE__ */ jsx(Zod, {
 					name: resolver.schema.inputName(node.name),
 					node,
-					printer: stdPrinters.input,
+					printer: stdPrinters.encode,
 					inferTypeName: inferred ? resolver.schema.inputTypeName(node.name) : null,
 					cyclic: cyclicSchemas.has(node.name)
 				})
@@ -1757,16 +1802,28 @@ const zodGenerator = defineGenerator({
 			group: group ?? void 0
 		}) };
 		const cyclicSchemas = new Set(ctx.meta.circularNames);
-		function renderSchemaEntry({ schema, name, keysToOmit, direction = "output" }) {
+		const printerOptions = {
+			coercion,
+			guidType,
+			regexType,
+			dateType,
+			resolver,
+			cyclicSchemas,
+			nodes: printer?.nodes
+		};
+		function renderSchemaEntry({ schema, name, keysToOmit, direction = "decode" }) {
 			if (!schema) return null;
 			const inferTypeName = inferred ? resolver.schema.type(name) : null;
-			const codecRefNames = direction === "input" && !mini ? new Set(collectCodecRefNames(schema)) : null;
+			const directionalRefNames = direction === "encode" && !mini ? new Set(collectDirectionalRefNames({
+				node: schema,
+				printerOptions
+			})) : null;
 			const imports = resolver.imports({
 				node: schema,
 				root,
 				output,
 				group: group ?? void 0,
-				name: (schemaName) => codecRefNames?.has(schemaName) ? resolver.schema.inputName(schemaName) : resolver.name(schemaName)
+				name: (schemaName) => directionalRefNames?.has(schemaName) ? resolver.schema.inputName(schemaName) : resolver.name(schemaName)
 			});
 			const schemaPrinter = mini ? keysToOmit?.length ? printerZodMini({
 				guidType,
@@ -1855,7 +1912,7 @@ const zodGenerator = defineGenerator({
 		const paramSchemas = node.parameters.map((param) => renderSchemaEntry({
 			schema: param.schema,
 			name: resolver.param.name(node, param),
-			direction: "input"
+			direction: "encode"
 		}));
 		const responseSchemas = node.responses.map((res) => {
 			const variants = (res.content ?? []).filter((entry) => entry.schema);
@@ -1893,13 +1950,13 @@ const zodGenerator = defineGenerator({
 					},
 					name: resolver.response.body(node),
 					keysToOmit: entry.keysToOmit,
-					direction: "input"
+					direction: "encode"
 				});
 			}
 			return buildContentTypeVariants(requestBodyContent, resolver.response.body(node), (schema) => ({
 				...schema,
 				description: node.requestBody.description ?? schema.description
-			}), "input");
+			}), "encode");
 		})();
 		const { path, query, header } = getOperationParameters(node);
 		const paramGroupSchemas = inferred ? [
@@ -1918,12 +1975,12 @@ const zodGenerator = defineGenerator({
 		].filter(({ params }) => params.length > 0).map(({ kind, params }) => renderSchemaEntry({
 			schema: buildGroupedParamsSchema({ params }),
 			name: resolver.param[kind](node, params[0]),
-			direction: "input"
+			direction: "encode"
 		})) : [];
 		const optionsSchema = inferred ? renderSchemaEntry({
 			schema: buildOptionsSchema(node, resolver),
 			name: resolver.name(`${node.operationId} Options`),
-			direction: "input"
+			direction: "encode"
 		}) : null;
 		const responsesSchema = inferred ? renderSchemaEntry({
 			schema: buildResponses(node, resolver),