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

package/dist/index.d.ts

@@ -1,10 +1,486 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import { n as PluginZod, t as Options } from "./types-CoCoOc2u.js";
-import * as _kubb_core0 from "@kubb/core";
-
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ResolverPatch, ast } from "kubb/kit";
+import { AdapterOas } from "@kubb/adapter-oas";
+//#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, `this.base` to reuse the output of the
+ * handler being replaced, and `this.options` to read printer options.
+ *
+ * @example Override the `date` handler
+ * ```ts
+ * pluginZod({
+ *   printer: {
+ *     nodes: {
+ *       date(node) {
+ *         return 'z.iso.date()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example Wrap the built-in output
+ * ```ts
+ * pluginZod({
+ *   printer: {
+ *     nodes: {
+ *       object(node) {
+ *         return `${this.base(node)}.openapi(${JSON.stringify({ description: node.description })})`
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+type PrinterZodNodes = ast.PrinterPartial<string, PrinterZodOptions>;
+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'];
+  /**
+   * Output form for an OpenAPI `pattern` inside `.regex(...)`: a regex literal
+   * (`'literal'`) or the `RegExp` constructor (`'constructor'`).
+   *
+   * @default 'literal'
+   */
+  regexType?: PluginZod['resolvedOptions']['regexType'];
+  /**
+   * Date format in the OpenAPI spec (`'date'` or `'date-time'`).
+   */
+  dateType?: AdapterOas['resolvedOptions']['dateType'];
+  /**
+   * Transforms raw schema names into valid JavaScript identifiers.
+   */
+  resolver?: ResolverZod;
+  /**
+   * Properties to exclude using `.omit({ key: true })`.
+   */
+  keysToOmit?: Array<string> | null;
+  /**
+   * Schema names that form circular dependency chains.
+   * Properties referencing these emit lazy getters wrapping refs in `z.lazy(() => …)`.
+   */
+  cyclicSchemas?: ReadonlySet<string>;
+  /**
+   * Print direction for `dateType: 'date'` fields (`Date` in TypeScript):
+   * - `'output'` (default): decode the wire `string` into a `Date` (response bodies).
+   * - `'input'`: encode a `Date` back into the wire `string` (request bodies/params).
+   *
+   * Diverging the directions requires the generator to emit an `${name}InputSchema`
+   * variant for each date-bearing component.
+   */
+  direction?: 'input' | 'output';
+  /**
+   * Custom handler map for node type overrides.
+   */
+  nodes?: PrinterZodNodes;
+};
+/**
+ * Factory options for the Zod printer, defining input/output types and configuration.
+ */
+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()"
+ * ```
+ */
+declare const printerZod: (options?: PrinterZodOptions | undefined) => ast.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, `this.base` to reuse the output of the
+ * handler being replaced, 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 = ast.PrinterPartial<string, PrinterZodMiniOptions>;
+type PrinterZodMiniOptions = {
+  /**
+   * Use `z.guid()` or `z.uuid()` for UUID/GUID validation.
+   *
+   * @default 'uuid'
+   */
+  guidType?: PluginZod['resolvedOptions']['guidType'];
+  /**
+   * Output form for an OpenAPI `pattern` inside `z.regex(...)`: a regex literal
+   * (`'literal'`) or the `RegExp` constructor (`'constructor'`).
+   *
+   * @default 'literal'
+   */
+  regexType?: PluginZod['resolvedOptions']['regexType'];
+  /**
+   * Transforms raw schema names into valid JavaScript identifiers.
+   */
+  resolver?: ResolverZod;
+  /**
+   * Properties to exclude using `.omit({ key: true })`.
+   */
+  keysToOmit?: Array<string> | null;
+  /**
+   * 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.
+ */
+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())"
+ * ```
+ */
+declare const printerZodMini: (options?: PrinterZodMiniOptions | undefined) => ast.Printer<PrinterZodMiniFactory>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Resolver for Zod that provides naming methods for schema types.
+ *
+ * The top-level `name` resolves a camelCase schema function name with a `Schema` suffix
+ * (`listPetsSchema`), and `file` casts generated file names the same way. Composite naming lives in
+ * the `schema`, `param`, and `response` namespaces.
+ */
+type ResolverZod = Resolver & {
+  /**
+   * Names derived from a component schema: its inferred types and the request (input) direction
+   * variant, where a date-bearing component encodes `Date` back to a wire `string`.
+   */
+  schema: {
+    /**
+     * Resolves the schema type name (inferred type from schema).
+     *
+     * @example Schema type names
+     * `resolver.schema.typeName('pet') // → 'PetSchemaType'`
+     */
+    typeName(name: string): string;
+    /**
+     * Resolves the generated type name from the schema.
+     *
+     * @example Type names
+     * `resolver.schema.type('petSchema') // → 'PetSchemaType'`
+     */
+    type(name: string): string;
+    /**
+     * Resolves the schema function name for the request (input) direction of a
+     * date-bearing component, where `Date` is encoded back to a wire `string`.
+     *
+     * @example Input schema names
+     * `resolver.schema.inputName('order') // → 'orderInputSchema'`
+     */
+    inputName(name: string): string;
+    /**
+     * Resolves the inferred type name for the request (input) direction variant.
+     *
+     * @example Input schema type names
+     * `resolver.schema.inputTypeName('order') // → 'OrderInputSchemaType'`
+     */
+    inputTypeName(name: string): string;
+  };
+  /**
+   * Names for an operation's parameters: an individual parameter and the grouped path, query, and
+   * header schemas.
+   */
+  param: {
+    /**
+     * Resolves the schema name for an individual parameter.
+     *
+     * @example Individual parameter name
+     * `resolver.param.name(node, param) // → 'deletePetPathPetIdSchema'`
+     */
+    name(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the name for an operation's grouped path parameters schema.
+     *
+     * @example Path parameters names
+     * `resolver.param.path(node, param) // → 'deletePetPathSchema'`
+     */
+    path(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the name for an operation's grouped query parameters schema.
+     *
+     * @example Query parameters names
+     * `resolver.param.query(node, param) // → 'findPetsByStatusQuerySchema'`
+     */
+    query(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the name for an operation's grouped header parameters schema.
+     *
+     * @example Header parameters names
+     * `resolver.param.headers(node, param) // → 'deletePetHeadersSchema'`
+     */
+    headers(node: ast.OperationNode, param: ast.ParameterNode): string;
+  };
+  /**
+   * Names for an operation's responses: per-status schemas, the request body, and the combined,
+   * union, and error names.
+   */
+  response: {
+    /**
+     * Resolves the name for an operation response by status code.
+     *
+     * @example Response status names
+     * `resolver.response.status(node, 200) // → 'listPetsStatus200Schema'`
+     */
+    status(node: ast.OperationNode, statusCode: ast.StatusCode): string;
+    /**
+     * Resolves the request body schema name.
+     *
+     * @example Request body names
+     * `resolver.response.body(node) // → 'createPetBodySchema'`
+     */
+    body(node: ast.OperationNode): string;
+    /**
+     * Resolves the name for the collection of all operation responses.
+     *
+     * @example Responses collection names
+     * `resolver.response.responses(node) // → 'listPetsResponsesSchema'`
+     */
+    responses(node: ast.OperationNode): string;
+    /**
+     * Resolves the name for the union of all operation responses.
+     *
+     * @example Response union names
+     * `resolver.response.response(node) // → 'listPetsResponseSchema'`
+     */
+    response(node: ast.OperationNode): string;
+    /**
+     * Resolves the name for the union of an operation's error (non-2xx) responses. Generated clients
+     * validate the error body against this on the non-throw path.
+     *
+     * @example Error union names
+     * `resolver.response.error(node) // → 'listPetsErrorSchema'`
+     */
+    error(node: ast.OperationNode): string;
+    /**
+     * Resolves the inferred type name for an operation's combined `{ body, path, query, headers }`
+     * options object. Only meaningful when `inferred: true`, since the schema and type this name
+     * points to are generated only in that case.
+     *
+     * @example Options type names
+     * `resolver.response.options(node) // → 'ListPetsOptionsSchemaType'`
+     */
+    options(node: ast.OperationNode): string;
+  };
+};
+/**
+ * Where the generated Zod schemas are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'zod', barrel: { type: 'named' } }
+ */
+type Options = OutputOptions & {
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>;
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  override?: Array<Override<ResolvedOptions>>;
+  /**
+   * Module specifier used in the `import { z } from '...'` statement.
+   * Use `'zod/mini'` for the tree-shakeable bundle.
+   *
+   * @default mini ? 'zod/mini' : 'zod'
+   */
+  importPath?: 'zod' | 'zod/mini' | (string & {});
+  /**
+   * Export a `z.infer<typeof schema>` type alias next to every generated schema.
+   * Lets the Zod schema act as the single source of truth.
+   */
+  inferred?: boolean;
+  /**
+   * Wrap schemas in `z.coerce` so input is coerced before validation. Useful for
+   * form data and query params where everything arrives as a string.
+   * - `true` coerces strings, numbers, and dates.
+   * - Object form picks per-primitive coercion.
+   *
+   * `dates` applies to fields typed as `Date` (adapter `dateType: 'date'`): they
+   * validate with `z.coerce.date()` instead of the string-to-Date codec. Fields
+   * kept as ISO strings (`z.iso.date()`, `z.iso.datetime()`) are never coerced.
+   *
+   * @default false
+   * @see https://zod.dev/?id=coercion-for-primitives
+   */
+  coercion?: boolean | {
+    dates?: boolean;
+    strings?: boolean;
+    numbers?: boolean;
+  };
+  /**
+   * Validator for `format: uuid` properties.
+   * - `'uuid'`: `z.uuid()`. Standard RFC 4122.
+   * - `'guid'`: `z.guid()`. Accepts Microsoft-style GUIDs.
+   *
+   * @default 'uuid'
+   */
+  guidType?: 'uuid' | 'guid';
+  /**
+   * Output form for an OpenAPI `pattern` inside `.regex(...)`.
+   * - `'literal'`: a regex literal, `.regex(/^[a-z]+$/)`.
+   * - `'constructor'`: the `RegExp` constructor, `.regex(new RegExp("^[a-z]+$"))`.
+   *
+   * @default 'literal'
+   */
+  regexType?: 'literal' | 'constructor';
+  /**
+   * Switch to Zod Mini's functional API for better tree-shaking. Also defaults
+   * `importPath` to `'zod/mini'`.
+   *
+   * @default false
+   * @beta
+   */
+  mini?: boolean;
+  /**
+   * Override how schema and operation names are built. Methods you omit fall back
+   * to the default `resolverZod`.
+   */
+  resolver?: ResolverPatch<ResolverZod>;
+  /**
+   * Replace the Zod handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * When `mini: true`, overrides target the Zod Mini printer instead.
+   */
+  printer?: {
+    nodes?: PrinterZodNodes | PrinterZodMiniNodes;
+  };
+  /**
+   * Macros applied to each schema or operation node before printing.
+   */
+  macros?: Array<ast.Macro>;
+};
+type ResolvedOptions = {
+  output: Output;
+  exclude: Array<Exclude>;
+  include: Array<Include> | undefined;
+  override: Array<Override<ResolvedOptions>>;
+  group: Group | null;
+  inferred: NonNullable<Options['inferred']>;
+  importPath: NonNullable<Options['importPath']>;
+  coercion: NonNullable<Options['coercion']>;
+  guidType: NonNullable<Options['guidType']>;
+  regexType: NonNullable<Options['regexType']>;
+  mini: NonNullable<Options['mini']>;
+  printer: Options['printer'];
+};
+type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, ResolverZod>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-zod': PluginZod;
+    }
+  }
+}
+//#endregion
+//#region src/generators/zodGenerator.d.ts
+/**
+ * Built-in generator for `@kubb/plugin-zod`. Emits one Zod schema per
+ * schema in the spec plus per-operation request/response/parameter schemas.
+ * When `mini: true`, schemas use the Zod Mini functional API instead of
+ * chainable methods.
+ */
+declare const zodGenerator: import("kubb/kit").Generator<PluginZod, unknown>;
+//#endregion
 //#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-zod`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 declare const pluginZodName = "plugin-zod";
-declare const pluginZod: (options?: Options | undefined) => _kubb_core0.UserPluginWithLifeCycle<PluginZod>;
+/**
+ * Generates Zod v4 schemas from an OpenAPI spec. Use them to validate API
+ * responses at runtime, build form schemas, or feed back into router libraries
+ * that consume Zod (tRPC, Hono, Elysia). Pair with `@kubb/plugin-axios` or
+ * `@kubb/plugin-fetch` and set the client's `validator: 'zod'` to validate every response
+ * automatically.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb/config'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ *
+ * export default defineConfig({
+ *   input: './petStore.yaml',
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginZod({
+ *       output: { path: './zod' },
+ *       inferred: true,
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare const pluginZod: (options?: Options | undefined) => import("kubb/kit").Plugin<PluginZod>;
+//#endregion
+//#region src/resolvers/resolverZod.d.ts
+/**
+ * Default resolver used by `@kubb/plugin-zod`. Decides the names and file
+ * paths for every generated Zod schema. Schemas use camelCase with a
+ * `Schema` suffix (`listPetsSchema`); their inferred types use PascalCase
+ * with a `SchemaType` suffix (`PetSchemaType`), so the value and the type
+ * never share an identifier even when the schema name is all-uppercase.
+ *
+ * @example Resolve schema and type names
+ * ```ts
+ * import { resolverZod } from '@kubb/plugin-zod'
+ *
+ * resolverZod.name('list pets')          // 'listPetsSchema'
+ * resolverZod.schema.typeName('pet')     // 'PetSchemaType'
+ * ```
+ */
+declare const resolverZod: 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 as default, pluginZod, pluginZodName, printerZod, printerZodMini, resolverZod, zodGenerator };
 //# sourceMappingURL=index.d.ts.map