@kubb/plugin-zod 5.4.9 → 5.4.12

package/dist/index.d.cts

@@ -0,0 +1,555 @@
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "kubb/kit";
+//#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?: ast.ParserOptions['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>;
+  /**
+   * Which way a node converts between its wire type and its runtime type:
+   * - `'decode'` (default): wire into runtime, used by response schemas.
+   * - `'encode'`: runtime back to wire, used by request bodies and parameters.
+   *
+   * Named for the conversion rather than the slot, since Zod's own `z.input` and `z.output`
+   * describe a different axis and read inverted here: the `'decode'` schema is the one whose
+   * `z.input` is the wire type.
+   *
+   * A handler returning different output per direction makes the generator emit an
+   * `${name}InputSchema` variant for that component.
+   */
+  direction?: 'encode' | 'decode';
+  /**
+   * 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()"
+ * ```
+ */
+export 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 = {
+  /**
+   * Enable automatic type coercion for strings, numbers, and dates through `z.coerce.*()`.
+   */
+  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 `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())"
+ * ```
+ */
+export 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;
+    /**
+     * Resolves the type guard function name for a schema.
+     *
+     * @example Type guard names
+     * `resolver.schema.isName('pet') // → 'isPet'`
+     */
+    isName(name: string): string;
+    /**
+     * Resolves the assertion function name for a schema.
+     *
+     * @example Assertion names
+     * `resolver.schema.assertName('pet') // → 'assertPet'`
+     */
+    assertName(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 per-status record of all operation responses. Only meaningful when
+     * `inferred: true`, since the schema and type this name points to are generated only in that
+     * case. Generated clients key their `RequestResult` on the inferred type.
+     *
+     * @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 CompileOptions = {
+  /**
+   * Throw an error if any part of the schema cannot be compiled into flat JavaScript,
+   * preventing silent fallback to the standard interpreter.
+   *
+   * @default false
+   */
+  strict?: boolean;
+};
+/**
+ * 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,
+   * and neither are `format: time` fields, since `new Date()` cannot parse a bare
+   * `HH:mm:ss` value.
+   *
+   * `bigint` fields (`format: int64`) always coerce, regardless of this option:
+   * `JSON.parse` hands back a `number`, which a plain `z.bigint()` rejects.
+   *
+   * @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';
+  /**
+   * Wrap generated schemas with `z.compile(...)` to enable Zod's hyperoptimized
+   * fast-path validation logic.
+   *
+   * Set to `true` or pass `{ strict: true }` to enforce that schemas compile into
+   * flat JavaScript without silently degrading to the standard interpreter.
+   *
+   * @default false
+   * @note Only compatible with Zod v4.5.0 or above.
+   * @see https://zod.dev/blog/introducing-z-compile
+   */
+  compile?: boolean | CompileOptions;
+  /**
+   * 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>;
+  /**
+   * Generate TypeScript type guards (`is*`) and assertion functions (`assert*`) for schemas
+   * using Zod v4's native `validate` API.
+   * - `true`: Generates both `is*` type guards and `assert*` assertion functions.
+   * - `{ is?: boolean; assert?: boolean }`: Selectively enable type guards or assertions.
+   *
+   * @default false
+   * @note Only compatible with Zod v4.6.0 or above.
+   * @see https://zod.dev
+   */
+  typeGuards?: boolean | {
+    is?: boolean;
+    assert?: boolean;
+  };
+  /**
+   * Replace the Zod handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * When `mini: true`, overrides target the Zod Mini printer instead.
+   *
+   * A handler that returns a different expression per `this.options.direction` declares a two-way
+   * conversion, such as a `time` field carried as an ISO string but modeled as a
+   * `Temporal.PlainTime`. The generator then emits an `${name}InputSchema` variant for request
+   * bodies to resolve to, `$ref` included. Ignore `direction` and only the printed output changes.
+   */
+  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']>;
+  compile: NonNullable<Options['compile']>;
+  mini: NonNullable<Options['mini']>;
+  typeGuards: NonNullable<Options['typeGuards']>;
+  printer: Options['printer'];
+};
+type PluginZod = PluginType<'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.
+ */
+export 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.
+ */
+export declare const pluginZodName = "plugin-zod";
+/**
+ * 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,
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export declare const pluginZod: import("kubb/kit").PluginFactory<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'
+ * ```
+ */
+export declare const resolverZod: ResolverZod;
+//#endregion
+export { type CompileOptions, type PluginZod, type PrinterZodFactory, type PrinterZodMiniFactory, type PrinterZodMiniNodes, type PrinterZodMiniOptions, type PrinterZodNodes, type PrinterZodOptions, type ResolverZod, pluginZod as default };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, 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.
@@ -58,7 +56,7 @@ type PrinterZodOptions = {
   /**
    * Date format in the OpenAPI spec (`'date'` or `'date-time'`).
    */
-  dateType?: AdapterOas['resolvedOptions']['dateType'];
+  dateType?: ast.ParserOptions['dateType'];
   /**
    * Transforms raw schema names into valid JavaScript identifiers.
    */