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

package/src/plugin.ts

@@ -1,183 +1,94 @@
-import path from 'node:path'
-import { camelCase, pascalCase } from '@internals/utils'
-import { createPlugin, type Group, getBarrelFiles, getMode, satisfiesDependency } from '@kubb/core'
-import { OperationGenerator, pluginOasName, SchemaGenerator } from '@kubb/plugin-oas'
-import { pluginTsName } from '@kubb/plugin-ts'
-import { operationsGenerator } from './generators'
+import { camelCase } from '@internals/utils'
+import { definePlugin, type Group } from '@kubb/core'
 import { zodGenerator } from './generators/zodGenerator.tsx'
-import { source as toZodSource } from './templates/ToZod.source.ts'
+import { resolverZod } from './resolvers/resolverZod.ts'
 import type { PluginZod } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-zod`, used in driver lookups and warnings.
+ */
 export const pluginZodName = 'plugin-zod' satisfies PluginZod['name']
 
-export const pluginZod = createPlugin<PluginZod>((options) => {
+/**
+ * Generates Zod validation schemas from an OpenAPI specification.
+ * Walks schemas and operations, delegates to generators, and writes barrel files
+ * based on the configured `barrelType`.
+ *
+ * @example Zod schema generator
+ * ```ts
+ * import pluginZod from '@kubb/plugin-zod'
+ * export default defineConfig({
+ *   plugins: [pluginZod({ output: { path: 'zod' } })]
+ * })
+ * ```
+ */
+export const pluginZod = definePlugin<PluginZod>((options) => {
   const {
     output = { path: 'zod', barrelType: 'named' },
     group,
     exclude = [],
     include,
     override = [],
-    transformers = {},
-    dateType = 'string',
-    unknownType = 'any',
-    emptySchemaType = unknownType,
-    integerType = 'number',
     typed = false,
-    mapper = {},
     operations = false,
     mini = false,
-    version = mini ? '4' : satisfiesDependency('zod', '>=4') ? '4' : '3',
     guidType = 'uuid',
-    importPath = mini ? 'zod/mini' : version === '4' ? 'zod/v4' : 'zod',
+    importPath = mini ? 'zod/mini' : 'zod',
     coercion = false,
     inferred = false,
-    generators = [zodGenerator, operations ? operationsGenerator : undefined].filter(Boolean),
     wrapOutput = undefined,
-    contentType,
+    paramsCasing,
+    printer,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
-  // @deprecated Will be removed in v5 when collisionDetection defaults to true
-  const usedEnumNames = {}
+  const groupConfig = group
+    ? ({
+        ...group,
+        name: (ctx) => {
+          if (group.type === 'path') {
+            return `${ctx.group.split('/')[1]}`
+          }
+          return `${camelCase(ctx.group)}Controller`
+        },
+      } satisfies Group)
+    : undefined
 
   return {
     name: pluginZodName,
-    options: {
-      output,
-      transformers,
-      include,
-      exclude,
-      override,
-      typed,
-      dateType,
-      unknownType,
-      emptySchemaType,
-      integerType,
-      mapper,
-      importPath,
-      coercion,
-      operations,
-      inferred,
-      group,
-      wrapOutput,
-      version,
-      guidType,
-      mini,
-      usedEnumNames,
-    },
-    pre: [pluginOasName, typed ? pluginTsName : undefined].filter(Boolean),
-    resolvePath(baseName, pathMode, options) {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = pathMode ?? getMode(path.resolve(root, output.path))
-
-      if (mode === 'single') {
-        /**
-         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
-         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
-         */
-        return path.resolve(root, output.path)
-      }
-
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
-          ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-              return `${camelCase(ctx.group)}Controller`
-            }
-
-        return path.resolve(
-          root,
-          output.path,
-          groupName({
-            group: group.type === 'path' ? options.group.path! : options.group.tag!,
-          }),
-          baseName,
-        )
-      }
-
-      return path.resolve(root, output.path, baseName)
-    },
-    resolveName(name, type) {
-      let resolvedName = camelCase(name, {
-        suffix: type ? 'schema' : undefined,
-        isFile: type === 'file',
-      })
-
-      if (type === 'type') {
-        resolvedName = pascalCase(resolvedName)
-      }
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
-      }
-
-      return resolvedName
-    },
-    async install() {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = getMode(path.resolve(root, output.path))
-      const oas = await this.getOas()
-
-      if (this.plugin.options.typed && this.plugin.options.version === '3') {
-        // pre add bundled
-        await this.addFile({
-          baseName: 'ToZod.ts',
-          path: path.resolve(root, '.kubb/ToZod.ts'),
-          sources: [
-            {
-              name: 'ToZod',
-              value: toZodSource,
-            },
-          ],
-          imports: [],
-          exports: [],
+    options,
+    hooks: {
+      'kubb:plugin:setup'(ctx) {
+        ctx.setOptions({
+          output,
+          exclude,
+          include,
+          override,
+          group: groupConfig,
+          typed,
+          importPath,
+          coercion,
+          operations,
+          inferred,
+          guidType,
+          mini,
+          wrapOutput,
+          paramsCasing,
+          printer,
         })
-      }
-
-      const schemaGenerator = new SchemaGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        include: undefined,
-        override,
-        mode,
-        output: output.path,
-      })
-
-      const schemaFiles = await schemaGenerator.build(...generators)
-      await this.upsertFile(...schemaFiles)
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-      })
-
-      const operationFiles = await operationGenerator.build(...generators)
-      await this.upsertFile(...operationFiles)
-
-      const barrelFiles = await getBarrelFiles(this.fabric.files, {
-        type: output.barrelType ?? 'named',
-        root,
-        output,
-        meta: {
-          pluginName: this.plugin.name,
-        },
-      })
-
-      await this.upsertFile(...barrelFiles)
+        ctx.setResolver(userResolver ? { ...resolverZod, ...userResolver } : resolverZod)
+        if (userTransformer) {
+          ctx.setTransformer(userTransformer)
+        }
+        ctx.addGenerator(zodGenerator)
+        for (const gen of userGenerators) {
+          ctx.addGenerator(gen)
+        }
+      },
     },
   }
 })
+
+export default pluginZod

package/src/printers/printerZod.ts

@@ -0,0 +1,339 @@
+import { stringify } from '@internals/utils'
+
+import { ast } from '@kubb/core'
+import type { PluginZod, ResolverZod } from '../types.ts'
+import { applyModifiers, formatLiteral, lengthConstraints, numberConstraints, shouldCoerce } from '../utils.ts'
+import type { AdapterOas } from '@kubb/adapter-oas'
+
+/**
+ * Partial map of node-type overrides for the Zod 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({
+ *   printer: {
+ *     nodes: {
+ *       date(node) {
+ *         return 'z.string().date()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export type PrinterZodNodes = ast.PrinterPartial<string, PrinterZodOptions>
+
+export type PrinterZodOptions = {
+  /**
+   * Enable automatic type coercion for strings, numbers, and dates.
+   */
+  coercion?: PluginZod['resolvedOptions']['coercion']
+  /**
+   * Use `z.guid()` or `z.uuid()` for UUID/GUID validation.
+   *
+   * @default 'uuid'
+   */
+  guidType?: PluginZod['resolvedOptions']['guidType']
+  /**
+   * Date format in the OpenAPI spec (`'date'` or `'date-time'`).
+   */
+  dateType?: AdapterOas['resolvedOptions']['dateType']
+  /**
+   * 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?: PrinterZodNodes
+}
+
+/**
+ * Factory options for the Zod printer, defining input/output types and configuration.
+ */
+export type PrinterZodFactory = ast.PrinterFactoryOptions<'zod', PrinterZodOptions, string, string>
+
+/**
+ * Zod v4 printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST into a Zod v4 code string using the chainable API
+ * (`.optional()`, `.nullable()`, `.omit()`, etc.). For improved tree-shaking, see {@link printerZodMini}.
+ *
+ * @example Chainable API
+ * ```ts
+ * const printer = printerZod({ coercion: false })
+ * const code = printer.print(stringNode) // "z.string()"
+ * ```
+ */
+export const printerZod = ast.definePrinter<PrinterZodFactory>((options) => {
+  return {
+    name: 'zod',
+    options,
+    nodes: {
+      any: () => 'z.any()',
+      unknown: () => 'z.unknown()',
+      void: () => 'z.void()',
+      never: () => 'z.never()',
+      boolean: () => 'z.boolean()',
+      null: () => 'z.null()',
+      string(node) {
+        const base = shouldCoerce(this.options.coercion, 'strings') ? 'z.coerce.string()' : 'z.string()'
+
+        return `${base}${lengthConstraints(node)}`
+      },
+      number(node) {
+        const base = shouldCoerce(this.options.coercion, 'numbers') ? 'z.coerce.number()' : 'z.number()'
+
+        return `${base}${numberConstraints(node)}`
+      },
+      integer(node) {
+        const base = shouldCoerce(this.options.coercion, 'numbers') ? 'z.coerce.number().int()' : 'z.int()'
+
+        return `${base}${numberConstraints(node)}`
+      },
+      bigint() {
+        return shouldCoerce(this.options.coercion, 'numbers') ? 'z.coerce.bigint()' : 'z.bigint()'
+      },
+      date(node) {
+        if (node.representation === 'string') {
+          return 'z.iso.date()'
+        }
+
+        return shouldCoerce(this.options.coercion, 'dates') ? 'z.coerce.date()' : 'z.date()'
+      },
+      datetime(node) {
+        const offset = node.offset || this.options.dateType === 'stringOffset'
+        const local = node.local || this.options.dateType === 'stringLocal'
+
+        if (offset) return 'z.iso.datetime({ offset: true })'
+        if (local) return 'z.iso.datetime({ local: true })'
+
+        return 'z.iso.datetime()'
+      },
+      time(node) {
+        if (node.representation === 'string') {
+          return 'z.iso.time()'
+        }
+
+        return shouldCoerce(this.options.coercion, 'dates') ? 'z.coerce.date()' : 'z.date()'
+      },
+      uuid(node) {
+        const base = this.options.guidType === 'guid' ? 'z.guid()' : 'z.uuid()'
+
+        return `${base}${lengthConstraints(node)}`
+      },
+      email(node) {
+        return `z.email()${lengthConstraints(node)}`
+      },
+      url(node) {
+        return `z.url()${lengthConstraints(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
+
+            // When a property schema is not a ref but the metadata is from a ref (e.g., discriminator
+            // property override), skip applying the description from the ref target to avoid applying
+            // metadata from a replaced schema.
+            let descriptionToApply = meta.description
+            if (schema.type !== 'ref' && meta.type === 'ref') {
+              descriptionToApply = undefined
+            }
+
+            const value = applyModifiers({
+              value: wrappedOutput,
+              nullable: isNullable,
+              optional: isOptional,
+              nullish: isNullish,
+              defaultValue: meta.default,
+              description: descriptionToApply,
+            })
+
+            if (hasSelfRef) {
+              return `get "${propName}"() { return ${value} }`
+            }
+            return `"${propName}": ${value}`
+          })
+          .join(',\n    ')
+
+        let result = `z.object({\n    ${properties}\n    })`
+
+        // Handle additionalProperties as .catchall() or .strict()
+        if (node.additionalProperties && node.additionalProperties !== true) {
+          const catchallType = this.transform(node.additionalProperties)
+          if (catchallType) {
+            result += `.catchall(${catchallType})`
+          }
+        } else if (node.additionalProperties === true) {
+          result += `.catchall(${this.transform(ast.createSchema({ type: 'unknown' }))})`
+        } else if (node.additionalProperties === false) {
+          result += '.strict()'
+        }
+
+        return result
+      },
+      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})${lengthConstraints(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 = lengthConstraints(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 = numberConstraints(n ?? {})
+            if (c) {
+              base += c
+              continue
+            }
+          } else if (member.primitive === 'array') {
+            const a = ast.narrowSchema(member, 'array')
+            const c = lengthConstraints(a ?? {})
+            if (c) {
+              base += c
+              continue
+            }
+          }
+          const transformed = this.transform(member)
+          if (transformed) base = `${base}.and(${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 applyModifiers({
+        value: base,
+        nullable: meta.nullable,
+        optional: meta.optional,
+        nullish: meta.nullish,
+        defaultValue: meta.default,
+        description: meta.description,
+      })
+    },
+  }
+})