Control event groups
This module lets you group event listeners so you can separate/isolate listeners from other listeners, such that you can call removeAllListeners and it will only remove the listeners on the current event wrapper. No need to keep track of specific groups of listeners when this can do it for you.
If you have an EventEmitter which has important event listeners on it, and you have a module that you want others to use without them removing those said event listeners by mistake, then this will let you protect them by exporting the wrapped EventEmitter instead of the main one.
Or, in the case of why I needed this module, I have portions of my applications as reloadable, and each time some code unloads, I have the events on a wrapper that I simply remove the listeners from without effecting other parts of my application.
Install via NPM: with the NPM package
npm install eventemitter-wrapper
Install via NPM from Github: with a GitHub Tag to specify version (specifed as #hash)
npm install jashepp/eventemitter-wrapper#v2.0.1
Or download the latest release, or use github packages, or git clone the repository on GitHub.
This module is written with ES6 features.
This module is available as both CommonJS and ES Module. The ES Module calls the CommonJS file under the hood.
Require or import the module, wrap an existing EventEmitter instance, and use methods as you usually would.
This should behave like the original EventEmitter, with the same methods and functionality, since it wraps it and uses it under the hood.
CommonJS Method:
const EventEmitter = require('node:events');
const EventEmitterWrapper = require('eventemitter-wrapper');
const events = new EventEmitter();
const eventsWrapped = new EventEmitterWrapper(events);
// ...ES Module Method:
import { EventEmitter } from 'node:events';
import { EventEmitterWrapper } from 'eventemitter-wrapper';
const events = new EventEmitter();
const eventsWrapped = new EventEmitterWrapper(events);
// ...The passed argument for EventEmitterWrapper can be any object that is an EventEmitter directly or prototyped.
The old v1.0 method of creating the wrapped EventEmitter is still available:
const eventsWrapped = EventEmitterWrapper.createWrapper(events);API for the wrapped instance created via new EventEmitterWrapper(events);
Only eventEmitter is new, along with unlisted internal methods & properties.
| Method / Property | Type | Notes |
|---|---|---|
eventEmitter |
prop | Original EventEmitter |
addListener(eventName,listener) |
method | Listens on original & wrapped |
on(eventName,listener) |
method | Listens on original & wrapped |
once(eventName,listener) |
method | Listens on original & wrapped |
prependListener(eventName,listener) |
method | Listens on original & wrapped |
prependOnceListener(eventName,listener) |
method | Listens on original & wrapped |
rawListeners(eventName) |
method | Lists only wrapped listeners |
listeners(eventName) |
method | Lists only wrapped listeners |
listenerCount(eventName[,listener]) |
method | Counts only wrapped listeners |
eventNames() |
method | Lists only wrapped listeners |
emit(eventName[,...args]) |
method | Directly calls original method |
removeAllListeners([eventName]) |
method | Removes only wrapped listeners |
removeListener(eventName,listener) |
method | Removes on both original & wrapped |
off(eventName,listener) |
method | Removes on both original & wrapped |
getMaxListeners() |
method | Directly calls original method |
setMaxListeners(n) |
method | Directly calls original method |
When the wrapper has events listening on the original EventEmitter, a removeListener event will be internally listened on for clean-up after an event is removed.
On this wrapper, there are internal methods & properties prefixed with '_eew'. These are available (see source code) to use, but they may change in future releases.
// Require modules
const EventEmitter = require('node:events');
const EventEmitterWrapper = require('eventemitter-wrapper');
// Create instances
const events = new EventEmitter();
const eventsWrapped = new EventEmitterWrapper(events);
// Attach a listener to original EventEmitter
events.on('original',(...args)=>{
console.log('original:',...args);
});
// Fire event on either original or wrapped
events.emit('original','foo');
// Logs: original: foo
// Attach a listener to wrapped EventEmitter
eventsWrapped.on('wrapped',(...args)=>{
console.log('wrapped:',...args);
});
// Fire event on either original or wrapped
events.emit('wrapped','bar');
// Logs: wrapped: bar
// Fetch a list of events on the original
// "removeListener" event is used by the wrapper for event clean-up
console.log(events.eventNames());
// Logs: [ 'original', 'wrapped', 'removeListener' ]
// Fetch a list of events on the wrapper
console.log(eventsWrapped.eventNames());
// Logs: [ 'wrapped' ]
// Remove all listeners on the wrapper
eventsWrapped.removeAllListeners();
// Fetch a list of events on the original
console.log(events.eventNames());
// Logs: [ 'original' ]
// Fetch a list of events on the wrapper
console.log(eventsWrapped.eventNames());
// Logs: []Tests are located within ./tests/ on the git repository on GitHub or locally if pulled. NPM version does not include tests.
To get started with tests, we need to install some dev dependencies. Enter local directory of this repository and run:
npm install --only=dev
To run the tests, run:
npm run test
To continuously run tests while editing, run: npm run test-watch
test-watch currently not supported with mocha, chai & sinon moving to ESM. There are workarounds.
To submit a contribution, create issues or pull requests on the GitHub repository.
Please be sure to run tests after any changes.
All help is appreciated. Even if it's just improvements to this readme or the tests.
MIT License
Copyright (c) 2023 Jason Sheppard @ https://github.com/Jashepp
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Github Repository: https://github.com/Jashepp/eventemitter-wrapper
NPM Package: https://www.npmjs.com/package/eventemitter-wrapper