@kubb/plugin-ts 5.0.0-alpha.21 → 5.0.0-alpha.23

package/dist/index.d.ts

@@ -1,10 +1,491 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { n as Options, r as PluginTs } from "./types-BcyuFDn9.js";
-import * as _kubb_core0 from "@kubb/core";
+import ts from "typescript";
+import { OperationParamsResolver } from "@kubb/ast";
+import * as _$_kubb_core0 from "@kubb/core";
+import { CompatibilityPreset, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, PrinterFactoryOptions, ResolvePathOptions, Resolver, UserGroup } from "@kubb/core";
+import { EnumSchemaNode, FunctionNode, OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from "@kubb/ast/types";
+import { FabricReactNode } from "@kubb/react-fabric/types";
 
+//#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 & 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
+   * resolver.resolveName('list pets status 200') // → 'ListPetsStatus200'
+   */
+  resolveName(name: string): string;
+  /**
+   * Resolves the file/path name for a given identifier using PascalCase.
+   *
+   * @example
+   * resolver.resolvePathName('list pets', 'file') // → 'ListPets'
+   */
+  resolvePathName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string; /** Resolves the request body type name (required on ResolverTs). */
+  resolveDataName(node: 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
+   * resolver.resolveResponseStatusName(node, 200) // → 'ListPetsStatus200'
+   */
+  resolveResponseStatusName(node: OperationNode, statusCode: StatusCode): string;
+  /**
+   * Resolves the name for an operation's request config (`RequestConfig`).
+   *
+   * @example
+   * resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'
+   */
+  resolveRequestConfigName(node: OperationNode): string;
+  /**
+   * Resolves the name for the collection of all operation responses (`Responses`).
+   *
+   * @example
+   * resolver.resolveResponsesName(node) // → 'ListPetsResponses'
+   */
+  resolveResponsesName(node: OperationNode): string;
+  /**
+   * Resolves the name for the union of all operation responses (`Response`).
+   *
+   * @example
+   * resolver.resolveResponseName(node) // → 'ListPetsResponse'
+   */
+  resolveResponseName(node: 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
+   * resolver.resolveEnumKeyName(node, 'Key')   // → 'PetStatusKey'
+   * resolver.resolveEnumKeyName(node, 'Value') // → 'PetStatusValue'
+   * resolver.resolveEnumKeyName(node, '')      // → 'PetStatus'
+   */
+  resolveEnumKeyName(node: SchemaNode, enumTypeSuffix: string): string;
+  /**
+   * Resolves the name for an operation's grouped path parameters type.
+   *
+   * @example
+   * resolver.resolvePathParamsName(node, param) // → 'GetPetByIdPathParams'
+   */
+  resolvePathParamsName(node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the name for an operation's grouped query parameters type.
+   *
+   * @example
+   * resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'
+   */
+  resolveQueryParamsName(node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the name for an operation's grouped header parameters type.
+   *
+   * @example
+   * resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'
+   */
+  resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string;
+};
+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?: 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>>;
+  /**
+   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+   * - 'enum' generates TypeScript enum declarations.
+   * - 'asConst' generates const objects with camelCase names and as const assertion.
+   * - 'asPascalConst' generates const objects with PascalCase names and as const assertion.
+   * - 'constEnum' generates TypeScript const enum declarations.
+   * - 'literal' generates literal union types.
+   * - 'inlineLiteral' inline enum values directly into the type (default in v5).
+   * @default 'asConst'
+   * @note In Kubb v5, 'inlineLiteral' becomes the default.
+   */
+  enumType?: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral';
+  /**
+   * Suffix appended to the generated type alias name when `enumType` is `asConst` or `asPascalConst`.
+   *
+   * 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?: 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none';
+  /**
+   * 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>>;
+  /**
+   * Apply a compatibility naming preset.
+   * Use `kubbV4` for strict v4 type-generation compatibility.
+   * You can further customize naming with `resolvers`.
+   * @default 'default'
+   */
+  compatibilityPreset?: CompatibilityPreset;
+  /**
+   * Array of named resolvers that control naming conventions.
+   * Later entries override earlier ones (last wins).
+   * Built-in: `resolverTs` (default), `resolverTsLegacy`.
+   * @default [resolverTs]
+   */
+  resolvers?: Array<ResolverTs>;
+  /**
+   * Array of AST visitors applied to each SchemaNode/OperationNode before printing.
+   * Uses `transform()` from `@kubb/ast` — visitors can modify, replace, or annotate nodes.
+   *
+   * @example Remove writeOnly properties from response types
+   * ```ts
+   * transformers: [{
+   *   property(node) {
+   *     if (node.schema.writeOnly) return undefined
+   *   }
+   * }]
+   * ```
+   *
+   * @example Force all dates to plain strings
+   * ```ts
+   * transformers: [{
+   *   schema(node) {
+   *     if (node.type === 'date') return { ...node, type: 'string' }
+   *   }
+   * }]
+   * ```
+   */
+  transformers?: Array<Visitor>;
+};
+type ResolvedOptions = {
+  output: Output;
+  group: Group | undefined;
+  enumType: NonNullable<Options['enumType']>;
+  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>;
+  enumKeyCasing: NonNullable<Options['enumKeyCasing']>;
+  optionalType: NonNullable<Options['optionalType']>;
+  arrayType: NonNullable<Options['arrayType']>;
+  syntaxType: NonNullable<Options['syntaxType']>;
+  paramsCasing: Options['paramsCasing'];
+  transformers: Array<Visitor>;
+};
+type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions, ResolverTs>;
+//#endregion
+//#region src/components/Enum.d.ts
+type Props$1 = {
+  node: EnumSchemaNode;
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  resolver: ResolverTs;
+};
+/**
+ * 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): FabricReactNode;
+//#endregion
+//#region src/components/Type.d.ts
+type Props = {
+  name: string;
+  node: SchemaNode;
+  optionalType: PluginTs['resolvedOptions']['optionalType'];
+  arrayType: PluginTs['resolvedOptions']['arrayType'];
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  syntaxType: PluginTs['resolvedOptions']['syntaxType'];
+  resolver: PluginTs['resolver'];
+  description?: string;
+  keysToOmit?: string[];
+};
+declare function Type({
+  name,
+  node,
+  keysToOmit,
+  optionalType,
+  arrayType,
+  syntaxType,
+  enumType,
+  enumTypeSuffix,
+  enumKeyCasing,
+  description,
+  resolver
+}: Props): FabricReactNode;
+//#endregion
+//#region src/generators/typeGenerator.d.ts
+declare const typeGenerator: _$_kubb_core0.ReactGeneratorV2<PluginTs>;
+//#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.UserPluginWithLifeCycle<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: FunctionNode) => string | null | undefined;
+  print: (node: FunctionNode) => string | null | undefined;
+};
+//#endregion
+//#region src/printers/printerTs.d.ts
+type TsOptions = {
+  /**
+   * @default `'questionToken'`
+   */
+  optionalType: PluginTs['resolvedOptions']['optionalType'];
+  /**
+   * @default `'array'`
+   */
+  arrayType: PluginTs['resolvedOptions']['arrayType'];
+  /**
+   * @default `'inlineLiteral'`
+   */
+  enumType: PluginTs['resolvedOptions']['enumType'];
+  /**
+   * Suffix appended to the generated type alias name when `enumType` is `asConst` or `asPascalConst`.
+   *
+   * @default `'Key'`
+   */
+  enumTypeSuffix?: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  /**
+   * Controls whether a `type` alias or `interface` declaration is emitted.
+   * @default `'type'`
+   */
+  syntaxType?: PluginTs['resolvedOptions']['syntaxType'];
+  /**
+   * When set, `printer.print(node)` produces a full `type Name = …` declaration.
+   * When omitted, `printer.print(node)` returns the raw type node.
+   */
+  name?: string;
+  /**
+   * JSDoc `@description` comment added to the generated type or interface declaration.
+   */
+  description?: string;
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Forces type-alias syntax even when `syntaxType` is `'interface'`.
+   */
+  keysToOmit?: Array<string>;
+  /**
+   * Resolver used to transform raw schema names into valid TypeScript identifiers.
+   */
+  resolver: ResolverTs;
+};
+/**
+ * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
+ */
+type TsPrinter = PrinterFactoryOptions<'typescript', TsOptions, 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?: TsOptions | undefined) => _$_kubb_core0.Printer<TsPrinter>;
+//#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
+//#region src/resolvers/resolverTsLegacy.d.ts
+/**
+ * Legacy resolver for `@kubb/plugin-ts` that reproduces the naming conventions
+ * used before the v2 resolver refactor. Enable via `compatibilityPreset: 'kubbV4'`
+ * (or by composing this resolver manually).
+ *
+ * Key differences from the default resolver:
+ * - Response status types: `<OperationId><StatusCode>` (e.g. `CreatePets201`) instead of `<OperationId>Status201`
+ * - Default/error responses: `<OperationId>Error` instead of `<OperationId>StatusDefault`
+ * - Request body: `<OperationId>MutationRequest` (non-GET) / `<OperationId>QueryRequest` (GET)
+ * - Combined responses type: `<OperationId>Mutation` / `<OperationId>Query`
+ * - Response union: `<OperationId>MutationResponse` / `<OperationId>QueryResponse`
+ *
+ * @example
+ * ```ts
+ * import { resolverTsLegacy } from '@kubb/plugin-ts'
+ *
+ * resolverTsLegacy.resolveResponseStatusTypedName(node, 201)  // → 'CreatePets201'
+ * resolverTsLegacy.resolveResponseStatusTypedName(node, 'default')  // → 'CreatePetsError'
+ * resolverTsLegacy.resolveDataTypedName(node)  // → 'CreatePetsMutationRequest' (POST)
+ * resolverTsLegacy.resolveResponsesTypedName(node)  // → 'CreatePetsMutation' (POST)
+ * resolverTsLegacy.resolveResponseTypedName(node)  // → 'CreatePetsMutationResponse' (POST)
+ * ```
+ */
+declare const resolverTsLegacy: ResolverTs;
 //#endregion
-export { type PluginTs, pluginTs, pluginTsName };
+export { Enum, type PluginTs, type ResolverTs, Type, functionPrinter, pluginTs, pluginTsName, printerTs, resolverTs, resolverTsLegacy, typeGenerator };
 //# sourceMappingURL=index.d.ts.map