event-emitter-enhancer

Extends the Node.js events.EventEmitter to provide additional functionality.

• Overview
• Usage
  • on(event, listener)
  • on(options)
  • once(event, listener)
  • removeAllListeners
  • else
  • suspend
  • elseError
  • emitAsync
  • onAsync
  • onAny
  • filter
  • proxyEvents
  • addNoop
  • ignoreError
• Installation
• API Documentation
• Contributing
• Release History
• License

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;

//Get predefined extended version of the events.EventEmitter class (original EventEmitter is not impacted)
var emitter = new EventEmitterEnhancer.EnhancedEventEmitter();   //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 way
var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);   //extend the event emitter class (can be Node.js of some custom event emitter). original base class is not affected.
var emitter = new EnhancedEventEmitter();   //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(EventEmitter); //modify the event emitter class prototype (can be Node.js of some custom event emitter). existing instances are impacted.
var emitter = new EventEmitter();   //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 = new EventEmitter();   //create an instance of an event emitter (can be Node.js of some custom event emitter)
EventEmitterEnhancer.modifyInstance(emitter);   //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.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();

const remove = emitter.on('error', function (error) {
   console.error(error);
});

//remove listener (no longer need to keep a reference to the listener function)
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'], //The event names (can be string for a single event)
  listener: [ //The listener callback functions (can be a function instead of an array for a single listener callback)
    function firstListener(arg1, arg2) {
      //do something
    },
    function secondListener(arg1, arg2) {
      //do something
    }
  ],
  async: true, //The callback functions will be called after next tick
  timeout: 1500 //All listeners will be removed after the provided timeout (if not provided, listeners can only be removed manually via returned function)
});

//emit any event
emitter.emit('write-error', 1, 2, 3);

//once done, remove all listeners from all events
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 listener (no longer need to keep a reference to the listener function)
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();

//same as the basic removeAllListeners
emitter.removeAllListeners('my-event');

//also supports array of event names
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) {
 //logic here....

 //to remove 'else' listeners, simply use the unelse function
 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 () {
  //will never be called
});

emitter.suspended = true;  //suspend ALL events (to unsuspend use emitter.suspended = false;)
//or
emitter.suspend('test');   //suspend only 'test' event (to unsuspend use emitter.unsuspend('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) {
  //logic here...

  //To remove elseError
  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) {
   //event logic here
});

emitter.emitAsync('test', 1, 2, function onEmitDone(event, num1, num2, emitted) {
   //emit callback logic
});

'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() {
  //sync handle function logic
});
const removeListener = emitter.onAsync('test', function onEventAsync() {
  //async handle function logic
});

emitter.emit('test', 1, 2);

//remove the async listener
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();

//add same listener to multiple events
const remove = emitter.onAny(['test1', 'test2', 'test3'], function (arg1, arg2, arg3) {
   console.log(arg1, arg2, arg3);
});

//remove listener from all events
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();

//add filters for test event only
const removeTestEventFilter = emitter.filter('test', function (event, arg1, arg2) {
   if (arg1 && (arg1 > 3)) {
       return true;    //continue with emit
   }

   return false;   //prevent emit
});
emitter.filter('test', function (event, arg1, arg2) {
   if (arg2 && (arg2 < 20)) {
       return true;    //continue with emit
   }

   return false;   //prevent emit
});

//add global filter for all events
emitter.filter(function (event, arg1, arg2) {
   if (arg1 && (arg1 > 5)) {
       return true;    //continue with emit
   }

   return false;   //prevent emit
});
const removeGlobalArg2Filter = emitter.filter(function (event, arg1, arg2) {
   if (arg2 && (arg2 < 18)) {
       return true;    //continue with emit
   }

   return false;   //prevent emit
});

emitter.on('test', function onTestEvent(arg1, arg2) {
   //event logic here...
});

emitter.emit('test', 10, 15);

//remove some filters
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();

//proxy the 'data' and 'end' events from all sockets
const stop = emitter.proxyEvents(sockets, ['data', 'end']);

//listen to events via emitter
emitter.on('data', onData);

//stop events proxy
stop();

'emitter.addNoop(event) ⇒ function'

Adds empty event handler.

Example

const EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
const emitter = new EnhancedEventEmitter();

//add noop even handler for the 'error' event
const remove = emitter.addNoop('error');

//remove listener
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();

//adds empty error handler
emitter.ignoreError();

//emit error will not crash the node.js process
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 instancefunctions 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.