EventListener

A TypeScript sourced event listener for efficient applications based on the subscribe-publish pattern, around 700 bytes when minified and packs a surprising amount of power.

Features

• EventListener is TypeScript sourced, with some types addapted from React;
• EventListener makes use of the native Map to subscribe/register or unsubscribe/remove listeners, which is perfect since we need to make sure the exact listeners are added/removed; this completely invalidates the need to deconstruct function objects for comparison's sake to make sure event listeners are properly handled;
• EventListener allows you to register multiple listeners for the same target, even of the same type, but always uses a single globalListener to call them all at once when event is triggered;
• EventListener "should" be able to manage event options, especially once, meaning that when the option is true, the listener is automatically un-subscribed and detached from target;
• EventListener will unsubscribe and detach listeners with the same options used when attached, which means you can "lazy" remove listeners on the fly.

Install

1pnpm install @thednp/event-listener

1yarn add @thednp/event-listener

1npm install @thednp/event-listener

1deno add npm:@thednp/event-listener@latest

CDN

1<script src="https://cdn.jsdelivr.net/npm/@thednp/event-listener/dist/event-listener.js"></script>

Use

1import * as Listener from '@thednp/event-listener';
2
3// execute a listener once
4Listener.on(document, 'DOMContentLoaded', () => {
5    console.log('document is now loaded');
6  },
7  { once: true },
8);
9
10// add a listener with `useCapture: false`
11function handleMyClick(e: Listener.NativeEvent) {
12  if (e.target.tagName === 'button') {
13    e.preventDefault();
14    e.stopImmediatePropagation();
15  }
16  console.log('do something else instead');
17}
18Listener.on(document, 'click', handleMyClick, false);
19
20// remove a listener, `EventListener` will get listener options from registry
21Listener.off(document, 'click', handleMyClick);
22
23// add listener to `window`, this listener has no name and cannot be removed
24Listener.on(window, 'scroll', () => console.log(window.scrollY));

Since we're implementing Map, you can make use of its prototype to access registry:

1// get element listener registry
2const documentClickListeners = Listener.registry['click'].get(document);
3
4// returns
5Map(1) {
6  Entries => [
7    0: {
8      key: handleMyClick() // listener
9      value: false // listener options
10    }
11  ],
12  size: 1, // size of the Map
13  prototype: [Prototype(Map)]
14}
15
16// check if element has listener
17if (documentClickListeners && documentClickListeners.has(handleMyClick)) {
18  // do something about it
19}
20
21// check if a listener is the one you're looking for
22if (documentClickListeners) {
23  const [eventListener] = documentClickListeners;
24  if (eventListener === handleMyClick) {
25    // do something about it
26  }
27}
28
29// get listener options
30const myListenerOptions = documentClickListeners && documentClickListeners.get(handleMyClick);
31
32// returns false, which is the `useCapture` option value added for `handleMyClick`

Advanced Use

You can also make use of the types for more consistent code:

1import { on, FocusEventHandler } from '@thednp/event-listener';
2
3const handleMyFocus: FocusEventHandler<HTMLInputElement> = (e) => {
4  console.log(e)
5}
6
7const myInput = document.querySelector('input') || document.createElement('input');
8on(myInput, 'focus', handleMyFocus);

For more advanced use, check out the demo, showcasing the EventListener usage with a demo component.

Run the tests suite

• Download the package from Github;
• unpack/unzip and open the folder with your editor;
• open your terminal and navigate to the root of the unpacked folder;
• run npm install or npm update, takes a few minutes to download the Electron browser;
• run npm run test-ui to open the browser mode testing OR npm run test to run the tests in headless mode.

License

EventListener is released under the MIT License.