@kubb/plugin-zod 5.0.0-alpha.24 → 5.0.0-alpha.26

package/src/types.ts

@@ -1,18 +1,90 @@
-import type { Output, PluginFactoryOptions, ResolveNameParams, UserGroup } 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 { OperationParamsResolver } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from '@kubb/ast/types'
+import type {
+  CompatibilityPreset,
+  Exclude,
+  Generator,
+  Group,
+  Include,
+  Output,
+  Override,
+  PluginFactoryOptions,
+  ResolvePathOptions,
+  Resolver,
+  UserGroup,
+} from '@kubb/core'
+
+/**
+ * The concrete resolver type for `@kubb/plugin-zod`.
+ * Extends the base `Resolver` with zod-specific naming helpers.
+ */
+export type ResolverZod = Resolver &
+  OperationParamsResolver & {
+    /**
+     * Resolves a camelCase schema function name with a `Schema` suffix.
+     */
+    resolveName(name: string): string
+    /**
+     * Resolves the name for a `z.infer<typeof ...>` type export from an already-resolved function name.
+     *
+     * @example
+     * resolver.resolveInferName('petSchema') // → 'PetSchema'
+     * resolver.resolveInferName('addPet200Schema') // → 'AddPet200Schema'
+     */
+    resolveInferName(name: string): string
+    /**
+     * Resolves a PascalCase path/file name for the generated output.
+     */
+    resolvePathName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+    /**
+     * Resolves the name for an operation response by status code.
+     *
+     * @example
+     * resolver.resolveResponseStatusName(node, 200) // → 'listPetsStatus200Schema'
+     */
+    resolveResponseStatusName(node: OperationNode, statusCode: StatusCode): string
+    /**
+     * Resolves the name for the collection of all operation responses.
+     *
+     * @example
+     * resolver.resolveResponsesName(node) // → 'listPetsResponsesSchema'
+     */
+    resolveResponsesName(node: OperationNode): string
+    /**
+     * Resolves the name for the union of all operation responses.
+     *
+     * @example
+     * resolver.resolveResponseName(node) // → 'listPetsResponseSchema'
+     */
+    resolveResponseName(node: OperationNode): string
+    /**
+     * Resolves the name for an operation's grouped path parameters type.
+     *
+     * @example
+     * resolver.resolvePathParamsName(node, param) // → 'deletePetPathPetIdSchema'
+     */
+    resolvePathParamsName(node: OperationNode, param: ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped query parameters type.
+     *
+     * @example
+     * resolver.resolveQueryParamsName(node, param) // → 'findPetsByStatusQueryStatusSchema'
+     */
+    resolveQueryParamsName(node: OperationNode, param: ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped header parameters type.
+     *
+     * @example
+     * resolver.resolveHeaderParamsName(node, param) // → 'deletePetHeaderApiKeySchema'
+     */
+    resolveHeaderParamsName(node: OperationNode, param: 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.
    */
@@ -36,8 +108,7 @@ export type Options = {
    * Path is used as-is; relative paths are based on the generated file location.
    * @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.
@@ -46,33 +117,8 @@ export type Options = {
    * - '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.
    */
@@ -82,91 +128,74 @@ export type Options = {
    */
   inferred?: boolean
   /**
-   * Use of z.coerce.string() instead of z.string()
-   * can also be an object to enable coercion for dates, strings, and numbers
+   * Use of z.coerce.string() instead of z.string().
+   * Can also be an object to enable coercion for dates, strings, and numbers.
    */
-  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).
+   * - 'guid' uses GUID validation.
    * @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'.
+   * When enabled, generates functional syntax (e.g., `z.optional(z.string())`)
+   * instead of chainable methods (e.g., `z.string().optional()`).
+   * When `mini: true`, `importPath` will default to 'zod/mini'.
    * @default false
    */
   mini?: boolean
   /**
-   * Callback function to wrap the output of the generated zod schema
+   * Callback function to wrap the output of the generated zod schema.
    *
-   * 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 edge cases like adding `.openapi()` metadata or wrapping
+   * schemas with extension helpers (openapi -> zod -> openapi round-trips).
+   */
+  wrapOutput?: (arg: { output: string; schema: SchemaNode }) => string | undefined
+  /**
+   * How to style your params, by default no casing is applied
+   * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
+   * @default undefined
    */
-  wrapOutput?: (arg: { output: string; schema: SchemaObject }) => string | undefined
+  paramsCasing?: 'camelcase'
   /**
-   * Define some generators next to the zod generators
+   * Define additional generators next to the zod generators.
    */
   generators?: Array<Generator<PluginZod>>
+  /**
+   * Compatibility preset to ease migration from previous Kubb versions.
+   */
+  compatibilityPreset?: CompatibilityPreset
+  /**
+   * Custom resolver instances for zod-specific name resolution.
+   */
+  resolvers?: Array<ResolverZod>
+  /**
+   * AST visitor transformers applied during code generation.
+   */
+  transformers?: Array<Visitor>
 }
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group: Options['group']
-  override: NonNullable<Options['override']>
-  transformers: NonNullable<Options['transformers']>
+  output: Output
+  group: Group | undefined
   dateType: NonNullable<Options['dateType']>
-  integerType: NonNullable<Options['integerType']>
-  unknownType: NonNullable<Options['unknownType']>
-  emptySchemaType: NonNullable<Options['emptySchemaType']>
   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']
+  transformers: Array<Visitor>
 }
 
-export type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, never, ResolvePathOptions, ResolverZod>

package/src/utils.ts

@@ -0,0 +1,248 @@
+import { stringify, toRegExpString } from '@internals/utils'
+import { createProperty, createSchema, extractRefName } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
+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: OperationNode, { params, resolver }: { params: Array<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?.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)
+}
+
+export type NumericConstraints = {
+  min?: number
+  max?: number
+  exclusiveMinimum?: number
+  exclusiveMaximum?: number
+  multipleOf?: number
+}
+
+export type LengthConstraints = {
+  min?: number
+  max?: number
+  pattern?: string
+}
+
+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
+}
+
+/**
+ * Returns true when the schema tree contains a self-referential `$ref`
+ * whose resolved name matches `schemaName`.
+ *
+ * A `visited` set prevents infinite recursion on circular schema graphs.
+ */
+export function containsSelfRef(
+  node: SchemaNode,
+  { schemaName, resolver, visited = new Set() }: { schemaName: string; resolver: ResolverZod | undefined; visited?: Set<SchemaNode> },
+): boolean {
+  if (visited.has(node)) return false
+  visited.add(node)
+
+  if (node.type === 'ref' && node.ref) {
+    const rawName = extractRefName(node.ref) ?? node.name
+    const resolved = rawName ? (resolver?.default(rawName, 'function') ?? rawName) : node.name
+    return resolved === schemaName
+  }
+  if (node.type === 'object') {
+    if (node.properties?.some((p) => containsSelfRef(p.schema, { schemaName, resolver, visited }))) return true
+    if (node.additionalProperties && node.additionalProperties !== true) {
+      return containsSelfRef(node.additionalProperties, { schemaName, resolver, visited })
+    }
+    return false
+  }
+  if (node.type === 'array' || node.type === 'tuple') {
+    return node.items?.some((item) => containsSelfRef(item, { schemaName, resolver, visited })) ?? false
+  }
+  if (node.type === 'union' || node.type === 'intersection') {
+    return node.members?.some((m) => containsSelfRef(m, { schemaName, resolver, visited })) ?? false
+  }
+  return false
+}
+
+type BuildGroupedParamsSchemaOptions = {
+  params: Array<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): SchemaNode {
+  return createSchema({
+    type: 'object',
+    optional,
+    primitive: 'object',
+    properties: params.map((param) =>
+      createProperty({
+        name: param.name,
+        required: param.required,
+        schema: param.schema,
+      }),
+    ),
+  })
+}