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

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
@@ -1190,6 +1220,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 +1258,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() {
@@ -1451,6 +1511,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 +1546,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) {
@@ -1667,7 +1753,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 +1809,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 +1865,10 @@ const zodGenerator = defineGenerator({
 					node,
 					printer: schemaPrinter,
 					inferTypeName,
+					typeGuards,
+					isName,
+					assertName,
+					mini,
 					cyclic: cyclicSchemas.has(node.name)
 				}),
 				hasDirectionalNode && stdPrinters && /* @__PURE__ */ jsx(Zod, {
@@ -1784,6 +1876,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 +2158,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 +2214,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 +2232,7 @@ const pluginZod = definePlugin((options) => {
 				guidType,
 				regexType,
 				mini,
+				typeGuards,
 				printer
 			});
 			ctx.setResolver(userResolver ? Resolver.merge(resolverZod, userResolver) : resolverZod);