English 日本語

TypedCustomEventTarget(tcet).

A strictly typed EventTarget(TypedCustomEventTarget) and related definitions. type, currentTarget and detail fields of event, and addEventListener, removeEventListener and dispatcheEvent of event target are typed based on event definitions.

Only 242 bytes of es format JavaScript code will be generated by static build.

Quick start

npm i tcet

Define event target class that extends TypedCustomEventTarget and give self type and events definition as the value of type parameter. Then, strongly typed definitions including addEventListener or other methods will be defined automatically.

class MyClass extends TypedCustomEventTarget<MyClass, {greeting: string}>{
  fire(){
    // dispatchEvent accepts event type and detail value those defined as the second parameter of TypedCustomEventTarget.
    this.dispatchEvent('greeting', {detail: 'hello'});
  }
}

const mc = new MyClass();
mc.addEventListener('greeting', ({type, currentTarget, detail})=>{
  // type is 'greeting' type. currentTarget is `MyClass` type. detail is `string` type.
  console.log(`${detail}`);
});
mc.fire(); // outputs 'hello'

// `ListenerFor` creates the type of event listener for specific event.
const listener: ListenerFor<MyClass, 'greeting'> = ({detail})=>{
  console.log(`${detail}`);
};
mc.addEventListener('greeting', listener);
mc.removeEventListener('greeting', listener);

Code completion and type hinting

dispatchEvent

addEventListener

ListenerFor

detail field of event

currentTarget field of event

type field of event

Type checking

class MyClass extends TypedCustomEventTarget<MyClass, {greeting: string, foo: void}>{
  fire(){
    this.dispatchEvent("greeting", {detail: "hello"});  // OK
    this.dispatchEvent("greeting", {detail: "hello", cancelable: true});  // OK
    this.dispatchEvent("greeting");  // NG
    this.dispatchEvent("greeting", {});  // NG
    this.dispatchEvent("foo");  // OK
    this.dispatchEvent("foo", {cancelable: true});  // OK
    this.dispatchEvent("foo", {detail: "hello"});  // NG
    this.dispatchEvent("bar");  // NG
    this.dispatchEvent(new Event("greeting", {detail: "hello"}));  // NG
    this.dispatchEvent(new CustomEvent("greeting", {detail: "hello"}));  // NG
    this.dispatchEvent(new TypedCustomEvent("greeting", {detail: "hello"}));  // OK
    this.dispatchEvent(new TypedCustomEvent("greeting", {detail: "hello", cancelable: true}));  // OK
    this.dispatchEvent(new TypedCustomEvent("greeting"));  // NG
    this.dispatchEvent(new TypedCustomEvent("greeting", {}));  // NG
    this.dispatchEvent(new TypedCustomEvent("foo"));  // OK
    this.dispatchEvent(new TypedCustomEvent("foo", {cancelable: true}));  // OK
    this.dispatchEvent(new TypedCustomEvent("foo", {detail: "hello"}));  // NG
    this.dispatchEvent(new TypedCustomEvent("bar"));  // NG
  }
}
const mc = new MyClass();
const gl: ListenerFor<MyClass, "greeting"> = ({detail})=>{
    console.log(detail);
};
const fl: ListenerFor<MyClass, "foo"> = ()=>{};
mc.addEventListener('greeting', gl);  // OK
mc.addEventListener('foo', gl);  // NG
mc.addEventListener('foo', null);  // OK
mc.addEventListener('bar', fl);  // NG

Features

In addition to standard EventTarget or related libraries, tcet has following definitions.

• An base class of event target class TypedCustomEventTarget<T, Events>. This class extends EventTarget. T is the event target class and Events is the definition of events that consists of pairs of event name and detail class. This class has following methods.
  • addEventListener and removeEventListener. These methods add or remove the event listener for specific events. These methods accepts event types and listners like overload method for each event definition. (This technic is also used in other library typescript-event-target)
  • dispatchEvent. This method dispatches specific event. This method accepts event types and options like overload method for each events. Events are defined in Events type as K: D style. K is the event name and D is the type that defines the detail information of event (see example section below for details).
• Typed event class TypedCustomEvent<T, K>. This class extends CustomEvent<D>. T is the event target class and K is the name of an event. This class has following fields.
  • type. The type is K.
  • currentTarget. The type is the event target class T.
  • detail. The type is the detail type of event K. This field is defined by the base class CustomEvent<D>. TypedCustomEvent<T, K> extract D from the definition of T and pass it to D of CustomEvent<D>.

The code added by tcet is only the implementation of dispatchEvent method. Other codes are used for type cheking in compile time and have no effect to generated code by static build.

Example 1

Event definition

interface MyClassEvents{
  notify1: string;
  notify2: number;
}

In this example, notify1 and notify2 are event types, and string and number are types of detail object corresponding to each event types.

EventTarget definition

import { TypedCustomEventTarget } from "tcet";

class MyClass extends TypedCustomEventTarget<MyClass, MyClassEvents>{
  f1(){
    // You can fire event by calling dispatchEvent.
    // This is effectively same as dispatchEvent(new TypedCustomEvent("notify1", {detail: "hello"})).
    // Code completion available from IDE(i.e. VSCode).
    this.dispatchEvent("notify1", {detail: "hello"});
  }
  f2(){
    this.dispatchEvent("notify2", {detail: 100});
  }
}

Receiving events

const mc = new MyClass();
// code completion available from IDE(i.e. VSCode)
mc.addEventListener("notify1", ({currentTarget, detail})=>{
  // The type of currentTarget is MyClass
  console.log(detail); // prints "hello"
});
mc.addEventListener("notify2", ({detail})=>{
  console.log(detail); // prints 100
});

Example 2

EventTarget definition

import { type ListenerFor, TypedCustomEventTarget } from "tcet";

// You can give an event defition inline.
class MyClass extends TypedCustomEventTarget<MyClass, {
  hello: {
    message: string;
  }
}>{
  f1(){
    this.dispatchEvent("hello", {detail: {message: "hello"}});
  }
}

Adding or removing event listener

// You can define event listener independently using ListenerFor type that extract listener type from EventTarget class and event name.
const listner: ListenerFor<MyClass, "hello"> = ({detail: {message}})=>{
  console.log(message);
};
const mc = new MyClass();
mc.addEventListener("hello", listener);
mc.f1();
mc.removeEventListener("hello", listener);

(FYI) Getting type information

type EventsDefinitionOfMyClass = EventsOf<MyClass>; // -> {hello: {message: string}}
type DetailTypeOfHelloEvent = EventDetailOf<MyClass, "hello">; // -> {message: string}