@kubb/plugin-zod 5.0.0-alpha.3 → 5.0.0-alpha.30

package/dist/index.d.ts

@@ -1,10 +1,424 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { n as PluginZod, t as Options } from "./types-D0wsPC6Y.js";
-import * as _kubb_core0 from "@kubb/core";
+import * as _$_kubb_ast0 from "@kubb/ast";
+import { OperationParamsResolver } from "@kubb/ast";
+import * as _$_kubb_core0 from "@kubb/core";
+import { CompatibilityPreset, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, PrinterFactoryOptions, PrinterPartial, ResolvePathOptions, Resolver, UserGroup } from "@kubb/core";
+import { OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from "@kubb/ast/types";
 
+//#region src/printers/printerZod.d.ts
+/**
+ * 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()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+type PrinterZodNodes = PrinterPartial<string, PrinterZodOptions>;
+type PrinterZodOptions = {
+  coercion?: PluginZod['resolvedOptions']['coercion'];
+  guidType?: PluginZod['resolvedOptions']['guidType'];
+  wrapOutput?: PluginZod['resolvedOptions']['wrapOutput'];
+  resolver?: ResolverZod;
+  schemaName?: string;
+  /**
+   * Property keys to exclude from the generated object schema via `.omit({ key: true })`.
+   */
+  keysToOmit?: Array<string>;
+  /**
+   * Partial map of node-type overrides. Each entry replaces the built-in handler for that node type.
+   */
+  nodes?: PrinterZodNodes;
+};
+type PrinterZodFactory = PrinterFactoryOptions<'zod', PrinterZodOptions, string, string>;
+/**
+ * Zod v4 printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST into a **standard** Zod v4 code string
+ * using the chainable method API (`.optional()`, `.nullable()`, etc.).
+ *
+ * For the `zod/mini` functional API, see {@link printerZodMini}.
+ *
+ * @example
+ * ```ts
+ * const printer = printerZod({ coercion: false })
+ * const code = printer.print(stringSchemaNode) // "z.string()"
+ * ```
+ */
+declare const printerZod: (options?: PrinterZodOptions | undefined) => _$_kubb_ast0.Printer<PrinterZodFactory>;
+//#endregion
+//#region src/printers/printerZodMini.d.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()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+type PrinterZodMiniNodes = PrinterPartial<string, PrinterZodMiniOptions>;
+type PrinterZodMiniOptions = {
+  guidType?: PluginZod['resolvedOptions']['guidType'];
+  wrapOutput?: PluginZod['resolvedOptions']['wrapOutput'];
+  resolver?: ResolverZod;
+  schemaName?: string;
+  /**
+   * Property keys to exclude from the generated object schema via `.omit({ key: true })`.
+   */
+  keysToOmit?: Array<string>;
+  /**
+   * Partial map of node-type overrides. Each entry replaces the built-in handler for that node type.
+   */
+  nodes?: PrinterZodMiniNodes;
+};
+type PrinterZodMiniFactory = PrinterFactoryOptions<'zod-mini', PrinterZodMiniOptions, string, string>;
+/**
+ * Zod v4 **Mini** printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST into a Zod v4 Mini code string using the
+ * functional API (`z.optional(z.string())`) for better tree-shaking.
+ *
+ * For the standard chainable API, see {@link printerZod}.
+ *
+ * @example
+ * ```ts
+ * const printer = printerZodMini({})
+ * const code = printer.print(optionalStringNode) // "z.optional(z.string())"
+ * ```
+ */
+declare const printerZodMini: (options?: PrinterZodMiniOptions | undefined) => _$_kubb_ast0.Printer<PrinterZodMiniFactory>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * The concrete resolver type for `@kubb/plugin-zod`.
+ * Extends the base `Resolver` with zod-specific naming helpers.
+ */
+type ResolverZod = Resolver & OperationParamsResolver & {
+  /**
+   * Resolves a camelCase schema function name with a `Schema` suffix.
+   */
+  resolveSchemaName(this: ResolverZod, name: string): string;
+  /**
+   * Resolves the name for a `z.infer<typeof ...>` type export.
+   * Strips the trailing `Schema` suffix (added by `resolveSchemaName`) before PascalCasing.
+   *
+   * @example
+   * resolver.resolveSchemaTypeName('pet) // → 'PetSchema'
+   * resolver.resolveSchemaTypeName('addPet200') // → 'AddPet200Schema'
+   * resolver.resolveSchemaTypeName('PetName') // → 'PetNameSchema'
+   */
+  resolveSchemaTypeName(this: ResolverZod, name: string): string;
+  /**
+   * Resolves the name for a `z.infer<typeof ...>` type export.
+   * Strips the trailing `Schema` suffix (added by `resolveSchemaName`) before PascalCasing.
+   *
+   * @example
+   * resolver.resolveTypeName('pet') // → 'Pet'
+   * resolver.resolveTypeName('addPet200') // → 'AddPet200'
+   * resolver.resolveTypeName('PetName') // → 'PetName'
+   */
+  resolveTypeName(this: ResolverZod, name: string): string;
+  /**
+   * Resolves a PascalCase path/file name for the generated output.
+   */
+  resolvePathName(this: ResolverZod, 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(this: ResolverZod, node: OperationNode, statusCode: StatusCode): string;
+  /**
+   * Resolves the name for the collection of all operation responses.
+   *
+   * @example
+   * resolver.resolveResponsesName(node) // → 'listPetsResponsesSchema'
+   */
+  resolveResponsesName(this: ResolverZod, node: OperationNode): string;
+  /**
+   * Resolves the name for the union of all operation responses.
+   *
+   * @example
+   * resolver.resolveResponseName(node) // → 'listPetsResponseSchema'
+   */
+  resolveResponseName(this: ResolverZod, node: OperationNode): string;
+  /**
+   * Resolves the name for an operation's grouped path parameters type.
+   *
+   * @example
+   * resolver.resolvePathParamsName(node, param) // → 'deletePetPathPetIdSchema'
+   */
+  resolvePathParamsName(this: ResolverZod, node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the name for an operation's grouped query parameters type.
+   *
+   * @example
+   * resolver.resolveQueryParamsName(node, param) // → 'findPetsByStatusQueryStatusSchema'
+   */
+  resolveQueryParamsName(this: ResolverZod, node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the name for an operation's grouped header parameters type.
+   *
+   * @example
+   * resolver.resolveHeaderParamsName(node, param) // → 'deletePetHeaderApiKeySchema'
+   */
+  resolveHeaderParamsName(this: ResolverZod, node: OperationNode, param: ParameterNode): string;
+};
+type Options = {
+  /**
+   * @default 'zod'
+   */
+  output?: Output;
+  /**
+   * Group the Zod schemas based on the provided name.
+   */
+  group?: UserGroup;
+  /**
+   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Array containing include parameters to include tags/operations/methods/paths.
+   */
+  include?: Array<Include>;
+  /**
+   * Array containing override parameters to override `options` based on tags/operations/methods/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.
+   * @default 'zod'
+   */
+  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'
+   */
+  dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
+  /**
+   * Use TypeScript(`@kubb/plugin-ts`) to add type annotation.
+   */
+  typed?: boolean;
+  /**
+   * Return Zod generated schema as type with z.infer<TYPE>
+   */
+  inferred?: boolean;
+  /**
+   * 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;
+  };
+  /**
+   * Generate operation-level schemas (grouped by operationId).
+   */
+  operations?: boolean;
+  /**
+   * Which Zod GUID validator to use for OpenAPI `format: uuid`.
+   * - 'uuid' uses UUID validation.
+   * - '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()`).
+   * When `mini: true`, `importPath` will default to 'zod/mini'.
+   * @default false
+   */
+  mini?: boolean;
+  /**
+   * Callback function to wrap the output of the generated zod schema.
+   *
+   * 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
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * Define additional generators next to the zod generators.
+   */
+  generators?: Array<Generator<PluginZod>>;
+  /**
+   * Compatibility preset to ease migration from previous Kubb versions.
+   */
+  compatibilityPreset?: CompatibilityPreset;
+  /**
+   * A single resolver whose methods override the default resolver's naming conventions.
+   * When a method returns `null` or `undefined`, the default resolver's result is used instead.
+   */
+  resolver?: Partial<ResolverZod> & ThisType<ResolverZod>;
+  /**
+   * Override individual printer node handlers to customize rendering of specific schema types.
+   *
+   * Each key is a `SchemaType` (e.g. `'date'`, `'string'`). The function replaces the
+   * built-in handler for that type. Use `this.transform` to recurse into nested schema nodes.
+   * When `mini: true`, the overrides apply to the Zod Mini printer.
+   *
+   * @example Override the `date` node to use `z.string().date()`
+   * ```ts
+   * pluginZod({
+   *   printer: {
+   *     nodes: {
+   *       date(node) {
+   *         return 'z.string().date()'
+   *       },
+   *     },
+   *   },
+   * })
+   * ```
+   */
+  printer?: {
+    nodes?: PrinterZodNodes | PrinterZodMiniNodes;
+  };
+  /**
+   * A single AST visitor applied to each SchemaNode/OperationNode before printing.
+   * When a visitor method returns `null` or `undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor;
+};
+type ResolvedOptions = {
+  output: Output;
+  exclude: Array<Exclude>;
+  include: Array<Include> | undefined;
+  override: Array<Override<ResolvedOptions>>;
+  group: Group | undefined;
+  dateType: NonNullable<Options['dateType']>;
+  typed: NonNullable<Options['typed']>;
+  inferred: NonNullable<Options['inferred']>;
+  importPath: NonNullable<Options['importPath']>;
+  coercion: NonNullable<Options['coercion']>;
+  operations: NonNullable<Options['operations']>;
+  guidType: NonNullable<Options['guidType']>;
+  mini: NonNullable<Options['mini']>;
+  wrapOutput: Options['wrapOutput'];
+  paramsCasing: Options['paramsCasing'];
+  printer: Options['printer'];
+};
+type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, never, ResolvePathOptions, ResolverZod>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-zod': PluginZod;
+    }
+  }
+}
+//#endregion
+//#region src/generators/zodGenerator.d.ts
+declare const zodGenerator: _$_kubb_core0.Generator<PluginZod>;
+//#endregion
+//#region src/generators/zodGeneratorLegacy.d.ts
+declare const zodGeneratorLegacy: _$_kubb_core0.Generator<PluginZod>;
+//#endregion
 //#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-zod`, used to identify the plugin in driver lookups and warnings.
+ */
 declare const pluginZodName = "plugin-zod";
-declare const pluginZod: (options?: Options | undefined) => _kubb_core0.UserPluginWithLifeCycle<PluginZod>;
+/**
+ * The `@kubb/plugin-zod` plugin factory.
+ *
+ * Generates Zod validation schemas from an OpenAPI/AST `RootNode`.
+ * Walks schemas and operations, delegates rendering to the active generators,
+ * and writes barrel files based on `output.barrelType`.
+ *
+ * @example
+ * ```ts
+ * import { pluginZod } from '@kubb/plugin-zod'
+ *
+ * export default defineConfig({
+ *   plugins: [pluginZod({ output: { path: 'zod' } })],
+ * })
+ * ```
+ */
+declare const pluginZod: (options?: Options | undefined) => _$_kubb_core0.UserPluginWithLifeCycle<PluginZod>;
+//#endregion
+//#region src/resolvers/resolverZod.d.ts
+/**
+ * Default resolver for `@kubb/plugin-zod`.
+ *
+ * Uses `camelCase` naming with a `Schema` suffix for function/type/const names.
+ *
+ * @example
+ * ```ts
+ * resolverZod.default('list pets', 'function') // → 'listPetsSchema'
+ * resolverZod.default('Pet', 'file')           // → 'pet'
+ * resolverZod.resolveName('list pets')          // → 'listPetsSchema'
+ * ```
+ */
+declare const resolverZod: ResolverZod;
+//#endregion
+//#region src/resolvers/resolverZodLegacy.d.ts
+/**
+ * Legacy resolver for `@kubb/plugin-zod` that reproduces the naming conventions
+ * used in Kubb v4. Enable via `compatibilityPreset: 'kubbV4'`
+ * (or by composing this resolver manually).
+ *
+ * Key differences from the default resolver:
+ * - Response status types: `<operationId><StatusCode>Schema` (e.g. `createPets201Schema`) instead of `<operationId>Status201Schema`
+ * - Default/error responses: `<operationId>ErrorSchema` instead of `<operationId>StatusDefaultSchema`
+ * - Request body: `<operationId>MutationRequestSchema` (non-GET) / `<operationId>QueryRequestSchema` (GET)
+ * - Combined responses type: `<operationId>MutationSchema` / `<operationId>QuerySchema`
+ * - Response union: `<operationId>MutationResponseSchema` / `<operationId>QueryResponseSchema`
+ *
+ * @example
+ * ```ts
+ * import { resolverZodLegacy } from '@kubb/plugin-zod'
+ *
+ * resolverZodLegacy.resolveResponseStatusName(node, 201)  // → 'createPets201Schema'
+ * resolverZodLegacy.resolveResponseStatusName(node, 'default')  // → 'createPetsErrorSchema'
+ * resolverZodLegacy.resolveDataName(node)  // → 'createPetsMutationRequestSchema' (POST)
+ * resolverZodLegacy.resolveResponsesName(node)  // → 'createPetsMutationSchema' (POST)
+ * resolverZodLegacy.resolveResponseName(node)  // → 'createPetsMutationResponseSchema' (POST)
+ * ```
+ */
+declare const resolverZodLegacy: ResolverZod;
 //#endregion
-export { type PluginZod, pluginZod, pluginZodName };
+export { type PluginZod, type PrinterZodFactory, type PrinterZodMiniFactory, type PrinterZodMiniNodes, type PrinterZodMiniOptions, type PrinterZodNodes, type PrinterZodOptions, type ResolverZod, pluginZod, pluginZodName, printerZod, printerZodMini, resolverZod, resolverZodLegacy, zodGenerator, zodGeneratorLegacy };
 //# sourceMappingURL=index.d.ts.map