Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thednp/event-listener
Modern event listener for efficient applications based on the subscribe-publish pattern.
https://github.com/thednp/event-listener
event-listener events javascript javascript-events typescript
Last synced: 2 months ago
JSON representation
Modern event listener for efficient applications based on the subscribe-publish pattern.
- Host: GitHub
- URL: https://github.com/thednp/event-listener
- Owner: thednp
- License: mit
- Created: 2021-01-22T08:48:56.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-06T06:08:24.000Z (4 months ago)
- Last Synced: 2024-10-14T09:04:53.538Z (3 months ago)
- Topics: event-listener, events, javascript, javascript-events, typescript
- Language: TypeScript
- Homepage: https://thednp.github.io/event-listener
- Size: 1.16 MB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## EventListener
[](https://coveralls.io/github/thednp/event-listener)
[](https://github.com/thednp/event-listener/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@thednp/event-listener)
[](http://npm-stat.com/charts.html?package=@thednp/event-listener)
[](https://www.jsdelivr.com/package/npm/@thednp/event-listener)
[](https://www.typescriptlang.org/)
[](https://github.com/eslint)
[](https://prettier.io/)
[](https://vitest.dev/)
[](https://github.com/vitejs)
A TypeScript sourced event listener for efficient applications based on the [subscribe-publish](https://hackernoon.com/do-you-still-register-window-event-listeners-in-each-component-react-in-example-31a4b1f6f1c8) 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](https://caniuse.com/mdn-javascript_builtins_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](https://stackoverflow.com/questions/122102/what-is-the-most-efficient-way-to-deep-clone-an-object-in-javascript) 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
```html
```
## Use
```js
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:
```js
// 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:
```js
import { on, FocusEventHandler } from '@thednp/event-listener';
const handleMyFocus: FocusEventHandler = (e) => {
console.log(e)
}
const myInput = document.querySelector('input') || document.createElement('input');
on(myInput, 'focus', handleMyFocus);
```
For more advanced use, check out the [demo](https://thednp.github.io/event-listener), showcasing the **EventListener** usage with a demo component.
## Run the tests suite
- [Download](https://github.com/thednp/event-listener/archive/refs/heads/master.zip) 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](https://github.com/thednp/event-listener/blob/main/LICENSE).