@kubb/plugin-zod 5.2.0-canary.20260922T120902 → 5.2.1

package/dist/index.d.ts

@@ -225,6 +225,20 @@ type ResolverZod = Resolver & {
      * `resolver.schema.inputTypeName('order') // → 'OrderInputSchemaType'`
      */
     inputTypeName(name: string): string;
+    /**
+     * Resolves the type guard function name for a schema.
+     *
+     * @example Type guard names
+     * `resolver.schema.isName('pet') // → 'isPet'`
+     */
+    isName(name: string): string;
+    /**
+     * Resolves the assertion function name for a schema.
+     *
+     * @example Assertion names
+     * `resolver.schema.assertName('pet') // → 'assertPet'`
+     */
+    assertName(name: string): string;
   };
   /**
    * Names for an operation's parameters: an individual parameter and the grouped path, query, and
@@ -395,6 +409,20 @@ type Options = OutputOptions & {
    * to the default `resolverZod`.
    */
   resolver?: ResolverPatch<ResolverZod>;
+  /**
+   * Generate TypeScript type guards (`is*`) and assertion functions (`assert*`) for schemas
+   * using Zod v4's native `validate` API.
+   * - `true`: Generates both `is*` type guards and `assert*` assertion functions.
+   * - `{ is?: boolean; assert?: boolean }`: Selectively enable type guards or assertions.
+   *
+   * @default false
+   * @note Only compatible with Zod v4.6.0 or above.
+   * @see https://zod.dev
+   */
+  typeGuards?: boolean | {
+    is?: boolean;
+    assert?: boolean;
+  };
   /**
    * Replace the Zod handler for a specific schema type (`'integer'`, `'date'`, ...).
    * When `mini: true`, overrides target the Zod Mini printer instead.
@@ -424,6 +452,7 @@ type ResolvedOptions = {
   guidType: NonNullable<Options['guidType']>;
   regexType: NonNullable<Options['regexType']>;
   mini: NonNullable<Options['mini']>;
+  typeGuards: NonNullable<Options['typeGuards']>;
   printer: Options['printer'];
 };
 type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, ResolverZod>;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
 import { Resolver, ast, containsCircularRef, createResolver, defineGenerator, definePlugin, extractRefName, syncSchemaRef } from "kubb/kit";
-import { Const, File, Type, jsxRenderer } from "kubb/jsx";
+import { Const, File, Function, Type, jsxRenderer } from "kubb/jsx";
 import { Fragment, jsx, jsxs } from "kubb/jsx/jsx-runtime";
 //#region ../../internals/shared/src/params.ts
 /**
@@ -735,31 +735,61 @@ function mapSchemaItems(node, transform) {
 }
 //#endregion
 //#region src/components/Zod.tsx
-function Zod({ name, node, printer, inferTypeName, cyclic }) {
+function Zod({ name, node, printer, inferTypeName, typeGuards, isName, assertName, mini, 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,
-		isIndexable: true,
-		children: /* @__PURE__ */ jsx(Const, {
-			export: true,
+	const targetType = inferTypeName ?? `z.infer<typeof ${name}>`;
+	const shouldGenerateIs = isName && (typeof typeGuards === "object" ? typeGuards.is ?? true : Boolean(typeGuards));
+	const shouldGenerateAssert = assertName && (typeof typeGuards === "object" ? typeGuards.assert ?? true : Boolean(typeGuards));
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx(File.Source, {
 			name,
-			type: needsAnnotation ? "z.ZodType" : void 0,
-			children: output
-		})
-	}), inferTypeName && /* @__PURE__ */ jsx(File.Source, {
-		name: inferTypeName,
-		isExportable: true,
-		isIndexable: true,
-		isTypeOnly: true,
-		children: /* @__PURE__ */ jsx(Type, {
-			export: true,
+			isExportable: true,
+			isIndexable: true,
+			children: /* @__PURE__ */ jsx(Const, {
+				export: true,
+				name,
+				type: needsAnnotation ? "z.ZodType" : void 0,
+				children: output
+			})
+		}),
+		inferTypeName && /* @__PURE__ */ jsx(File.Source, {
 			name: inferTypeName,
-			children: `z.infer<typeof ${name}>`
+			isExportable: true,
+			isIndexable: true,
+			isTypeOnly: true,
+			children: /* @__PURE__ */ jsx(Type, {
+				export: true,
+				name: inferTypeName,
+				children: `z.infer<typeof ${name}>`
+			})
+		}),
+		shouldGenerateIs && /* @__PURE__ */ jsx(File.Source, {
+			name: isName,
+			isExportable: true,
+			isIndexable: true,
+			children: /* @__PURE__ */ jsx(Const, {
+				export: true,
+				name: isName,
+				JSDoc: { comments: [`Type guard for {@link ${name}}`] },
+				children: mini ? `(data: unknown): data is ${targetType} => z.validate(${name}, data)` : `(data: unknown): data is ${targetType} => ${name}.validate(data)`
+			})
+		}),
+		shouldGenerateAssert && /* @__PURE__ */ jsx(File.Source, {
+			name: assertName,
+			isExportable: true,
+			isIndexable: true,
+			children: /* @__PURE__ */ jsx(Function, {
+				export: true,
+				name: assertName,
+				params: "data: unknown",
+				returnType: `asserts data is ${targetType}`,
+				JSDoc: { comments: [`Asserter for {@link ${name}}`, "@throws {z.ZodError} If data is invalid"] },
+				children: mini ? `if (!z.validate(${name}, data)) {\n  z.parse(${name}, data)\n}` : `if (!${name}.validate(data)) {\n  ${name}.parse(data)\n}`
+			})
 		})
-	})] });
+	] });
 }
 //#endregion
 //#region src/constants.ts
