# event-target-shim
[](https://www.npmjs.com/package/event-target-shim)
[](http://www.npmtrends.com/event-target-shim)
[](https://travis-ci.org/mysticatea/event-target-shim)
[](https://codecov.io/gh/mysticatea/event-target-shim)
[](https://david-dm.org/mysticatea/event-target-shim)
An implementation of [WHATWG EventTarget interface](https://dom.spec.whatwg.org/#interface-eventtarget), 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`).
```js
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](https://www.npmjs.com/) to install then use a bundler.
```
npm install event-target-shim
```
Or download from [`dist` directory](./dist).
- [dist/event-target-shim.mjs](dist/event-target-shim.mjs) ... ES modules version.
- [dist/event-target-shim.js](dist/event-target-shim.js) ... Common JS version.
- [dist/event-target-shim.umd.js](dist/event-target-shim.umd.js) ... UMD (Universal Module Definition) version. This is transpiled by [Babel](https://babeljs.io/) for IE 11.
## 📖 Usage
```js
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](https://dom.spec.whatwg.org/#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](https://dom.spec.whatwg.org/#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:
```js
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:
```js
// This has `onabort` property.
class AbortSignal extends EventTarget("abort") {
constructor() {
this.aborted = false
}
}
```
## 📚 Examples
### ES2015 and later
> https://jsfiddle.net/636vea92/
```js
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
```ts
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"`.
```ts
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:
1. Use the third type parameter `"strict"`. This prevents inferring to `dispatchEvent<string>()`.
2. Make the `type` property of event definitions stricter.
```ts
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
> https://jsfiddle.net/522zc9de/
```js
// 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](https://github.com/mysticatea/event-target-shim/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.
![[ICO]](/icons/blank.gif){kind=icon}
![[PARENTDIR]](/icons/back.gif){kind=icon}
![[DIR]](/icons/folder.gif){kind=icon}
![[TXT]](/icons/text.gif){kind=icon}
![[ ]](/icons/unknown.gif){kind=icon}