@kubb/plugin-zod 5.0.0-beta.22 → 5.0.0-beta.27

package/dist/index.d.ts

@@ -222,41 +222,53 @@ type ResolverZod = Resolver & ast.OperationParamsResolver & {
 };
 type Options = {
   /**
-   * @default 'zod'
+   * Where the generated Zod schemas are written and how they are exported.
+   *
+   * @default { path: 'zod', barrel: { type: 'named' } }
    */
   output?: Output;
   /**
-   * Group the Zod schemas based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group;
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Import path for Zod package.
+   * Module specifier used in the `import { z } from '...'` statement.
+   * Use `'zod/mini'` for the tree-shakeable bundle.
    *
    * @default 'zod'
    */
   importPath?: 'zod' | 'zod/mini' | (string & {});
   /**
-   * Add TypeScript type annotations to generated schemas.
+   * Tie each Zod schema to its TypeScript type from `@kubb/plugin-ts`. Requires
+   * `@kubb/plugin-ts` in the plugins list. TypeScript fails compilation when the
+   * schema drifts from the type.
    */
   typed?: boolean;
   /**
-   * Return schemas as inferred types using `z.infer`.
+   * Export a `z.infer<typeof schema>` type alias next to every generated schema.
+   * Lets the Zod schema act as the single source of truth.
    */
   inferred?: boolean;
   /**
-   * Apply coercion to string values or configure coercion per type.
+   * Wrap schemas in `z.coerce` so input is coerced before validation. Useful for
+   * form data and query params where everything arrives as a string.
+   * - `true` coerces strings, numbers, and dates.
+   * - Object form picks per-primitive coercion.
+   *
+   * @default false
+   * @see https://zod.dev/?id=coercion-for-primitives
    */
   coercion?: boolean | {
     dates?: boolean;
@@ -264,50 +276,59 @@ type Options = {
     numbers?: boolean;
   };
   /**
-   * Generate operation-level schemas (grouped by operationId).
+   * Emit an `operations.ts` file with request body, query/path params, and per-status
+   * response schemas grouped by operation.
    */
   operations?: boolean;
   /**
-   * Validator to use for UUID format: `uuid` or `guid`.
+   * Validator for `format: uuid` properties.
+   * - `'uuid'` — `z.uuid()`. Standard RFC 4122.
+   * - `'guid'` — `z.guid()`. Accepts Microsoft-style GUIDs.
    *
    * @default 'uuid'
    */
   guidType?: 'uuid' | 'guid';
   /**
-   * Use Zod Mini's functional API for better tree-shaking.
+   * Switch to Zod Mini's functional API for better tree-shaking. Also defaults
+   * `importPath` to `'zod/mini'`.
    *
    * @default false
+   * @beta
    */
   mini?: boolean;
   /**
-   * Callback to wrap the generated schema output.
-   *
-   * Useful for adding metadata like `.openapi()` or extension helpers.
+   * Wrap the generated Zod schema string with extra calls. Receives the raw output
+   * and the originating `SchemaNode`. Useful for round-tripping OpenAPI metadata
+   * back into Zod (e.g. `.openapi(...)`).
    */
   wrapOutput?: (arg: {
     output: string;
     schema: ast.SchemaNode;
   }) => string | undefined;
   /**
-   * Apply casing to parameter names.
+   * Rename properties inside path/query/header schemas. Body schemas are unaffected.
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase';
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in Zod generators.
    */
   generators?: Array<Generator<PluginZod>>;
   /**
-   * Override naming conventions for schema names and types.
+   * Override how schema and operation names are built. Methods you omit fall back
+   * to the default `resolverZod`.
    */
   resolver?: Partial<ResolverZod> & ThisType<ResolverZod>;
   /**
-   * Override printer node handlers to customize rendering of specific schema types.
+   * Replace the Zod handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * When `mini: true`, overrides target the Zod Mini printer instead.
    */
   printer?: {
     nodes?: PrinterZodNodes | PrinterZodMiniNodes;
   };
   /**
-   * AST visitor to transform schema and operation nodes.
+   * AST visitor applied to each schema or operation node before printing.
    */
   transformer?: ast.Visitor;
 };
@@ -316,7 +337,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
   override: Array<Override<ResolvedOptions>>;
-  group: Group | undefined;
+  group: Group | null;
   typed: NonNullable<Options['typed']>;
   inferred: NonNullable<Options['inferred']>;
   importPath: NonNullable<Options['importPath']>;
@@ -338,23 +359,42 @@ declare global {
 }
 //#endregion
 //#region src/generators/zodGenerator.d.ts
+/**
+ * Built-in generator for `@kubb/plugin-zod`. Emits one Zod schema per
+ * schema in the spec plus per-operation request/response/parameter schemas.
+ * When `mini: true`, schemas use the Zod Mini functional API instead of
+ * chainable methods.
+ */
 declare const zodGenerator: _$_kubb_core0.Generator<PluginZod, unknown>;
 //#endregion
 //#region src/plugin.d.ts
 /**
- * Canonical plugin name for `@kubb/plugin-zod`, used in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-zod`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 declare const pluginZodName = "plugin-zod";
 /**
- * Generates Zod validation schemas from an OpenAPI specification.
- * Walks schemas and operations, delegates to generators, and writes barrel files
- * based on the configured `barrelType`.
+ * 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-client` and
+ * set the client's `parser: 'zod'` to validate every response automatically.
  *
- * @example Zod schema generator
+ * @example
  * ```ts
- * import pluginZod from '@kubb/plugin-zod'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ *
  * export default defineConfig({
- *   plugins: [pluginZod({ output: { path: 'zod' } })]
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginZod({
+ *       output: { path: './zod' },
+ *       typed: true,
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -362,12 +402,17 @@ declare const pluginZod: (options?: Options | undefined) => _$_kubb_core0.Plugin
 //#endregion
 //#region src/resolvers/resolverZod.d.ts
 /**
- * Naming convention resolver for Zod plugin.
+ * Default resolver used by `@kubb/plugin-zod`. Decides the names and file
+ * paths for every generated Zod schema. Schemas use camelCase with a
+ * `Schema` suffix (`listPetsSchema`); their inferred types use PascalCase.
  *
- * Provides default naming helpers using camelCase with a `Schema` suffix for schemas.
+ * @example Resolve schema and type names
+ * ```ts
+ * import { resolverZod } from '@kubb/plugin-zod'
  *
- * @example
- * `resolverZod.default('list pets', 'function')  // → 'listPetsSchema'`
+ * resolverZod.default('list pets', 'function') // 'listPetsSchema'
+ * resolverZod.resolveSchemaTypeName('pet')     // 'PetSchema'
+ * ```
  */
 declare const resolverZod: ResolverZod;
 //#endregion

package/dist/index.js

@@ -126,6 +126,129 @@ function toRegExpString(text, func = "RegExp") {
 	return `new ${func}(${JSON.stringify(source)}${flags ? `, ${JSON.stringify(flags)}` : ""})`;
 }
 //#endregion
+//#region ../../internals/utils/src/reserved.ts
+/**
+* JavaScript and Java reserved words.
+* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
+*/
+const reservedWords = new Set([
+	"abstract",
+	"arguments",
+	"boolean",
+	"break",
+	"byte",
+	"case",
+	"catch",
+	"char",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"double",
+	"else",
+	"enum",
+	"eval",
+	"export",
+	"extends",
+	"false",
+	"final",
+	"finally",
+	"float",
+	"for",
+	"function",
+	"goto",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"int",
+	"interface",
+	"let",
+	"long",
+	"native",
+	"new",
+	"null",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"short",
+	"static",
+	"super",
+	"switch",
+	"synchronized",
+	"this",
+	"throw",
+	"throws",
+	"transient",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"volatile",
+	"while",
+	"with",
+	"yield",
+	"Array",
+	"Date",
+	"hasOwnProperty",
+	"Infinity",
+	"isFinite",
+	"isNaN",
+	"isPrototypeOf",
+	"length",
+	"Math",
+	"name",
+	"NaN",
+	"Number",
+	"Object",
+	"prototype",
+	"String",
+	"toString",
+	"undefined",
+	"valueOf"
+]);
+/**
+* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+*
+* @example
+* ```ts
+* isValidVarName('status')  // true
+* isValidVarName('class')   // false (reserved word)
+* isValidVarName('42foo')   // false (starts with digit)
+* ```
+*/
+function isValidVarName(name) {
+	if (!name || reservedWords.has(name)) return false;
+	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+}
+/**
+* Returns `name` when it's a syntactically valid JavaScript variable name,
+* otherwise prefixes it with `_` so the result is a valid identifier.
+*
+* Useful for sanitizing OpenAPI schema names or operation IDs that start with
+* a digit (e.g. `409`, `504AccountCancel`) before using them as exported
+* variable, type, or function names.
+*
+* @example
+* ```ts
+* ensureValidVarName('409')             // '_409'
+* ensureValidVarName('504AccountCancel') // '_504AccountCancel'
+* ensureValidVarName('Pet')              // 'Pet'
+* ensureValidVarName('class')            // '_class'
+* ```
+*/
+function ensureValidVarName(name) {
+	if (!name || isValidVarName(name)) return name;
+	return `_${name}`;
+}
+//#endregion
 //#region src/components/Operations.tsx
 function Operations({ name, operations }) {
 	const operationsJSON = operations.reduce((prev, acc) => {
@@ -261,11 +384,11 @@ function buildSchemaNames(node, { params, resolver }) {
 	}
 	responses["default"] = resolver.resolveResponseName(node);
 	return {
-		request: node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : void 0,
+		request: node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null,
 		parameters: {
-			path: pathParam ? resolver.resolvePathParamsName(node, pathParam) : void 0,
-			query: queryParam ? resolver.resolveQueryParamsName(node, queryParam) : void 0,
-			header: headerParam ? resolver.resolveHeaderParamsName(node, headerParam) : void 0
+			path: pathParam ? resolver.resolvePathParamsName(node, pathParam) : null,
+			query: queryParam ? resolver.resolveQueryParamsName(node, queryParam) : null,
+			header: headerParam ? resolver.resolveHeaderParamsName(node, headerParam) : null
 		},
 		responses,
 		errors
@@ -717,6 +840,12 @@ const printerZodMini = ast.definePrinter((options) => {
 //#region src/generators/zodGenerator.tsx
 const zodPrinterCache = /* @__PURE__ */ new WeakMap();
 const zodMiniPrinterCache = /* @__PURE__ */ new WeakMap();
+/**
+* Built-in generator for `@kubb/plugin-zod`. Emits one Zod schema per
+* schema in the spec plus per-operation request/response/parameter schemas.
+* When `mini: true`, schemas use the Zod Mini functional API instead of
+* chainable methods.
+*/
 const zodGenerator = defineGenerator({
 	name: "zod",
 	renderer: jsxRendererSync,
@@ -735,7 +864,7 @@ const zodGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			}).path
 		}));
 		const meta = {
@@ -746,10 +875,10 @@ const zodGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			})
 		};
-		const inferTypeName = inferred ? resolver.resolveSchemaTypeName(node.name) : void 0;
+		const inferTypeName = inferred ? resolver.resolveSchemaTypeName(node.name) : null;
 		const cyclicSchemas = new Set(ctx.meta.circularNames);
 		const schemaPrinter = mini ? getCachedMiniPrinter() : getCachedStdPrinter();
 		function getCachedStdPrinter() {
@@ -835,12 +964,12 @@ const zodGenerator = defineGenerator({
 		}, {
 			root,
 			output,
-			group
+			group: group ?? void 0
 		}) };
 		const cyclicSchemas = new Set(ctx.meta.circularNames);
 		function renderSchemaEntry({ schema, name, keysToOmit }) {
 			if (!schema) return null;
-			const inferTypeName = inferred ? resolver.resolveTypeName(name) : void 0;
+			const inferTypeName = inferred ? resolver.resolveTypeName(name) : null;
 			const imports = adapter.getImports(schema, (schemaName) => ({
 				name: resolver.resolveSchemaName(schemaName),
 				path: resolver.resolveFile({
@@ -849,7 +978,7 @@ const zodGenerator = defineGenerator({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				}).path
 			}));
 			const cachedStd = zodPrinterCache.get(resolver);
@@ -972,7 +1101,7 @@ const zodGenerator = defineGenerator({
 		}, {
 			root,
 			output,
-			group
+			group: group ?? void 0
 		}) };
 		const transformedOperations = nodes.map((node) => {
 			return {
@@ -997,7 +1126,7 @@ const zodGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			});
 			return names.map((name) => /* @__PURE__ */ jsx(File.Import, {
 				name: [name],
@@ -1036,31 +1165,37 @@ const zodGenerator = defineGenerator({
 //#endregion
 //#region src/resolvers/resolverZod.ts
 /**
-* Naming convention resolver for Zod plugin.
+* Default resolver used by `@kubb/plugin-zod`. Decides the names and file
+* paths for every generated Zod schema. Schemas use camelCase with a
+* `Schema` suffix (`listPetsSchema`); their inferred types use PascalCase.
 *
-* Provides default naming helpers using camelCase with a `Schema` suffix for schemas.
+* @example Resolve schema and type names
+* ```ts
+* import { resolverZod } from '@kubb/plugin-zod'
 *
-* @example
-* `resolverZod.default('list pets', 'function')  // → 'listPetsSchema'`
+* resolverZod.default('list pets', 'function') // 'listPetsSchema'
+* resolverZod.resolveSchemaTypeName('pet')     // 'PetSchema'
+* ```
 */
 const resolverZod = defineResolver(() => {
 	return {
 		name: "default",
 		pluginName: "plugin-zod",
 		default(name, type) {
-			return camelCase(name, {
+			const resolved = camelCase(name, {
 				isFile: type === "file",
 				suffix: type ? "schema" : void 0
 			});
+			return type === "file" ? resolved : ensureValidVarName(resolved);
 		},
 		resolveSchemaName(name) {
-			return camelCase(name, { suffix: "schema" });
+			return ensureValidVarName(camelCase(name, { suffix: "schema" }));
 		},
 		resolveSchemaTypeName(name) {
-			return pascalCase(name, { suffix: "schema" });
+			return ensureValidVarName(pascalCase(name, { suffix: "schema" }));
 		},
 		resolveTypeName(name) {
-			return pascalCase(name);
+			return ensureValidVarName(pascalCase(name));
 		},
 		resolvePathName(name, type) {
 			return this.default(name, type);
@@ -1094,19 +1229,32 @@ const resolverZod = defineResolver(() => {
 //#endregion
 //#region src/plugin.ts
 /**
-* Canonical plugin name for `@kubb/plugin-zod`, used in driver lookups and warnings.
+* Canonical plugin name for `@kubb/plugin-zod`. Used for driver lookups and
+* cross-plugin dependency references.
 */
 const pluginZodName = "plugin-zod";
 /**
-* Generates Zod validation schemas from an OpenAPI specification.
-* Walks schemas and operations, delegates to generators, and writes barrel files
-* based on the configured `barrelType`.
+* 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-client` and
+* set the client's `parser: 'zod'` to validate every response automatically.
 *
-* @example Zod schema generator
+* @example
 * ```ts
-* import pluginZod from '@kubb/plugin-zod'
+* import { defineConfig } from 'kubb'
+* import { pluginTs } from '@kubb/plugin-ts'
+* import { pluginZod } from '@kubb/plugin-zod'
+*
 * export default defineConfig({
-*   plugins: [pluginZod({ output: { path: 'zod' } })]
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginTs(),
+*     pluginZod({
+*       output: { path: './zod' },
+*       typed: true,
+*     }),
+*   ],
 * })
 * ```
 */
@@ -1121,7 +1269,7 @@ const pluginZod = definePlugin((options) => {
 			if (group.type === "path") return `${ctx.group.split("/")[1]}`;
 			return `${camelCase(ctx.group)}Controller`;
 		}
-	} : void 0;
+	} : null;
 	return {
 		name: pluginZodName,
 		options,