@kubb/plugin-zod 5.0.0-beta.4 → 5.0.0-beta.56

package/src/resolvers/resolverZod.ts

@@ -1,57 +1,71 @@
-import { camelCase, pascalCase } from '@internals/utils'
+import { camelCase, ensureValidVarName, pascalCase, toFilePath } 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
+ * with a `SchemaType` suffix (`PetSchemaType`), so the value and the type
+ * never share an identifier even when the schema name is all-uppercase.
  *
- * 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')     // 'PetSchemaType'
+ * ```
  */
-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 })
+      if (type === 'file') return toFilePath(name, (part) => camelCase(part, { suffix: 'schema' }))
+      return ensureValidVarName(camelCase(name, { suffix: type ? 'schema' : undefined }))
     },
     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 type' }))
+    },
+    resolveInputSchemaName(name) {
+      return this.resolveSchemaName(`${name} input`)
+    },
+    resolveInputSchemaTypeName(name) {
+      return this.resolveSchemaTypeName(`${name} input`)
     },
     resolveTypeName(name) {
-      return pascalCase(name)
+      return ensureValidVarName(pascalCase(name, { suffix: 'type' }))
     },
     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

@@ -1,4 +1,4 @@
-import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
+import type { ast, Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
 import type { PrinterZodNodes } from './printers/printerZod.ts'
 import type { PrinterZodMiniNodes } from './printers/printerZodMini.ts'
 
@@ -15,14 +15,29 @@ export type ResolverZod = Resolver &
      * Resolves the schema type name (inferred type from schema).
      *
      * @example Schema type names
-     * `resolver.resolveSchemaTypeName('pet') // → 'Pet'`
+     * `resolver.resolveSchemaTypeName('pet') // → 'PetSchemaType'`
      */
     resolveSchemaTypeName(this: ResolverZod, name: string): string
+    /**
+     * Resolves the schema function name for the request (input) direction of a
+     * date-bearing component, where `Date` is encoded back to a wire `string`.
+     *
+     * @example Input schema names
+     * `resolver.resolveInputSchemaName('order') // → 'orderInputSchema'`
+     */
+    resolveInputSchemaName(this: ResolverZod, name: string): string
+    /**
+     * Resolves the inferred type name for the request (input) direction variant.
+     *
+     * @example Input schema type names
+     * `resolver.resolveInputSchemaTypeName('order') // → 'OrderInputSchemaType'`
+     */
+    resolveInputSchemaTypeName(this: ResolverZod, name: string): string
     /**
      * Resolves the generated type name from the schema.
      *
      * @example Type names
-     * `resolver.resolveTypeName('pet') // → 'Pet'`
+     * `resolver.resolveTypeName('petSchema') // → 'PetSchemaType'`
      */
     resolveTypeName(this: ResolverZod, name: string): string
     /**
@@ -73,87 +88,104 @@ export type ResolverZod = Resolver &
     resolveHeaderParamsName(this: ResolverZod, node: ast.OperationNode, param: ast.ParameterNode): string
   }
 
-export type Options = {
-  /**
-   * @default 'zod'
-   */
-  output?: Output
-  /**
-   * Group the Zod schemas based on the provided name.
-   */
-  group?: Group
+/**
+ * Where the generated Zod schemas are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'zod', barrel: { type: 'named' } }
+ */
+export type Options = OutputOptions & {
   /**
-   * 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'
+   * @default mini ? 'zod/mini' : '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 +195,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

@@ -1,4 +1,4 @@
-import { stringify, toRegExpString } from '@internals/utils'
+import { extractRefName, stringify, toRegExpString } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
 import type { PluginZod, ResolverZod } from './types.ts'
 
@@ -12,6 +12,99 @@ export function shouldCoerce(coercion: PluginZod['resolvedOptions']['coercion']
   return !!coercion[type]
 }
 
+/**
+ * A codec for a schema node whose runtime type differs from its JSON wire type:
+ * the output (response) schema decodes wire → runtime, and the input (request)
+ * variant encodes runtime → wire.
+ *
+ * To support another codec type, append a `Codec` to `codecs` and route that
+ * type's printer node handler through `getCodec`.
+ */
+export type Codec = {
+  /**
+   * Whether this node is encoded/decoded by this codec.
+   */
+  matches(node: ast.SchemaNode): boolean
+  /**
+   * Output direction (response): decode the wire value into the runtime type.
+   */
+  decode(node: ast.SchemaNode): string
+  /**
+   * Input direction (request): encode the runtime value back to the wire value.
+   */
+  encode(node: ast.SchemaNode): string
+}
+
+/**
+ * `dateType: 'date'` fields are typed as `Date` but travel as ISO `string`s.
+ * Output decodes `string → Date`; input encodes `Date → string`, preserving the
+ * `date` (`YYYY-MM-DD`) vs `date-time` precision carried on `node.format`.
+ */
+const dateCodec: Codec = {
+  matches(node) {
+    return node.type === 'date' && node.representation === 'date'
+  },
+  decode(node) {
+    return node.format === 'date' ? 'z.iso.date().transform((value) => new Date(value))' : 'z.iso.datetime().transform((value) => new Date(value))'
+  },
+  encode(node) {
+    return node.format === 'date' ? 'z.date().transform((value) => value.toISOString().slice(0, 10))' : 'z.date().transform((value) => value.toISOString())'
+  },
+}
+
+/**
+ * Registered codecs, checked in order.
+ */
+const codecs: Array<Codec> = [dateCodec]
+
+/**
+ * Returns the codec for this node, or `undefined` when the node needs no
+ * encode/decode (its wire and runtime types match).
+ */
+export function getCodec(node: ast.SchemaNode | undefined): Codec | undefined {
+  if (!node) return undefined
+  return codecs.find((codec) => codec.matches(node))
+}
+
+/**
+ * Returns `true` when the node itself is encoded/decoded by a codec.
+ */
+export function hasCodec(node: ast.SchemaNode | undefined): boolean {
+  return getCodec(node) !== undefined
+}
+
+/**
+ * Returns `true` when the schema transitively contains a codec node —
+ * a value whose runtime type differs from its wire type (see {@link hasCodec}),
+ * so it must be decoded (response) or encoded (request) at the validation boundary.
+ * `$ref`s are followed via their resolved schema; a `seen` set guards cycles.
+ */
+export function containsCodec(node: ast.SchemaNode | undefined, seen: Set<string> = new Set()): boolean {
+  if (!node) return false
+
+  if (hasCodec(node)) return true
+
+  if (node.type === 'ref') {
+    if (!node.ref) return false
+    const refName = extractRefName(node.ref)
+    if (refName) {
+      if (seen.has(refName)) return false
+      seen.add(refName)
+    }
+    const resolved = ast.syncSchemaRef(node)
+    if (resolved.type === 'ref') return false
+    return containsCodec(resolved, seen)
+  }
+
+  const children: Array<ast.SchemaNode | undefined> = []
+  if ('properties' in node && node.properties) children.push(...node.properties.map((prop) => prop.schema))
+  if ('items' in node && node.items) children.push(...node.items)
+  if ('members' in node && node.members) children.push(...node.members)
+  if ('additionalProperties' in node && node.additionalProperties && node.additionalProperties !== true) children.push(node.additionalProperties)
+
+  return children.some((child) => containsCodec(child, seen))
+}
+
 /**
  * Collects all resolved schema names for an operation's parameters and responses
  * into a single lookup object, useful for building imports and type references.
@@ -39,11 +132,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 +226,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 +239,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 +251,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 +266,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 = {