@kubb/plugin-zod 5.0.0-beta.10 → 5.0.0-beta.100

package/dist/index.d.ts

@@ -1,15 +1,14 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import * as _$_kubb_core0 from "@kubb/core";
-import { Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver, ast } 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, and `this.options` to read printer options.
+ * 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
@@ -17,7 +16,20 @@ import { AdapterOas } from "@kubb/adapter-oas";
  *   printer: {
  *     nodes: {
  *       date(node) {
- *         return 'z.string().date()'
+ *         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 })})`
  *       },
  *     },
  *   },
@@ -37,13 +49,16 @@ type PrinterZodOptions = {
    */
   guidType?: PluginZod['resolvedOptions']['guidType'];
   /**
-   * Date format in the OpenAPI spec (`'date'` or `'date-time'`).
+   * Output form for an OpenAPI `pattern` inside `.regex(...)`: a regex literal
+   * (`'literal'`) or the `RegExp` constructor (`'constructor'`).
+   *
+   * @default 'literal'
    */
-  dateType?: AdapterOas['resolvedOptions']['dateType'];
+  regexType?: PluginZod['resolvedOptions']['regexType'];
   /**
-   * Hook to transform generated Zod schema before output.
+   * Date format in the OpenAPI spec (`'date'` or `'date-time'`).
    */
-  wrapOutput?: PluginZod['resolvedOptions']['wrapOutput'];
+  dateType?: AdapterOas['resolvedOptions']['dateType'];
   /**
    * Transforms raw schema names into valid JavaScript identifiers.
    */
@@ -51,12 +66,21 @@ type PrinterZodOptions = {
   /**
    * Properties to exclude using `.omit({ key: true })`.
    */
-  keysToOmit?: Array<string>;
+  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.
    */
@@ -86,7 +110,8 @@ declare const printerZod: (options?: PrinterZodOptions | undefined) => ast.Print
  *
  * 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.
+ * 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
@@ -111,9 +136,12 @@ type PrinterZodMiniOptions = {
    */
   guidType?: PluginZod['resolvedOptions']['guidType'];
   /**
-   * Hook to transform generated Zod schema before output.
+   * Output form for an OpenAPI `pattern` inside `z.regex(...)`: a regex literal
+   * (`'literal'`) or the `RegExp` constructor (`'constructor'`).
+   *
+   * @default 'literal'
    */
-  wrapOutput?: PluginZod['resolvedOptions']['wrapOutput'];
+  regexType?: PluginZod['resolvedOptions']['regexType'];
   /**
    * Transforms raw schema names into valid JavaScript identifiers.
    */
@@ -121,7 +149,7 @@ type PrinterZodMiniOptions = {
   /**
    * Properties to exclude using `.omit({ key: true })`.
    */
-  keysToOmit?: Array<string>;
+  keysToOmit?: Array<string> | null;
   /**
    * Schema names that form circular dependency chains.
    * Properties referencing these emit lazy getters wrapping refs in `z.lazy(() => …)`.
@@ -137,7 +165,7 @@ type PrinterZodMiniOptions = {
  */
 type PrinterZodMiniFactory = ast.PrinterFactoryOptions<'zod-mini', PrinterZodMiniOptions, string, string>;
 /**
- * Zod v4 **Mini** printer built with `definePrinter`.
+ * 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.
@@ -153,110 +181,176 @@ declare const printerZodMini: (options?: PrinterZodMiniOptions | undefined) => a
 //#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 & 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;
+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;
+  };
   /**
-   * 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;
+   * 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;
+  };
   /**
-   * 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;
+   * 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;
+  };
 };
-type Options = {
-  /**
-   * @default 'zod'
-   */
-  output?: Output;
-  /**
-   * Group the Zod schemas based on the provided name.
-   */
-  group?: Group;
+/**
+ * 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 & {
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Import path for Zod package.
+   * Module specifier used in the `import { z } from '...'` statement.
+   * Use `'zod/mini'` for the tree-shakeable bundle.
    *
-   * @default 'zod'
+   * @default mini ? 'zod/mini' : 'zod'
    */
   importPath?: 'zod' | 'zod/mini' | (string & {});
   /**
-   * Add TypeScript type annotations to generated schemas.
-   */
-  typed?: boolean;
-  /**
-   * Return schemas as inferred types using `z.infer`.
+   * 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;
   /**
-   * Apply coercion to string values or configure coercion per type.
+   * 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;
@@ -264,68 +358,58 @@ type Options = {
     numbers?: boolean;
   };
   /**
-   * Generate operation-level schemas (grouped by operationId).
-   */
-  operations?: boolean;
-  /**
-   * Validator to use for UUID format: `uuid` or `guid`.
+   * Validator for `format: uuid` properties.
+   * - `'uuid'`: `z.uuid()`. Standard RFC 4122.
+   * - `'guid'`: `z.guid()`. Accepts Microsoft-style GUIDs.
    *
    * @default 'uuid'
    */
   guidType?: 'uuid' | 'guid';
   /**
-   * Use Zod Mini's functional API for better tree-shaking.
+   * 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 false
+   * @default 'literal'
    */
-  mini?: boolean;
+  regexType?: 'literal' | 'constructor';
   /**
-   * Callback to wrap the generated schema output.
+   * Switch to Zod Mini's functional API for better tree-shaking. Also defaults
+   * `importPath` to `'zod/mini'`.
    *
-   * Useful for adding metadata like `.openapi()` or extension helpers.
-   */
-  wrapOutput?: (arg: {
-    output: string;
-    schema: ast.SchemaNode;
-  }) => string | undefined;
-  /**
-   * Apply casing to parameter names.
-   */
-  paramsCasing?: 'camelcase';
-  /**
-   * Additional generators alongside the default generators.
+   * @default false
+   * @beta
    */
-  generators?: Array<Generator<PluginZod>>;
+  mini?: boolean;
   /**
-   * Override naming conventions for schema names and types.
+   * Override how schema and operation names are built. Methods you omit fall back
+   * to the default `resolverZod`.
    */
-  resolver?: Partial<ResolverZod> & ThisType<ResolverZod>;
+  resolver?: ResolverPatch<ResolverZod>;
   /**
-   * Override printer node handlers to customize rendering of specific schema types.
+   * 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;
   };
   /**
-   * AST visitor to transform schema and operation nodes.
+   * Macros applied to each schema or operation node before printing.
    */
-  transformer?: ast.Visitor;
+  macros?: Array<ast.Macro>;
 };
 type ResolvedOptions = {
   output: Output;
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
   override: Array<Override<ResolvedOptions>>;
-  group: Group | undefined;
-  typed: NonNullable<Options['typed']>;
+  group: Group | null;
   inferred: NonNullable<Options['inferred']>;
   importPath: NonNullable<Options['importPath']>;
   coercion: NonNullable<Options['coercion']>;
-  operations: NonNullable<Options['operations']>;
   guidType: NonNullable<Options['guidType']>;
+  regexType: NonNullable<Options['regexType']>;
   mini: NonNullable<Options['mini']>;
-  wrapOutput: Options['wrapOutput'];
-  paramsCasing: Options['paramsCasing'];
   printer: Options['printer'];
 };
 type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, ResolverZod>;
@@ -338,36 +422,63 @@ declare global {
 }
 //#endregion
 //#region src/generators/zodGenerator.d.ts
-declare const zodGenerator: _$_kubb_core0.Generator<PluginZod, unknown>;
+/**
+ * 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 in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-zod`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 declare const pluginZodName = "plugin-zod";
 /**
- * Generates Zod validation schemas from an OpenAPI specification.
- * Walks schemas and operations, delegates to generators, and writes barrel files
- * based on the configured `barrelType`.
+ * 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 Zod schema generator
+ * @example
  * ```ts
- * import pluginZod from '@kubb/plugin-zod'
+ * import { defineConfig } from 'kubb/config'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ *
  * export default defineConfig({
- *   plugins: [pluginZod({ output: { path: 'zod' } })]
+ *   input: './petStore.yaml',
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginZod({
+ *       output: { path: './zod' },
+ *       inferred: true,
+ *     }),
+ *   ],
  * })
  * ```
  */
-declare const pluginZod: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginZod>;
+declare const pluginZod: (options?: Options | undefined) => import("kubb/kit").Plugin<PluginZod>;
 //#endregion
 //#region src/resolvers/resolverZod.d.ts
 /**
- * Naming convention resolver for Zod plugin.
+ * 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.
  *
- * Provides default naming helpers using camelCase with a `Schema` suffix for schemas.
+ * @example Resolve schema and type names
+ * ```ts
+ * import { resolverZod } from '@kubb/plugin-zod'
  *
- * @example
- * `resolverZod.default('list pets', 'function')  // → 'listPetsSchema'`
+ * resolverZod.name('list pets')          // 'listPetsSchema'
+ * resolverZod.schema.typeName('pet')     // 'PetSchemaType'
+ * ```
  */
 declare const resolverZod: ResolverZod;
 //#endregion