@kubb/plugin-ts 5.0.0-alpha.8 → 5.0.0-beta.3

package/dist/index.d.ts

@@ -1,10 +1,580 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { n as PluginTs, t as Options } from "./types-CsvB6X5Y.js";
-import * as _kubb_core0 from "@kubb/core";
+import * as _$_kubb_core0 from "@kubb/core";
+import { Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+import ts from "typescript";
+import { KubbReactNode } from "@kubb/renderer-jsx/types";
 
+//#region src/printers/printerTs.d.ts
+/**
+ * Partial map of node-type overrides for the TypeScript 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
+ * pluginTs({
+ *   printer: {
+ *     nodes: {
+ *       date(node) {
+ *         return ts.factory.createTypeReferenceNode('Date', [])
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+type PrinterTsNodes = ast.PrinterPartial<ts.TypeNode, PrinterTsOptions>;
+type PrinterTsOptions = {
+  /**
+   * Mark parameters as optional with `?` or `| undefined`.
+   * - `'questionToken'` adds `?` to properties
+   * - `'undefined'` adds `| undefined` to types
+   *
+   * @default `'questionToken'`
+   */
+  optionalType: PluginTs['resolvedOptions']['optionalType'];
+  /**
+   * Array representation style.
+   * - `'array'` uses bracket notation (`T[]`)
+   * - `'generic'` uses generic syntax (`Array<T>`)
+   *
+   * @default `'array'`
+   */
+  arrayType: PluginTs['resolvedOptions']['arrayType'];
+  /**
+   * Enum output format.
+   * - `'inlineLiteral'` embeds literal unions inline
+   * - `'asPascalConst'` generates named const unions
+   * - `'asConst'` generates as const declarations
+   *
+   * @default `'inlineLiteral'`
+   */
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  /**
+   * Suffix appended to enum key reference names.
+   *
+   * @example Enum key naming
+   * `StatusKey` when `enumType` is `'asConst'`
+   *
+   * @default `'Key'`
+   */
+  enumTypeSuffix?: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  /**
+   * Syntax for generated declarations.
+   * - `'type'` generates type aliases
+   * - `'interface'` generates interface declarations
+   *
+   * @default `'type'`
+   */
+  syntaxType?: PluginTs['resolvedOptions']['syntaxType'];
+  /**
+   * Exported name for the type declaration.
+   * When omitted, returns only the raw type node.
+   */
+  name?: string;
+  /**
+   * JSDoc comment to attach to the generated type.
+   */
+  description?: string;
+  /**
+   * Properties to exclude using `Omit<Type, Keys>`.
+   * Forces type alias syntax regardless of `syntaxType` setting.
+   */
+  keysToOmit?: Array<string>;
+  /**
+   * Transforms raw schema names into valid TypeScript identifiers.
+   */
+  resolver: ResolverTs;
+  /**
+   * Schema names that represent enums for suffixed key references.
+   */
+  enumSchemaNames?: Set<string>;
+  /**
+   * Custom handler map for node type overrides.
+   */
+  nodes?: PrinterTsNodes;
+};
+/**
+ * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
+ */
+type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, ts.TypeNode, string>;
+/**
+ * TypeScript type printer built with `definePrinter`.
+ *
+ * Converts a `SchemaNode` AST node into a TypeScript AST node:
+ * - **`printer.print(node)`** — when `options.typeName` is set, returns a full
+ *   `type Name = …` or `interface Name { … }` declaration (`ts.Node`).
+ *   Without `typeName`, returns the raw `ts.TypeNode` for the schema.
+ *
+ * Dispatches on `node.type` to the appropriate handler in `nodes`. Options are closed
+ * over per printer instance, so each call to `printerTs(options)` produces an independent printer.
+ *
+ * @example Raw type node (no `typeName`)
+ * ```ts
+ * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enumType: 'inlineLiteral' })
+ * const typeNode = printer.print(schemaNode) // ts.TypeNode
+ * ```
+ *
+ * @example Full declaration (with `typeName`)
+ * ```ts
+ * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enumType: 'inlineLiteral', typeName: 'MyType' })
+ * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
+ * ```
+ */
+declare const printerTs: (options?: PrinterTsOptions | undefined) => ast.Printer<PrinterTsFactory>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * The concrete resolver type for `@kubb/plugin-ts`.
+ * Extends the base `Resolver` (which provides `default` and `resolveOptions`) with
+ * plugin-specific naming helpers for operations, parameters, responses, and schemas.
+ */
+type ResolverTs = Resolver & ast.OperationParamsResolver & {
+  /**
+   * Resolves the name for a given raw name (equivalent to `default(name, 'function')`).
+   * Since TypeScript only emits types, this is the canonical naming method.
+   *
+   * @example Resolving type names
+   * `resolver.resolveName('list pets status 200') // → 'ListPetsStatus200'`
+   */
+  resolveTypeName(name: string): string;
+  /**
+   * Resolves the file/path name for a given identifier using PascalCase.
+   *
+   * @example Resolving path names
+   * `resolver.resolvePathName('list pets', 'file') // → 'ListPets'`
+   */
+  resolvePathName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves the request body type name for an operation (required on ResolverTs).
+   */
+  resolveDataName(node: ast.OperationNode): string;
+  /**
+   * Resolves the name for an operation response by status code.
+   * Encapsulates the `<operationId> Status <statusCode>` template with PascalCase applied to the result.
+   *
+   * @example Response status names
+   * `resolver.resolveResponseStatusName(node, 200) // → 'ListPetsStatus200'`
+   */
+  resolveResponseStatusName(node: ast.OperationNode, statusCode: ast.StatusCode): string;
+  /**
+   * Resolves the name for an operation's request config (`RequestConfig`).
+   *
+   * @example Request config names
+   * `resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'`
+   */
+  resolveRequestConfigName(node: ast.OperationNode): string;
+  /**
+   * Resolves the name for the collection of all operation responses (`Responses`).
+   *
+   * @example Responses collection names
+   * `resolver.resolveResponsesName(node) // → 'ListPetsResponses'`
+   */
+  resolveResponsesName(node: ast.OperationNode): string;
+  /**
+   * Resolves the name for the union of all operation responses (`Response`).
+   *
+   * @example Response union names
+   * `resolver.resolveResponseName(node) // → 'ListPetsResponse'`
+   */
+  resolveResponseName(node: ast.OperationNode): string;
+  /**
+   * Resolves the TypeScript type alias name for an enum schema's key variant.
+   * Appends `enumTypeSuffix` (default `'Key'`) after applying the default naming convention.
+   *
+   * @example Enum key names with different suffixes
+   * ```ts
+   * resolver.resolveEnumKeyName(node, 'Key')   // → 'PetStatusKey'
+   * resolver.resolveEnumKeyName(node, 'Value') // → 'PetStatusValue'
+   * resolver.resolveEnumKeyName(node, '')      // → 'PetStatus'
+   * ```
+   */
+  resolveEnumKeyName(node: {
+    name?: string | null;
+  }, enumTypeSuffix: string): string;
+  /**
+   * Resolves the name for an operation's grouped path parameters type.
+   *
+   * @example Path parameters names
+   * `resolver.resolvePathParamsName(node, param) // → 'GetPetByIdPathParams'`
+   */
+  resolvePathParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the name for an operation's grouped query parameters type.
+   *
+   * @example Query parameters names
+   * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
+   */
+  resolveQueryParamsName(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) // → 'DeletePetHeaderParams'`
+   */
+  resolveHeaderParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
+};
+type EnumKeyCasing = 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none';
+/**
+ * Discriminated union that ties `enumTypeSuffix` and `enumKeyCasing` to the enum types that actually use them.
+ *
+ * - `'asConst'` / `'asPascalConst'` — emit a `const` object; both `enumTypeSuffix` (type-alias suffix) and
+ *    `enumKeyCasing` (key formatting) are meaningful.
+ * - `'enum'` / `'constEnum'` — emit a TypeScript enum; `enumKeyCasing` applies to member names,
+ *    but there is no separate type alias so `enumTypeSuffix` is not used.
+ * - `'literal'` / `'inlineLiteral'` — emit only union literals; keys are discarded entirely,
+ *    so neither `enumTypeSuffix` nor `enumKeyCasing` have any effect.
+ */
+type EnumTypeOptions = {
+  /**
+   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+   * - 'asConst' generates const objects with camelCase names and as const assertion.
+   * - 'asPascalConst' generates const objects with PascalCase names and as const assertion.
+   * @default 'asConst'
+   */
+  enumType?: 'asConst' | 'asPascalConst';
+  /**
+   * Suffix appended to the generated type alias name.
+   *
+   * Only affects the type alias — the const object name is unchanged.
+   *
+   * @default 'Key'
+   * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
+   */
+  enumTypeSuffix?: string;
+  /**
+   * Choose the casing for enum key names.
+   * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
+   * - 'snakeCase' generates keys in snake_case format.
+   * - 'pascalCase' generates keys in PascalCase format.
+   * - 'camelCase' generates keys in camelCase format.
+   * - 'none' uses the enum value as-is without transformation.
+   * @default 'none'
+   */
+  enumKeyCasing?: EnumKeyCasing;
+} | {
+  /**
+   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+   * - 'enum' generates TypeScript enum declarations.
+   * - 'constEnum' generates TypeScript const enum declarations.
+   * @default 'asConst'
+   */
+  enumType?: 'enum' | 'constEnum';
+  /**
+   * `enumTypeSuffix` has no effect for this `enumType`.
+   * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+   */
+  enumTypeSuffix?: never;
+  /**
+   * Choose the casing for enum key names.
+   * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
+   * - 'snakeCase' generates keys in snake_case format.
+   * - 'pascalCase' generates keys in PascalCase format.
+   * - 'camelCase' generates keys in camelCase format.
+   * - 'none' uses the enum value as-is without transformation.
+   * @default 'none'
+   */
+  enumKeyCasing?: EnumKeyCasing;
+} | {
+  /**
+   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+   * - 'literal' generates literal union types.
+   * - 'inlineLiteral' will inline enum values directly into the type (default in v5).
+   * @default 'asConst'
+   * @note In Kubb v5, 'inlineLiteral' becomes the default.
+   */
+  enumType?: 'literal' | 'inlineLiteral';
+  /**
+   * `enumTypeSuffix` has no effect for this `enumType`.
+   * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+   */
+  enumTypeSuffix?: never;
+  /**
+   * `enumKeyCasing` has no effect for this `enumType`.
+   * Literal and inlineLiteral modes emit only values — keys are discarded entirely.
+   */
+  enumKeyCasing?: never;
+};
+type Options = {
+  /**
+   * Specify the export location for the files and define the behavior of the output
+   * @default { path: 'types', barrelType: 'named' }
+   */
+  output?: Output;
+  /**
+   * Define which contentType should be used.
+   * By default, uses the first valid JSON media type.
+   */
+  contentType?: 'application/json' | (string & {});
+  /**
+   * Group the clients based on the provided name.
+   */
+  group?: Group;
+  /**
+   * 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>>;
+  /**
+   * Switch between type or interface for creating TypeScript types.
+   * - 'type' generates type alias declarations.
+   * - 'interface' generates interface declarations.
+   * @default 'type'
+   */
+  syntaxType?: 'type' | 'interface';
+  /**
+   * Choose what to use as mode for an optional value.
+   * - 'questionToken' marks the property as optional with ? (e.g., type?: string).
+   * - 'undefined' adds undefined to the type union (e.g., type: string | undefined).
+   * - 'questionTokenAndUndefined' combines both approaches (e.g., type?: string | undefined).
+   * @default 'questionToken'
+   */
+  optionalType?: 'questionToken' | 'undefined' | 'questionTokenAndUndefined';
+  /**
+   * Choose between Array<string> or string[] for array types.
+   * - 'generic' generates Array<Type> syntax.
+   * - 'array' generates Type[] syntax.
+   * @default 'array'
+   */
+  arrayType?: 'generic' | 'array';
+  /**
+   * How to style your params, by default no casing is applied
+   * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
+   * @default undefined
+   * @note response types (data/body) are NOT affected by this option
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * Define some generators next to the ts generators
+   */
+  generators?: Array<Generator<PluginTs>>;
+  /**
+   * Override naming conventions. When a method returns `null` or `undefined`, the preset
+   * resolver (`resolverTs`) is used as fallback.
+   */
+  resolver?: Partial<ResolverTs> & ThisType<ResolverTs>;
+  /**
+   * AST visitor applied to each schema/operation node before printing.
+   * Returning `null` or `undefined` from a visitor method falls back to the preset transformer.
+   *
+   * @example Remove writeOnly properties from response types
+   * ```ts
+   * transformer: {
+   *   property(node) {
+   *     if (node.schema.writeOnly) return undefined
+   *   }
+   * }
+   * ```
+   */
+  transformer?: ast.Visitor;
+  /**
+   * 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.
+   *
+   * @example Override the `date` node to use the `Date` object type
+   * ```ts
+   * import ts from 'typescript'
+   * pluginTs({
+   *   printer: {
+   *     nodes: {
+   *       date(node) {
+   *         return ts.factory.createTypeReferenceNode('Date', [])
+   *       },
+   *     },
+   *   },
+   * })
+   * ```
+   */
+  printer?: {
+    nodes?: PrinterTsNodes;
+  };
+} & EnumTypeOptions;
+type ResolvedOptions = {
+  output: Output;
+  exclude: Array<Exclude>;
+  include: Array<Include> | undefined;
+  override: Array<Override<ResolvedOptions>>;
+  group: Group | undefined;
+  enumType: NonNullable<Options['enumType']>;
+  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>;
+  enumKeyCasing: EnumKeyCasing;
+  optionalType: NonNullable<Options['optionalType']>;
+  arrayType: NonNullable<Options['arrayType']>;
+  syntaxType: NonNullable<Options['syntaxType']>;
+  paramsCasing: Options['paramsCasing'];
+  printer: Options['printer'];
+};
+type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, ResolverTs>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-ts': PluginTs;
+    }
+  }
+}
+//#endregion
+//#region src/components/Enum.d.ts
+type Props$1 = {
+  node: ast.EnumSchemaNode;
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  resolver: ResolverTs;
+  key?: string | number | null;
+};
+/**
+ * Resolves the runtime identifier name and the TypeScript type name for an enum schema node.
+ *
+ * The raw `node.name` may be a YAML key such as `"enumNames.Type"` which is not a
+ * valid TypeScript identifier. The resolver normalizes it; for inline enum
+ * properties the adapter already emits a PascalCase+suffix name so resolution is typically a no-op.
+ */
+/**
+ * Renders the enum declaration(s) for a single named `EnumSchemaNode`.
+ *
+ * Depending on `enumType` this may emit:
+ * - A runtime object (`asConst` / `asPascalConst`) plus a `typeof` type alias
+ * - A `const enum` or plain `enum` declaration (`constEnum` / `enum`)
+ * - A union literal type alias (`literal`)
+ *
+ * The emitted `File.Source` nodes carry the resolved names so that the barrel
+ * index picks up the correct export identifiers.
+ */
+declare function Enum({
+  node,
+  enumType,
+  enumTypeSuffix,
+  enumKeyCasing,
+  resolver
+}: Props$1): KubbReactNode;
+//#endregion
+//#region src/components/Type.d.ts
+type Props = {
+  name: string;
+  node: ast.SchemaNode;
+  /**
+   * Pre-configured printer instance created by the generator.
+   * Created with `printerTs({ ..., nodes: options.printer?.nodes })`.
+   */
+  printer: ast.Printer<PrinterTsFactory>;
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  resolver: ResolverTs;
+};
+declare function Type({
+  name,
+  node,
+  printer,
+  enumType,
+  enumTypeSuffix,
+  enumKeyCasing,
+  resolver
+}: Props): KubbReactNode;
+//#endregion
+//#region src/generators/typeGenerator.d.ts
+declare const typeGenerator: _$_kubb_core0.Generator<PluginTs, unknown>;
+//#endregion
 //#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-ts`, used to identify the plugin in driver lookups and warnings.
