Liskov Substitution checks for overloads behave inconsistently

[TimWolla]

Bug Report

🔎 Search Terms

• liskov
• addEventListener
• overload

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about everything. I've checked the full FAQ.

⏯ Playground Link

Playground link with relevant code

💻 Code

interface FooBarEventMap {
  click: CustomEvent;
}

class FooBarElement extends HTMLElement {

}

interface FooBarElement extends HTMLElement {
  addEventListener<T extends keyof FooBarEventMap>(
    type: T,
    listener: (this: FooBarElement, ev: FooBarEventMap[T]) => any,
    options?: boolean | AddEventListenerOptions,
  ): void;
}

interface HTMLElementTagNameMap {
    "foo-bar": FooBarElement;
}

let one: NodeListOf<Node> = document.querySelectorAll('foo-bar')!;

one.forEach(el => el.addEventListener('click', null));

let two: NodeListOf<Node> = document.querySelectorAll('div')!;

two.forEach(el => el.addEventListener('click', null));

let three: NodeListOf<FooBarElement> = document.querySelectorAll('foo-bar')!;

three.forEach(el => el.addEventListener('click', null));

let four: NodeListOf<HTMLDivElement> = document.querySelectorAll('div')!;

four.forEach(el => el.addEventListener('click', null));

🙁 Actual behavior

An error is reported for the assignment to one.

This is technically correct: FooBarElement is a subtype of HTMLElement which in turn is a subtype of Node. FooBarElement.addEventListener() does not accept all parameters that are accepted by Node.addEventListener(), making this a LSP violation.

However the same is true for HTMLDivElement. The assignment to two is accepted, but as evidenced by the assignment to four, an HTMLDivElement does not actually accept null.

When I duplicate the addEventListener overload to:

interface FooBarElement extends HTMLElement {
  addEventListener<T extends keyof FooBarEventMap>(
    type: T,
    listener: (this: FooBarElement, ev: FooBarEventMap[T]) => any,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener<T extends keyof FooBarEventMap>(
    type: T,
    listener: (this: FooBarElement, ev: FooBarEventMap[T]) => any,
    options?: boolean | AddEventListenerOptions,
  ): void;
}

… both overloads are 100% identical. Then the assignment to one is no longer reported as an error.

🙂 Expected behavior

I would not expect this inconsistent behavior:

• Either both HTMLDivElement and FooBarElement should report an error when assigning to a NodeListOf<Node>, or neither should.
• Adding an additional identical overload should not make the error go away.

Additional context

The real world use case is consuming the WoltLab/d.ts repository with a tsconfig.json that has strict: true configured.

Within that repository there is an element with an incompatible overload in:

https://github.com/WoltLab/d.ts/blob/57f923f03e37885885326bbd622d15b554feb9b5/WoltLabSuite/Core/Element/woltlab-core-dialog.d.ts#L40

and it is registered in global.d.ts in:

https://github.com/WoltLab/d.ts/blob/57f923f03e37885885326bbd622d15b554feb9b5/global.d.ts#L122

Now when attempting to compile a project that has the repository as a dependency, the following error is reported:

node_modules/typescript/lib/lib.dom.d.ts:10535:87 - error TS2344: Type 'HTMLElementTagNameMap[K]' does not satisfy the constraint 'Node'.
  Type 'HTMLInputElement | HTMLElement | WoltlabCoreDialogElement | HTMLDialogElement | WoltlabCoreDialogControlElement | ... 66 more ... | HTMLVideoElement' is not assignable to type 'Node'.
    Type 'WoltlabCoreDialogElement' is not assignable to type 'Node'.
      Types of property 'addEventListener' are incompatible.
        Type '<T extends keyof WoltlabCoreDialogEventMap>(type: T, listener: (this: WoltlabCoreDialogElement, ev: WoltlabCoreDialogEventMap[T]) => any, options?: boolean | ... 1 more ... | undefined) => void' is not assignable to type '(type: string, callback: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions | undefined) => void'.
          Types of parameters 'listener' and 'callback' are incompatible.
            Type 'EventListenerOrEventListenerObject | null' is not assignable to type '(this: WoltlabCoreDialogElement, ev: CustomEvent<any> | CustomEvent<ValidateCallback[]>) => any'.
              Type 'null' is not assignable to type '(this: WoltlabCoreDialogElement, ev: CustomEvent<any> | CustomEvent<ValidateCallback[]>) => any'.

10535     querySelectorAll<K extends keyof HTMLElementTagNameMap>(selectors: K): NodeListOf<HTMLElementTagNameMap[K]>;

[TimWolla]

Related: Is it possible to automatically inherit all overloads of the parent type (i.e. HTMLElement) to add a more specific overload, or do I need to use copy and paste?

[RyanCavanaugh]

Here's a repro that does not need the DOM lib.

interface MyEvent { isEvent: true }
interface MyCustomEvent extends MyEvent {
  detail: any;
}
interface MyEventListenerObject {
  handleEvent(object: MyEvent): void;
}
interface MyEventListener {
  (event: MyEvent): void;
}
type MyEventListenerOrMyEventListenerObject = MyEventListener | MyEventListenerObject;

interface MyNode {
  addEventListener(type: string, callback: MyEventListenerOrMyEventListenerObject): void;
}

interface Demo1Map {
  close: MyCustomEvent;
  another: MyEvent;
}
interface ElementDemo1 {
  addEventListener<T extends keyof Demo1Map>(type: T, listener: (ev: Demo1Map[T]) => any): void;
}

interface Demo2Map {
  click: MyCustomEvent;
}
interface ElementDemo2 {
  addEventListener<T extends keyof Demo2Map>(type: T, listener: (ev: Demo2Map[T]) => any): void;
//addEventListener<T extends keyof Demo2Map>(type: T, listener: (ev: Demo2Map[T]) => any): void;
}

type Is<T, U extends T> = never;
type A = Is<MyNode, ElementDemo1>;
type C = Is<MyNode, ElementDemo2>;

Working hypothesis: The core problem here is that (to avoid combinatorial explosions), when the source signature is overloaded, we take the erased form of the signature's generic constraints, which effectively turns

