selectedItem property of Select$ChangeEventParameters should not be optional

[biscimus]

Describe the bug

public async onChangeDimensionType(event: sap.m.Select$ChangeEvent) {
        const selectedItem = event.getParameter("selectedItem"); 
}

TS tells me that selectedItem might be undefined, which is wrong.

Expected behavior
Should return a selected item, as defined by the UI5 API reference.

[nkappler]

This bothers me alot, too, as not only this interface is affected, but virtually every event parameter interfaces members are optional, even when there are always present in practice.

[akudev]

The control metadata has no way to express whether the parameter is always there (or is never null). In particular the Select doesn't specify anything:
https://github.com/UI5/openui5/blob/master/src/sap.m/src/sap/m/Select.js#L522-L524

There is a way to specify by manually adding JSDoc, as it is done here for example. This difference even shows up in the API documentation.

So... all good and just fix the dts-generator to use this information?

Unfortunately not: the generic/generated ones are interpreted as "mandatory" in api.json and hence in the API documentation, which is likely wrong in many cases, as this is just the default and developers have not explicitly specified that the parameter will be always there. Without TypeScript this was not really an issue, now it makes a difference:
Applying the same logic in the dts-generator would mean that many nullable/optional event parameters would be marked as mandatory. As result, the TypeScript compiler would gladly accept code expecting the value to never be null, but at runtime the code will crash in many cases. This is against the purpose of type checking, so we cannot solve it like this.

A cleaner solution would be to err on the safe side for all the generic cases where control developers have not explicitly specified whether the parameter can be null, BUT to identify those cases where additional JSDoc has been written. In those cases we can reasonably assume that the JSDoc is correct (or have it fixed if not).
This would require some adaptations here in dts-generator, plus a change in the JSDoc parser in the OpenUI5 repo, plus explicit JSDoc for the Select's "change" event. And in all others where mandatory event parameters are bothering people, which could be a lot... But this is the direction we are looking into right now.

[codeworrior]

the generic/generated ones are interpreted as "mandatory" in api.json and hence in the API documentation, which is likely wrong in many cases,...

Well, I doubt this "many". IMO, most parameters are meant to be mandatory. Still, it is a valid question how to proceed. Not taking own choices in the dts-generators when the same choice can be taken by the developer in the source code to me seems to be the right direction. But without adjusting those cases where a parameter is indeed optional, we risk to break future code. On the other side, the current state is also not ideal: forcing apps to add noise in the form of optional chaining or additional if statements where they are completely unnecessary, does not improve readability of the app code.

My proposal would be to allow to flag parameters as optional in the metadata (e.g. with a trailing "?" much like in TypeScript and as we do already for interface methods in the JSDoc). The "?" should be used if and only if the parameter can be undefined (or omitted). Any other specifics (e.g. a possible null value) should be expressed in the type string as before (Element | null). Then, we should adjust (let adjust) the metadata for the obviously optional params (see below). For the "to be analyzed" events, I would maintain their names in the .dtsgenrc files and keep the current behavior for them (all params optional).

(see internal changes I50c9aee7d8a4b4aadcd940b0a5ac91a68ef83101 for a preview)

I tried to get some numbers how often event parameters are mandatory and how often they are rather optional. For that, I scanned all fireEvent/fireXYZ methods in the SAPUI5 code base and checked what parameters they provide, compared to the metadata of the event. The result (only for JS code, and only non-private events with metadata):

Count	Event Category
309	No parameters
435	Only mandatory parameters
65	At least one optional param
84	Could not be analyzed with simple static code checks
893	Total

BTW: Besides those numbers, I found surprisingly many undocumented parameters and undocumented events.

Disclaimer: the numbers are the result of a static code check. Even if a parameter is provided according to the code, it still might be null or undefined at runtime (e.g when retrieved via a method call). The numbers therefore can serve only as a rough indicator how event parameters are used. The set of optional parameters, however, is a safe information.

Raw "fire" calls: events-statistics.json
Aggregated summary: events.csv