@@ -1034,8 +1064,20 @@ function buildGroupedParamsSchema({ params, optional }) {
 }
 //#endregion
 //#region src/printers/printerZod.ts
-function strictOneOfMember$1(member, node, cyclicSchemas) {
-	if (node.type === "object" && node.additionalProperties === void 0) return `${member}.strict()`;
+/**
+* A `oneOf` member that is an inline object is exhaustive, so it prints as a strict object.
+* Marking the node lets `object()` build `z.strictObject(...)` itself; appending `.strict()` to the
+* printed member instead would read `.shape` eagerly and run a self-reference's deferred getter
+* inside the temporal dead zone.
+*/
+function strictOneOfNode$1(node) {
+	return node.type === "object" && node.additionalProperties === void 0 ? {
+		...node,
+		additionalProperties: false
+	} : node;
+}
+__name(strictOneOfNode$1, "strictOneOfNode");
+function strictOneOfMember(member, node, cyclicSchemas) {
 	if (node.type === "ref") {
 		if (member.startsWith("z.lazy(")) return member;
 		const refName = ast.resolveRefName(node);
@@ -1046,7 +1088,6 @@ function strictOneOfMember$1(member, node, cyclicSchemas) {
 	}
 	return member;
 }
-__name(strictOneOfMember$1, "strictOneOfMember");
 function getMemberConstraint({ member, regexType }) {
 	if (member.primitive === "string") return lengthConstraints({
 		...ast.narrowSchema(member, "string") ?? {},
@@ -1190,6 +1231,32 @@ const scalarNodes = {
 	boolean: () => "z.boolean()",
 	null: () => "z.null()",
 	string(node) {
+		if (!shouldCoerce(this.options.coercion, "strings")) {
+			if (node.format === "byte" || node.format === "base64") return `z.base64()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+			if (node.format === "base64url") return `z.base64url()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+			if (node.format === "jwt") return `z.jwt()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+			if (node.format === "ulid") return `z.ulid()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+			if (node.format === "iban") return `z.iban()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+			if (node.format === "duration") return `z.iso.duration()${lengthConstraints({
+				...node,
+				regexType: this.options.regexType
+			})}`;
+		}
 		const base = shouldCoerce(this.options.coercion, "strings") ? "z.coerce.string()" : "z.string()";
 		const pattern = node.pattern ?? integerFormatPattern(node.format);
 		return `${base}${lengthConstraints({
@@ -1202,6 +1269,10 @@ const scalarNodes = {
 		return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number()" : "z.number()"}${numberConstraints(node)}`;
 	},
 	integer(node) {
+		if (!shouldCoerce(this.options.coercion, "numbers")) {
+			if (node.format === "int32") return `z.int32()${numberConstraints(node)}`;
+			if (node.format === "uint32") return `z.uint32()${numberConstraints(node)}`;
+		}
 		return `${shouldCoerce(this.options.coercion, "numbers") ? "z.coerce.number().int()" : "z.int()"}${numberConstraints(node)}`;
 	},
 	bigint() {
@@ -1288,15 +1359,16 @@ const printerZod = ast.createPrinter((options) => {
 			},
 			object(node) {
 				const entries = node.properties ?? [];
-				const objectBase = `z.object(${buildZodObjectShape(this, node)})`;
+				const patterns = node.patternProperties ? Object.entries(node.patternProperties) : [];
+				const isStrict = node.additionalProperties === false && patterns.length === 0;
+				const objectBase = `${isStrict ? "z.strictObject" : "z.object"}(${buildZodObjectShape(this, node)})`;
 				return (() => {
-					const patterns = node.patternProperties ? Object.entries(node.patternProperties) : [];
 					if (node.additionalProperties && node.additionalProperties !== true) {
 						const catchallType = this.transform(node.additionalProperties);
 						return catchallType ? `${objectBase}.catchall(${catchallType})` : objectBase;
 					}
 					if (node.additionalProperties === true) return `${objectBase}.catchall(${this.transform(ast.factory.createSchema({ type: "unknown" }))})`;
-					if (node.additionalProperties === false && patterns.length === 0) return `${objectBase}.strict()`;
+					if (isStrict) return objectBase;
 					if (patterns.length > 0) {
 						const values = patterns.map(([, valueSchema]) => {
 							const valueType = this.transform(valueSchema) ?? this.transform(ast.factory.createSchema({ type: "unknown" }));
@@ -1325,7 +1397,7 @@ 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, cyclicSchemaNames) : output).filter(Boolean);
+				const members = mapSchemaMembers(node, (memberNode) => this.transform(node.strategy === "one" ? strictOneOfNode$1(memberNode) : memberNode)).map(({ schema, output }) => output && node.strategy === "one" ? strictOneOfMember(output, schema, cyclicSchemaNames) : output).filter(Boolean);
 				if (members.length === 0) return "";
 				if (members.length === 1) return members[0];
 				const allDiscriminable = nodeMembers.every((m) => isObjectSchemaNode(m, cyclicSchemaNames));
@@ -1379,9 +1451,15 @@ const printerZod = ast.createPrinter((options) => {
 });
 //#endregion
 //#region src/printers/printerZodMini.ts
-function strictOneOfMember(member, node) {
-	if (node.type === "object" && (node.additionalProperties === void 0 || node.additionalProperties === false)) return member.replace(/^z\.object\(/, "z.strictObject(");
-	return member;
+/**
+* A `oneOf` member that is an inline object is exhaustive, so it prints as a strict object.
+* Marking the node lets `object()` build `z.strictObject(...)` itself, with no rewrite afterwards.
+*/
+function strictOneOfNode(node) {
+	return node.type === "object" && node.additionalProperties === void 0 ? {
+		...node,
+		additionalProperties: false
+	} : node;
 }
 function getMemberConstraintMini({ member, regexType }) {
 	if (member.primitive === "string") return lengthChecksMini({
@@ -1451,6 +1529,30 @@ const printerZodMini = ast.createPrinter((options) => {
 			boolean: () => "z.boolean()",
 			null: () => "z.null()",
 			string(node) {
+				if (node.format === "byte" || node.format === "base64") return `z.base64()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
+				if (node.format === "base64url") return `z.base64url()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
+				if (node.format === "jwt") return `z.jwt()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
+				if (node.format === "ulid") return `z.ulid()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
+				if (node.format === "iban") return `z.iban()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
+				if (node.format === "duration") return `z.iso.duration()${lengthChecksMini({
+					...node,
+					regexType: this.options.regexType
+				})}`;
 				const pattern = node.pattern ?? integerFormatPattern(node.format);
 				return `z.string()${lengthChecksMini({
 					...node,
@@ -1462,6 +1564,8 @@ const printerZodMini = ast.createPrinter((options) => {
 				return `z.number()${numberChecksMini(node)}`;
 			},
 			integer(node) {
+				if (node.format === "int32") return `z.int32()${numberChecksMini(node)}`;
+				if (node.format === "uint32") return `z.uint32()${numberChecksMini(node)}`;
 				return `z.int()${numberChecksMini(node)}`;
 			},
 			bigint(node) {
@@ -1518,14 +1622,15 @@ const printerZodMini = ast.createPrinter((options) => {
 			},
 			object(node) {
 				const entries = node.properties ?? [];
-				const objectBase = `z.object(${buildZodMiniObjectShape(this, node)})`;
 				const patterns = node.patternProperties ? Object.entries(node.patternProperties) : [];
+				const isStrict = node.additionalProperties === false && patterns.length === 0;
+				const objectBase = `${isStrict ? "z.strictObject" : "z.object"}(${buildZodMiniObjectShape(this, node)})`;
 				if (node.additionalProperties && node.additionalProperties !== true) {
 					const catchallType = this.transform(node.additionalProperties);
 					return catchallType ? `z.catchall(${objectBase}, ${catchallType})` : objectBase;
 				}
 				if (node.additionalProperties === true) return `z.catchall(${objectBase}, ${this.transform(ast.factory.createSchema({ type: "unknown" }))})`;
-				if (node.additionalProperties === false && patterns.length === 0) return objectBase.replace(/^z\.object\(/, "z.strictObject(");
+				if (isStrict) return objectBase;
 				if (patterns.length > 0) {
 					const values = patterns.map(([, valueSchema]) => {
 						const valueType = this.transform(valueSchema) ?? this.transform(ast.factory.createSchema({ type: "unknown" }));
@@ -1553,7 +1658,7 @@ const printerZodMini = 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(output, schema) : output).filter(Boolean);
+				const members = mapSchemaMembers(node, (memberNode) => this.transform(node.strategy === "one" ? strictOneOfNode(memberNode) : memberNode)).map(({ output }) => output).filter(Boolean);
 				if (members.length === 0) return "";
 				if (members.length === 1) return members[0];
 				const allDiscriminable = nodeMembers.every((m) => isObjectSchemaNode(m, cyclicSchemaNames));
@@ -1667,7 +1772,7 @@ const zodGenerator = defineGenerator({
 	renderer: jsxRenderer,
 	schema(node, ctx) {
 		const { adapter, config, resolver, root } = ctx;
-		const { output, coercion, guidType, regexType, mini, inferred, importPath, group, printer } = ctx.options;
+		const { output, coercion, guidType, regexType, mini, inferred, typeGuards, importPath, group, printer } = ctx.options;
 		const dateType = getOasAdapter(adapter).options.dateType;
 		if (!node.name) return;
 		const isZodImport = ZOD_NAMESPACE_IMPORTS.has(importPath);
@@ -1723,6 +1828,8 @@ const zodGenerator = defineGenerator({
 			})
 		};
 		const inferTypeName = inferred ? resolver.schema.typeName(node.name) : null;
+		const isName = typeGuards ? resolver.schema.isName(node.name) : null;
+		const assertName = typeGuards ? resolver.schema.assertName(node.name) : null;
 		const stdPrinters = mini ? null : getStdPrinters(resolver, {
 			coercion,
 			guidType,
@@ -1777,6 +1884,10 @@ const zodGenerator = defineGenerator({
 					node,
 					printer: schemaPrinter,
 					inferTypeName,
+					typeGuards,
+					isName,
+					assertName,
+					mini,
 					cyclic: cyclicSchemas.has(node.name)
 				}),
 				hasDirectionalNode && stdPrinters && /* @__PURE__ */ jsx(Zod, {
@@ -1784,6 +1895,10 @@ const zodGenerator = defineGenerator({
 					node,
 					printer: stdPrinters.encode,
 					inferTypeName: inferred ? resolver.schema.inputTypeName(node.name) : null,
+					typeGuards,
+					isName: typeGuards ? resolver.schema.isName(resolver.schema.inputName(node.name)) : null,
+					assertName: typeGuards ? resolver.schema.assertName(resolver.schema.inputName(node.name)) : null,
+					mini,
 					cyclic: cyclicSchemas.has(node.name)
 				})
 			]
@@ -2062,6 +2177,12 @@ const resolverZod = createResolver({
 		},
 		inputTypeName(name) {
 			return this.schema.typeName(`${name} input`);
+		},
+		isName(name) {
+			return ensureValidVarName(camelCase(name, { prefix: "is" }));
+		},
+		assertName(name) {
+			return ensureValidVarName(camelCase(name, { prefix: "assert" }));
 		}
 	},
 	param: createOperationParamResolver(),
@@ -2112,7 +2233,7 @@ const pluginZod = definePlugin((options) => {
 	const { output = {
 		path: "zod",
 		barrel: { type: "named" }
-	}, group, exclude = [], include, override = [], mini = false, guidType = "uuid", regexType = "literal", importPath = mini ? "zod/mini" : "zod", coercion = false, inferred = false, printer, resolver: userResolver, macros: userMacros } = options;
+	}, group, exclude = [], include, override = [], mini = false, guidType = "uuid", regexType = "literal", importPath = mini ? "zod/mini" : "zod", coercion = false, inferred = false, typeGuards = false, printer, resolver: userResolver, macros: userMacros } = options;
 	const groupConfig = createGroupConfig(group);
 	return {
 		name: pluginZodName,
@@ -2130,6 +2251,7 @@ const pluginZod = definePlugin((options) => {
 				guidType,
 				regexType,
 				mini,
+				typeGuards,
 				printer
 			});
 			ctx.setResolver(userResolver ? Resolver.merge(resolverZod, userResolver) : resolverZod);