  addEventListener<T extends keyof Demo2Map>(type: T, listener: (ev: Demo2Map[T]) => any): void;

into

  addEventListener(type: keyof Demo2Map, listener: (ev: Demo2Map[keyof Demo2Map]) => any): void;

This is why the contents of Demo2Map are critical to the repro, since if any of its entries are just MyEvent, then there's no error again -- we're (probably?) doing a questionable subtype reduction here during a contravariant operation, and instead should be doing supertype reduction.

That said, four of us poked at this for an hour and we're still not even sure why | MyEventListenerObject even matters here.

The two likely outcomes are that this is fundamentally unfixable, or after forty hours of debugging, someone might be able to produce a three-line fix. Hard to say until we try.

[TimWolla]

@RyanCavanaugh Thank you. What have I found there 🙈

Do you happen to have a hint about my question in the follow-up comment?

Is it possible to automatically inherit all overloads of the parent type (i.e. HTMLElement) to add a more specific overload, or do I need to use copy and paste?

Our addEventListener definition is actually invalid to my understanding (i.e. we reject valid calls to HTMLElement in our custom element). If I had some syntax to inherit all overloads from HTMLElement["addEventListener"] and then to add my single more specific overload this would likely fix the symptoms of this issue (due to the overload) and at the same time make the definition more correct. I want to avoid copying the original definitions from HTMLElement into every custom element, though.

[RyanCavanaugh]

No, we don't currently have an explicit way to say "all those overloads plus this one", unfortunately. You can do a little bit of tricky via intersection, e.g.

addEventListener: HTMLElement["addEventListener"] & {
  (s: string): void;
}

Note that this operation & is order-sensitive (as are overloads themselves)

[TimWolla]

Thank you. For reference: The following appears to do the trick in our real-world use case. Good you mention that order was important, the new overload needs to come first, because it's more specific:

export interface WoltlabCoreDialogElement extends HTMLElement {
  addEventListener: {
    <T extends keyof WoltlabCoreDialogEventMap>(
      type: T,
      listener: (this: WoltlabCoreDialogElement, ev: WoltlabCoreDialogEventMap[T]) => any,
      options?: boolean | AddEventListenerOptions,
    ): void
  } & HTMLElement["addEventListener"];
}