feat(dts-generator): allow "esmOnly" in directives and "readonly" props

"esmOnly" can be used as property of entire overlays as well as of
single methods and properties.
An ObjectProperty in api.json or an overlay for it can now be
"readonly".

Author: akudev

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

@@ -52,7 +52,9 @@ export interface Directives {
         [orgNamespace: string]: true | [true] | [true, "keep_original_ns"];
     };
     overlays: {
-        [libraryName: string]: ConcreteSymbol[];
+        [libraryName: string]: (ConcreteSymbol & {
+            esmOnly?: boolean;
+        })[];
     };
     typeTyposMap: {
         [orgType: string]: string;

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

@@ -82,7 +82,7 @@ export interface Directives {
    * mapped to TypeScript and cannot be changed in a compatible way.
    */
   overlays: {
-    [libraryName: string]: ConcreteSymbol[];
+    [libraryName: string]: (ConcreteSymbol & { esmOnly?: boolean })[];
   };
 
   /**
@@ -160,6 +160,7 @@ export async function generateFromObjects(config: GenerateFromObjectsConfig) {
     apiObject,
     actualOptions.dependencyApiObjects,
     actualOptions.directives,
+    actualOptions.generateGlobals,
   );
 
   // Phase 2 - jsonToAst:

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

@@ -630,6 +630,7 @@ function genField(ast: Variable) {
   text += JSDOC(ast) + NL;
   text += applyTsIgnore(ast);
   text += ast.static ? "static " : "";
+  text += ast.readonly ? "readonly " : "";
   text +=
     `${ast.name} : ${ast.type ? genType(ast.type, "property") : "any"}` + NL;
   return text;

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

@@ -31,7 +31,11 @@ const preparedCache = new Map();
  * @param apijson
  * @param directives
  */
-function mergeOverlays(apijson: ApiJSON, directives: Directives) {
+function mergeOverlays(
+  apijson: ApiJSON,
+  directives: Directives,
+  options = { generateGlobals: false },
+) {
   const overlays = directives.overlays && directives.overlays[apijson.library];
   if (overlays == null) {
     return; // no overlays defined
@@ -81,25 +85,36 @@ function mergeOverlays(apijson: ApiJSON, directives: Directives) {
   }
 
   overlays.forEach((overlay) => {
+    // do not generate esm-only symbols if generateGlobals is set
+    if (overlay.esmOnly && options.generateGlobals) {
+      return;
+    }
     log.verbose(`  ${overlay.name}`);
     const symbol = find(overlay.name);
     if (symbol == null) {
       // addition
       apijson.symbols.push(overlay);
       return;
     }
-    // overlay
+    // overlay needs to be merged into existing symbol
     Object.keys(overlay).forEach((prop) => {
       if (prop == "name") {
         return; // ignore name property, it's the 'primary key' and can't be changed
       }
       if (mapLikeProperties.has(prop)) {
-        if (!Array.isArray(symbol[prop])) {
-          symbol[prop] = overlay[prop];
+        // = methods, properties
+        if (!Array.isArray(symbol[prop]) && Array.isArray(overlay[prop])) {
+          symbol[prop] = overlay[prop].filter(
+            (item) => !options.generateGlobals || !item.esmOnly,
+          );
           return;
         }
         const symbolItems: ConcreteSymbol[] = symbol[prop];
         overlay[prop].forEach((overlayItem: ConcreteSymbol) => {
+          if (overlayItem.esmOnly && options.generateGlobals) {
+            // skip esm-only ones in globals mode
+            return;
+          }
           const item = symbolItems.find(
             (symbolItem) =>
               symbolItem.name === overlayItem.name &&
@@ -864,9 +879,9 @@ function markDeprecatedAliasesForEnums(
 function _prepareApiJson(
   json: ApiJSON,
   directives: Directives,
-  options = { mainLibrary: false },
+  options = { mainLibrary: false, generateGlobals: false },
 ) {
-  mergeOverlays(json, directives);
+  mergeOverlays(json, directives, { generateGlobals: options.generateGlobals });
   substituteSapClassInfoTypedef(json);
   convertCoreAndConfigurationIntoANamespace(json, directives);
   moveTypeParametersFromConstructorToClass(json);
@@ -904,10 +919,12 @@ export function fixApiJsons(
   targetLibJson: ApiJSON,
   dependencies: ApiJSON[],
   directives: Directives,
+  generateGlobals?: boolean,
 ) {
   // Part 1: "prepare JSON"
   let targetLibFixedJson = _prepareApiJson(targetLibJson, directives, {
     mainLibrary: true,
+    generateGlobals,
   });
 
   let depsFixedJsons: ApiJSON[] = dependencies.map((depjson) => {

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

@@ -1197,14 +1197,18 @@ const buildNestedTypedefs = _.partialRight(
  * @returns
  */
 function buildVariable(property: ObjProperty): Variable {
-  assertKnownProps(["examples", "name", "type", "value", "optional"], property);
+  assertKnownProps(
+    ["examples", "name", "type", "value", "optional", "esmOnly", "readonly"],
+    property,
+  );
 
   const astNode: Variable = {
     kind: "Variable",
     name: property.name,
     static: property.static === true,
     type: buildType(property.type),
     visibility: property.visibility,
+    readonly: property.readonly === true,
     optional: property.optional === true,
   };
 

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

@@ -257,6 +257,7 @@ export interface ObjProperty {
   export?: string;
   resource?: string;
   visibility?: "public" | "protected" | "private" | "restricted";
+  readonly?: boolean;
   static?: boolean;
   type: string;
   description?: string;

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

@@ -129,6 +129,7 @@ export interface Variable extends AstNode, UI5JSDocs {
   static?: boolean;
   type: Type;
   visibility: UI5Visibility;
+  readonly?: boolean;
   optional: boolean;
 }