@kubb/plugin-zod 5.0.0-beta.3 → 5.0.0-beta.30

package/src/printers/printerZodMini.ts

@@ -45,7 +45,7 @@ export type PrinterZodMiniOptions = {
   /**
    * Properties to exclude using `.omit({ key: true })`.
    */
-  keysToOmit?: Array<string>
+  keysToOmit?: Array<string> | null
   /**
    * Schema names that form circular dependency chains.
    * Properties referencing these emit lazy getters wrapping refs in `z.lazy(() => …)`.
@@ -61,6 +61,22 @@ export type PrinterZodMiniOptions = {
  * Factory options for the Zod Mini printer, defining input/output types and configuration.
  */
 export type PrinterZodMiniFactory = ast.PrinterFactoryOptions<'zod-mini', PrinterZodMiniOptions, string, string>
+
+function strictOneOfMember(member: string, node: ast.SchemaNode): string {
+  if (node.type === 'object' && (node.additionalProperties === undefined || node.additionalProperties === false)) {
+    return member.replace(/^z\.object\(/, 'z.strictObject(')
+  }
+
+  return member
+}
+
+function getMemberConstraintMini(member: ast.SchemaNode): string | undefined {
+  if (member.primitive === 'string') return lengthChecksMini(ast.narrowSchema(member, 'string') ?? {}) || undefined
+  if (member.primitive === 'number' || member.primitive === 'integer')
+    return numberChecksMini(ast.narrowSchema(member, 'number') ?? ast.narrowSchema(member, 'integer') ?? {}) || undefined
+  if (member.primitive === 'array') return lengthChecksMini(ast.narrowSchema(member, 'array') ?? {}) || undefined
+}
+
 /**
  * Zod v4 **Mini** printer built with `definePrinter`.
  *
@@ -144,7 +160,7 @@ export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options)
       },
 
       ref(node) {
-        if (!node.name) return undefined
+        if (!node.name) return null
         const refName = node.ref ? (ast.extractRefName(node.ref) ?? node.name) : node.name
         const resolvedName = node.ref ? (this.options.resolver?.default(refName, 'function') ?? refName) : node.name
 
@@ -168,9 +184,12 @@ export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options)
             const hasSelfRef = this.options.cyclicSchemas != null && ast.containsCircularRef(schema, { circularSchemas: this.options.cyclicSchemas })
             // Inside a getter the getter itself defers evaluation, so suppress
             // z.lazy() wrapping on nested refs by temporarily clearing cyclicSchemas.
+            // Save before clearing: this.options === options (same reference via definePrinter),
+            // so reading options.cyclicSchemas after mutation would return undefined.
+            const savedCyclicSchemas = this.options.cyclicSchemas
             if (hasSelfRef) this.options.cyclicSchemas = undefined
             const baseOutput = this.transform(schema) ?? this.transform(ast.createSchema({ type: 'unknown' }))!
-            if (hasSelfRef) this.options.cyclicSchemas = options.cyclicSchemas
+            if (hasSelfRef) this.options.cyclicSchemas = savedCyclicSchemas
 
             const wrappedOutput = this.options.wrapOutput ? this.options.wrapOutput({ output: baseOutput, schema }) || baseOutput : baseOutput
 
@@ -194,13 +213,9 @@ export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options)
       array(node) {
         const items = (node.items ?? []).map((item) => this.transform(item)).filter(Boolean)
         const inner = items.join(', ') || this.transform(ast.createSchema({ type: 'unknown' }))!
-        let result = `z.array(${inner})${lengthChecksMini(node)}`
-
-        if (node.unique) {
-          result += `.refine(items => new Set(items).size === items.length, { message: "Array entries must be unique" })`
-        }
+        const base = `z.array(${inner})${lengthChecksMini(node)}`
 
-        return result
+        return node.unique ? `${base}.refine(items => new Set(items).size === items.length, { message: "Array entries must be unique" })` : base
       },
       tuple(node) {
         const items = (node.items ?? []).map((item) => this.transform(item)).filter(Boolean)
@@ -209,7 +224,13 @@ export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options)
       },
       union(node) {
         const nodeMembers = node.members ?? []
-        const members = nodeMembers.map((m) => this.transform(m)).filter(Boolean)
+        const members = nodeMembers
+          .map((memberNode) => {
+            const member = this.transform(memberNode)
+
+            return member && node.strategy === 'one' ? strictOneOfMember(member, memberNode) : member
+          })
+          .filter(Boolean)
         if (members.length === 0) return ''
         if (members.length === 1) return members[0]!
         if (node.discriminatorPropertyName && !nodeMembers.some((m) => m.type === 'intersection')) {
@@ -227,61 +248,37 @@ export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options)
         const [first, ...rest] = members
         if (!first) return ''
 
-        let base = this.transform(first)
-        if (!base) return ''
+        const firstBase = this.transform(first)
+        if (!firstBase) return ''
 
-        for (const member of rest) {
-          if (member.primitive === 'string') {
-            const s = ast.narrowSchema(member, 'string')
-            const c = lengthChecksMini(s ?? {})
-            if (c) {
-              base += c
-              continue
-            }
-          } else if (member.primitive === 'number' || member.primitive === 'integer') {
-            const n = ast.narrowSchema(member, 'number') ?? ast.narrowSchema(member, 'integer')
-            const c = numberChecksMini(n ?? {})
-            if (c) {
-              base += c
-              continue
-            }
-          } else if (member.primitive === 'array') {
-            const a = ast.narrowSchema(member, 'array')
-            const c = lengthChecksMini(a ?? {})
-            if (c) {
-              base += c
-              continue
-            }
-          }
+        return rest.reduce((acc, member) => {
+          const constraint = getMemberConstraintMini(member)
+          if (constraint) return acc + constraint
           const transformed = this.transform(member)
-          if (transformed) base = `z.intersection(${base}, ${transformed})`
-        }
-
-        return base
+          return transformed ? `z.intersection(${acc}, ${transformed})` : acc
+        }, firstBase)
       },
       ...options.nodes,
     },
     print(node) {
       const { keysToOmit } = this.options
 
-      let base = this.transform(node)
-      if (!base) return null
+      const transformed = this.transform(node)
+      if (!transformed) return null
 
       const meta = ast.syncSchemaRef(node)
 
-      if (keysToOmit?.length && meta.primitive === 'object' && !(meta.type === 'union' && meta.discriminatorPropertyName)) {
+      const base = (() => {
+        if (!keysToOmit?.length || meta.primitive !== 'object' || (meta.type === 'union' && meta.discriminatorPropertyName)) return transformed
         // Mirror printerTs `nonNullable: true`: when omitting keys, the resulting
         // schema is a new non-nullable object type — skip optional/nullable/nullish.
         // Discriminated unions (z.discriminatedUnion) do not support .omit(), so skip them.
 
         // If this is a lazy reference, apply omit inside the lazy function
-        const lazyMatch = base.match(/^z\.lazy\(\(\)\s*=>\s*(.+)\)$/)
-        if (lazyMatch) {
-          base = `z.lazy(() => ${lazyMatch[1]}.omit({ ${keysToOmit.map((k: string) => `"${k}": true`).join(', ')} }))`
-        } else {
-          base = `${base}.omit({ ${keysToOmit.map((k: string) => `"${k}": true`).join(', ')} })`
-        }
-      }
+        const lazyMatch = transformed.match(/^z\.lazy\(\(\)\s*=>\s*(.+)\)$/)
+        if (lazyMatch) return `z.lazy(() => ${lazyMatch[1]}.omit({ ${keysToOmit.map((k: string) => `"${k}": true`).join(', ')} }))`
+        return `${transformed}.omit({ ${keysToOmit.map((k: string) => `"${k}": true`).join(', ')} })`
+      })()
 
       return applyMiniModifiers({
         value: base,

package/src/resolvers/resolverZod.ts

@@ -1,57 +1,63 @@
-import { camelCase, pascalCase } from '@internals/utils'
+import { camelCase, ensureValidVarName, pascalCase } from '@internals/utils'
 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>((ctx) => {
+export const resolverZod = defineResolver<PluginZod>(() => {
   return {
     name: 'default',
     pluginName: 'plugin-zod',
     default(name, type) {
-      return camelCase(name, { isFile: type === 'file', suffix: type ? 'schema' : undefined })
+      const resolved = camelCase(name, { isFile: type === 'file', suffix: type ? 'schema' : undefined })
+      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 ctx.default(name, type)
+      return this.default(name, type)
     },
     resolveParamName(node, param) {
-      return ctx.resolveSchemaName(`${node.operationId} ${param.in} ${param.name}`)
+      return this.resolveSchemaName(`${node.operationId} ${param.in} ${param.name}`)
     },
     resolveResponseStatusName(node, statusCode) {
-      return ctx.resolveSchemaName(`${node.operationId} Status ${statusCode}`)
+      return this.resolveSchemaName(`${node.operationId} Status ${statusCode}`)
     },
     resolveDataName(node) {
-      return ctx.resolveSchemaName(`${node.operationId} Data`)
+      return this.resolveSchemaName(`${node.operationId} Data`)
     },
     resolveResponsesName(node) {
-      return ctx.resolveSchemaName(`${node.operationId} Responses`)
+      return this.resolveSchemaName(`${node.operationId} Responses`)
     },
     resolveResponseName(node) {
-      return ctx.resolveSchemaName(`${node.operationId} Response`)
+      return this.resolveSchemaName(`${node.operationId} Response`)
     },
     resolvePathParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
     resolveQueryParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
     resolveHeaderParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
   }
 })

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)})`)
@@ -158,21 +158,14 @@ export function lengthChecksMini({ min, max, pattern }: LengthConstraints): stri
  * to a schema value string using the chainable Zod v4 API.
  */
 export function applyModifiers({ value, nullable, optional, nullish, defaultValue, description }: ModifierOptions): string {
-  let result = value
-  if (nullish || (nullable && optional)) {
-    result = `${result}.nullish()`
-  } else if (optional) {
-    result = `${result}.optional()`
-  } else if (nullable) {
-    result = `${result}.nullable()`
-  }
-  if (defaultValue !== undefined) {
-    result = `${result}.default(${formatDefault(defaultValue)})`
-  }
-  if (description) {
-    result = `${result}.describe(${stringify(description)})`
-  }
-  return result
+  const withModifier = (() => {
+    if (nullish || (nullable && optional)) return `${value}.nullish()`
+    if (optional) return `${value}.optional()`
+    if (nullable) return `${value}.nullable()`
+    return value
+  })()
+  const withDefault = defaultValue !== undefined ? `${withModifier}.default(${formatDefault(defaultValue)})` : withModifier
+  return description ? `${withDefault}.describe(${stringify(description)})` : withDefault
 }
 
 /**
@@ -180,21 +173,12 @@ export function applyModifiers({ value, nullable, optional, nullish, defaultValu
  * (`z.nullable()`, `z.optional()`, `z.nullish()`).
  */
 export function applyMiniModifiers({ value, nullable, optional, nullish, defaultValue }: Omit<ModifierOptions, 'description'>): string {
-  let result = value
-  if (nullish) {
-    result = `z.nullish(${result})`
-  } else {
-    if (nullable) {
-      result = `z.nullable(${result})`
-    }
-    if (optional) {
-      result = `z.optional(${result})`
-    }
-  }
-  if (defaultValue !== undefined) {
-    result = `z._default(${result}, ${formatDefault(defaultValue)})`
-  }
-  return result
+  const withModifier = (() => {
+    if (nullish) return `z.nullish(${value})`
+    const withNullable = nullable ? `z.nullable(${value})` : value
+    return optional ? `z.optional(${withNullable})` : withNullable
+  })()
+  return defaultValue !== undefined ? `z._default(${withModifier}, ${formatDefault(defaultValue)})` : withModifier
 }
 
 type BuildGroupedParamsSchemaOptions = {