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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-ts",
-  "version": "5.0.0-alpha.23",
+  "version": "5.0.0-alpha.24",
   "description": "TypeScript code generation plugin for Kubb, transforming OpenAPI schemas into TypeScript interfaces, types, and utility functions.",
   "keywords": [
     "typescript",
@@ -53,8 +53,8 @@
     "@kubb/react-fabric": "0.15.1",
     "remeda": "^2.33.6",
     "typescript": "5.9.3",
-    "@kubb/ast": "5.0.0-alpha.23",
-    "@kubb/core": "5.0.0-alpha.23"
+    "@kubb/ast": "5.0.0-alpha.24",
+    "@kubb/core": "5.0.0-alpha.24"
   },
   "peerDependencies": {
     "@kubb/react-fabric": "0.15.1"

package/src/components/Enum.tsx

@@ -35,17 +35,12 @@ export function getEnumNames({
 }): {
   enumName: string
   typeName: string
-  /**
-   * The PascalCase name that `$ref` importers will use to reference this enum type.
-   * For `asConst`/`asPascalConst` this differs from `typeName` (which has a `Key` suffix).
-   */
-  refName: string
 } {
   const resolved = resolver.default(node.name!, 'type')
   const enumName = enumType === 'asPascalConst' ? resolved : camelCase(node.name!)
   const typeName = ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolved
 
-  return { enumName, typeName, refName: resolved }
+  return { enumName, typeName }
 }
 
 /**

package/src/components/Type.tsx

@@ -18,6 +18,12 @@ type Props = {
   resolver: PluginTs['resolver']
   description?: string
   keysToOmit?: string[]
+  /**
+   * Names of top-level schemas that are enums.
+   * Used so the printer's `ref` handler can use the suffixed type name (e.g. `StatusKey`)
+   * instead of the plain PascalCase name (e.g. `Status`) when resolving `$ref` enum targets.
+   */
+  enumSchemaNames?: Set<string>
 }
 
 export function Type({
@@ -32,6 +38,7 @@ export function Type({
   enumKeyCasing,
   description,
   resolver,
+  enumSchemaNames,
 }: Props): FabricReactNode {
   const resolvedDescription = description || node?.description
   const enumSchemaNodes = collect<EnumSchemaNode>(node, {
@@ -51,6 +58,7 @@ export function Type({
     description: resolvedDescription,
     keysToOmit,
     resolver,
+    enumSchemaNames,
   })
   const output = printer.print(node)
 

package/src/generators/typeGenerator.tsx

@@ -21,6 +21,17 @@ export const typeGenerator = defineGenerator<PluginTs>({
 
     const params = caseParams(node.parameters, paramsCasing)
 
+    // Build a set of schema names that are enums so the ref handler and getImports
+    // callback can use the suffixed type name (e.g. `StatusKey`) for those refs.
+    const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name!))
+
+    function resolveImportName(schemaName: string): string {
+      if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) {
+        return resolver.resolveEnumKeyName({ name: schemaName } as SchemaNode, enumTypeSuffix)
+      }
+      return resolver.default(schemaName, 'type')
+    }
+
     function renderSchemaType({
       node: schemaNode,
       name,
@@ -39,7 +50,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
       const transformedNode = transform(schemaNode, composeTransformers(...transformers))
 
       const imports = adapter.getImports(transformedNode, (schemaName) => ({
-        name: resolver.default(schemaName, 'type'),
+        name: resolveImportName(schemaName),
         path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
       }))
 
@@ -59,6 +70,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
             syntaxType={syntaxType}
             resolver={resolver}
             keysToOmit={keysToOmit}
+            enumSchemaNames={enumSchemaNames}
           />
         </>
       )
@@ -134,8 +146,19 @@ export const typeGenerator = defineGenerator<PluginTs>({
 
     const transformedNode = transform(node, composeTransformers(...transformers))
 
+    // Build a set of schema names that are enums so the ref handler and getImports
+    // callback can use the suffixed type name (e.g. `StatusKey`) for those refs.
+    const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name!))
+
+    function resolveImportName(schemaName: string): string {
+      if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) {
+        return resolver.resolveEnumKeyName({ name: schemaName } as SchemaNode, enumTypeSuffix)
+      }
+      return resolver.default(schemaName, 'type')
+    }
+
     const imports = adapter.getImports(transformedNode, (schemaName) => ({
-      name: resolver.default(schemaName, 'type'),
+      name: resolveImportName(schemaName),
       path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
     }))
 
@@ -170,6 +193,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
           arrayType={arrayType}
           syntaxType={syntaxType}
           resolver={resolver}
+          enumSchemaNames={enumSchemaNames}
         />
       </File>
     )

package/src/printers/printerTs.ts

@@ -52,6 +52,12 @@ type TsOptions = {
    * Resolver used to transform raw schema names into valid TypeScript identifiers.
    */
   resolver: ResolverTs
+  /**
+   * Names of top-level schemas that are enums.
+   * When set, the `ref` handler uses the suffixed type name (e.g. `StatusKey`) for enum refs
+   * instead of the plain PascalCase name, so imports align with what the enum file actually exports.
+   */
+  enumSchemaNames?: Set<string>
 }
 
 /**
@@ -254,7 +260,17 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         // (e.g. by single-member allOf flatten using the property-derived child name).
         // Inline refs (without $ref) from utils already carry resolved type names.
         const refName = node.ref ? (node.ref.split('/').at(-1) ?? node.name) : node.name
-        const name = node.ref ? this.options.resolver.default(refName, 'type') : refName
+
+        // When a Key suffix is configured, enum refs must use the suffixed name (e.g. `StatusKey`)
+        // so the reference matches what the enum file actually exports.
+        const isEnumRef =
+          node.ref && ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix && this.options.enumSchemaNames?.has(refName)
+
+        const name = isEnumRef
+          ? this.options.resolver.resolveEnumKeyName({ name: refName } as SchemaNode, this.options.enumTypeSuffix!)
+          : node.ref
+            ? this.options.resolver.default(refName, 'type')
+            : refName
 
         return factory.createTypeReferenceNode(name, undefined)
       },

package/src/types.ts

@@ -100,6 +100,92 @@ export type ResolverTs = Resolver &
     resolveHeaderParamsName(node: OperationNode, param: 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' inlines 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
+    }
+
 export type Options = {
   /**
    * Specify the export location for the files and define the behavior of the output
@@ -127,37 +213,6 @@ export type Options = {
    * 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.
@@ -228,14 +283,14 @@ export type Options = {
    * ```
    */
   transformers?: Array<Visitor>
-}
+} & EnumTypeOptions
 
 type ResolvedOptions = {
   output: Output
   group: Group | undefined
   enumType: NonNullable<Options['enumType']>
   enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
-  enumKeyCasing: NonNullable<Options['enumKeyCasing']>
+  enumKeyCasing: EnumKeyCasing
   optionalType: NonNullable<Options['optionalType']>
   arrayType: NonNullable<Options['arrayType']>
   syntaxType: NonNullable<Options['syntaxType']>