Strongly typed custom events

[ashubham]

IMO, If properties are inputs to a Custom element, Custom Events are outputs. Currently properties are first class citizens, they can be annotated via decorators and type checked.

CustomEvents are defined like this:

// my-custom-element.ts

let event = new CustomEvent('my-event', {
      detail: {
        message: 'Something important happened'
      }
    });
this.dispath(event);

You listen on the parent like this

<my-custom-element @my-event=${this.handleMyEvent}></my-custom-element>

When listening for these events on the parent(s), the only source of API knowledge is documentation if it all exists else you are left to reading internal implementation. The types on detail key are not enforced. It will be great if lit-element could implement maybe decorators to annotate custom events emitted by an Element.

[LarsDenBakker]

CustomEvent uses generics, so you can type the detail property with CustomEvent<YourTypeHere>.

You're not limited to using CustomEvent, you can and should create your own events if you're using types:

class MyEvent extends Event {
  ...
}

[chase-moskal]

@ashubham — i use this pattern regularly to attain strongly typed events

import {AuthContext} from "../interfaces.js"

export class UserLoginEvent extends CustomEvent<AuthContext> {
  static eventName = "user-login"

  constructor(detail: AuthContext) {
    super(UserLoginEvent.eventName, {
      detail,
      bubbles: true,
      composed: true
    })
  }
}

[ashubham]

How do you annotate what Events are fired from a Component ? We can annotate properties, I created a decorator for my own use case something like this:

export class MyComponent extends LitElement {
  @property({type: String}) prop: string = '';
  @event<string> myEventName!: (string) => void;

  render() {
    return html`<div @click=${this.onClick}></div>`
  }

  private onClick(e) {
    this.myEventName('my string');
  }

And the implementation of the decorator is something like:

export function event<T>() {
  return (component: LitElement, name) => {
    component[name] = (detail: T) => {
      this.dispatchEvent(new CustomEvent(name, {
        detail, bubbles: true, composed: true
      }));
    }
  }
}

this approach has a couple of problems:

1. Code completion/checking on the consumer side of the component
   <my-component @myEventName=${this.onEvent}></my-component>. Does myEventName exists ? Maybe we can workaround this by using @fires jsdoc comment and using vscode lit plugin.

2. What is the shape of the event triggered ? How do we export the types of the detail ie. the generic T to the consumer of my-component.

[chase-moskal]

i think you're onto a cool idea! this could be an ergonomic improvement over calling this.dispatchEvent directly

i would really like it if we could whip up an @event decorator, however there are so many ways we can go about this

[edit: redacted obsolete chatter now that my next comment is more complete]

👋 chase

[chase-moskal]

hello friend, i was inspired by your idea of an @event decorator, so i made this implementation

event-decorator.ts — this is the event decorator utility

export function dashify(camel: string) {
  return camel.replace(/([a-zA-Z])(?=[A-Z])/g, '$1-').toLowerCase()
}

export type EventDetails<T extends CustomEvent> =
  T extends CustomEvent<infer D> ? D : never

export type Dispatcher<E extends CustomEvent> = (
  options?: CustomEventInit<EventDetails<E>>
) => void

export function dashifyEventName(EventClass: Function) {
  const dashed = dashify(EventClass.name)
  const result = /^(.*)-event$/i.exec(dashed)
  return result ? result[1] : dashed
}

export function prepareEventDecorator(
  fallbackOptions: CustomEventInit = {}
) {
  return function event<E extends CustomEvent>(
    EventClass: new(...args: any[]) => E,
    name2?: string,
  ): PropertyDecorator {
    const name = name2 || dashifyEventName(EventClass)
    return (target, key) => {
      target[key] = <any>function(this, options = {}) {
        this.dispatchEvent(new EventClass(
          name,
          {...fallbackOptions, ...options}
        ))
      }
    }
  }
}

export const event = prepareEventDecorator()

events.ts — this is how i create my event classes

import {AuthContext, Profile} from "./interfaces.js"
import {
  Dispatcher,
  dashifyEventName,
  prepareEventDecorator,
} from "./event-decorator.js"

// here i export my own event decorator
// configured with my own defaults
// (otherwise the browser defaults to false and false)
export const event = prepareEventDecorator({
  bubbles: true,
  composed: true
})

// the event names are derived directly from the class names
// by converting camel case to dashes
// so "UserLoginEvent" becomes "user-login" automatically,
// this is good for maintenence so there is a single source of truth for the event names
// which can be easily refactored in an ide
export class UserLoginEvent extends CustomEvent<AuthContext> {}
export class UserLogoutEvent extends CustomEvent<{}> {}
export class ProfileLoadedEvent extends CustomEvent<Profile> {}

export {Dispatcher, dashifyEventName}

user-panel.ts

import {LitElement} from "lit-element"
import {
  event,
  Dispatcher,
  UserLoginEvent,
  UserLogoutEvent,
} from "./events.js"

export class UserPanel extends LitElement {
  @event(UserLoginEvent) dispatchUserLogin: Dispatcher<UserLoginEvent>
  @event(UserLogoutEvent) dispatchUserLogout: Dispatcher<UserLogoutEvent>

