@kubb/plugin-zod 5.0.0-alpha.9 → 5.0.0-beta.4

package/src/printers/printerZodMini.ts

@@ -0,0 +1,295 @@
+import { stringify } from '@internals/utils'
+
+import { ast } from '@kubb/core'
+import type { PluginZod, ResolverZod } from '../types.ts'
+import { applyMiniModifiers, formatLiteral, lengthChecksMini, numberChecksMini } from '../utils.ts'
+
+/**
+ * Partial map of node-type overrides for the Zod Mini printer.
+ *
+ * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`). The function
+ * replaces the built-in handler for that node type. Use `this.transform` to
+ * recurse into nested schema nodes, and `this.options` to read printer options.
+ *
+ * @example Override the `date` handler
+ * ```ts
+ * pluginZod({
+ *   mini: true,
+ *   printer: {
+ *     nodes: {
+ *       date(node) {
+ *         return 'z.iso.date()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export type PrinterZodMiniNodes = ast.PrinterPartial<string, PrinterZodMiniOptions>
+
+export type PrinterZodMiniOptions = {
+  /**
+   * Use `z.guid()` or `z.uuid()` for UUID/GUID validation.
+   *
+   * @default 'uuid'
+   */
+  guidType?: PluginZod['resolvedOptions']['guidType']
+  /**
+   * Hook to transform generated Zod schema before output.
+   */
+  wrapOutput?: PluginZod['resolvedOptions']['wrapOutput']
+  /**
+   * Transforms raw schema names into valid JavaScript identifiers.
+   */
+  resolver?: ResolverZod
+  /**
+   * Properties to exclude using `.omit({ key: true })`.
+   */
+  keysToOmit?: Array<string>
+  /**
+   * Schema names that form circular dependency chains.
+   * Properties referencing these emit lazy getters wrapping refs in `z.lazy(() => …)`.
+   */
+  cyclicSchemas?: ReadonlySet<string>
+  /**
+   * Custom handler map for node type overrides.
+   */
+  nodes?: PrinterZodMiniNodes
+}
+
+/**
+ * Factory options for the Zod Mini printer, defining input/output types and configuration.
+ */
+export type PrinterZodMiniFactory = ast.PrinterFactoryOptions<'zod-mini', PrinterZodMiniOptions, string, string>
+/**
+ * Zod v4 **Mini** printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST into a Zod v4 code string using the functional API
+ * (`z.optional(z.string())`) for improved tree-shaking. See {@link printerZod} for the chainable API.
+ *
+ * @example Functional Mini API
+ * ```ts
+ * const printer = printerZodMini({})
+ * const code = printer.print(optionalStringNode) // "z.optional(z.string())"
+ * ```
+ */
+export const printerZodMini = ast.definePrinter<PrinterZodMiniFactory>((options) => {
+  return {
+    name: 'zod-mini',
+    options,
+    nodes: {
+      any: () => 'z.any()',
+      unknown: () => 'z.unknown()',
+      void: () => 'z.void()',
+      never: () => 'z.never()',
+      boolean: () => 'z.boolean()',
+      null: () => 'z.null()',
+      string(node) {
+        return `z.string()${lengthChecksMini(node)}`
+      },
+      number(node) {
+        return `z.number()${numberChecksMini(node)}`
+      },
+      integer(node) {
+        return `z.int()${numberChecksMini(node)}`
+      },
+      bigint(node) {
+        return `z.bigint()${numberChecksMini(node)}`
+      },
+      date(node) {
+        if (node.representation === 'string') {
+          return 'z.iso.date()'
+        }
+
+        return 'z.date()'
+      },
+      datetime() {
+        // Mini mode: datetime validation via z.string() (z.iso.datetime not available in mini)
+        return 'z.string()'
+      },
+      time(node) {
+        if (node.representation === 'string') {
+          return 'z.iso.time()'
+        }
+
+        return 'z.date()'
+      },
+      uuid(node) {
+        const base = this.options.guidType === 'guid' ? 'z.guid()' : 'z.uuid()'
+
+        return `${base}${lengthChecksMini(node)}`
+      },
+      email(node) {
+        return `z.email()${lengthChecksMini(node)}`
+      },
+      url(node) {
+        return `z.url()${lengthChecksMini(node)}`
+      },
+      ipv4: () => 'z.ipv4()',
+      ipv6: () => 'z.ipv6()',
+      blob: () => 'z.instanceof(File)',
+      enum(node) {
+        const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []
+        const nonNullValues = values.filter((v): v is string | number | boolean => v !== null)
+
+        // asConst-style enum: use z.union([z.literal(…), …])
+        if (node.namedEnumValues?.length) {
+          const literals = nonNullValues.map((v) => `z.literal(${formatLiteral(v)})`)
+          if (literals.length === 1) return literals[0]!
+          return `z.union([${literals.join(', ')}])`
+        }
+
+        // Regular enum: use z.enum([…])
+        return `z.enum([${nonNullValues.map(formatLiteral).join(', ')}])`
+      },
+
+      ref(node) {
+        if (!node.name) return undefined
+        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
+
+        if (node.ref && this.options.cyclicSchemas?.has(refName)) {
+          return `z.lazy(() => ${resolvedName})`
+        }
+
+        return resolvedName
+      },
+      object(node) {
+        const properties = node.properties
+          .map((prop) => {
+            const { name: propName, schema } = prop
+
+            const meta = ast.syncSchemaRef(schema)
+
+            const isNullable = meta.nullable
+            const isOptional = schema.optional
+            const isNullish = schema.nullish
+
+            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.
+            if (hasSelfRef) this.options.cyclicSchemas = undefined
+            const baseOutput = this.transform(schema) ?? this.transform(ast.createSchema({ type: 'unknown' }))!
+            if (hasSelfRef) this.options.cyclicSchemas = options.cyclicSchemas
+
+            const wrappedOutput = this.options.wrapOutput ? this.options.wrapOutput({ output: baseOutput, schema }) || baseOutput : baseOutput
+
+            const value = applyMiniModifiers({
+              value: wrappedOutput,
+              nullable: isNullable,
+              optional: isOptional,
+              nullish: isNullish,
+              defaultValue: meta.default,
+            })
+
+            if (hasSelfRef) {
+              return `get "${propName}"() { return ${value} }`
+            }
+            return `"${propName}": ${value}`
+          })
+          .join(',\n    ')
+
+        return `z.object({\n    ${properties}\n    })`
+      },
+      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" })`
+        }
+
+        return result
+      },
+      tuple(node) {
+        const items = (node.items ?? []).map((item) => this.transform(item)).filter(Boolean)
+
+        return `z.tuple([${items.join(', ')}])`
+      },
+      union(node) {
+        const nodeMembers = node.members ?? []
+        const members = nodeMembers.map((m) => this.transform(m)).filter(Boolean)
+        if (members.length === 0) return ''
+        if (members.length === 1) return members[0]!
+        if (node.discriminatorPropertyName && !nodeMembers.some((m) => m.type === 'intersection')) {
+          // z.discriminatedUnion requires ZodObject members; intersections (ZodIntersection) are not
+          // assignable to $ZodDiscriminant, so fall back to z.union when any member is an intersection.
+          return `z.discriminatedUnion(${stringify(node.discriminatorPropertyName)}, [${members.join(', ')}])`
+        }
+
+        return `z.union([${members.join(', ')}])`
+      },
+      intersection(node) {
+        const members = node.members ?? []
+        if (members.length === 0) return ''
+
+        const [first, ...rest] = members
+        if (!first) return ''
+
+        let base = this.transform(first)
+        if (!base) 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
+            }
+          }
+          const transformed = this.transform(member)
+          if (transformed) base = `z.intersection(${base}, ${transformed})`
+        }
+
+        return base
+      },
+      ...options.nodes,
+    },
+    print(node) {
+      const { keysToOmit } = this.options
+
+      let base = this.transform(node)
+      if (!base) return null
+
+      const meta = ast.syncSchemaRef(node)
+
+      if (keysToOmit?.length && meta.primitive === 'object' && !(meta.type === 'union' && meta.discriminatorPropertyName)) {
+        // 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(', ')} })`
+        }
+      }
+
+      return applyMiniModifiers({
+        value: base,
+        nullable: meta.nullable,
+        optional: meta.optional,
+        nullish: meta.nullish,
+        defaultValue: meta.default,
+      })
+    },
+  }
+})

