@kubb/plugin-zod 5.0.0-alpha.8 → 5.0.0-beta.3

package/src/types.ts

@@ -1,172 +1,187 @@
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
-import type { contentType, Oas, SchemaObject } from '@kubb/oas'
-import type { Exclude, Include, Override, ResolvePathOptions, Schema } from '@kubb/plugin-oas'
-import type { Generator } from '@kubb/plugin-oas/generators'
+import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
+import type { PrinterZodNodes } from './printers/printerZod.ts'
+import type { PrinterZodMiniNodes } from './printers/printerZodMini.ts'
+
+/**
+ * Resolver for Zod that provides naming methods for schema types.
+ */
+export type ResolverZod = Resolver &
+  ast.OperationParamsResolver & {
+    /**
+     * Resolves a camelCase schema function name with a `Schema` suffix.
+     */
+    resolveSchemaName(this: ResolverZod, name: string): string
+    /**
+     * Resolves the schema type name (inferred type from schema).
+     *
+     * @example Schema type names
+     * `resolver.resolveSchemaTypeName('pet') // → 'Pet'`
+     */
+    resolveSchemaTypeName(this: ResolverZod, name: string): string
+    /**
+     * Resolves the generated type name from the schema.
+     *
+     * @example Type names
+     * `resolver.resolveTypeName('pet') // → 'Pet'`
+     */
+    resolveTypeName(this: ResolverZod, name: string): string
+    /**
+     * Resolves the output file name for a schema.
+     */
+    resolvePathName(this: ResolverZod, name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+    /**
+     * Resolves the name for an operation response by status code.
+     *
+     * @example Response status names
+     * `resolver.resolveResponseStatusName(node, 200) // → 'listPetsStatus200Schema'`
+     */
+    resolveResponseStatusName(this: ResolverZod, node: ast.OperationNode, statusCode: ast.StatusCode): string
+    /**
+     * Resolves the name for the collection of all operation responses.
+     *
+     * @example Responses collection names
+     * `resolver.resolveResponsesName(node) // → 'listPetsResponsesSchema'`
+     */
+    resolveResponsesName(this: ResolverZod, node: ast.OperationNode): string
+    /**
+     * Resolves the name for the union of all operation responses.
+     *
+     * @example Response union names
+     * `resolver.resolveResponseName(node) // → 'listPetsResponseSchema'`
+     */
+    resolveResponseName(this: ResolverZod, node: ast.OperationNode): string
+    /**
+     * Resolves the name for an operation's grouped path parameters type.
+     *
+     * @example Path parameters names
+     * `resolver.resolvePathParamsName(node, param) // → 'deletePetPathPetIdSchema'`
+     */
+    resolvePathParamsName(this: ResolverZod, node: ast.OperationNode, param: ast.ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped query parameters type.
+     *
+     * @example Query parameters names
+     * `resolver.resolveQueryParamsName(node, param) // → 'findPetsByStatusQueryStatusSchema'`
+     */
+    resolveQueryParamsName(this: ResolverZod, node: ast.OperationNode, param: ast.ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped header parameters type.
+     *
+     * @example Header parameters names
+     * `resolver.resolveHeaderParamsName(node, param) // → 'deletePetHeaderApiKeySchema'`
+     */
+    resolveHeaderParamsName(this: ResolverZod, node: ast.OperationNode, param: ast.ParameterNode): string
+  }
 
 export type Options = {
   /**
    * @default 'zod'
    */
-  output?: Output<Oas>
-  /**
-   * Define which contentType should be used.
-   * By default, the first JSON valid mediaType is used
-   */
-  contentType?: contentType
+  output?: Output
   /**
    * Group the Zod schemas based on the provided name.
    */
   group?: Group
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Tags, operations, or paths to exclude from generation.
    */
   exclude?: Array<Exclude>
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Tags, operations, or paths to include in generation.
    */
   include?: Array<Include>
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Override options for specific tags, operations, or paths.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * Path to Zod
-   * It used as `import { z } from '${importPath}'`.
-   * Accepts relative and absolute paths.
-   * Path is used as-is; relative paths are based on the generated file location.
+   * Import path for Zod package.
+   *
    * @default 'zod'
    */
-  importPath?: string
-
+  importPath?: 'zod' | 'zod/mini' | (string & {})
   /**
-   * Choose to use date or datetime as JavaScript Date instead of string.
-   * - false falls back to a simple z.string() format.
-   * - 'string' uses z.string().datetime() for datetime validation.
-   * - 'stringOffset' uses z.string().datetime({ offset: true }) for datetime with timezone offset validation.
-   * - 'stringLocal' uses z.string().datetime({ local: true }) for local datetime validation.
-   * - 'date' uses z.date() for JavaScript Date objects.
-   * @default 'string'
-   * @note 'stringOffset' will become the default in Kubb v3.
-   */
-  dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
-  /**
-   * Choose to use `number` or `bigint` for integer fields with `int64` format.
-   * - 'number' uses the JavaScript `number` type (matches JSON.parse() runtime behavior).
-   * - 'bigint' uses the JavaScript `bigint` type (accurate for values exceeding Number.MAX_SAFE_INTEGER).
-   * @note in v5 of Kubb 'bigint' will become the default to better align with OpenAPI's int64 specification.
-   * @default 'number'
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * Which type to use when the Swagger/OpenAPI file is not providing more information.
-   * - 'any' allows any value.
-   * - 'unknown' requires type narrowing before use.
-   * - 'void' represents no value.
-   * @default 'any'
-   */
-  unknownType?: 'any' | 'unknown' | 'void'
-  /**
-   * Which type to use for empty schema values.
-   * - 'any' allows any value.
-   * - 'unknown' requires type narrowing before use.
-   * - 'void' represents no value.
-   * @default `unknownType`
-   */
-  emptySchemaType?: 'any' | 'unknown' | 'void'
-  /**
-   * Use TypeScript(`@kubb/plugin-ts`) to add type annotation.
+   * Add TypeScript type annotations to generated schemas.
    */
   typed?: boolean
   /**
-   * Return Zod generated schema as type with z.infer<TYPE>
+   * Return schemas as inferred types using `z.infer`.
    */
   inferred?: boolean
   /**
-   * Use of z.coerce.string() instead of z.string()
-   * can also be an object to enable coercion for dates, strings, and numbers
+   * Apply coercion to string values or configure coercion per type.
    */
-  coercion?:
-    | boolean
-    | {
-        dates?: boolean
-        strings?: boolean
-        numbers?: boolean
-      }
-  operations?: boolean
-  mapper?: Record<string, string>
-  transformers?: {
-    /**
-     * Customize the names based on the type that is provided by the plugin.
-     */
-    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
-    /**
-     * Receive schema and baseName(propertyName) and return FakerMeta array
-     * TODO TODO add docs
-     * @beta
-     */
-    schema?: (
-      props: {
-        schema: SchemaObject | null
-        name: string | null
-        parentName: string | null
-      },
-      defaultSchemas: Schema[],
-    ) => Schema[] | undefined
-  }
+  coercion?: boolean | { dates?: boolean; strings?: boolean; numbers?: boolean }
   /**
-   * Which version of Zod should be used.
-   * - '3' uses Zod v3.x syntax and features.
-   * - '4' uses Zod v4.x syntax and features.
-   * @default '3'
+   * Generate operation-level schemas (grouped by operationId).
    */
-  version?: '3' | '4'
+  operations?: boolean
   /**
-   * Which Zod GUID validator to use for OpenAPI `format: uuid`.
-   * - 'uuid' uses UUID validation.
-   * - 'guid' uses GUID validation (Zod v4 only).
+   * Validator to use for UUID format: `uuid` or `guid`.
+   *
    * @default 'uuid'
    */
   guidType?: 'uuid' | 'guid'
   /**
-   * Use Zod Mini's functional API for better tree-shaking support.
-   * When enabled, generates functional syntax (e.g., `z.optional(z.string())`) instead of chainable methods (e.g., `z.string().optional()`).
-   * Requires Zod v4 or later. When `mini: true`, `version` is set to '4' and `importPath` will default to 'zod/mini'.
+   * Use Zod Mini's functional API for better tree-shaking.
+   *
    * @default false
    */
   mini?: boolean
   /**
-   * Callback function to wrap the output of the generated zod schema
+   * Callback to wrap the generated schema output.
    *
-   * This is useful for edge case scenarios where you might leverage something like `z.object({ ... }).openapi({ example: { some: "complex-example" }})`
-   * or `extendApi(z.object({ ... }), { example: { some: "complex-example", ...otherOpenApiProperties }})`
-   * while going from openapi -> zod -> openapi
+   * Useful for adding metadata like `.openapi()` or extension helpers.
    */
-  wrapOutput?: (arg: { output: string; schema: SchemaObject }) => string | undefined
+  wrapOutput?: (arg: { output: string; schema: ast.SchemaNode }) => string | undefined
   /**
-   * Define some generators next to the zod generators
+   * Apply casing to parameter names.
+   */
+  paramsCasing?: 'camelcase'
+  /**
+   * Additional generators alongside the default generators.
    */
   generators?: Array<Generator<PluginZod>>
+  /**
+   * Override naming conventions for schema names and types.
+   */
+  resolver?: Partial<ResolverZod> & ThisType<ResolverZod>
+  /**
+   * Override printer node handlers to customize rendering of specific schema types.
+   */
+  printer?: {
+    nodes?: PrinterZodNodes | PrinterZodMiniNodes
+  }
+  /**
+   * AST visitor to transform schema and operation nodes.
+   */
+  transformer?: ast.Visitor
 }
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group: Options['group']
-  override: NonNullable<Options['override']>
-  transformers: NonNullable<Options['transformers']>
-  dateType: NonNullable<Options['dateType']>
-  integerType: NonNullable<Options['integerType']>
-  unknownType: NonNullable<Options['unknownType']>
-  emptySchemaType: NonNullable<Options['emptySchemaType']>
+  output: Output
+  exclude: Array<Exclude>
+  include: Array<Include> | undefined
+  override: Array<Override<ResolvedOptions>>
+  group: Group | undefined
   typed: NonNullable<Options['typed']>
   inferred: NonNullable<Options['inferred']>
-  mapper: NonNullable<Options['mapper']>
   importPath: NonNullable<Options['importPath']>
   coercion: NonNullable<Options['coercion']>
   operations: NonNullable<Options['operations']>
-  wrapOutput: Options['wrapOutput']
-  version: NonNullable<Options['version']>
   guidType: NonNullable<Options['guidType']>
   mini: NonNullable<Options['mini']>
+  wrapOutput: Options['wrapOutput']
+  paramsCasing: Options['paramsCasing']
+  printer: Options['printer']
 }
 
-export type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, ResolverZod>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-zod': PluginZod
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,222 @@
+import { stringify, toRegExpString } from '@internals/utils'
+import { ast } from '@kubb/core'
+import type { PluginZod, ResolverZod } from './types.ts'
+
+/**
+ * Returns `true` when the given coercion option enables coercion for the specified type.
+ */
+export function shouldCoerce(coercion: PluginZod['resolvedOptions']['coercion'] | undefined, type: 'dates' | 'strings' | 'numbers'): boolean {
+  if (coercion === undefined || coercion === false) return false
+  if (coercion === true) return true
+
+  return !!coercion[type]
+}
+
+/**
+ * Collects all resolved schema names for an operation's parameters and responses
+ * into a single lookup object, useful for building imports and type references.
+ */
+export function buildSchemaNames(node: ast.OperationNode, { params, resolver }: { params: Array<ast.ParameterNode>; resolver: ResolverZod }) {
+  const pathParam = params.find((p) => p.in === 'path')
+  const queryParam = params.find((p) => p.in === 'query')
+  const headerParam = params.find((p) => p.in === 'header')
+
+  const responses: Record<number | string, string> = {}
+  const errors: Record<number | string, string> = {}
+
+  for (const res of node.responses) {
+    const name = resolver.resolveResponseStatusName(node, res.statusCode)
+    const statusNum = Number(res.statusCode)
+
+    if (!Number.isNaN(statusNum)) {
+      responses[statusNum] = name
+      if (statusNum >= 400) {
+        errors[statusNum] = name
+      }
+    }
+  }
+
+  responses['default'] = resolver.resolveResponseName(node)
+
+  return {
+    request: node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined,
+    parameters: {
+      path: pathParam ? resolver.resolvePathParamsName(node, pathParam) : undefined,
+      query: queryParam ? resolver.resolveQueryParamsName(node, queryParam) : undefined,
+      header: headerParam ? resolver.resolveHeaderParamsName(node, headerParam) : undefined,
+    },
+    responses,
+    errors,
+  }
+}
+
+/**
+ * Format a default value as a code-level literal.
+ * Objects become `{}`, primitives become their string representation, strings are quoted.
+ */
+export function formatDefault(value: unknown): string {
+  if (typeof value === 'string') return stringify(value)
+  if (typeof value === 'object' && value !== null) return '{}'
+
+  return String(value ?? '')
+}
+
+/**
+ * Format a primitive enum/literal value.
+ * Strings are quoted; numbers and booleans are emitted raw.
+ */
+export function formatLiteral(v: string | number | boolean): string {
+  if (typeof v === 'string') return stringify(v)
+
+  return String(v)
+}
+
+/**
+ * Numeric constraint limits for Zod schemas (min, max, and exclusive bounds).
+ */
+export type NumericConstraints = {
+  min?: number
+  max?: number
+  exclusiveMinimum?: number
+  exclusiveMaximum?: number
+  multipleOf?: number
+}
+
+/**
+ * Length constraint limits for string and array schemas (min, max, and regex pattern).
+ */
+export type LengthConstraints = {
+  min?: number
+  max?: number
+  pattern?: string
+}
+
+/**
+ * Modifier options for applying chainable methods to Zod schema values.
+ */
+export type ModifierOptions = {
+  value: string
+  nullable?: boolean
+  optional?: boolean
+  nullish?: boolean
+  defaultValue?: unknown
+  description?: string
+}
+
+/**
+ * Build `.min()` / `.max()` / `.gt()` / `.lt()` constraint chains for numbers
+ * using the standard chainable Zod v4 API.
+ */
+export function numberConstraints({ min, max, exclusiveMinimum, exclusiveMaximum, multipleOf }: NumericConstraints): string {
+  return [
+    min !== undefined ? `.min(${min})` : '',
+    max !== undefined ? `.max(${max})` : '',
+    exclusiveMinimum !== undefined ? `.gt(${exclusiveMinimum})` : '',
+    exclusiveMaximum !== undefined ? `.lt(${exclusiveMaximum})` : '',
+    multipleOf !== undefined ? `.multipleOf(${multipleOf})` : '',
+  ].join('')
+}
+
+/**
+ * Build `.min()` / `.max()` / `.regex()` chains for strings/arrays
+ * using the standard chainable Zod v4 API.
+ */
+export function lengthConstraints({ min, max, pattern }: LengthConstraints): string {
+  return [
+    min !== undefined ? `.min(${min})` : '',
+    max !== undefined ? `.max(${max})` : '',
+    pattern !== undefined ? `.regex(${toRegExpString(pattern, null)})` : '',
+  ].join('')
+}
+
+/**
+ * Build `.check(z.minimum(), z.maximum())` for `zod/mini` numeric constraints.
+ */
+export function numberChecksMini({ min, max, exclusiveMinimum, exclusiveMaximum, multipleOf }: NumericConstraints): string {
+  const checks: 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 })`)
+  if (exclusiveMaximum !== undefined) checks.push(`z.maximum(${exclusiveMaximum}, { exclusive: true })`)
+  if (multipleOf !== undefined) checks.push(`z.multipleOf(${multipleOf})`)
+  return checks.length ? `.check(${checks.join(', ')})` : ''
+}
+
+/**
+ * Build `.check(z.minLength(), z.maxLength(), z.regex())` for `zod/mini` length constraints.
+ */
+export function lengthChecksMini({ min, max, pattern }: LengthConstraints): string {
+  const checks: 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)})`)
+  return checks.length ? `.check(${checks.join(', ')})` : ''
+}
+
+/**
+ * Apply nullable / optional / nullish modifiers and an optional `.describe()` call
+ * 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
+}
+
+/**
+ * Apply nullable / optional / nullish modifiers using the functional `zod/mini` API
+ * (`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
+}
+
+type BuildGroupedParamsSchemaOptions = {
+  params: Array<ast.ParameterNode>
+  optional?: boolean
+}
+
+/**
+ * Builds an `object` schema node grouping the given parameter nodes.
+ * The `primitive: 'object'` marker ensures the Zod printer emits `z.object(…)` rather than a record.
+ */
+export function buildGroupedParamsSchema({ params, optional }: BuildGroupedParamsSchemaOptions): ast.SchemaNode {
+  return ast.createSchema({
+    type: 'object',
+    optional,
+    primitive: 'object',
+    properties: params.map((param) =>
+      ast.createProperty({
+        name: param.name,
+        required: param.required,
+        schema: param.schema,
+      }),
+    ),
+  })
+}