@thednp/event-listener
TypeScript icon, indicating that this package has built-in type declarations

2.0.4 • Public • Published

EventListener

Coverage Status ci NPM Version NPM Downloads jsDeliver cypress version typescript version eslint version vite version prettier version

A TypeScript sourced event listener for efficient applications based on the subscribe-publish pattern, less than 900 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

npm i @thednp/event-listener

CDN

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

Use

import * as Listener from '@thednp/event-listener';

// execute a listener once
Listener.on(document, 'DOMContentLoaded', () => {
    console.log('document is now loaded');
  },
  { once: true },
);

// add a listener with `useCapture: false`
function handleMyClick(e: Listener.NativeEvent) {
  if (e.target.tagName === 'button') {
    e.preventDefault();
    e.stopImmediatePropagation();
  }
  console.log('do something else instead');
}
Listener.on(document, 'click', handleMyClick, false);

// remove a listener, `EventListener` will get listener options from registry
Listener.off(document, 'click', handleMyClick);

// add listener to `window`, this listener has no name and cannot be removed
Listener.on(window, 'scroll', () => console.log(window.scrollY));

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

// get element listener registry
const documentClickListeners = Listener.registry['click'].get(document);

// returns
Map(1) {
  Entries(Array) => [
    0: {
      key: handleMyClick() // listener
      value: false // listener options
    }
  ],
  size: 1, // size of the Map
  prototype: [Prototype(Object)]
}

// check if element has listener
if (documentClickListeners && documentClickListeners.has(handleMyClick)) {
  // do something about it
}

// check if a listener is the one you're looking for
if (documentClickListeners) {
  const [eventListener] = documentClickListeners;
  if (eventListener === handleMyClick) {
    // do something about it
  }
}

// get listener options
const myListenerOptions = documentClickListeners && documentClickListeners.get(handleMyClick);

// 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:

import { on, FocusEventHandler } from '@thednp/event-listener';

const handleMyFocus: FocusEventHandler<HTMLInputElement> = (e) => {
  console.log(e)
}

const myInput = document.querySelector('input') || document.createElement('input');
on(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 cypress to open the Cypress console OR npm run test to run the tests in headless mode.

License

EventListener is released under the MIT License.

Package Sidebar

Install

npm i @thednp/event-listener

Weekly Downloads

139,195

Version

2.0.4

License

MIT

Unpacked Size

72.6 kB

Total Files

31

Last publish

Collaborators

  • thednp