Associate HTML Elements and EventMaps in a map

[waynevanson]

Search Terms

• dom.d.ts
• eventmap

Suggestion

Create a "map" that pairs HTMLElement with it's relevant EventMap types.

We can infer a tagName from a HTMLElement and visa-versa, from the HTMLElementTagNameMap type.

type GetHTMLElementByTagName<
  K extends keyof HTMLElementTagNameMap
> = HTMLElementTagNameMap[K];

type GetTagNameByHTMLElement<
  E extends HTMLElementTagNameMap[keyof HTMLElementTagNameMap]
> = {
  [P in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[P] extends E
    ? P
    : never;
}[keyof HTMLElementTagNameMap];

But there is currently no way with Typescript's type system to infer what the event map of an element is from the existing types in dom.d.ts.

interface HTMLElement  extends ... {

// ...
// how to extract type HTMLElementEventMap from keyof HTMLElementEventMap?
  addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
// ...

Use Cases

It would be nice to create our own versions of [element].(add|remove)EventListener(). For the drag and drop library sortablejs, we expose a helper that is [element].(add|remove)EventListener() that assigns the capture value based on the browser.

function off(el, event, fn) {
  el.removeEventListener(event, fn, captureMode());
}

Unfortunately, I cannot infer the event and fn function parameters from the element el with generics.

Examples

All these other "map" implementations are string <-> Type pairs using an interface, where as we'll need Type <-> Type pairs.

// dom.d.ts
interface HTMLElementTagNameMap {
    "a": HTMLAnchorElement;
    "abbr": HTMLElement;
    "address": HTMLElement;
    "applet": HTMLAppletElement;
    // ...
}

Here is the janky work around I've come up with so far. You can see more in dom-ts. I figured many other users would want this, which is why I've created this issue.

// helper
export type CreateElementMeta<R extends string, E extends Element, A extends ElementEventMap> = {
  _tagName: R
  _element: E
  _eventMap: A
}

// creating every type.. this is an example of one.
export type HTMLFormElementMeta = CreateElementMeta<
  "form",
  HTMLFormElement,
  HTMLFrameSetElementEventMap
>

// Union of ALL these meta types
type AllElementMeta = HTMLFormElementMeta | HTML[Name]Element //...

// helper for matching types, in this case
//  filtering out mismatched tagNames

export type MatchTagName<R extends string> = AllElementMeta extends infer T
  ? T extends CreateElementMeta<R, infer E, infer A>
    ? CreateElementMeta<R, E, A>
    : never
  : never


// using said types on document.creatElement
declare function createElement<
  K extends meta.AllElementMeta["_tagName"],
  L extends meta.AllElementMeta["_tagName"]
>(
  tagName: K,
  options: { is: L }
): meta.MatchTagName<K>["_element"] & meta.MatchTagName<L>["_element"]

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Side Notes

• This is a breaking change, but unsure how it could be handled elegantly since Typescript doesn't follow the semantic versioning specification.
• There are some missing events like pointermove on HTMLElement. These should be updated. I'll post a new issue unless advised otherwise.
• Users using custom elements and custom events need a way to insert their own Element <-> EventMap pairs. This would probably be done by append their types to the global namespace.

[std4453]

I found this: https://stackoverflow.com/a/62010854/3871776

[waynevanson]

@std4453 Related but doesn't solve the problem of inferring the event map from the type.

[leokang94]

How about this? (most of inspiration from @std4453's shared thing.)

// I only use the 3 types most of the time, so...
type DOMEventMapDefinitions = [
  [HTMLElement, HTMLElementEventMap],
  [Window, WindowEventMap],
  [Document, DocumentEventMap],
];

type DOMEventSubscriber = DOMEventMapDefinitions[number][0];
type MapDefinitionToEventMap<D extends { [K: number]: any[] }, T> = {
  [K in keyof D]: D[K] extends any[]
    ? T extends D[K][0]
      ? D[K][1]
      : never
    : never;
}[number];

type GetEventMapFromByElement<T extends DOMEventSubscriber> =
  MapDefinitionToEventMap<DOMEventMapDefinitions, T>;

// usage
function customAddEventListener<
  Element extends DOMEventSubscriber,
  Type extends keyof GetEventMapFromByElement<Element> & string,
  Event extends GetEventMapFromByElement<Element>[Type]
>(element: Element, eventType: Type, listener: (event: Event) => any, options?: boolean | AddEventListenerOptions) {
  element.addEventListener(eventType, listener as EventListener, options);
}

playground

[waynevanson]

I think the goal of this discussion shouldn't be "let's explore workarounds", but more towards "let's add the capability into Typescript or the types themselves". We already have workarounds.