feat(dts-generator): introduce new directive for modules with named exports (#525)

The new .dtsgenrc option "modulesWithNamedExports" can be an array of
module names for which named exports are generated. For library modules,
this happens automatically, the y don't have to be listed.

The new option is useful for the webcomponent package files created by
ui5-tooling-modules. They should behave similar to library modules.

Author: codeworrior

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

@@ -48,6 +48,7 @@ export interface Directives {
     fqnToIgnore: {
         [fqn: string]: string;
     };
+    modulesWithNamedExports: string[];
     namespacesToInterfaces: {
         [orgNamespace: string]: true | [true] | [true, "keep_original_ns"];
     };

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

@@ -94,6 +94,15 @@ export interface Directives {
   deprecatedEnumAliases: {
     [fqn: string]: string;
   };
+
+  /**
+   * A list of modules (their names w/o the *.js extension) for which named exports
+   * will be generated.
+   *
+   * All `** /library.js` modules automatically use named exports, they don't have
+   * to be listed.
+   */
+  modulesWithNamedExports: string[];
 }
 
 /**
@@ -135,6 +144,7 @@ const defaultOptions: GenerateFromObjectsConfig = {
     fqnToIgnore: {},
     overlays: {},
     deprecatedEnumAliases: {},
+    modulesWithNamedExports: [],
   },
   generateGlobals: false,
 };

packages/dts-generator/src/generate.ts

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

packages/dts-generator/src/js-utils/ui5-metadata.js

@@ -243,6 +243,8 @@ export async function loadDirectives(directivesFiles) {
     forwardDeclarations: {},
     fqnToIgnore: {},
     overlays: {},
+    deprecatedEnumAliases: {},
+    modulesWithNamedExports: [],
   };
   function mergeDirectives(loadedDirectives) {
     Object.keys(loadedDirectives).forEach((key) => {

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

@@ -899,6 +899,23 @@ function markDeprecatedAliasesForEnums(
   });
 }
 
+function markEnumsAsUsingNamedExports(
+  symbols: ConcreteSymbol[],
+  directives: Directives,
+) {
+  const modulesWithNamedExports = new Set(directives.modulesWithNamedExports);
+  symbols.forEach((symbol) => {
+    if (
+      symbol.kind === "enum" &&
+      symbol.module &&
+      symbol.export &&
+      modulesWithNamedExports.has(symbol.module)
+    ) {
+      symbol.useNamedExport = true;
+    }
+  });
+}
+
 function _prepareApiJson(
   json: ApiJSON,
   directives: Directives,
@@ -915,6 +932,7 @@ function _prepareApiJson(
   determineMissingExportsForTypes(json.symbols);
   parseTypeExpressions(json.symbols);
   markDeprecatedAliasesForEnums(json.symbols, directives);
+  markEnumsAsUsingNamedExports(json.symbols, directives);
   if (options.mainLibrary) {
     addForwardDeclarations(json, directives);
     addInterfaceWithModuleNames(json.symbols);

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

@@ -700,7 +700,8 @@ class ModuleBuilder extends ScopeBuilder {
           if (
             !moduleImport.module.endsWith("/library") &&
             exportName != "" &&
-            symbol.kind === "enum"
+            symbol.kind === "enum" &&
+            !symbol.useNamedExport
           ) {
             const defaultFQN = fqn.substring(0, fqn.lastIndexOf("."));
             const defaultImportName =
@@ -1656,7 +1657,7 @@ function buildInterfaceFromObject(ui5Object): Interface {
  */
 function buildEnum(ui5Enum: EnumSymbol) {
   assertKnownProps(
-    ["name", "basename", "properties", "deprecatedAliasFor"],
+    ["name", "basename", "properties", "deprecatedAliasFor", "useNamedExport"],
     ui5Enum,
   );
 
@@ -1668,7 +1669,8 @@ function buildEnum(ui5Enum: EnumSymbol) {
     kind: "Enum",
     name: ui5Enum.basename,
     withValues: true,
-    isLibraryEnum: ui5Enum.module.endsWith("/library"),
+    isLibraryEnum:
+      ui5Enum.useNamedExport || ui5Enum.module.endsWith("/library"),
     deprecatedAliasFor: ui5Enum.deprecatedAliasFor,
     values: _.map(ui5Enum.properties, (prop) =>
       buildVariableWithValue(prop, isStandardEnum),

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

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