@kubb/plugin-ts 5.0.0-beta.42 → 5.0.0-beta.64

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { t as __name } from "./chunk-C0LytTxp.js";
-import { Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
 import ts from "typescript";
+import { Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
 import { KubbReactNode } from "@kubb/renderer-jsx/types";
 
 //#region src/printers/printerTs.d.ts
@@ -43,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
@@ -112,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
  * ```
  */
@@ -216,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.
@@ -252,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.
@@ -275,43 +279,37 @@ 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';
+  type?: 'literal' | 'inlineLiteral';
   /**
-   * `enumTypeSuffix` has no effect for this `enumType`.
-   * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+   * `constCasing` has no effect for this `type`; literal modes emit no const object.
    */
-  enumTypeSuffix?: never;
+  constCasing?: never;
   /**
-   * `enumKeyCasing` has no effect for this `enumType`.
-   * Literal and inlineLiteral modes emit only values; keys are discarded entirely.
+   * `typeSuffix` has no effect for this `type`; literal modes emit no separate type alias.
    */
-  enumKeyCasing?: never;
-};
-type Options = {
+  typeSuffix?: never;
   /**
-   * Where the generated `.ts` files are written and how they are exported.
-   *
-   * @default { path: 'types', barrel: { type: 'named' } }
+   * `keyCasing` has no effect for this `type`. Literal and inlineLiteral modes emit only values,
+   * so the keys are discarded.
    */
-  output?: Output;
-  /**
-   * Media type read from the OpenAPI spec when an operation defines several.
-   * Defaults to the first JSON-compatible media type Kubb finds.
-   */
-  contentType?: 'application/json' | (string & {});
-  /**
-   * Split generated files into subfolders based on the operation's tag.
-   */
-  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 & {
   /**
    * Skip operations matching at least one entry in the list.
    */
@@ -370,19 +368,22 @@ type Options = {
    */
   resolver?: Partial<ResolverTs> & ThisType<ResolverTs>;
   /**
-   * AST visitor applied to each schema or operation node before printing.
-   * Methods you omit fall back to the preset transformer.
+   * Macros applied to each schema or operation node before printing.
+   * Callbacks you omit fall back to the preset behavior.
    *
    * @example Drop writeOnly properties from response types
    * ```ts
-   * transformer: {
-   *   property(node) {
-   *     if (node.schema.writeOnly) return undefined
-   *   }
-   * }
+   * macros: [
+   *   {
+   *     name: 'drop-write-only',
+   *     property(node) {
+   *       if (node.schema.writeOnly) return undefined
+   *     },
+   *   },
+   * ]
    * ```
    */
-  transformer?: ast.Visitor;
+  macros?: Array<ast.Macro>;
   /**
    * 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`
@@ -405,16 +406,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 | null;
-  enumType: NonNullable<Options['enumType']>;
-  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>;
-  enumKeyCasing: EnumKeyCasing;
+  enum: ResolvedEnumOptions;
   optionalType: NonNullable<Options['optionalType']>;
   arrayType: NonNullable<Options['arrayType']>;
   syntaxType: NonNullable<Options['syntaxType']>;
@@ -431,11 +440,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;
 };
@@ -443,14 +451,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`)
  *
@@ -459,9 +470,7 @@ type Props$1 = {
  */
 declare function Enum({
   node,
-  enumType,
-  enumTypeSuffix,
-  enumKeyCasing,
+  enum: enumOptions,
   resolver
 }: Props$1): KubbReactNode;
 //#endregion
@@ -474,18 +483,14 @@ 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
@@ -521,7 +526,7 @@ declare const pluginTsName = "plugin-ts";
  *   plugins: [
  *     pluginTs({
  *       output: { path: './types' },
- *       enumType: 'asConst',
+ *       enum: { type: 'asConst' },
  *       optionalType: 'questionTokenAndUndefined',
  *     }),
  *   ],
@@ -531,18 +536,27 @@ declare const pluginTsName = "plugin-ts";
 declare const pluginTs: (options?: Options | undefined) => import("@kubb/core").Plugin<PluginTs>;
 //#endregion
 //#region src/printers/functionPrinter.d.ts
+/**
+ * Renders a {@link ast.TypeExpression} to its TypeScript source.
+ *
+ * - a `string` is a type reference, returned as-is
+ * - an `IndexedAccessType` becomes `objectType['indexType']`
+ * - a `TypeLiteral` becomes `{ key: Type; key?: Type }`
+ *
+ * `transformType` is applied once to the fully rendered type, matching how the
+ * printer wrapped reference types before the `ts.factory` model.
+ */
+declare function renderType(type: ast.TypeExpression, transformType?: (type: string) => string): string;
 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          | Output example                    | Use case                       |
+   * |---------------|-----------------------------------|--------------------------------|
+   * | `declaration` | `id: string, config: Config = {}` | Function parameter declaration |
+   * | `call`        | `id, { method, url }`             | Function call arguments        |
    */
-  mode: 'declaration' | 'call' | 'keys' | 'values';
+  mode: 'declaration' | 'call';
   /**
    * Optional transformation applied to every parameter name before printing.
    */
@@ -553,8 +567,8 @@ type FunctionPrinterOptions = {
   transformType?: (type: string) => string;
 };
 /**
- * Default function-signature printer.
- * Covers the four standard output modes used across Kubb plugins.
+ * Default function-signature printer. Renders a parameter list in one of two modes:
+ * `declaration` for the function signature and `call` for the call arguments.
  *
  * @example
  * ```ts
@@ -585,7 +599,7 @@ declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) =>
  * casing/file-layout rules.
  *
  * The `default` method is supplied by `defineResolver`. It uses PascalCase for
- * type names and PascalCase-with-isFile for files.
+ * type names and PascalCase file paths (dotted names become `/`-joined) for files.
  *
  * @example Resolve a type and file name
  * ```ts
@@ -598,5 +612,5 @@ declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) =>
  */
 declare const resolverTs: ResolverTs;
 //#endregion
-export { Enum, type PluginTs, type PrinterTsFactory, type PrinterTsNodes, type PrinterTsOptions, type ResolverTs, Type, pluginTs as default, pluginTs, functionPrinter, pluginTsName, printerTs, resolverTs, typeGenerator };
+export { Enum, type PluginTs, type PrinterTsFactory, type PrinterTsNodes, type PrinterTsOptions, type ResolverTs, Type, pluginTs as default, pluginTs, functionPrinter, pluginTsName, printerTs, renderType, resolverTs, typeGenerator };
 //# sourceMappingURL=index.d.ts.map