DOM: `Element#matches()` incorrectly narrows types

[Derugon]

🔎 Search Terms

element matches narrow never

🕗 Version & Regression Information

• This changed between versions 5.9.3 and 6.0.3

⏯ Playground Link

https://www.typescriptlang.org/play/?ts=6.0.3#code/CYUwxgNghgTiAEEQBd4iQWxAO2QLngAkAVAWQBkBRTHZAbgCgBCdELXAOgymTAAsQAZwAU8AOTBkY+AEp4AMnloanbrwEjxwYNJlA

💻 Code

declare let element: HTMLElement;
!element.matches( 'dt' ) && element.matches( 'dd' )

🙁 Actual behavior

element.matches( 'dd' ) throws a Property 'matches' does not exist on type 'never' compilation error.

🙂 Expected behavior

element.matches( 'dd' ) does not throw any error.

Additional information about the issue

element.matches( 'dt' ) uses the following overload:

matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];

The return type of element.matches( 'dt' ) is then this is HTMLElementTagNameMap['dt'] that maps to this is HTMLElement.

Since this is HTMLElement:

• When false, the type of element is HTMLElement (not narrowed further).
• When false, the type of element is never.

[MartinJohns]

This is due to this change: microsoft/TypeScript-DOM-lib-generator#2147

A workaround would be to use the string overload: element.matches('dt' as string)

[RyanCavanaugh]

🤖 Thank you for your issue! I've done some analysis to help get you started. This response is automatically generated; feel free to 👍 or 👎 this comment according to its usefulness.

Similar Issues

Here are the most similar issues I found

• (67%) microsoft/typescript#5813: Property 'matches' does not exist on type 'Element'
• (67%) microsoft/typescript#49454: element.matches() can be array of strings

If your issue is a duplicate of one of these, feel free to close this issue. Otherwise, no action is needed.

Possibly Working as Intended

It looks like this behavior might be intentional. Here's what a computer had to say about it.

[nmain]

matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];

Because typeguards are two-sided, this would only be correct if each member of HTMLElementTagNameMap was a structurally distinct subclass, but that's not the case.

[RyanCavanaugh]

The provided repro is a little weird since there's no reason to write code that way, but you could imagine e.g.

declare let element: HTMLElement;
if (element.matches('dt')) {
    // ...
} else {
    // uh oh
    const s: string = element;
}

[voxpelli]

This is due to this change: microsoft/TypeScript-DOM-lib-generator#2147

A workaround would be to use the string overload: element.matches('dt' as string)

That PR didn't ship in TS 6.0, it shipped earlier? So it's either due to something that changed in TS 6.0 or it's been there since before 6.0?

It did apparently first ship in TS 6.0 I was wrong.

[voxpelli]

Proper fix for it (on my phone and about to sleep so can't make PR now but should work):

type SpecificHTMLElementTagNameMap = {
    [K in keyof HTMLElementTagNameMap as HTMLElement extends HTMLElementTagNameMap[K] ? never : K]: HTMLElementTagNameMap[K];
};
type SpecificSVGElementTagNameMap = {
    [K in keyof SVGElementTagNameMap as SVGElement extends SVGElementTagNameMap[K] ? never : K]: SVGElementTagNameMap[K];
};

matches<K extends keyof SpecificHTMLElementTagNameMap>(selectors: K): this is SpecificHTMLElementTagNameMap[K];
matches<K extends keyof SpecificSVGElementTagNameMap>(selectors: K): this is SpecificSVGElementTagNameMap[K];
matches(selectors: string): boolean;

MathML excluded intentionally, it can never work with narrowing as it is now

[Derugon]

The provided repro is a little weird since there's no reason to write code that way

Yes, I'm sorry, the code above was just a small chunk highlighting the issue. The actual use case is a sequence of conditionals, choosing which method to call depending on selector matches, either with a single element name or multiple checks, for example:

declare let element: HTMLElement;
if ( element.matches( 'th[scope=row], th[scope=rowgroup], td.cell-base' ) ) {
	// ok
} else if ( element.matches( 'dt' ) ) {
	// ok
} else if ( element.matches( 'h2, h3, h4, h5, h6, .headline' ) ) {
	// Error: Property 'matches' does not exist on type 'never'
}

[Derugon]

Proper fix for it (on my phone and about to sleep so can't make PR now but should work):

The issue applies when element.matches() on an element: X returns this is X, and not this is Y (with Y != X). For example, this fix would still allow narrowing HTMLTableCellElement to itself:

(playground link)

declare let element: HTMLTableCellElement;
if (element.matches('th')) {
	// ...
} else {
	const id = element.id; // Error: Property 'id' does not exist on type 'never'
}

Below are a few test cases checking for narrowing and this issue (this should compile):

(playground link)

declare const element: Element;
declare const htmlElement: HTMLElement;
declare const htmlTableCellElement: HTMLTableCellElement;

// N1: Element can be narrowed to HTMLElement.
if (element.matches('dt')) {
	const isNarrowed: HTMLElement = element;
}
// E1: HTMLElement should not be narrowed to HTMLElement.
if (!htmlElement.matches('dt')) {
	const isNotNever: typeof htmlElement = new HTMLElement();
}
// N2: HTMLElement can be narrowed to HTMLTableCellElement.
if (htmlElement.matches('td')) {
	const isNarrowed: HTMLTableCellElement = htmlElement;
}
// E2: HTMLTableCellElement should not be narrowed to HTMLTableCellElement.
if (!htmlTableCellElement.matches('th')) {
	const isNotNever: typeof htmlTableCellElement = new HTMLTableCellElement();
}