Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including event-emitter-enhancer with all npm packages installed. Try it out:

var eventEmitterEnhancer = require("event-emitter-enhancer")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

event-emitter-enhancer v1.0.58

Enhances the Node.js EventEmitter with extra capabilities.

event-emitter-enhancer

NPM Version Build Status Coverage Status Known Vulnerabilities Inline docs
License Total Downloads Dependency Status devDependency Status

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;

//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

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

var 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

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

var 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

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

var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var emitter = new EnhancedEventEmitter();
emitter.on('test', function onEventSync() {
  //sync handle function logic
});
var 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

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

//add same listener to multiple events
var 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

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

//add filters for test event only
var 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
});
var 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

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

//proxy the 'data' and 'end' events from all sockets
var 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

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

//add noop even handler for the 'error' event
var 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

var EnhancedEventEmitter = EventEmitterEnhancer.extend(EventEmitter);
var 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

DateVersionDescription
2019-02-08v1.0.58Maintenance
2018-06-13v1.0.57Added typescript definition (#5 and #6)
2017-11-03v1.0.51Added 'addNoop'
2017-10-30v1.0.49Added 'ignoreError'
2017-10-30v1.0.48New extended 'removeAllListeners' function
2017-01-16v1.0.27New extended 'once' function
2017-01-07v1.0.25New 'proxyEvents' function
2017-01-06v1.0.24New extended 'on' function
2016-11-11v1.0.15'emitAsync' callback is now optional
2015-09-23v0.0.44Added 'onAny'
2015-04-22v0.0.31Prevent from multiple enhance of same prototype/instance
2014-12-31v0.0.10EventEmitter is no longer automatically modified,
instead there are 2 ways to extend/modify prototype/modify instance
functions exposed by this library.
2014-12-30v0.0.9Added ability to enhance compatible EventEmitter types
2014-12-29v0.0.6Added 'filter'
2014-12-28v0.0.5Added 'onAsync'
2014-12-28v0.0.4Added 'emitAsync'
2014-12-28v0.0.2Initial release.

License

Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free