+ */
 declare const pluginTsName = "plugin-ts";
-declare const pluginTs: (options?: Options | undefined) => _kubb_core0.UserPluginWithLifeCycle<PluginTs>;
+/**
+ * The `@kubb/plugin-ts` plugin factory.
+ *
+ * Generates TypeScript type declarations 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 pluginTs from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   plugins: [pluginTs({ output: { path: 'types' }, enumType: 'asConst' })],
+ * })
+ * ```
+ */
+declare const pluginTs: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginTs>;
+//#endregion
+//#region src/printers/functionPrinter.d.ts
+type FunctionPrinterOptions = {
+  /**
+   * Rendering modes supported by `functionPrinter`.
+   *
+   * | Mode          | Output example                              | Use case                        |
+   * |---------------|---------------------------------------------|---------------------------------|
+   * | `declaration` | `id: string, config: Config = {}`           | Function parameter declaration |
+   * | `call`        | `id, { method, url }`                       | Function call arguments |
+   * | `keys`        | `{ id, config }`                            | Key names only (destructuring) |
+   * | `values`      | `{ id: id, config: config }`                | Key/value object entries |
+   */
+  mode: 'declaration' | 'call' | 'keys' | 'values';
+  /**
+   * Optional transformation applied to every parameter name before printing.
+   */
+  transformName?: (name: string) => string;
+  /**
+   * Optional transformation applied to every type string before printing.
+   */
+  transformType?: (type: string) => string;
+};
+/**
+ * Default function-signature printer.
+ * Covers the four standard output modes used across Kubb plugins.
+ *
+ * @example
+ * ```ts
+ * const printer = functionPrinter({ mode: 'declaration' })
+ *
+ * const sig = createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'config', type: 'Config', optional: false, default: '{}' }),
+ *   ],
+ * })
+ *
+ * printer.print(sig)  // → "petId: string, config: Config = {}"
+ * ```
+ */
+declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) => {
+  name: "functionParameters";
+  options: FunctionPrinterOptions;
+  transform: (node: ast.FunctionParamNode) => string | null | undefined;
+  print: (node: ast.FunctionParamNode) => string | null | undefined;
+};
+//#endregion
+//#region src/resolvers/resolverTs.d.ts
+/**
+ * Resolver for `@kubb/plugin-ts` that provides the default naming and path-resolution
+ * helpers used by the plugin. Import this in other plugins to resolve the exact names and
+ * paths that `plugin-ts` generates without hardcoding the conventions.
+ *
+ * The `default` method is automatically injected by `defineResolver` — it uses `camelCase`
+ * for identifiers/files and `pascalCase` for type names.
+ *
+ * @example
+ * ```ts
+ * import { resolver } from '@kubb/plugin-ts'
+ *
+ * resolver.default('list pets', 'type')              // → 'ListPets'
+ * resolver.resolveName('list pets status 200')        // → 'ListPetsStatus200'
+ * resolver.resolvePathName('list pets', 'file')       // → 'listPets'
+ * ```
+ */
+declare const resolverTs: ResolverTs;
 //#endregion
-export { type PluginTs, pluginTs, pluginTsName };
+export { Enum, type PluginTs, type PrinterTsFactory, type PrinterTsNodes, type PrinterTsOptions, type ResolverTs, Type, pluginTs as default, pluginTs, functionPrinter, pluginTsName, printerTs, resolverTs, typeGenerator };
 //# sourceMappingURL=index.d.ts.map