@kubb/plugin-ts 5.0.0-beta.4 → 5.0.0-beta.56

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-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 "./chunk-C0LytTxp.js";
+import { Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
 import ts from "typescript";
 import { KubbReactNode } from "@kubb/renderer-jsx/types";
 
@@ -44,23 +43,11 @@ type PrinterTsOptions = {
    */
   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'`
+   * Grouped enum settings. The printer emits references to enums, not the enum declarations, so only
+   * `type` (the output format) and `typeSuffix` (the enum key reference suffix) matter here.
+   * `constCasing` and `keyCasing` are ignored.
    */
-  enumTypeSuffix?: PluginTs['resolvedOptions']['enumTypeSuffix'];
+  enum: PluginTs['resolvedOptions']['enum'];
   /**
    * Syntax for generated declarations.
    * - `'type'` generates type aliases
@@ -82,7 +69,7 @@ type PrinterTsOptions = {
    * Properties to exclude using `Omit<Type, Keys>`.
    * Forces type alias syntax regardless of `syntaxType` setting.
    */
-  keysToOmit?: Array<string>;
+  keysToOmit?: Array<string> | null;
   /**
    * Transforms raw schema names into valid TypeScript identifiers.
    */
@@ -113,13 +100,13 @@ type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions
  *
  * @example Raw type node (no `typeName`)
  * ```ts
- * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enumType: 'inlineLiteral' })
+ * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: '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 printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' }, typeName: 'MyType' })
  * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
  * ```
  */
@@ -217,33 +204,47 @@ type ResolverTs = Resolver & ast.OperationParamsResolver & {
   resolveHeaderParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
 };
 type EnumKeyCasing = 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none';
+type EnumConstCasing = 'camelCase' | 'pascalCase';
 /**
- * Discriminated union that ties `enumTypeSuffix` and `enumKeyCasing` to the enum types that actually use them.
+ * Grouped enum settings. Each `type` uses only some of the other fields.
  *
- * - `'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.
+ * - `'asConst'` emits a `const` object plus a `typeof` type alias, so `constCasing`, `typeSuffix`, and `keyCasing` all apply.
+ * - `'enum'` and `'constEnum'` emit a TypeScript enum, so only `keyCasing` (the member names) applies.
+ * - `'literal'` and `'inlineLiteral'` emit union literals and drop the keys, so none of the other fields apply.
+ *
+ * @example Share one name between the const and the type
+ * ```ts
+ * enum: { type: 'asConst', constCasing: 'pascalCase', typeSuffix: '' }
+ * // export const VehicleType = { … } as const
+ * // export type VehicleType = (typeof VehicleType)[keyof typeof VehicleType]
+ * ```
  */
-type EnumTypeOptions = {
+type EnumOptions$1 = {
   /**
-   * 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.
+   * Emit a `const` object asserted with `as const`, paired with a `typeof` type alias.
+   * This is tree-shakeable and adds no enum runtime.
+   *
    * @default 'asConst'
    */
-  enumType?: 'asConst' | 'asPascalConst';
+  type?: 'asConst';
   /**
-   * Suffix appended to the generated type alias name.
+   * Casing of the generated const variable.
+   * - 'camelCase' names the const `vehicleType`.
+   * - 'pascalCase' names the const `VehicleType`, matching the schema name.
    *
-   * Only affects the type alias — the const object name is unchanged.
+   * @default 'camelCase'
+   */
+  constCasing?: EnumConstCasing;
+  /**
+   * Suffix appended to the generated type alias name. Only the type alias is renamed. The const
+   * object name stays the same. Set it to `''` together with `constCasing: 'pascalCase'` to merge
+   * the const and type under the schema's exact name.
    *
    * @default 'Key'
-   * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
+   * @example A custom suffix
+   * `typeSuffix: 'Value'` renames the alias to `PetStatusValue`
    */
-  enumTypeSuffix?: string;
+  typeSuffix?: string;
   /**
    * Choose the casing for enum key names.
    * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
@@ -253,22 +254,24 @@ type EnumTypeOptions = {
    * - 'none' uses the enum value as-is without transformation.
    * @default 'none'
    */
-  enumKeyCasing?: EnumKeyCasing;
+  keyCasing?: EnumKeyCasing;
 } | {
   /**
-   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
-   * - 'enum' generates TypeScript enum declarations.
-   * - 'constEnum' generates TypeScript const enum declarations.
+   * Emit a TypeScript `enum` (`'enum'`) or `const enum` (`'constEnum'`) declaration.
+   *
    * @default 'asConst'
    */
-  enumType?: 'enum' | 'constEnum';
+  type?: 'enum' | 'constEnum';
   /**
-   * `enumTypeSuffix` has no effect for this `enumType`.
-   * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+   * `constCasing` has no effect for this `type`. Only `'asConst'` emits a const object.
    */
-  enumTypeSuffix?: never;
+  constCasing?: never;
   /**
-   * Choose the casing for enum key names.
+   * `typeSuffix` has no effect for this `type`. Only `'asConst'` emits a separate type alias.
+   */
+  typeSuffix?: never;
+  /**
+   * Choose the casing for enum member names.
    * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
    * - 'snakeCase' generates keys in snake_case format.
    * - 'pascalCase' generates keys in PascalCase format.
@@ -276,97 +279,99 @@ type EnumTypeOptions = {
    * - 'none' uses the enum value as-is without transformation.
    * @default 'none'
    */
-  enumKeyCasing?: EnumKeyCasing;
+  keyCasing?: 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).
+   * Emit a union of literals as a named alias (`'literal'`) or inline the union at every usage
+   * site (`'inlineLiteral'`).
+   *
    * @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 = {
+  type?: 'literal' | 'inlineLiteral';
   /**
-   * Specify the export location for the files and define the behavior of the output
-   * @default { path: 'types', barrelType: 'named' }
+   * `constCasing` has no effect for this `type`; literal modes emit no const object.
    */
-  output?: Output;
+  constCasing?: never;
   /**
-   * Define which contentType should be used.
-   * By default, uses the first valid JSON media type.
+   * `typeSuffix` has no effect for this `type`; literal modes emit no separate type alias.
    */
-  contentType?: 'application/json' | (string & {});
+  typeSuffix?: never;
   /**
-   * Group the clients based on the provided name.
+   * `keyCasing` has no effect for this `type`. Literal and inlineLiteral modes emit only values,
+   * so the keys are discarded.
    */
-  group?: Group;
+  keyCasing?: never;
+};
+/**
+ * Where the generated `.ts` files 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: 'types', barrel: { type: 'named' } }
+ */
+type Options = OutputOptions & {
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Switch between type or interface for creating TypeScript types.
-   * - 'type' generates type alias declarations.
-   * - 'interface' generates interface declarations.
+   * Whether object schemas are emitted as `type` aliases or `interface` declarations.
+   * - `'type'` emits closed type aliases. Safer default for generated code.
+   * - `'interface'` emits interfaces. Useful when consumers rely on declaration merging.
+   *
    * @default 'type'
+   * @see https://www.totaltypescript.com/type-vs-interface-which-should-you-use
    */
   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).
+   * How optional properties are written in generated types.
+   * - `'questionToken'` — `type?: string`. The property may be missing.
+   * - `'undefined'` — `type: string | undefined`. Required to exist, may be `undefined`.
+   * - `'questionTokenAndUndefined'` — `type?: string | undefined`. Strictest.
+   *
    * @default 'questionToken'
+   * @note Pick `'questionTokenAndUndefined'` when `exactOptionalPropertyTypes` is on in `tsconfig.json`.
    */
   optionalType?: 'questionToken' | 'undefined' | 'questionTokenAndUndefined';
   /**
-   * Choose between Array<string> or string[] for array types.
-   * - 'generic' generates Array<Type> syntax.
-   * - 'array' generates Type[] syntax.
+   * Syntax used for array types.
+   * - `'array'` — `Type[]`. Shorter.
+   * - `'generic'` — `Array<Type>`. More readable for complex element types.
+   *
    * @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
+   * Rename properties inside `PathParams`, `QueryParams`, and `HeaderParams` types.
+   * Response and request body types are not affected.
+   *
+   * @note Every plugin that touches operation parameters must use the same value.
    */
   paramsCasing?: 'camelcase';
   /**
-   * Define some generators next to the ts generators
+   * Custom generators that run alongside the built-in TypeScript generators.
    */
   generators?: Array<Generator<PluginTs>>;
   /**
-   * Override naming conventions. When a method returns `null` or `undefined`, the preset
-   * resolver (`resolverTs`) is used as fallback.
+   * Override how names and file paths are built for generated symbols.
+   * Methods you omit fall back to the default `resolverTs`. `this` is bound to the
+   * full resolver, so `this.default(name, 'function')` delegates to the built-in
+   * implementation.
    */
   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.
+   * AST visitor applied to each schema or operation node before printing.
+   * Methods you omit fall back to the preset transformer.
    *
-   * @example Remove writeOnly properties from response types
+   * @example Drop writeOnly properties from response types
    * ```ts
    * transformer: {
    *   property(node) {
@@ -377,18 +382,17 @@ type Options = {
    */
   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.
+   * Replace the TypeScript handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * Each handler returns a TypeScript AST node for that schema type. Use `this.transform`
+   * to recurse into nested schema nodes.
    *
-   * @example Override the `date` node to use the `Date` object type
+   * @example Use the JavaScript `Date` object for date schemas
    * ```ts
    * import ts from 'typescript'
    * pluginTs({
    *   printer: {
    *     nodes: {
-   *       date(node) {
+   *       date() {
    *         return ts.factory.createTypeReferenceNode('Date', [])
    *       },
    *     },
@@ -399,16 +403,24 @@ type Options = {
   printer?: {
     nodes?: PrinterTsNodes;
   };
-} & EnumTypeOptions;
+  /**
+   * How OpenAPI enums are represented in the generated TypeScript, and how their names are cased.
+   */
+  enum?: EnumOptions$1;
+};
+type ResolvedEnumOptions = {
+  type: NonNullable<EnumOptions$1['type']>;
+  constCasing: EnumConstCasing;
+  typeSuffix: string;
+  keyCasing: EnumKeyCasing;
+};
 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;
+  group: Group | null;
+  enum: ResolvedEnumOptions;
   optionalType: NonNullable<Options['optionalType']>;
   arrayType: NonNullable<Options['arrayType']>;
   syntaxType: NonNullable<Options['syntaxType']>;
@@ -425,11 +437,10 @@ declare global {
 }
 //#endregion
 //#region src/components/Enum.d.ts
+type EnumOptions = PluginTs['resolvedOptions']['enum'];
 type Props$1 = {
   node: ast.EnumSchemaNode;
-  enumType: PluginTs['resolvedOptions']['enumType'];
-  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
-  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  enum: EnumOptions;
   resolver: ResolverTs;
   key?: string | number | null;
 };
@@ -437,14 +448,17 @@ type Props$1 = {
  * 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.
+ * 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.
+ *
+ * When `constCasing` is `'pascalCase'` and `typeSuffix` is empty, the const and the type
+ * resolve to the same name, which TypeScript merges into a single value+type declaration.
  */
 /**
  * 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
+ * Depending on `enum.type` this may emit:
+ * - A runtime object (`asConst`) plus a `typeof` type alias
  * - A `const enum` or plain `enum` declaration (`constEnum` / `enum`)
  * - A union literal type alias (`literal`)
  *
@@ -453,9 +467,7 @@ type Props$1 = {
  */
 declare function Enum({
   node,
-  enumType,
-  enumTypeSuffix,
-  enumKeyCasing,
+  enum: enumOptions,
   resolver
 }: Props$1): KubbReactNode;
 //#endregion
@@ -468,46 +480,57 @@ type Props = {
    * Created with `printerTs({ ..., nodes: options.printer?.nodes })`.
    */
   printer: ast.Printer<PrinterTsFactory>;
-  enumType: PluginTs['resolvedOptions']['enumType'];
-  enumTypeSuffix: PluginTs['resolvedOptions']['enumTypeSuffix'];
-  enumKeyCasing: PluginTs['resolvedOptions']['enumKeyCasing'];
+  enum: PluginTs['resolvedOptions']['enum'];
   resolver: ResolverTs;
 };
 declare function Type({
   name,
   node,
   printer,
-  enumType,
-  enumTypeSuffix,
-  enumKeyCasing,
+  enum: enumOptions,
   resolver
 }: Props): KubbReactNode;
 //#endregion
 //#region src/generators/typeGenerator.d.ts
-declare const typeGenerator: _$_kubb_core0.Generator<PluginTs, unknown>;
+/**
+ * Built-in generator for `@kubb/plugin-ts`. Emits one TypeScript file per
+ * schema in the spec plus per-operation request, response, and parameter
+ * types. Drop-replace with a custom `Generator<PluginTs>` to change how
+ * TypeScript output is produced.
+ */
+declare const typeGenerator: import("@kubb/core").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.
+ * Canonical plugin name for `@kubb/plugin-ts`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 declare const pluginTsName = "plugin-ts";
 /**
- * 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`.
+ * Generates TypeScript `type` aliases and `interface` declarations from an
+ * OpenAPI spec. The foundation that every other Kubb plugin builds on:
+ * clients, query hooks, mocks, and validators all reference the names this
+ * plugin produces.
  *
  * @example
  * ```ts
- * import pluginTs from '@kubb/plugin-ts'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   plugins: [pluginTs({ output: { path: 'types' }, enumType: 'asConst' })],
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs({
+ *       output: { path: './types' },
+ *       enum: { type: 'asConst' },
+ *       optionalType: 'questionTokenAndUndefined',
+ *     }),
+ *   ],
  * })
  * ```
  */
-declare const pluginTs: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginTs>;
+declare const pluginTs: (options?: Options | undefined) => import("@kubb/core").Plugin<PluginTs>;
 //#endregion
 //#region src/printers/functionPrinter.d.ts
 type FunctionPrinterOptions = {
@@ -552,26 +575,27 @@ type FunctionPrinterOptions = {
 declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) => {
   name: "functionParameters";
   options: FunctionPrinterOptions;
-  transform: (node: ast.FunctionParamNode) => string | null | undefined;
-  print: (node: ast.FunctionParamNode) => string | null | undefined;
+  transform: (node: ast.FunctionParamNode) => string | null;
+  print: (node: ast.FunctionParamNode) => string | null;
 };
 //#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.
+ * Default resolver used by `@kubb/plugin-ts`. Decides the names and file paths
+ * for every generated TypeScript type. Import this in other plugins that need
+ * to reference the exact names `plugin-ts` produces without duplicating the
+ * casing/file-layout rules.
  *
- * The `default` method is automatically injected by `defineResolver` — it uses `camelCase`
- * for identifiers/files and `pascalCase` for type names.
+ * The `default` method is supplied by `defineResolver`. It uses PascalCase for
+ * type names and PascalCase file paths (dotted names become `/`-joined) for files.
  *
- * @example
+ * @example Resolve a type and file name
  * ```ts
- * import { resolver } from '@kubb/plugin-ts'
+ * import { resolverTs } from '@kubb/plugin-ts'
  *
- * resolver.default('list pets', 'type')              // → 'ListPets'
- * resolver.resolveName('list pets status 200')        // → 'ListPetsStatus200'
- * resolver.resolvePathName('list pets', 'file')       // → 'listPets'
+ * resolverTs.default('list pets', 'type')        // 'ListPets'
+ * resolverTs.resolvePathName('list pets', 'file') // 'ListPets'
+ * resolverTs.resolveResponseStatusName(node, 200) // 'ListPetsStatus200'
  * ```
  */
 declare const resolverTs: ResolverTs;