  private async _login() {
    const authContext = await this._doAuthStuff()
    this.dispatchUserLogin({detail: authContext})
     //                         ↑
     //             (detail object is correctly typed based on the event)
  }

  private async _logout() {
    await this._clearAuthStuff()
    this.dispatchUserLogout()
  }
}

it took me awhile to brain my way through the typings for the decorator to infer correctly, thankfully with the help of some fine folks on my twitch stream

• declaring the property type as Dispatcher<CustomEvent<Detail>> allows the typings to flow through to the calling of the dispatcher function, thus that the detail type must be correct
• you can also specify an event name while using the event decorator, if you don't want to use the auto-generated dashed name: @event(UserLoginEvent, "my-login-event") dispatchLogin: Dispatch<UserLoginEvent>
• you can also specify other EventInit options for each dispatch call like this: this.dispatchUserLogin({detail: authContext, bubbles: true, composed: true})

i've implemented this in my open source auth software i'm working on: https://github.com/chase-moskal/authoritarian-client/blob/refactor/source/toolbox/event-decorator.ts

let me know what you think, cheers!

👋 chase

[chase-moskal]

a friend of mine just suggested a cool idea

we should also make a property decorator to whip up event handlers that get automatically attached and removed upon connectedCallback and disconnectedCallback

class MyComponent extends LitElement {
  @listener(["scroll", "resize", MySizingEvent]) handleResize = event => {
    console.log("blah")
  }
}

i believe it will require a class decorator to mixin the functionality to make it work

i'm interested to create a publish these ideas to a library soon, i'd love to hear if anybody has any alternative approaches

👋 chase

[chase-moskal]

i've just made an implementation in a new repository that i'm pretty stoked about

with only two decorators, @event and @listener, we can declare, dispatch, and listen for events on our web components

• mega-robot.ts example component declares and dispatches events
  • using @bubblingEvent decorator
• robot-vizualizer.ts example component listens for events
  • using @listener decorator
  • automatically adds/removes event listeners when component is connected/disconnected
  • replaces the listener property with an object containing:
    • this._handleRobotSelfAware.handler: actual handler
    • this._handleRobotSelfAware.remove(): function to remove handler manually
    • this._handleRobotSelfAware.add(): function to add handler manually

each decorator takes, as a second argument, an optional options object

i'm glad i was able to avoid needing to implement a class mixin for this, making it work with two decorators rather than three

once i come up with a better name than eventatarian, i'm going to publish this to npm

now it's time for breakfast, cheers!

👋 chase

[ashubham]

@chase-moskal thanks for the effort. I think in the examples, we should define and export events from the component itself. The consumer can then import it from the component itself.

However, this does not address the requirement of being able to typecheck it on the consumer side.

render() {
  html`<mega-robot @robot-self-aware=${this.handleRobotSelfAware}></mega-robot>`;
}

handleRobotSelfAware(e: <What type to put here?>) {
 // ...
}

[chase-moskal]

@ashubham

unfortunately, with the way typescript works, we cannot export the event types directly from the component itself, however,

for your case, to gain the typings you want, you should define/use custom event classes, like this:

export interface RobotAwareness {
  level: number
}

export class RobotSelfAwareEvent extends CustomEvent<RobotAwareness> {}

then you can use the event types in your handlers, like this:

private _handleRobotSelfAware = (event: RobotSelfAwareEvent) => {
  console.log(event.level)
}

i went to great lengths to accomplish as much automatic type inference as possible, and i think the patterns here and in my example repo represent the best we can do on this front

i'm quite pleased with the results, and will begin implementing these patterns in my work tomorrow

sometime soon, i'll be publishing the decorator library to npm, and writing a readme to explain the best practices

let me know and i'd be happy to chat further about this with you on discord or on my twitch stream, cheers!

👋 chase

[chase-moskal]

i've renamed and published the package as "event-decorators"

[justinfagnani]

I want to chime in, since this thread has been going on for a while...

Events are unlike properties in that they don't have a standard class-member representation. So there's nothing for TypeScript to be able to read statically from the element definition to determine what events are fired and what their types are.

However, JSDoc has the @fires tag and @event tag which can be used to tell documentation generators about the events. I think they need a little modernization to use them with DOM events however.

TypeScript also has the ElementEventMap which associates event names with types. This is unfortunately global, but it can help for type-checking with addEventListener(). You add an event type to it like you add a custom element type to HTMLElementTagNameMap:

interface ElementEventMap {
    'my-event': MyEvent;
}

Event decorators are interesting, but I personally don't see the need for creating event listener properties when we have the more general addEventListener and dispatchEvent methods. Given that we want to 1) keep LitElement as small as possible, and 2) support TypeScript transforms that completely compile out decorators (transform them to plain class members), I wouldn't want to add more decorators to the core lit-element package.

Great conversation however, and a really good area for various community opinions and add-ons. I'll close this for now.

[chase-moskal]

I personally don't see the need for creating event listener properties when we have the more general addEventListener and dispatchEvent methods

i previously found myself doing a lot of boilerplate addEventListener and removeEventListener in connectedCallback and disconnectedCallback, and the decorators can help cut down on the noise

there isn't much benefit over perceived readability if it floats your boat ⛵

cheers!

👋 chase

[justinfagnani]

i previously found myself doing a lot of boilerplate addEventListener and removeEventListener in connectedCallback and disconnectedCallback

Why the removeEventListener in disconnectedCallback? I find adding host listeners in the constructor to be just fine:

class MyElement extends HTMLElement {
  constructor() {
    super();
    this.addEventListener('click', this._onClick);
  }

