event-emitter-enhancer
Extends the Node.js events.EventEmitter to provide additional functionality.
Overview
This library extends the Node.js events.EventEmitter to provide additional functionality.
Usage
First you must require this library as follows:
var EventEmitterEnhancer = require('event-emitter-enhancer');
Next you can either modify the proto of an EventEmiter type class, or extend it to get a new custom type or modify a specific emitter instance.
var EventEmitter = require('events').EventEmitter;
var emitter = new EventEmitterEnhancer.EnhancedEventEmitter();
var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var emitter = new EnhancedEventEmitter();
EventEmitterEnhancer.modify(EventEmitter);
var emitter = new EventEmitter();
var emitter = new EventEmitter();
EventEmitterEnhancer.modifyInstance(emitter);
'emitter.on(event, listener) ⇒ function'
See node.js events.EventEmitter.on.
This function also returns a removeListener function to easily remove the provided listener.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const remove = emitter.on('error', function (error) {
console.error(error);
});
remove();
'emitter.on(options) ⇒ function'
Enables more complex on capabilities including providing multiple listeners/event names, timeout the listener and more.
To remove the listener/s, the returned function must be called instead of doing emitter.removeListener(...)
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const removeListener = emitter.on({
event: ['error', 'connection-error', 'write-error', 'read-error'],
listener: [
function firstListener(arg1, arg2) {
},
function secondListener(arg1, arg2) {
}
],
async: true,
timeout: 1500
});
emitter.emit('write-error', 1, 2, 3);
removeListener();
'emitter.once(event, listener) ⇒ function'
See node.js events.EventEmitter.once.
This function also returns a removeListener function to easily remove the provided listener.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const remove = emitter.once('error', function (error) {
console.error(error);
});
remove();
'emitter.removeAllListeners([event])'
See node.js events.EventEmitter.removeAllListeners.
This function is modified to also accept an array of event names.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.removeAllListeners('my-event');
emitter.removeAllListeners(['my-event', 'another-event']);
'emitter.else(listener)'
Adds an 'else' listener which will be triggered by all events that do not have a listener currently for them (apart of the special 'error' event).
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.else(function onUnhandledEvent(event, arg1, arg2) {
emitter.unelse(this);
});
emitter.emit('test', 1, 2);
'emitter.suspend(event)'
Suspends all emit calls for the provided event name (including 'else' listeners).
For suspended events, the emit function will simply do nothing ('else' listeners won't be invoked either).
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.on('test', function () {
});
emitter.suspended = true;
emitter.suspend('test');
emitter.emit('test');
'emitter.elseError(event)'
In case an event with the provided name is emitted but no listener is attached to it, an error event will emitted by this emitter instance instead.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.on('error', function (error) {
emitter.unelseError('test');
});
emitter.elseError('test');
emitter.emit('test');
'emitter.emitAsync(event, [...params], [callback])'
Invokes the emit after a timeout to enable calling flow to continue and not block due to event listeners.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.on('test', function onTestEvent(num1, num2) {
});
emitter.emitAsync('test', 1, 2, function onEmitDone(event, num1, num2, emitted) {
});
'emitter.onAsync(event, listener) ⇒ function'
Adds a listener that will be triggered after a timeout during an emit.
This ensures that the provided listener is invoked after all other listeners and that it will not block the emit caller flow.
To remove the listener, the returned function must be called instead of doing emitter.removeListener(...)
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.on('test', function onEventSync() {
});
const removeListener = emitter.onAsync('test', function onEventAsync() {
});
emitter.emit('test', 1, 2);
removeListener();
'emitter.onAny(events, listener) ⇒ function'
Adds a listener to all provided event names.
To remove the listener, the returned function must be called instead of doing emitter.removeListener(...)
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const remove = emitter.onAny(['test1', 'test2', 'test3'], function (arg1, arg2, arg3) {
console.log(arg1, arg2, arg3);
});
remove();
'emitter.filter([event], filter) ⇒ function'
Adds a filter that will be triggered before every emit for the provided event type (if no event is provided, than the filter is invoked for all events).
The filter enables to prevent events from reaching the listeners in case some criteria is met.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const removeTestEventFilter = emitter.filter('test', function (event, arg1, arg2) {
if (arg1 && (arg1 > 3)) {
return true;
}
return false;
});
emitter.filter('test', function (event, arg1, arg2) {
if (arg2 && (arg2 < 20)) {
return true;
}
return false;
});
emitter.filter(function (event, arg1, arg2) {
if (arg1 && (arg1 > 5)) {
return true;
}
return false;
});
const removeGlobalArg2Filter = emitter.filter(function (event, arg1, arg2) {
if (arg2 && (arg2 < 18)) {
return true;
}
return false;
});
emitter.on('test', function onTestEvent(arg1, arg2) {
});
emitter.emit('test', 10, 15);
removeTestEventFilter();
removeGlobalArg2Filter();
'emitter.proxyEvents(emitters, events) ⇒ function'
Will setup an event proxy so if any of the requested event/s are fired from the provided emitter/s, they will be triggered by this emitter.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const stop = emitter.proxyEvents(sockets, ['data', 'end']);
emitter.on('data', onData);
stop();
'emitter.addNoop(event) ⇒ function'
Adds empty event handler.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
const remove = emitter.addNoop('error');
remove();
'emitter.ignoreError()'
Adds empty error event handler to prevent node.js from crashing in case of an error which we do not want/need to handle.
This function will only add a new empty handler in case no other handler is defined for the error event.
Example
const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();
emitter.ignoreError();
emitter.emit('error', new Error('test'));
Installation
In order to use this library, just run the following npm install command:
npm install --save event-emitter-enhancer
API Documentation
See full docs at: API Docs
Contributing
See contributing guide
Release History
Date | Version | Description |
---|
2020-05-11 | v2.0.0 | Migrate to github actions and upgrade minimal node version |
2019-12-06 | v1.1.0 | Support event parent parsing and emit #7 |
2018-06-13 | v1.0.57 | Added typescript definition (#5 and #6) |
2017-11-03 | v1.0.51 | Added 'addNoop' |
2017-10-30 | v1.0.49 | Added 'ignoreError' |
2017-10-30 | v1.0.48 | New extended 'removeAllListeners' function |
2017-01-16 | v1.0.27 | New extended 'once' function |
2017-01-07 | v1.0.25 | New 'proxyEvents' function |
2017-01-06 | v1.0.24 | New extended 'on' function |
2016-11-11 | v1.0.15 | 'emitAsync' callback is now optional |
2015-09-23 | v0.0.44 | Added 'onAny' |
2015-04-22 | v0.0.31 | Prevent from multiple enhance of same prototype/instance |
2014-12-31 | v0.0.10 | EventEmitter is no longer automatically modified, instead there are 2 ways to extend/modify prototype/modify instance functions exposed by this library. |
2014-12-30 | v0.0.9 | Added ability to enhance compatible EventEmitter types |
2014-12-29 | v0.0.6 | Added 'filter' |
2014-12-28 | v0.0.5 | Added 'onAsync' |
2014-12-28 | v0.0.4 | Added 'emitAsync' |
2014-12-28 | v0.0.2 | Initial release. |
License
Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.