JarCastingevent-target-shim
An implementation of WHATWG EventTarget interface, plus few extensions.
- This provides
EventTargetconstructor 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
eventTarget.addEventListener(type, callback, options)
Register an event listener.
typeis a string. This is the event name to register.callbackis a function. This is the event listener to register.optionsis a boolean or an object{ capture?: boolean, passive?: boolean, once?: boolean }. If this is a boolean, it's same meaning as{ capture: options }.captureis the flag to register the event listener for capture phase.passiveis the flag to ignoreevent.preventDefault()method in the event listener.onceis the flag to remove the event listener automatically after the first call.
eventTarget.removeEventListener(type, callback, options)
Unregister an event listener.
typeis a string. This is the event name to unregister.callbackis a function. This is the event listener to unregister.optionsis a boolean or an object{ capture?: boolean }. If this is a boolean, it's same meaning as{ capture: options }.captureis the flag to register the event listener for capture phase.
eventTarget.dispatchEvent(event)
Dispatch an event.
eventis 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.
protois an object (assuming it's a prototype object). This function defines a getter/setter pair for the event attribute.typeis 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.
typesis 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
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" }))
Typescript
import { EventTarget, defineEventAttribute } from "event-target-shim";
// Define events
type FooEvents = {
hello: CustomEvent
}
type FooEventAttributes = {
onhello: CustomEvent
}
// Define a derived class.
class Foo extends EventTarget<FooEvents, FooEventAttributes> {
// ...
}
// Define `foo.onhello` property's implementation.
defineEventAttribute(Foo.prototype, "hello")
// Register event listeners.
const foo = new Foo()
foo.addEventListener("hello", (e) => {
console.log("hello", e.detail)
})
foo.onhello = (e) => {
console.log("onhello", e.detail)
}
// Dispatching events
foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))
Unfortunately, both FooEvents and FooEventAttributes are needed because TypeScript doesn't allow the mutation of string literal types. If TypeScript allowed us to compute "onhello" from "hello" in types, FooEventAttributes will be optional.
This EventTarget type is compatible with EventTarget interface of lib.dom.d.ts.
To disallow unknown events
By default, methods such as addEventListener accept unknown events. You can disallow unknown events by the third type parameter "strict".
type FooEvents = {
hello: CustomEvent
}
class Foo extends EventTarget<FooEvents, {}, "strict"> {
// ...
}
// OK because `hello` is defined in FooEvents.
foo.addEventListener("hello", (e) => {
})
// Error because `unknown` is not defined in FooEvents.
foo.addEventListener("unknown", (e) => {
})
However, if you use "strict" parameter, it loses compatibility with EventTarget interface of lib.dom.d.ts.
To infer the type of dispatchEvent() method
TypeScript cannot infer the event type of dispatchEvent() method properly from the argument in most cases. You can improve this behavior with the following steps:
- Use the third type parameter
"strict". This prevents inferring todispatchEvent<string>(). - Make the
typeproperty of event definitions stricter.
type FooEvents = {
hello: CustomEvent & { type: "hello" }
hey: Event & { type: "hey" }
}
class Foo extends EventTarget<FooEvents, {}, "strict"> {
// ...
}
// Error because `detail` property is lacking.
foo.dispatchEvent({ type: "hello" })
ES5
// 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 installinstalls dependencies for development.npm testruns tests and measures code coverage.npm run cleanremoves temporary files of tests.npm run coverageopens code coverage of the previous test with your default browser.npm run lintruns ESLint.npm run buildgeneratesdistcodes.npm run watchruns tests on each file change.