  _onClick = (e) => {
    console.log('click', this);
  };
}

[chase-moskal]

Why the removeEventListener in disconnectedCallback? I find adding host listeners in the constructor to be just fine

that's a great question! i suppose for host listeners, that's perfectly reasonable, as i imagine when elements are disconnected, all attached listeners become irrelevant/forgotten

however removing event listeners in disconnectedCallback is important when the event target is anything else, like window — or at least this is what i assume, i don't suppose the browser knows to remove the correct window event listeners when a web component is disconnected? (that would be some unexpected funky magic in my estimation)

at the moment, my use-case happens to involve several components that are interacting in a decoupled way via events that bubble up to the window

i also happen to like what the decorators do for the readability of the components — visually the @listener decorators are very clear, and leave only one relevant spot for each listener (rather than two like with _onClick versus addEventListener) — the @event decorators are also a nice self-documenting visual aid

in my event-decorators library, for the case of lit-element, i wonder if it makes sense to add the listeners in firstUpdated instead of connectedCallback, such that the event target could be a property that was assigned via <x-lol .eventTarget=${myTarget}>.. perhaps i could add a string option for which callback gets hitched.. and add @litListener for that purpose.. hmm, food for thought!

👋 chase

[difosfor]

Interesting!

You don't have to modify the global ElementEventMap to add support for your custom event types. I'm currently using this approach: https://gist.github.com/difosfor/ceeb01d03a8db7dc68d5cd4167d60637

I like the idea of adding support for strongly typed custom events to LitElement, particularly using decorators. Ideally I'd also like other tooling like web-component-analyzer and VS Code lit-plugin to use the type information and descriptions instead of requiring me to additionally document the events using @fires tags.

The search for a fully functional typed custom element approach continues.. 😉
Please ping me if you have any further suggestions!