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 = ;
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 = EventEmitter; //Get predefined extended version of the events.EventEmitter class (original EventEmitter is not impacted)var emitter = ; //create a new instance using the new extended class type. //extend events.EventEmitter class (or any class that has the same interface)//now you can create instances of the new EnhancedEventEmitter type while events.EventEmitter is not modified/impacted in any wayvar EnhancedEventEmitter = EventEmitterEnhancer; //extend the event emitter class (can be Node.js of some custom event emitter). original base class is not affected.var emitter = ; //create a new instance using the new extended class type. //modify the proto of an events.EventEmitter class (or any class that has the same interface)//now all existing and future instances of the original class are modified to include the new extended capabilities.EventEmitterEnhancer; //modify the event emitter class prototype (can be Node.js of some custom event emitter). existing instances are impacted.var emitter = ; //create an instance of the original class and automatically get the new extended capabilities. //modify specific instance to include the extended capabilities (other existing/future instances of that class type are not modified/impacted in any way).var emitter = ; //create an instance of an event emitter (can be Node.js of some custom event emitter)EventEmitterEnhancer; //modify the specific instance and add the extended capabilities. the original prototype is not affected.
'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;const emitter = ; const remove = emitter; //remove listener (no longer need to keep a reference to the listener function);
'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;const emitter = ; const removeListener = emitter; //emit any eventemitter; //once done, remove all listeners from all events;
'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;const emitter = ; const remove = emitter; //remove listener (no longer need to keep a reference to the listener function);
'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;const emitter = ; //same as the basic removeAllListenersemitter; //also supports array of event namesemitter;
'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;const emitter = ;emitter; emitter;
'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;const emitter = ;emitter; emittersuspended = true; //suspend ALL events (to unsuspend use emitter.suspended = false;)//oremitter; //suspend only 'test' event (to unsuspend use emitter.unsuspend('test');) emitter;
'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;const emitter = ;emitter; emitter; emitter;
'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;const emitter = ;emitter; emitter;
'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;const emitter = ;emitter;const removeListener = emitter; emitter; //remove the async listener;
'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;const emitter = ; //add same listener to multiple eventsconst remove = emitter; //remove listener from all events;
'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;const emitter = ; //add filters for test event onlyconst removeTestEventFilter = emitter;emitter; //add global filter for all eventsemitter;const removeGlobalArg2Filter = emitter; emitter; emitter; //remove some filters;;
'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;const emitter = ; //proxy the 'data' and 'end' events from all socketsconst stop = emitter; //listen to events via emitteremitter; //stop events proxy;
'emitter.addNoop(event) ⇒ function'
Adds empty event handler.
Example
const EnhancedEventEmitter = EventEmitterEnhancer;const emitter = ; //add noop even handler for the 'error' eventconst remove = emitter; //remove listener;
'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;const emitter = ; //adds empty error handleremitter; //emit error will not crash the node.js processemitter;
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
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.