event-target-shim

What is event-target-shim?

The event-target-shim npm package provides a cross-platform, shim implementation of the EventTarget interface, allowing developers to use a consistent API for event handling across different environments. It supports the standard addEventListener, removeEventListener, and dispatchEvent methods, along with custom event types. This makes it useful for projects that need to handle events in both browser and non-browser environments, such as Node.js applications or web components.

What are event-target-shim's main functionalities?

Basic Event Handling

This demonstrates how to create an instance of EventTarget, add an event listener for a custom event type, and then dispatch an event of that type. It's the basic usage for handling custom events.

const EventTargetShim = require('event-target-shim');
const myEventTarget = new EventTargetShim();

myEventTarget.addEventListener('customEvent', function(event) {
  console.log(`Received: ${event.type}`);
});

myEventTarget.dispatchEvent(new EventTargetShim.Event('customEvent'));

Using Options for addEventListener

This example shows how to use the `once` option with `addEventListener` to automatically remove the event listener after it has been invoked once, demonstrating the package's support for event listener options.

const EventTargetShim = require('event-target-shim');
const myEventTarget = new EventTargetShim();

myEventTarget.addEventListener('customEvent', function(event) {
  console.log(`Received: ${event.type}`);
}, { once: true });

myEventTarget.dispatchEvent(new EventTargetShim.Event('customEvent'));
myEventTarget.dispatchEvent(new EventTargetShim.Event('customEvent'));

Other packages similar to event-target-shim

eventemitter3

EventEmitter3 is a high-performance event emitter. While event-target-shim mimics the EventTarget interface specifically, EventEmitter3 provides a more general-purpose event handling mechanism. It doesn't follow the browser's EventTarget API as closely but offers a lightweight, fast solution for event management.

wolfy87-eventemitter

Wolfy87's EventEmitter is another alternative for event handling, offering a similar set of functionalities to event-target-shim but with a different API. It provides a more object-oriented approach to event handling, with features like namespaced events, which can be particularly useful in complex applications. Compared to event-target-shim, it might offer more flexibility in certain scenarios but doesn't aim to replicate the EventTarget interface directly.

README

event-target-shim

An implementation of WHATWG EventTarget interface, plus few extensions.

• This provides EventTarget constructor that can inherit for your custom object.
• This provides an utility that defines properties of attribute listeners (e.g. obj.onclick).

import {EventTarget, defineEventAttribute} from "event-target-shim"

class Foo extends EventTarget {
    // ...
}

// Define `foo.onhello` property.
defineEventAttribute(Foo.prototype, "hello")

// Use
const foo = new Foo()
foo.addEventListener("hello", e => console.log("hello", e))
foo.onhello = e => console.log("onhello:", e)
foo.dispatchEvent(new CustomEvent("hello"))

💿 Installation

Use npm to install then use a bundler.

npm install event-target-shim

Or download from dist directory.

• dist/event-target-shim.mjs ... ES modules version.
• dist/event-target-shim.js ... Common JS version.
• dist/event-target-shim.umd.js ... UMD (Universal Module Definition) version. This is transpiled by Babel for IE 11.

📖 Usage

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

// or UMD version defines a global variable:
const {EventTarget, defineEventAttribute} = window.EventTargetShim

EventTarget

https://dom.spec.whatwg.org/#interface-eventtarget

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 a boolean or an object { capture?: boolean, passive?: boolean, once?: boolean }. If this is a boolean, it's same meaning as { capture: options }.
  • 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 the event listener automatically after the first call.

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 a boolean or an object { capture?: boolean }. If this is a boolean, it's same meaning as { capture: options }.
  • capture is the flag to register the event listener for capture phase.

eventTarget.dispatchEvent(event)

Dispatch an event.

• event is a Event object or an object { type: string, [key: string]: any }. The latter is non-standard but useful. In both cases, listeners receive the event as implementing Event interface.

defineEventAttribute(proto, type)

Define an event attribute (e.g. onclick) to proto. This is non-standard.

• proto is an object (assuming it's a prototype object). This function defines a getter/setter pair for the event attribute.
• type is a string. This is the event name to define.

For example:

class AbortSignal extends EventTarget {
    constructor() {
        this.aborted = false
    }
}
// Define `onabort` property.
defineEventAttribute(AbortSignal.prototype, "abort")

EventTarget(types)

Define a custom EventTarget class with event attributes. This is non-standard.

• types is a string or an array of strings. This is the event name to define.

For example:

// This has `onabort` property.
class AbortSignal extends EventTarget("abort") {
    constructor() {
        this.aborted = false
    }
}

📚 Examples

ES2015 and later

https://jsfiddle.net/636vea92/

const {EventTarget, defineEventAttribute} = EventTargetShim

// Define a derived class.
class Foo extends EventTarget {
    // ...
}

// Define `foo.onhello` property.
defineEventAttribute(Foo.prototype, "hello")

// Register event listeners.
const foo = new Foo()
foo.addEventListener("hello", (e) => {
    console.log("hello", e)
})
foo.onhello = (e) => {
    console.log("onhello", e)
}

// Dispatching events
foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))

ES5

https://jsfiddle.net/522zc9de/

// Define a derived class.
function Foo() {
    EventTarget.call(this)
}
Foo.prototype = Object.create(EventTarget.prototype, {
    constructor: { value: Foo, configurable: true, writable: true }
    // ...
})

// Define `foo.onhello` property.
defineEventAttribute(Foo.prototype, "hello")

// Register event listeners.
var foo = new Foo()
foo.addEventListener("hello", function(e) {
    console.log("hello", e)
})
foo.onhello = function(e) {
    console.log("onhello", e)
}

// Dispatching events
function isSupportEventConstrucor() { // IE does not support.
    try {
        new CusomEvent("hello")
        return true
    } catch (_err) {
        return false
    }
}
if (isSupportEventConstrucor()) {
    foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))
} else {
    var e = document.createEvent("CustomEvent")
    e.initCustomEvent("hello", false, false, "detail")
    foo.dispatchEvent(e)
}

📰 Changelog

• See GitHub releases.

🍻 Contributing

Contributing is welcome ❤️

Please use GitHub issues/PRs.

Development tools

• npm install installs dependencies for development.
• npm test runs tests and measures code coverage.
• npm run clean removes temporary files of tests.
• npm run coverage opens code coverage of the previous test with your default browser.
• npm run lint runs ESLint.
• npm run build generates dist codes.
• npm run watch runs tests on each file change.