TS 5.4.5: Return type for performance.getEntriesByType is inaccurate

[lll000111]

⚙ Compilation target

ESNexr

⚙ Library

lib.dom.d.ts

Missing / Incorrect Definition

The return type for getEntriesByType is a union of many different object types. A list can be seen in the spec, or at https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry ("The PerformanceEntry instances will always be one of the following subclasses:: [List of possibel sub-classes]")

The return type can - and I think should - be hard-coded for the respective string parameter to getEntriesByType, since there is a limited short list of possible string constants, and each corresponds exactly to one possible return type. Maybe an overloaded definition for this function?

Right now the return type is set to PerformanceEntryList, which is PerformanceEntry[], and that type is an interface with only the minimal number of entries.

The effect is that when I use, for example, performance.getEntriesByType('navigation'), I get a TypeScript error trying to access the properties on the PerformanceNavigationTiming array I get from that query.

Sample Code

Playground Link

function pageWasRealoaded(): boolean {
    return performance
        .getEntriesByType('navigation')
        // Error: TS2339: Property type does not exist on type PerformanceEntry
        // This is wrong, because this is a PerformanceNavigationTiming object
        .some(entry => entry.type === 'reload');
}

Documentation Link

https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry

[heysujal]

Ryan Cavanaugh (@RyanCavanaugh) I would like to dive deep into this issue and work on it. I am new to contributing to this project.

[heysujal]

TypeScript/tests/lib/lib.d.ts

Line 12203 in cde45aa

interface Performance {

I think I need to make changes here, but what do I need to do?

[lll000111]

I think I need to make changes here, but what do I need to do?

I would use function signature overloads. That's just a bunch of different function header definitions for the same function, describing different combinations of parameters and return type for the same function.

Define one signature-overloaded function for every single type string - see here for the list of string constants and what object type is returned for each - and add the respective return type for that particular input string constant.

That's 14 (if I counted right) lines of one function header definition for each combination of string constant and return object.

I like function signature overloads the most because there is no magic, and they are far more readable than "type magic" stuff. What you see is what you get, it's plainly written, no type calculations and variables/type parameters/generics, or ifs or tertiaries, or indexed access into some helper interface type or whatever.

Apparently you can just write multiple method entries into the interface? Type demo: Playground Link -- I demoed it for one item. You may have to create the interfaces vor the various return objects too, at a glance I did not see e.g. "PerformanceElementTiming" declared yet. I think they all inherit from "PerformanceEntry" (so that inheritance needs to be added to each of the new object interfaces too), which is already defined.

Estimated effort: About half an our of pure typing and opening of MDN pages for each return object type, and checking, little need for thinking. I think.

[fahmij8]

Temporarily I just do entry as PerformanceNavigationTiming

[RyanCavanaugh]

performance.getEntriesByType("navigation") returns navigation timing entries at runtime, but the declaration still types them as PerformanceEntry[]. TypeScript 5.4.5 and the current native compiler both report TS2339 on entry.type.

// Expected: The callback entry is a PerformanceNavigationTiming.
// Actual: TS2339 reports that PerformanceEntry has no `type` property.
performance.getEntriesByType('navigation').some((entry) => entry.type === 'reload');

The DOM declaration should preserve the known result type for the literal "navigation" argument while retaining the general string overload.