feat(dts-generator): add special generation for deprecated enums

To improve compatibility with existing code, deprecated enums that are
aliases for new, non-deprecated enums are now generated as a re-export.

 - a directives file (.dtsgenrc) may now contain a map
   `deprecatedEnumAliases` which maps from deprecated enum name to
   the new name
 - when ESM types are generated, such deprecated enums are generated as
   a re-export of the new enum. A re-export preserves both, the type and
   the object nature of the enum.
 - when global types are generated, nothing changed as there's no
   equivalent to the re-export when using namespaces
 - additionally, the type alternative of using literals instead of enum
   values is no longer generated for the return type of a function,
   but it's now also generated for the type aliases, as long as they're
   not used as return type

Author: codeworrior

packages/dts-generator/api-report/dts-generator.api.md

@@ -39,6 +39,9 @@ export interface Directives {
     badInterfaces: string[];
     badMethods: string[];
     badSymbols: string[];
+    deprecatedEnumAliases: {
+        [fqn: string]: string;
+    };
     forwardDeclarations: {
         [libraryName: string]: ConcreteSymbol[];
     };

packages/dts-generator/src/generate-from-objects.ts

@@ -84,6 +84,16 @@ export interface Directives {
   overlays: {
     [libraryName: string]: ConcreteSymbol[];
   };
+
+  /**
+   * If a symbol of kind "enum" is used as key in this map, this enum is a deprecated
+   * alias for another enum, whose name is given as value in the map.
+   * For such deprecated aliases for enums, a different type signature is generated,
+   * see method `genDeprecatedAliasForEnum` in dts-code-gen.ts.
+   */
+  deprecatedEnumAliases: {
+    [fqn: string]: string;
+  };
 }
 
 /**
@@ -124,6 +134,7 @@ const defaultOptions: GenerateFromObjectsConfig = {
     forwardDeclarations: {},
     fqnToIgnore: {},
     overlays: {},
+    deprecatedEnumAliases: {},
   },
   generateGlobals: false,
 };

packages/dts-generator/src/generate.ts

@@ -32,6 +32,7 @@ async function loadDirectives(directivesPaths: string[]) {
     forwardDeclarations: {},
     fqnToIgnore: {},
     overlays: {},
+    deprecatedEnumAliases: {},
   };
 
   function mergeDirectives(loadedDirectives: Directives) {

packages/dts-generator/src/phases/dts-code-gen.ts

@@ -293,7 +293,7 @@ function genExport(_export: Export) {
           exportAsDefault: _export.asDefault,
         });
       case "Enum":
-        if (_export.asDefault) {
+        if (_export.asDefault && !_export.expression.deprecatedAliasFor) {
           // TS does not allow export of enums as default
           // see https://github.com/microsoft/TypeScript/issues/3320
           return (
@@ -559,7 +559,7 @@ function genMethodOrFunction(
   text += ")";
 
   let hasReturnType = ast.returns !== undefined && ast.returns.type;
-  text += `: ${hasReturnType ? genType(ast.returns.type) : "void"}`;
+  text += `: ${hasReturnType ? genType(ast.returns.type, "returnValue") : "void"}`;
 
   return text;
 }
@@ -609,7 +609,7 @@ function genInterfaceProperty(ast: Variable) {
   text += applyTsIgnore(ast);
   text +=
     `${ast.name}${ast.optional ? "?" : ""} : ${
-      ast.type ? genType(ast.type) : "any"
+      ast.type ? genType(ast.type, "property") : "any"
     }` + NL;
   return text;
 }
@@ -626,14 +626,16 @@ function genConstExport(
   if (options.export && options.exportAsDefault) {
     text += JSDOC(ast) + NL;
     text += applyTsIgnore(ast);
-    text += `const ${ast.name} : ${ast.type ? genType(ast.type) : "any"};` + NL;
+    text +=
+      `const ${ast.name} : ${ast.type ? genType(ast.type, "const") : "any"};` +
+      NL;
     text += NL;
     text += `export default ${ast.name};` + NL;
   } else if (options.export) {
     text += JSDOC(ast) + NL;
     text += applyTsIgnore(ast);
     text +=
-      `export const ${ast.name} : ${ast.type ? genType(ast.type) : "any"};` +
+      `export const ${ast.name} : ${ast.type ? genType(ast.type, "const") : "any"};` +
       NL;
   }
   return text;
@@ -648,7 +650,8 @@ function genField(ast: Variable) {
   text += JSDOC(ast) + NL;
   text += applyTsIgnore(ast);
   text += ast.static ? "static " : "";
-  text += `${ast.name} : ${ast.type ? genType(ast.type) : "any"}` + NL;
+  text +=
+    `${ast.name} : ${ast.type ? genType(ast.type, "property") : "any"}` + NL;
   return text;
 }
 
@@ -677,7 +680,7 @@ function genParameter(ast: Parameter) {
     });
     text += "}" + NL;
   } else {
-    text += `: ${ast.type ? genType(ast.type) : "any"}`;
+    text += `: ${ast.type ? genType(ast.type, "parameter") : "any"}`;
   }
 
   return text;
@@ -694,6 +697,10 @@ function genEnum(
     exportAsDefault: false,
   },
 ) {
+  if (options.export && ast.deprecatedAliasFor) {
+    return genDeprecatedAliasForEnum(ast, options);
+  }
+
   let text = "";
   text += JSDOC(ast) + NL;
   text +=
@@ -707,6 +714,38 @@ function genEnum(
   return text;
 }
 
+/**
+ * @param ast
+ * @return
+ */
+function genDeprecatedAliasForEnum(
+  ast: Enum,
+  options: { export: boolean; exportAsDefault?: boolean } = {
+    export: undefined,
+    exportAsDefault: false,
+  },
+) {
+  if (!options.export) {
+    console.error(
+      "deprecated alias is only supported for exported enums",
+      ast,
+      options,
+    );
+    throw new TypeError(
+      `deprecated alias is only supported for exported enums (${ast.name})`,
+    );
+  }
+  let text = "";
+  text += "export {";
+  text += JSDOC(ast) + NL;
+  text +=
+    `${ast.deprecatedAliasFor} as ${options.exportAsDefault ? "default " : ast.name}` +
+    NL;
+  text += "}" + NL;
+
+  return text;
+}
+
 /**
  *
  * @param ast
@@ -731,7 +770,7 @@ function genEnumValue(ast: Variable, withValue = false) {
 function genVariable(ast: Variable) {
   let text = "";
   text += JSDOC(ast) + NL;
-  text += `export const ${ast.name} : ${genType(ast.type)};` + NL;
+  text += `export const ${ast.name} : ${genType(ast.type, "const")};` + NL;
 
   return text;
 }
@@ -781,9 +820,10 @@ function hasSimpleElementType(ast: ArrayType): boolean {
 
 /**
  * @param ast
+ * @param usage Context in which the type is used
  * @returns
  */
-function genType(ast: Type): string {
+function genType(ast: Type, usage: string = "unknown"): string {
   let text;
   switch (ast.kind) {
     case "TypeReference":
@@ -799,49 +839,49 @@ function genType(ast: Type): string {
       if (ast.nullable) {
         text += `|null`;
       }
-      if (ast.isStandardEnum) {
+      if (ast.isStandardEnum && usage !== "returnValue") {
         text = `(${text} | keyof typeof ${ast.typeName})`; // TODO parentheses not always required
       }
       return text;
     case "ArrayType":
       if (hasSimpleElementType(ast)) {
-        return `${genType(ast.elementType)}[]`;
+        return `${genType(ast.elementType, usage)}[]`;
       }
-      return `Array<${genType(ast.elementType)}>`;
+      return `Array<${genType(ast.elementType, usage)}>`;
     case "LiteralType":
       return String(ast.literal);
     case "TypeLiteral":
       return `{${NL}${_.map(ast.members, (prop) => {
         let ptext = "";
         ptext += JSDOC(prop) + NL;
         ptext +=
-          `${prop.name}${prop.optional ? "?" : ""}: ${genType(prop.type)},` +
+          `${prop.name}${prop.optional ? "?" : ""}: ${genType(prop.type, usage)},` +
           NL;
         return ptext;
       }).join("")}}`;
     case "UnionType":
       const unionTypes: string[] = _.map(ast.types, (variantType) => {
         if (variantType.kind === "FunctionType") {
-          return `(${genType(variantType)})`;
+          return `(${genType(variantType, usage)})`;
         }
-        return genType(variantType);
+        return genType(variantType, usage);
       });
       return unionTypes.join(" | ");
     case "IntersectionType":
       const intersectionTypes: string[] = _.map(ast.types, (variantType) => {
         if (variantType.kind === "FunctionType") {
-          return `(${genType(variantType)})`;
+          return `(${genType(variantType, usage)})`;
         }
-        return genType(variantType);
+        return genType(variantType, usage);
       });
       return intersectionTypes.join(" & ");
     case "FunctionType":
       text = "";
       if (!_.isEmpty(ast.typeParameters)) {
         text += `<${_.map(ast.typeParameters, (param) => param.name).join(", ")}>`; // TODO defaults, constraints, expressions
       }
-      text += `(${_.map(ast.parameters, (param) => `${param.name}: ${genType(param.type)}`).join(", ")})`;
-      text += ` => ${ast.type ? genType(ast.type) : "void"}`;
+      text += `(${_.map(ast.parameters, (param) => `${param.name}: ${genType(param.type, "parameter")}`).join(", ")})`;
+      text += ` => ${ast.type ? genType(ast.type, "returnValue") : "void"}`;
       return text;
     case "NativeTSTypeExpression":
       // native TS type expression, emit the 'type' string "as is"

packages/dts-generator/src/phases/json-fixer.ts

@@ -839,6 +839,28 @@ function removeRestrictedMembers(json: ApiJSON) {
   });
 }
 
+/**
+ * The map `deprecatedEnumAliases`, which is part of the directives, can list deprecated enums
+ * for which a special type alias should be generated.
+ *
+ * In this method, the aliases are added to those enums, both as a  marker and as input for
+ * later generation of the alias.
+ *
+ * @param symbols Array of symbols for a library
+ * @param directives Directives for all libraries
+ */
+function markDeprecatedAliasesForEnums(
+  symbols: ConcreteSymbol[],
+  directives: Directives,
+) {
+  const deprecatedEnumAliases = directives.deprecatedEnumAliases;
+  symbols.forEach((symbol) => {
+    if (symbol.kind === "enum" && symbol.name in deprecatedEnumAliases) {
+      symbol.deprecatedAliasFor = deprecatedEnumAliases[symbol.name];
+    }
+  });
+}
+
 function _prepareApiJson(
   json: ApiJSON,
   directives: Directives,
@@ -853,6 +875,7 @@ function _prepareApiJson(
   convertNamespacesIntoTypedefsOrInterfaces(json.symbols, directives);
   determineMissingExportsForTypes(json.symbols);
   parseTypeExpressions(json.symbols);
+  markDeprecatedAliasesForEnums(json.symbols, directives);
   if (options.mainLibrary) {
     addForwardDeclarations(json, directives);
     addInterfaceWithModuleNames(json.symbols);

packages/dts-generator/src/phases/json-to-ast.ts

@@ -391,17 +391,29 @@ class ConvertGlobalsToImports extends ASTVisitor {
       this.#scopeBuilder.topLevelScope as ModuleBuilder
     ).typeUniverse.get(type);
     return (
-      symbolForType != null &&
-      symbolForType["ui5-metadata"] != null &&
-      symbolForType["ui5-metadata"].stereotype === "enum"
+      (symbolForType != null &&
+        symbolForType["ui5-metadata"] != null &&
+        symbolForType["ui5-metadata"].stereotype === "enum") ||
+      (generateGlobals === false &&
+        symbolForType != null &&
+        symbolForType.deprecatedAliasFor &&
+        this._isStandardEnum(symbolForType.deprecatedAliasFor))
     );
   }
-  _visitTypeName(typeName: string, usage: "extends" | "implements") {
+  _visitTypeName(typeName: string, usage: string) {
     return this._import(
       typeName,
       usage !== "extends" && usage !== "implements",
     );
   }
+  _visitEnum(_enum: Enum) {
+    if (_enum.deprecatedAliasFor) {
+      _enum.deprecatedAliasFor = this._visitTypeName(
+        _enum.deprecatedAliasFor,
+        "alias",
+      );
+    }
+  }
   _visitTypeReference(type) {
     if (this.mode !== "type-alias") {
       type.isStandardEnum = this._isStandardEnum(type.typeName);
@@ -1639,7 +1651,10 @@ function buildInterfaceFromObject(ui5Object): Interface {
  * @returns
  */
 function buildEnum(ui5Enum: EnumSymbol) {
-  assertKnownProps(["name", "basename", "properties"], ui5Enum);
+  assertKnownProps(
+    ["name", "basename", "properties", "deprecatedAliasFor"],
+    ui5Enum,
+  );
 
   const isStandardEnum =
     ui5Enum["ui5-metadata"] != null &&
@@ -1650,6 +1665,7 @@ function buildEnum(ui5Enum: EnumSymbol) {
     name: ui5Enum.basename,
     withValues: true,
     isLibraryEnum: ui5Enum.module.endsWith("/library"),
+    deprecatedAliasFor: ui5Enum.deprecatedAliasFor,
     values: _.map(ui5Enum.properties, (prop) =>
       buildVariableWithValue(prop, isStandardEnum),
     ),

packages/dts-generator/src/types/api-json.d.ts

@@ -157,6 +157,7 @@ export type EnumSymbol = SymbolBase & {
   "ui5-metadata"?: {
     stereotype?: "enum";
   };
+  deprecatedAliasFor?: string;
   [k: string]: any;
 };
 /**

packages/dts-generator/src/types/ast.d.ts

@@ -82,6 +82,10 @@ export interface Enum extends AstSymbol, UI5JSDocs {
   values: VariableWithValue[];
   withValues: true;
   isLibraryEnum: boolean;
+  /**
+   * When set, this enum is a deprecated alias for another enum whose name is given by this property
+   */
+  deprecatedAliasFor?: string;
 }
 
 // Other Nodes
@@ -206,7 +210,7 @@ export interface TypeReference {
   typeName: string;
   nullable?: boolean;
   typeArguments?: Type[];
-  isStandardEnum?: boolean;
+  isStandardEnum?: boolean; // only set when generating esm types
 }
 
 export interface TypeLiteral {