package/src/resolvers/resolverZod.ts

@@ -0,0 +1,57 @@
+import { camelCase, pascalCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginZod } from '../types.ts'
+
+/**
+ * Naming convention resolver for Zod plugin.
+ *
+ * Provides default naming helpers using camelCase with a `Schema` suffix for schemas.
+ *
+ * @example
+ * `resolverZod.default('list pets', 'function')  // → 'listPetsSchema'`
+ */
+export const resolverZod = defineResolver<PluginZod>((ctx) => {
+  return {
+    name: 'default',
+    pluginName: 'plugin-zod',
+    default(name, type) {
+      return camelCase(name, { isFile: type === 'file', suffix: type ? 'schema' : undefined })
+    },
+    resolveSchemaName(name) {
+      return camelCase(name, { suffix: 'schema' })
+    },
+    resolveSchemaTypeName(name) {
+      return pascalCase(name, { suffix: 'schema' })
+    },
+    resolveTypeName(name) {
+      return pascalCase(name)
+    },
+    resolvePathName(name, type) {
+      return ctx.default(name, type)
+    },
+    resolveParamName(node, param) {
+      return ctx.resolveSchemaName(`${node.operationId} ${param.in} ${param.name}`)
+    },
+    resolveResponseStatusName(node, statusCode) {
+      return ctx.resolveSchemaName(`${node.operationId} Status ${statusCode}`)
+    },
+    resolveDataName(node) {
+      return ctx.resolveSchemaName(`${node.operationId} Data`)
+    },
+    resolveResponsesName(node) {
+      return ctx.resolveSchemaName(`${node.operationId} Responses`)
+    },
+    resolveResponseName(node) {
+      return ctx.resolveSchemaName(`${node.operationId} Response`)
+    },
+    resolvePathParamsName(node, param) {
+      return ctx.resolveParamName(node, param)
+    },
+    resolveQueryParamsName(node, param) {
+      return ctx.resolveParamName(node, param)
+    },
+    resolveHeaderParamsName(node, param) {
+      return ctx.resolveParamName(node, param)
+    },
+  }
+})

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
+    }
+  }
+}