Skip to content

Latest commit

 

History

History
248 lines (175 loc) · 9.58 KB

reference.md

File metadata and controls

248 lines (175 loc) · 9.58 KB

📚 API Reference

■ EventTarget

import { EventTarget } from "event-target-shim";
// or
const { EventTarget } = require("event-target-shim");

The HTML Standard: EventTarget interface

▶ constructor

Create a new instance of the EventTarget class.

There are no arguments.

▶ eventTarget.addEventListener(type, callback, options)

Register an event listener.

  • type is a string. This is the event name to register.
  • callback is a function. This is the event listener to register.
  • options is an object { capture?: boolean; passive?: boolean; once?: boolean; signal?: AbortSignal }. This is optional.
    • capture is the flag to register the event listener for capture phase.
    • passive is the flag to ignore event.preventDefault() method in the event listener.
    • once is the flag to remove this callback automatically after the first call.
    • signal is an AbortSignal object to remove this callback. You can use this option as alternative to the eventTarget.removeEventListener(...) method.

▶ eventTarget.removeEventListener(type, callback, options)

Unregister an event listener.

  • type is a string. This is the event name to unregister.
  • callback is a function. This is the event listener to unregister.
  • options is an object { capture?: boolean }. This is optional.
    • capture is the flag to register the event listener for capture phase.

▶ eventTarget.dispatchEvent(event)

Dispatch an event.

  • event is a Event object to dispatch.

■ Event

import { Event } from "event-target-shim";
// or
const { Event } = require("event-target-shim");

The HTML Standard: Event interface

See MDN for details.

■ Event attribute handler

import {
  getEventAttributeValue,
  setEventAttributeValue,
} from "event-target-shim";
// or
const {
  getEventAttributeValue,
  setEventAttributeValue,
} = require("event-target-shim");

Non-standard.

You can define event attributes (e.g. onclick) on your derived classes of EventTarget.

Example

import {
  EventTarget,
  getEventAttributeValue,
  setEventAttributeValue,
} from "event-target-shim";

class AbortSignal extends EventTarget {
  constructor() {
    this.aborted = false;
  }

  // Define `onabort` property
  get onabort() {
    return getEventAttributeValue(this, "abort");
  }
  set onabort(value) {
    setEventAttributeValue(this, "abort", value);
  }
}

■ Error handling

import { setErrorHandler, setWarningHandler } from "event-target-shim";

Non-standard.

You can customize error/wanring behavior of EventTarget-shim.

▶ setErrorHandler(handler)

Set your error handler. The error means exceptions that event listeners threw.

The default handler is undefined. It dispatches an ErrorEvent on window on browsers, or emits an uncaughtException event on process on Node.js.

The first argument of the error handler is a thrown error.

Example

import { setErrorHandler } from "event-target-shim";

// Print log only.
setErrorHandler((error) => {
  console.error(error);
});

▶ setWarningHandler(handler)

Set your warning handler. The warning is reported when EventTarget or Event doesn't throw any errors but ignores operations silently.

The default handler is undefined. It prints warnings with the console.warn method.

The first argument of the warning handler is a reported warning information. It has three properties:

  • code ... A warning code. Use it for i18n.
  • message ... The warning message in English.
  • args ... The array of arguments for replacing placeholders in the message.

The warning handler will be called when...

Code Description
"W01" Event.prototype.initEvent method was called while dispatching. In this case, the method does nothing.
"W02" Event.prototype.cancelBubble setter received a falsy value. In this case, the setter does nothing.
"W03" Event.prototype.returnValue setter received a truthy value. In this case, the setter does nothing.
"W04" Event.prototype.preventDefault method was called or Event.prototype.returnValue setter received a falsy value, but the event was not cancelable. In this case, the method or setter does nothing.
"W05" Event.prototype.preventDefault method was called or Event.prototype.returnValue setter received a falsy value, but that's in a passive listener. In this case, the method or setter does nothing.
"W06" EventTarget.prototype.addEventListener method received a listener that has been added already. In this case, the method does nothing.
"W07" EventTarget.prototype.addEventListener method received a listener that has been added already, and any of passive, once, and signal options are different between the existing listener and the ignored listener. In this case, the new options are abandoned.
"W08" EventTarget.prototype.{addEventListener,removeEventListener} methods received an invalid event listener. In this case, the methods ignore the listener.
"W09" setEventAttributeValue function received an invalid event attribute handler. If that was a primitive value, the function removes the current event attribute handler. Otherwise, the function adopts the listener, but the listener will never be called.

Example

import { setWarningHandler } from "event-target-shim";

// Print log only.
setWarningHandler((warning) => {
  console.warn(warning.message, ...warning.args);
});

■ [TypeScript] Types

The EventTarget and Event classes this package provides are compatible with the EventTarget and Event interfaces in the built-in DOM library of TypeScript. We can assign those each other.

Additionally, the EventTarget and Event classes this package provides have some type parameters.

▶ EventTarget<TEventMap, TMode>

The EventTarget class has two type parameters.

  • TEventMap ... Optional. The event map. Keys are event types and each value is the type of Event class. Default is Record<string, Event>.
    This event map provides known event types. It's useful to infer the event types on addEventListener method.
  • TMode ... Optional. The mode of EventTarget type. This is "standard" or "strict". Default is "standard".
    If this is "standard", the EventTarget<EventMap, "standard"> type accepts unknown event types as well. It follows the standard.
    If this is "strict", the EventTarget<EventMap, "strict"> type accepts only known event types. It will protect the mistakes of giving wrong Event objects. On the other hand, the EventTarget<EventMap, "strict"> type is not compatible to the standard.

Example

type AbortSignalEventMap = {
  abort: Event<"abort">;
};

class AbortSignal extends EventTarget<AbortSignalEventMap> {
  // ....
}

type EventSourceEventMap = {
  close: Event<"close">;
  error: Event<"error">;
  message: MessageEvent;
};

class EventSource extends EventTarget<EventSourceEventMap> {
  // ....
}

type MyEventMap = {
  // ....
};

class MyStuff extends EventTarget<MyEventMap, "strict"> {
  // ....
}

▶ Event<T>

The Event class has a type parameter.

  • T ... Optional. The type of the type property. Default is string.

Example

const e = new Event("myevent");
const t: "myevent" = e.type; // the type of `type` property is `"myevent"`.

▶ getEventAttributeValue<T>(target, type), setEventAttributeValue<T>(target, type, value)

The getEventAttributeValue and setEventAttributeValue functions have a type parameter.

  • T ... The type of the Event class.

Example

type AbortSignalEventMap = {
  abort: Event<"abort">;
};

class AbortSignal extends EventTarget<AbortSignalEventMap> {
  // ....

  get onabort() {
    return getEventAttributeValue<AbortSignalEventMap["abort"]>(this, "abort");
  }
  set onabort(value) {
    setEventAttributeValue<AbortSignalEventMap["abort"]>(this, "abort", value);
  }
}