@kubb/plugin-zod 5.0.0-beta.76 → 5.0.0-beta.79

package/dist/index.d.ts

@@ -119,6 +119,12 @@ type PrinterZodOptions = {
    * variant for each date-bearing component.
    */
   direction?: 'input' | 'output';
+  /**
+   * Maps a component `$ref` path to its collision-resolved name. When two components collide
+   * (across sections or by case), the adapter renames one of them; the `ref()` handler resolves
+   * the referenced name through this map so the emitted schema reference matches the renamed component.
+   */
+  nameMapping?: ReadonlyMap<string, string>;
   /**
    * Custom handler map for node type overrides.
    */
@@ -196,6 +202,12 @@ type PrinterZodMiniOptions = {
    * Properties referencing these emit lazy getters wrapping refs in `z.lazy(() => …)`.
    */
   cyclicSchemas?: ReadonlySet<string>;
+  /**
+   * Maps a component `$ref` path to its collision-resolved name. When two components collide
+   * (across sections or by case), the adapter renames one of them; the `ref()` handler resolves
+   * the referenced name through this map so the emitted schema reference matches the renamed component.
+   */
+  nameMapping?: ReadonlyMap<string, string>;
   /**
    * Custom handler map for node type overrides.
    */
@@ -457,7 +469,7 @@ declare const pluginZodName = "plugin-zod";
  * Generates Zod v4 schemas from an OpenAPI spec. Use them to validate API
  * responses at runtime, build form schemas, or feed back into router libraries
  * that consume Zod (tRPC, Hono, Elysia). Pair with `@kubb/plugin-axios` or
- * `@kubb/plugin-fetch` and set the client's `parser: 'zod'` to validate every response
+ * `@kubb/plugin-fetch` and set the client's `validator: 'zod'` to validate every response
  * automatically.
  *
  * @example

package/dist/index.js

@@ -72,7 +72,7 @@ function toFilePath(name, caseLast = camelCase) {
 * JavaScript and Java reserved words.
 * @link https://github.com/jonschlinkert/reserved/blob/master/index.js
 */
-const reservedWords = new Set([
+const reservedWords = /* @__PURE__ */ new Set([
 	"abstract",
 	"arguments",
 	"boolean",
@@ -304,9 +304,10 @@ function createGroupConfig(group) {
 }
 //#endregion
 //#region src/components/Zod.tsx
-function Zod({ name, node, printer, inferTypeName }) {
+function Zod({ name, node, printer, inferTypeName, cyclic }) {
 	const output = printer.print(node);
 	if (!output) return;
+	const needsAnnotation = cyclic && node.type !== "object";
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(File.Source, {
 		name,
 		isExportable: true,
@@ -314,6 +315,7 @@ function Zod({ name, node, printer, inferTypeName }) {
 		children: /* @__PURE__ */ jsx(Const, {
 			export: true,
 			name,
+			type: needsAnnotation ? "z.ZodType" : void 0,
 			children: output
 		})
 	}), inferTypeName && /* @__PURE__ */ jsx(File.Source, {
@@ -334,7 +336,7 @@ function Zod({ name, node, printer, inferTypeName }) {
 * Import paths that use a namespace import (`import * as z from '...'`).
 * All other import paths use a named import (`import { z } from '...'`).
 */
-const ZOD_NAMESPACE_IMPORTS = new Set(["zod", "zod/mini"]);
+const ZOD_NAMESPACE_IMPORTS = /* @__PURE__ */ new Set(["zod", "zod/mini"]);
 //#endregion
 //#region src/utils.ts
 /**
@@ -417,6 +419,33 @@ function formatDefault(value) {
 	return String(value ?? "");
 }
 /**
+* Format a default for `.default(...)` so the literal matches the generated schema's type.
+*
+* An OpenAPI `default` does not always agree with the schema it sits on: a `bigint` field
+* (`format: int64`) carries a `number` default, and a spec may put `default: {}` on an `array`.
+* Emitting those verbatim produces a Zod schema that does not typecheck, so coerce the bigint case
+* to a `BigInt(...)` literal and emit an array literal for arrays (dropping a non-array default).
+* Returns `null` when no `.default(...)` should be emitted. Keys off the schema node's type.
+*/
+function defaultLiteral(node, value) {
+	if (value === null) return null;
+	if (node && ast.narrowSchema(node, "bigint")) {
+		if (typeof value === "bigint") return `BigInt(${value})`;
+		if (typeof value === "number" && Number.isInteger(value)) return `BigInt(${value})`;
+		return null;
+	}
+	if (node && ast.narrowSchema(node, "array")) return Array.isArray(value) ? JSON.stringify(value) : null;
+	const enumNode = node ? ast.narrowSchema(node, "enum") : void 0;
+	if (enumNode) {
+		const values = enumNode.namedEnumValues?.map((member) => member.value) ?? enumNode.enumValues ?? [];
+		if (values.length) {
+			const match = values.find((member) => member === value || String(member) === String(value));
+			return match != null ? formatLiteral(match) : null;
+		}
+	}
+	return formatDefault(value);
+}
+/**
 * Format a primitive enum/literal value.
 * Strings are quoted; numbers and booleans are emitted raw.
 */
@@ -425,6 +454,18 @@ function formatLiteral(v) {
 	return String(v);
 }
 /**
+* Build the Zod schema for a set of literal enum values.
+* `z.enum()` only accepts string members in Zod v4, so a numeric, boolean, or
+* mixed set is emitted as a single `z.literal(…)` or a `z.union([z.literal(…), …])`.
+* An all-string set keeps the more compact `z.enum([…])`.
+*/
+function buildEnum(values) {
+	if (values.every((v) => typeof v === "string")) return `z.enum([${values.map(formatLiteral).join(", ")}])`;
+	const literals = values.map((v) => `z.literal(${formatLiteral(v)})`);
+	if (literals.length === 1) return literals[0];
+	return `z.union([${literals.join(", ")}])`;
+}
+/**
 * Map a `regexType` to the `func` argument of `toRegExpString`: `'constructor'` emits
 * `new RegExp(...)`, while `'literal'` (the default) emits a regex literal.
 */
@@ -503,36 +544,62 @@ function lengthChecksMini({ min, max, pattern, regexType }) {
 * Apply nullable / optional / nullish modifiers, an optional `.describe()` call, and an
 * optional `.meta({ examples })` call to a schema value string using the chainable Zod v4 API.
 */
-function applyModifiers({ value, nullable, optional, nullish, defaultValue, description, examples }) {
+function applyModifiers({ value, schema, nullable, optional, nullish, defaultValue, description, examples }) {
 	const withModifier = (() => {
 		if (nullish || nullable && optional) return `${value}.nullish()`;
 		if (optional) return `${value}.optional()`;
 		if (nullable) return `${value}.nullable()`;
 		return value;
 	})();
-	const withDefault = defaultValue !== void 0 ? `${withModifier}.default(${formatDefault(defaultValue)})` : withModifier;
+	const literal = defaultValue !== void 0 ? defaultLiteral(schema, defaultValue) : null;
+	const withDefault = literal !== null ? `${withModifier}.default(${literal})` : withModifier;
 	const withDescription = description ? `${withDefault}.describe(${stringify(description)})` : withDefault;
 	return examples?.length ? `${withDescription}.meta({ examples: [${examples.map(formatDefault).join(", ")}] })` : withDescription;
 }
+function modifierDepth(schema) {
+	if (schema.nullish || schema.nullable && schema.optional) return 2;
+	if (schema.nullable || schema.optional) return 1;
+	return 0;
+}
+/**
+* Build the `.unwrap()` chain to insert before `.omit()` when the schema is a `$ref`.
+*
+* A `$ref` resolves to a named schema variable that already carries its own `.nullable()` /
+* `.optional()` / `.nullish()` / `.default()` wrappers. `.omit()` lives on the inner `ZodObject`,
+* not on those `ZodNullable` / `ZodOptional` / `ZodDefault` wrappers, so the omit has to unwrap
+* down to the object first. This mirrors plugin-ts emitting `Omit<NonNullable<T>, …>`. Inline
+* objects need no unwrap because the printer adds their modifiers after `.omit()`.
+*/
+function omitUnwrapChain(node) {
+	const ref = ast.narrowSchema(node, "ref");
+	if (!ref) return "";
+	const target = ref.schema ?? ref;
+	const depth = modifierDepth(target) + (target.default !== void 0 ? 1 : 0);
+	return ".unwrap()".repeat(depth);
+}
 /**
 * Apply nullable / optional / nullish modifiers using the functional `zod/mini` API
 * (`z.nullable()`, `z.optional()`, `z.nullish()`).
 */
-function applyMiniModifiers({ value, nullable, optional, nullish, defaultValue }) {
+function applyMiniModifiers({ value, schema, nullable, optional, nullish, defaultValue }) {
 	const withModifier = (() => {
 		if (nullish) return `z.nullish(${value})`;
 		const withNullable = nullable ? `z.nullable(${value})` : value;
 		return optional ? `z.optional(${withNullable})` : withNullable;
 	})();
-	return defaultValue !== void 0 ? `z._default(${withModifier}, ${formatDefault(defaultValue)})` : withModifier;
+	const literal = defaultValue !== void 0 ? defaultLiteral(schema, defaultValue) : null;
+	return literal !== null ? `z._default(${withModifier}, ${literal})` : withModifier;
 }
 //#endregion
 //#region src/printers/printerZod.ts
-function strictOneOfMember$1(member, node) {
+function strictOneOfMember$1(member, node, cyclicSchemas) {
 	if (node.type === "object" && node.additionalProperties === void 0) return `${member}.strict()`;
 	if (node.type === "ref") {
 		if (member.startsWith("z.lazy(")) return member;
+		const refName = (node.ref ? extractRefName(node.ref) : void 0) ?? node.name;
+		if (refName && cyclicSchemas?.has(refName)) return member;
 		const schema = syncSchemaRef(node);
+		if (schema.nullable || schema.optional || node.nullable || node.optional) return member;
 		if (schema.type === "object" && (schema.additionalProperties === void 0 || schema.additionalProperties === false)) return `${member}.strict()`;
 	}
 	return member;
@@ -562,6 +629,7 @@ function getMemberConstraint({ member, regexType }) {
 * ```
 */
 const printerZod = ast.createPrinter((options) => {
+	const cyclicSchemaNames = options.cyclicSchemas;
 	return {
 		name: "zod",
 		options,
@@ -631,11 +699,11 @@ const printerZod = ast.createPrinter((options) => {
 					if (literals.length === 1) return literals[0];
 					return `z.union([${literals.join(", ")}])`;
 				}
-				return `z.enum([${nonNullValues.map(formatLiteral).join(", ")}])`;
+				return buildEnum(nonNullValues);
 			},
 			ref(node) {
 				if (!node.name) return null;
-				const refName = node.ref ? extractRefName(node.ref) ?? node.name : node.name;
+				const refName = node.ref ? this.options.nameMapping?.get(node.ref) ?? extractRefName(node.ref) ?? node.name : node.name;
 				const useInputVariant = node.ref != null && this.options.direction === "input" && containsCodec(node);
 				const resolvedName = node.ref ? useInputVariant ? this.options.resolver?.resolveInputSchemaName(refName) ?? refName : this.options.resolver?.default(refName, "function") ?? refName : node.name;
 				if (node.ref && this.options.cyclicSchemas?.has(refName)) return `z.lazy(() => ${resolvedName})`;
@@ -660,6 +728,7 @@ const printerZod = ast.createPrinter((options) => {
 					const descriptionToApply = schema.type !== "ref" && meta.type === "ref" ? void 0 : meta.description;
 					const value = applyModifiers({
 						value: wrappedOutput,
+						schema,
 						nullable: meta.nullable,
 						optional: schema.optional || property.required === false,
 						nullish: schema.nullish,
@@ -709,10 +778,11 @@ const printerZod = ast.createPrinter((options) => {
 			},
 			union(node) {
 				const nodeMembers = node.members ?? [];
-				const members = mapSchemaMembers(node, (memberNode) => this.transform(memberNode)).map(({ schema, output }) => output && node.strategy === "one" ? strictOneOfMember$1(output, schema) : output).filter(Boolean);
+				const members = mapSchemaMembers(node, (memberNode) => this.transform(memberNode)).map(({ schema, output }) => output && node.strategy === "one" ? strictOneOfMember$1(output, schema, cyclicSchemaNames) : output).filter(Boolean);
 				if (members.length === 0) return "";
 				if (members.length === 1) return members[0];
-				if (node.discriminatorPropertyName && !nodeMembers.some((m) => m.type === "intersection")) return `z.discriminatedUnion(${stringify(node.discriminatorPropertyName)}, ${buildList(members)})`;
+				const allDiscriminable = nodeMembers.every((m) => (m.type === "ref" ? syncSchemaRef(m) : m).type !== "intersection");
+				if (node.discriminatorPropertyName && allDiscriminable) return `z.discriminatedUnion(${stringify(node.discriminatorPropertyName)}, ${buildList(members)})`;
 				return `z.union(${buildList(members)})`;
 			},
 			intersection(node) {
@@ -742,10 +812,13 @@ const printerZod = ast.createPrinter((options) => {
 			return applyModifiers({
 				value: (() => {
 					if (!keysToOmit?.length || meta.primitive !== "object" || meta.type === "union" && meta.discriminatorPropertyName) return transformed;
+					const unwrap = omitUnwrapChain(node);
+					const omit = `.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} })`;
 					const lazyMatch = transformed.match(/^z\.lazy\(\(\)\s*=>\s*(.+)\)$/);
-					if (lazyMatch) return `z.lazy(() => ${lazyMatch[1]}.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} }))`;
-					return `${transformed}.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} })`;
+					if (lazyMatch) return `z.lazy(() => ${lazyMatch[1]}${unwrap}${omit})`;
+					return `${transformed}${unwrap}${omit}`;
 				})(),
+				schema: node,
 				nullable: meta.nullable,
 				optional: meta.optional,
 				nullish: meta.nullish,
@@ -850,11 +923,11 @@ const printerZodMini = ast.createPrinter((options) => {
 					if (literals.length === 1) return literals[0];
 					return `z.union([${literals.join(", ")}])`;
 				}
-				return `z.enum([${nonNullValues.map(formatLiteral).join(", ")}])`;
+				return buildEnum(nonNullValues);
 			},
 			ref(node) {
 				if (!node.name) return null;
-				const refName = node.ref ? extractRefName(node.ref) ?? node.name : node.name;
+				const refName = node.ref ? this.options.nameMapping?.get(node.ref) ?? extractRefName(node.ref) ?? node.name : node.name;
 				const resolvedName = node.ref ? this.options.resolver?.default(refName, "function") ?? refName : node.name;
 				if (node.ref && this.options.cyclicSchemas?.has(refName)) return `z.lazy(() => ${resolvedName})`;
 				return resolvedName;
@@ -876,6 +949,7 @@ const printerZodMini = ast.createPrinter((options) => {
 							output: baseOutput,
 							schema
 						}) || baseOutput : baseOutput,
+						schema,
 						nullable: meta.nullable,
 						optional: schema.optional || property.required === false,
 						nullish: schema.nullish,
@@ -924,7 +998,8 @@ const printerZodMini = ast.createPrinter((options) => {
 				const members = mapSchemaMembers(node, (memberNode) => this.transform(memberNode)).map(({ schema, output }) => output && node.strategy === "one" ? strictOneOfMember(output, schema) : output).filter(Boolean);
 				if (members.length === 0) return "";
 				if (members.length === 1) return members[0];
-				if (node.discriminatorPropertyName && !nodeMembers.some((m) => m.type === "intersection")) return `z.discriminatedUnion(${stringify(node.discriminatorPropertyName)}, ${buildList(members)})`;
+				const allDiscriminable = nodeMembers.every((m) => (m.type === "ref" ? syncSchemaRef(m) : m).type !== "intersection");
+				if (node.discriminatorPropertyName && allDiscriminable) return `z.discriminatedUnion(${stringify(node.discriminatorPropertyName)}, ${buildList(members)})`;
 				return `z.union(${buildList(members)})`;
 			},
 			intersection(node) {
@@ -954,10 +1029,13 @@ const printerZodMini = ast.createPrinter((options) => {
 			return applyMiniModifiers({
 				value: (() => {
 					if (!keysToOmit?.length || meta.primitive !== "object" || meta.type === "union" && meta.discriminatorPropertyName) return transformed;
+					const unwrap = omitUnwrapChain(node);
+					const omit = `.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} })`;
 					const lazyMatch = transformed.match(/^z\.lazy\(\(\)\s*=>\s*(.+)\)$/);
-					if (lazyMatch) return `z.lazy(() => ${lazyMatch[1]}.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} }))`;
-					return `${transformed}.omit({ ${keysToOmit.map((k) => `"${k}": true`).join(", ")} })`;
+					if (lazyMatch) return `z.lazy(() => ${lazyMatch[1]}${unwrap}${omit})`;
+					return `${transformed}${unwrap}${omit}`;
 				})(),
+				schema: node,
 				nullable: meta.nullable,
 				optional: meta.optional,
 				nullish: meta.nullish,
@@ -1079,6 +1157,7 @@ const zodGenerator = defineGenerator({
 			})
 		};
 		const inferTypeName = inferred ? resolver.resolveSchemaTypeName(node.name) : null;
+		const nameMapping = adapter.options.nameMapping;
 		const stdPrinters = mini ? null : getStdPrinters(resolver, {
 			coercion,
 			guidType,
@@ -1086,6 +1165,7 @@ const zodGenerator = defineGenerator({
 			dateType,
 			wrapOutput,
 			cyclicSchemas,
+			nameMapping,
 			nodes: printer?.nodes
 		});
 		const schemaPrinter = mini ? getMiniPrinter(resolver, {
@@ -1093,6 +1173,7 @@ const zodGenerator = defineGenerator({
 			regexType,
 			wrapOutput,
 			cyclicSchemas,
+			nameMapping,
 			nodes: printer?.nodes
 		}) : stdPrinters.output;
 		return /* @__PURE__ */ jsxs(File, {
@@ -1134,13 +1215,15 @@ const zodGenerator = defineGenerator({
 					name: meta.name,
 					node,
 					printer: schemaPrinter,
-					inferTypeName
+					inferTypeName,
+					cyclic: cyclicSchemas.has(node.name)
 				}),
 				hasCodec && stdPrinters && /* @__PURE__ */ jsx(Zod, {
 					name: resolver.resolveInputSchemaName(node.name),
 					node,
 					printer: stdPrinters.input,
-					inferTypeName: inferred ? resolver.resolveInputSchemaTypeName(node.name) : null
+					inferTypeName: inferred ? resolver.resolveInputSchemaTypeName(node.name) : null,
+					cyclic: cyclicSchemas.has(node.name)
 				})
 			]
 		});
@@ -1163,6 +1246,7 @@ const zodGenerator = defineGenerator({
 			group: group ?? void 0
 		}) };
 		const cyclicSchemas = new Set(ctx.meta.circularNames);
+		const nameMapping = adapter.options.nameMapping;
 		function renderSchemaEntry({ schema, name, keysToOmit, direction = "output" }) {
 			if (!schema) return null;
 			const inferTypeName = inferred ? resolver.resolveTypeName(name) : null;
@@ -1185,12 +1269,14 @@ const zodGenerator = defineGenerator({
 				resolver,
 				keysToOmit,
 				cyclicSchemas,
+				nameMapping,
 				nodes: printer?.nodes
 			}) : getMiniPrinter(resolver, {
 				guidType,
 				regexType,
 				wrapOutput,
 				cyclicSchemas,
+				nameMapping,
 				nodes: printer?.nodes
 			}) : keysToOmit?.length ? printerZod({
 				coercion,
@@ -1201,6 +1287,7 @@ const zodGenerator = defineGenerator({
 				resolver,
 				keysToOmit,
 				cyclicSchemas,
+				nameMapping,
 				nodes: printer?.nodes,
 				direction
 			}) : getStdPrinters(resolver, {
@@ -1210,6 +1297,7 @@ const zodGenerator = defineGenerator({
 				dateType,
 				wrapOutput,
 				cyclicSchemas,
+				nameMapping,
 				nodes: printer?.nodes
 			})[direction];
 			return /* @__PURE__ */ jsxs(Fragment, { children: [imports.map((imp) => /* @__PURE__ */ jsx(File.Import, {
@@ -1224,7 +1312,8 @@ const zodGenerator = defineGenerator({
 				name,
 				node: schema,
 				printer: schemaPrinter,
-				inferTypeName
+				inferTypeName,
+				cyclic: false
 			})] });
 		}
 		function buildContentTypeVariants(entries, baseName, decorate, direction) {
@@ -1444,7 +1533,7 @@ const pluginZodName = "plugin-zod";
 * Generates Zod v4 schemas from an OpenAPI spec. Use them to validate API
 * responses at runtime, build form schemas, or feed back into router libraries
 * that consume Zod (tRPC, Hono, Elysia). Pair with `@kubb/plugin-axios` or
-* `@kubb/plugin-fetch` and set the client's `parser: 'zod'` to validate every response
+* `@kubb/plugin-fetch` and set the client's `validator: 'zod'` to validate every response
 * automatically.
 *
 * @example