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

package/dist/index.d.ts

@@ -90,6 +90,87 @@ type ResolverTs = Resolver & OperationParamsResolver & {
    */
   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;
+};
 type Options = {
   /**
    * Specify the export location for the files and define the behavior of the output
@@ -117,37 +198,6 @@ 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.
@@ -218,13 +268,13 @@ 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']>;
@@ -280,6 +330,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>;
 };
 declare function Type({
   name,
@@ -292,7 +348,8 @@ declare function Type({
   enumTypeSuffix,
   enumKeyCasing,
   description,
-  resolver
+  resolver,
+  enumSchemaNames
 }: Props): FabricReactNode;
 //#endregion
 //#region src/generators/typeGenerator.d.ts
@@ -411,6 +468,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>;
 };
 /**
  * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).

package/dist/index.js

@@ -410,8 +410,7 @@ function getEnumNames({ node, enumType, enumTypeSuffix, resolver }) {
 	const resolved = resolver.default(node.name, "type");
 	return {
 		enumName: enumType === "asPascalConst" ? resolved : camelCase(node.name),
-		typeName: ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolved,
-		refName: resolved
+		typeName: ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolved
 	};
 }
 /**
@@ -592,7 +591,7 @@ const printerTs = definePrinter((options) => {
 			ref(node) {
 				if (!node.name) return;
 				const refName = node.ref ? node.ref.split("/").at(-1) ?? node.name : node.name;
-				return createTypeReferenceNode(node.ref ? this.options.resolver.default(refName, "type") : refName, void 0);
+				return createTypeReferenceNode(node.ref && ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix && this.options.enumSchemaNames?.has(refName) ? this.options.resolver.resolveEnumKeyName({ name: refName }, this.options.enumTypeSuffix) : node.ref ? this.options.resolver.default(refName, "type") : refName, void 0);
 			},
 			enum(node) {
 				const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? [];
@@ -692,7 +691,7 @@ const printerTs = definePrinter((options) => {
 });
 //#endregion
 //#region src/components/Type.tsx
-function Type({ name, node, keysToOmit, optionalType, arrayType, syntaxType, enumType, enumTypeSuffix, enumKeyCasing, description, resolver }) {
+function Type({ name, node, keysToOmit, optionalType, arrayType, syntaxType, enumType, enumTypeSuffix, enumKeyCasing, description, resolver, enumSchemaNames }) {
 	const resolvedDescription = description || node?.description;
 	const enumSchemaNodes = collect(node, { schema(n) {
 		const enumNode = narrowSchema(n, schemaTypes.enum);
@@ -707,7 +706,8 @@ function Type({ name, node, keysToOmit, optionalType, arrayType, syntaxType, enu
 		syntaxType,
 		description: resolvedDescription,
 		keysToOmit,
-		resolver
+		resolver,
+		enumSchemaNames
 	}).print(node);
 	if (!output) return;
 	const enums = [...new Map(enumSchemaNodes.map((n) => [n.name, n])).values()].map((node) => {
@@ -864,11 +864,16 @@ const typeGenerator = defineGenerator({
 			group
 		});
 		const params = caseParams(node.parameters, paramsCasing);
+		const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name));
+		function resolveImportName(schemaName) {
+			if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) return resolver.resolveEnumKeyName({ name: schemaName }, enumTypeSuffix);
+			return resolver.default(schemaName, "type");
+		}
 		function renderSchemaType({ node: schemaNode, name, description, keysToOmit }) {
 			if (!schemaNode) return null;
 			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"
@@ -898,7 +903,8 @@ const typeGenerator = defineGenerator({
 				arrayType,
 				syntaxType,
 				resolver,
-				keysToOmit
+				keysToOmit,
+				enumSchemaNames
 			})] });
 		}
 		const paramTypes = params.map((param) => renderSchemaType({
@@ -970,8 +976,13 @@ const typeGenerator = defineGenerator({
 		const mode = getMode(path.resolve(root, output.path));
 		if (!node.name) return;
 		const transformedNode = transform(node, composeTransformers(...transformers));
+		const enumSchemaNames = new Set((adapter.rootNode?.schemas ?? []).filter((s) => narrowSchema(s, schemaTypes.enum) && s.name).map((s) => s.name));
+		function resolveImportName(schemaName) {
+			if (ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && enumTypeSuffix && enumSchemaNames.has(schemaName)) return resolver.resolveEnumKeyName({ name: schemaName }, 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"
@@ -1023,7 +1034,8 @@ const typeGenerator = defineGenerator({
 				optionalType,
 				arrayType,
 				syntaxType,
-				resolver
+				resolver,
+				enumSchemaNames
 			})]
 		});
 	}