support conditional ts enums (#2433)

* support conditional ts enums

* simplify enum test

* fix test context pollution

* add changeset

* add baseline test for disabled enums flag

* lint fix

Author: danitt

.changeset/every-roses-tickle.md

@@ -0,0 +1,5 @@
+---
+"openapi-typescript": minor
+---
+
+Conditionally generate TS enums

docs/cli.md

@@ -113,6 +113,7 @@ The following flags are supported in the CLI:
 | `--empty-objects-unknown`          |       | `false`  | Allow arbitrary properties for schema objects with no specified properties, and no specified `additionalProperties` |
 | `--enum`                           |       | `false`  | Generate true [TS enums](https://www.typescriptlang.org/docs/handbook/enums.html) rather than string unions.        |
 | `--enum-values`                    |       | `false`  | Export enum values as arrays.                                                                                       |
+| `--conditional-enums`              |       | `false`  | Only generate true TS enums when the `x-enum-*` metadata is available. Requires `--enum=true` to be enabled.        |
 | `--dedupe-enums`                   |       | `false`  | Dedupe enum types when `--enum=true` is set                                                                         |
 | `--check`                          |       | `false`  | Check that the generated types are up-to-date.                                                                      |
 | `--exclude-deprecated`             |       | `false`  | Exclude deprecated fields from types                                                                                |

packages/openapi-typescript/bin/cli.js

@@ -17,6 +17,7 @@ Options
   --output, -o               Specify output file (if not specified in redocly.yaml)
   --enum                     Export true TS enums instead of unions
   --enum-values              Export enum values as arrays
+  --conditional-enums        Only generate true TS enums when enum metadata is available (default: false)
   --dedupe-enums             Dedupe enum types when \`--enum=true\` is set
   --check                    Check that the generated types are up-to-date. (default: false)
   --export-type, -t          Export top-level \`type\` instead of \`interface\`
@@ -75,6 +76,7 @@ const flags = parser(args, {
     "emptyObjectsUnknown",
     "enum",
     "enumValues",
+    "conditionalEnums",
     "dedupeEnums",
     "check",
     "excludeDeprecated",
@@ -140,6 +142,7 @@ async function generateSchema(schema, { redocly, silent = false }) {
       emptyObjectsUnknown: flags.emptyObjectsUnknown,
       enum: flags.enum,
       enumValues: flags.enumValues,
+      conditionalEnums: flags.conditionalEnums,
       dedupeEnums: flags.dedupeEnums,
       excludeDeprecated: flags.excludeDeprecated,
       exportType: flags.exportType,

packages/openapi-typescript/src/index.ts

@@ -75,6 +75,7 @@ export default async function openapiTS(
     emptyObjectsUnknown: options.emptyObjectsUnknown ?? false,
     enum: options.enum ?? false,
     enumValues: options.enumValues ?? false,
+    conditionalEnums: options.conditionalEnums ?? false,
     dedupeEnums: options.dedupeEnums ?? false,
     excludeDeprecated: options.excludeDeprecated ?? false,
     exportType: options.exportType ?? false,

packages/openapi-typescript/src/transform/schema-object.ts

@@ -98,10 +98,7 @@ export function transformSchemaObjectWithComposition(
     !("additionalProperties" in schemaObject)
   ) {
     // hoist enum to top level if string/number enum and option is enabled
-    if (
-      options.ctx.enum &&
-      schemaObject.enum.every((v) => typeof v === "string" || typeof v === "number" || v === null)
-    ) {
+    if (shouldTransformToTsEnum(options, schemaObject)) {
       let enumName = parseRef(options.path ?? "").pointer.join("/");
       // allow #/components/schemas to have simpler names
       enumName = enumName.replace("components/schemas", "");
@@ -304,6 +301,35 @@ export function transformSchemaObjectWithComposition(
   return finalType;
 }
 
+/**
+ * Check if the given OAPI enum should be transformed to a TypeScript enum
+ */
+function shouldTransformToTsEnum(options: TransformNodeOptions, schemaObject: SchemaObject): boolean {
+  // Enum conversion not enabled or no enum present
+  if (!options.ctx.enum || !schemaObject.enum) {
+    return false;
+  }
+
+  // Enum must have string, number or null values
+  if (!schemaObject.enum.every((v) => ["string", "number", null].includes(typeof v))) {
+    return false;
+  }
+
+  // If conditionalEnums is enabled, only convert if x-enum-* metadata is present
+  if (options.ctx.conditionalEnums) {
+    const hasEnumMetadata =
+      Array.isArray(schemaObject["x-enum-varnames"]) ||
+      Array.isArray(schemaObject["x-enumNames"]) ||
+      Array.isArray(schemaObject["x-enum-descriptions"]) ||
+      Array.isArray(schemaObject["x-enumDescriptions"]);
+    if (!hasEnumMetadata) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 /**
  * Handle SchemaObject minus composition (anyOf/allOf/oneOf)
  */

packages/openapi-typescript/src/types.ts

@@ -658,6 +658,8 @@ export interface OpenAPITSOptions {
   enum?: boolean;
   /** Export union values as arrays */
   enumValues?: boolean;
+  /** Only generate TS Enums when `x-enum-*` metadata is available */
+  conditionalEnums?: boolean;
   /** Dedupe enum values */
   dedupeEnums?: boolean;
   /** (optional) Substitute path parameter names with their respective types */
@@ -695,6 +697,7 @@ export interface GlobalContext {
   emptyObjectsUnknown: boolean;
   enum: boolean;
   enumValues: boolean;
+  conditionalEnums: boolean;
   dedupeEnums: boolean;
   excludeDeprecated: boolean;
   exportType: boolean;

packages/openapi-typescript/test/test-helpers.ts

@@ -15,6 +15,7 @@ export const DEFAULT_CTX: GlobalContext = {
   emptyObjectsUnknown: false,
   enum: false,
   enumValues: false,
+  conditionalEnums: false,
   dedupeEnums: false,
   excludeDeprecated: false,
   exportType: false,