feat(dts-generator): trust source data for event parameter optionality

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

@@ -42,6 +42,7 @@ export interface Directives {
     deprecatedEnumAliases: {
         [fqn: string]: string;
     };
+    eventsWithAllParamsOptional?: string[];
     forwardDeclarations: {
         [libraryName: string]: ConcreteSymbol[];
     };

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

@@ -103,6 +103,13 @@ export interface Directives {
    * to be listed.
    */
   modulesWithNamedExports: string[];
+
+  /**
+   * Events listed here retain the legacy "all parameters optional" behavior.
+   * Format: "fully.qualified.ClassName:eventName"
+   * Used for events whose parameter optionality has not yet been verified in the source.
+   */
+  eventsWithAllParamsOptional?: string[];
 }
 
 /**
@@ -145,6 +152,7 @@ const defaultOptions: GenerateFromObjectsConfig = {
     overlays: {},
     deprecatedEnumAliases: {},
     modulesWithNamedExports: [],
+    eventsWithAllParamsOptional: [],
   },
   generateGlobals: false,
 };

packages/dts-generator/src/generate.ts

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

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

@@ -49,7 +49,7 @@ function mergeOverlays(
     );
   }
 
-  const mapLikeProperties = new Set(["methods", "properties"]);
+  const mapLikeProperties = new Set(["methods", "properties", "events"]);
 
   function mergeProp(
     obj: { [key: string]: unknown },
@@ -984,7 +984,7 @@ export function fixApiJsons(
 
   // Part 2: add interfaces for settings objects and event parameter objects
   addConstructorSettingsInterfaces(targetLibFixedJson, depsFixedJsons);
-  addEventParameterInterfaces(targetLibFixedJson, depsFixedJsons);
+  addEventParameterInterfaces(targetLibFixedJson, depsFixedJsons, directives);
 
   // Part 3: "fix JSON"
   targetLibFixedJson = _fixApiJson(targetLibFixedJson, directives.badSymbols);

packages/dts-generator/src/utils/json-event-parameter-interfaces.ts

@@ -4,18 +4,20 @@ import {
   ClassSymbol,
   ConcreteSymbol,
   InterfaceSymbol,
+  NestedProperties,
   ObjCallableParameter,
   TypedefSymbol,
   Ui5Event,
 } from "../types/api-json.js";
-const log = getLogger("@ui5/dts-generator/constructor-settings-interfaces");
+const log = getLogger("@ui5/dts-generator/event-parameter-interfaces");
 import { calculateDerivedNames } from "./base-utils.js";
 import {
   addJsDocProps,
   isA,
   makeSettingsNames,
 } from "./json-constructor-settings-interfaces.js";
 import { FunctionType, TypeReference } from "../types/ast.js";
+import { Directives } from "../generate-from-objects.js";
 
 /**
  * Creates for each event in an `EventProvider` subclass an interface that describes the
@@ -40,6 +42,7 @@ function createEventParameterInterfaces(
   symbols: ConcreteSymbol[],
   dependencies: ApiJSON[],
   addDetails: boolean,
+  directives?: Directives,
 ) {
   const typeUniverse = new Map();
 
@@ -71,20 +74,32 @@ function createEventParameterInterfaces(
     };
   };
 
-  function buildProperties(srcProperties) {
+  function buildProperties(
+    srcProperties: NestedProperties,
+    allOptional: boolean,
+    context: string,
+  ) {
     const transformedProperties = [];
     for (let propertyName in srcProperties) {
       const prop = srcProperties[propertyName];
-      transformedProperties.push(
-        addJsDocProps(
-          {
-            name: prop.name,
-            type: prop.type,
-            visibility: "public", // prop.visibility,
-          },
-          prop,
-        ),
+      const transformed = addJsDocProps(
+        {
+          name: prop.name,
+          type: prop.type,
+          visibility: "public", // prop.visibility,
+        },
+        prop,
       );
+      if (!allOptional) {
+        if (prop.optional === false) {
+          transformed.optional = false;
+        } else if (prop.optional !== true) {
+          log.warn(
+            `Event parameter "${prop.name}" in ${context} has no "optional" value; treating as optional.`,
+          );
+        }
+      }
+      transformedProperties.push(transformed);
     }
     return transformedProperties;
   }
@@ -118,7 +133,9 @@ function createEventParameterInterfaces(
           superEvent: superEvents[0],
         };
       } else if (superEvents && superEvents.length > 1) {
-        debugger; // should never happen
+        log.warn(
+          `Multiple events named "${eventName}" found on superclass ${superClassSymbol.name}`,
+        );
       } else {
         // superclass does not have the event -> go up the class hierarchy
         superClassSymbol = nextEventProviderSuperClass(superClassSymbol);
@@ -270,12 +287,12 @@ function createEventParameterInterfaces(
           };
 
           // collect parameters
-          const allParameters =
+          const allParameters: NestedProperties =
             (addDetails &&
               event.parameters &&
               (event.parameters[0] as ObjCallableParameter).parameterProperties
                 ?.getParameters?.parameterProperties) ||
-            [];
+            {};
           const hasParameters = Object.keys(allParameters).length > 0; // remember because elements from allParameters are removed below; if true, then at least somesuperclass has parameters
 
           // search superclasses for same event
@@ -320,7 +337,15 @@ function createEventParameterInterfaces(
           }
 
           // now add the parameters to the interface
-          const parameters = buildProperties(allParameters);
+          const allOptional =
+            directives?.eventsWithAllParamsOptional?.includes(
+              `${symbol.name}:${event.name}`,
+            ) ?? false;
+          const parameters = buildProperties(
+            allParameters,
+            allOptional,
+            `${symbol.name}#${event.name}`,
+          );
           eventParametersInterface.properties = parameters;
           eventParametersInterface.description = `Parameters of the ${symbol.basename}#${event.name} event.`;
           if (event.deprecated) {
@@ -418,9 +443,20 @@ function createEventParameterInterfaces(
 export function addEventParameterInterfaces(
   apijson: ApiJSON,
   dependencies: ApiJSON[],
+  directives?: Directives,
 ) {
   dependencies.forEach((dep) => {
-    createEventParameterInterfaces(dep.symbols, dependencies, false);
+    createEventParameterInterfaces(
+      dep.symbols,
+      dependencies,
+      false,
+      directives,
+    );
   });
-  createEventParameterInterfaces(apijson.symbols, dependencies, true);
+  createEventParameterInterfaces(
+    apijson.symbols,
+    dependencies,
+    true,
+    directives,
+  );
 }