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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-zod",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.25",
   "description": "Generate Zod validation schemas from your OpenAPI specification for runtime data parsing and type safety. Pairs perfectly with @kubb/plugin-ts for end-to-end type coverage.",
   "keywords": [
     "code-generation",
@@ -48,15 +48,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.22",
-    "@kubb/renderer-jsx": "5.0.0-beta.22",
+    "@kubb/core": "5.0.0-beta.25",
+    "@kubb/renderer-jsx": "5.0.0-beta.25",
     "remeda": "^2.34.1"
   },
   "devDependencies": {
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.22"
+    "@kubb/renderer-jsx": "5.0.0-beta.25"
   },
   "size-limit": [
     {

package/src/components/Operations.tsx

@@ -4,11 +4,11 @@ import { Const, File, Type } from '@kubb/renderer-jsx'
 import type { KubbReactNode } from '@kubb/renderer-jsx/types'
 
 type SchemaNames = {
-  request: string | undefined
+  request: string | null
   parameters: {
-    path: string | undefined
-    query: string | undefined
-    header: string | undefined
+    path: string | null
+    query: string | null
+    header: string | null
   }
   responses: { default?: string } & Record<number | string, string>
   errors: Record<number | string, string>

package/src/components/Zod.tsx

@@ -13,7 +13,7 @@ type Props = {
    * then merges in any user-supplied `printer.nodes` overrides.
    */
   printer: ast.Printer<PrinterZodFactory> | ast.Printer<PrinterZodMiniFactory>
-  inferTypeName?: string
+  inferTypeName?: string | null
 }
 
 export function Zod({ name, node, printer, inferTypeName }: Props): KubbReactNode {

package/src/generators/zodGenerator.tsx

@@ -17,6 +17,12 @@ type ZodMiniPrinterEntry = { printer: ReturnType<typeof printerZodMini>; guidTyp
 const zodPrinterCache = new WeakMap<ResolverZod, ZodPrinterEntry>()
 const zodMiniPrinterCache = new WeakMap<ResolverZod, ZodMiniPrinterEntry>()
 
+/**
+ * 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.
+ */
 export const zodGenerator = defineGenerator<PluginZod>({
   name: 'zod',
   renderer: jsxRendererSync,
@@ -34,15 +40,15 @@ export const zodGenerator = defineGenerator<PluginZod>({
 
     const imports = adapter.getImports(node, (schemaName) => ({
       name: resolver.resolveSchemaName(schemaName),
-      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
     }))
 
     const meta = {
       name: resolver.resolveSchemaName(node.name),
-      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group }),
+      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group: group ?? undefined }),
     } as const
 
-    const inferTypeName = inferred ? resolver.resolveSchemaTypeName(node.name) : undefined
+    const inferTypeName = inferred ? resolver.resolveSchemaTypeName(node.name) : null
 
     const cyclicSchemas = new Set<string>(ctx.meta.circularNames)
 
@@ -92,7 +98,10 @@ export const zodGenerator = defineGenerator<PluginZod>({
     const params = ast.caseParams(node.parameters, paramsCasing)
 
     const meta = {
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
     } as const
 
     const cyclicSchemas = new Set<string>(ctx.meta.circularNames)
@@ -100,11 +109,11 @@ export const zodGenerator = defineGenerator<PluginZod>({
     function renderSchemaEntry({ schema, name, keysToOmit }: { schema: ast.SchemaNode | null; name: string; keysToOmit?: Array<string> | null }) {
       if (!schema) return null
 
-      const inferTypeName = inferred ? resolver.resolveTypeName(name) : undefined
+      const inferTypeName = inferred ? resolver.resolveTypeName(name) : null
 
       const imports = adapter.getImports(schema, (schemaName) => ({
         name: resolver.resolveSchemaName(schemaName),
-        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
       }))
 
       const cachedStd = zodPrinterCache.get(resolver)
@@ -213,7 +222,7 @@ export const zodGenerator = defineGenerator<PluginZod>({
     const isZodImport = ZOD_NAMESPACE_IMPORTS.has(importPath as 'zod' | 'zod/mini')
 
     const meta = {
-      file: resolver.resolveFile({ name: 'operations', extname: '.ts' }, { root, output, group }),
+      file: resolver.resolveFile({ name: 'operations', extname: '.ts' }, { root, output, group: group ?? undefined }),
     } as const
 
     const transformedOperations = nodes.map((node) => {
@@ -226,8 +235,11 @@ export const zodGenerator = defineGenerator<PluginZod>({
     })
 
     const imports = transformedOperations.flatMap(({ node, data }) => {
-      const names = [data.request, ...Object.values(data.responses), ...Object.values(data.parameters)].filter(Boolean) as string[]
-      const opFile = resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group })
+      const names = [data.request, ...Object.values(data.responses), ...Object.values(data.parameters)].filter(Boolean) as Array<string>
+      const opFile = resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      )
 
       return names.map((name) => <File.Import key={[name, opFile.path].join('-')} name={[name]} root={meta.file.path} path={opFile.path} />)
     })

package/src/plugin.ts

@@ -5,20 +5,33 @@ import { resolverZod } from './resolvers/resolverZod.ts'
 import type { PluginZod } from './types.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.
  */
 export const pluginZodName = 'plugin-zod' satisfies PluginZod['name']
 
 /**
- * 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,
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -54,7 +67,7 @@ export const pluginZod = definePlugin<PluginZod>((options) => {
           return `${camelCase(ctx.group)}Controller`
         },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginZodName,

package/src/resolvers/resolverZod.ts

@@ -3,12 +3,17 @@ import { defineResolver } from '@kubb/core'
 import type { PluginZod } from '../types.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'
+ * ```
  */
 export const resolverZod = defineResolver<PluginZod>(() => {
   return {

package/src/types.ts

@@ -75,85 +75,106 @@ export type ResolverZod = Resolver &
 
 export 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; strings?: boolean; 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
 }
@@ -163,7 +184,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']>

package/src/utils.ts

@@ -39,11 +39,11 @@ export function buildSchemaNames(node: ast.OperationNode, { params, resolver }:
   responses['default'] = resolver.resolveResponseName(node)
 
   return {
-    request: node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined,
+    request: node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null,
     parameters: {
-      path: pathParam ? resolver.resolvePathParamsName(node, pathParam) : undefined,
-      query: queryParam ? resolver.resolveQueryParamsName(node, queryParam) : undefined,
-      header: headerParam ? resolver.resolveHeaderParamsName(node, headerParam) : undefined,
+      path: pathParam ? resolver.resolvePathParamsName(node, pathParam) : null,
+      query: queryParam ? resolver.resolveQueryParamsName(node, queryParam) : null,
+      header: headerParam ? resolver.resolveHeaderParamsName(node, headerParam) : null,
     },
     responses,
     errors,
@@ -133,7 +133,7 @@ export function lengthConstraints({ min, max, pattern }: LengthConstraints): str
  * Build `.check(z.minimum(), z.maximum())` for `zod/mini` numeric constraints.
  */
 export function numberChecksMini({ min, max, exclusiveMinimum, exclusiveMaximum, multipleOf }: NumericConstraints): string {
-  const checks: string[] = []
+  const checks: Array<string> = []
   if (min !== undefined) checks.push(`z.minimum(${min})`)
   if (max !== undefined) checks.push(`z.maximum(${max})`)
   if (exclusiveMinimum !== undefined) checks.push(`z.minimum(${exclusiveMinimum}, { exclusive: true })`)
@@ -146,7 +146,7 @@ export function numberChecksMini({ min, max, exclusiveMinimum, exclusiveMaximum,
  * Build `.check(z.minLength(), z.maxLength(), z.regex())` for `zod/mini` length constraints.
  */
 export function lengthChecksMini({ min, max, pattern }: LengthConstraints): string {
-  const checks: string[] = []
+  const checks: Array<string> = []
   if (min !== undefined) checks.push(`z.minLength(${min})`)
   if (max !== undefined) checks.push(`z.maxLength(${max})`)
   if (pattern !== undefined) checks.push(`z.regex(${toRegExpString(pattern, null)})`)