event-emitter-extra

EventEmitterExtra

EventEmitterExtra is an implementation of node.js's EventEmitter where can be found in events module. The interface is exactly same with node.js's EventEmitter. So you can directly replace require('events') to require('event-emitter-extra') without any hassle.

Extra features to boost your flow:

• Regex support for listening
• emit() method returns all results of listener functions
• Times to listen (TTL) with many() (Idea borrowed from EventEmitter2)
• Works in Node.js > v0.10
• Works in browsers
• Built-in typescript support

Getting Started

Install EventEmitterExtra as a dependency:

npm i event-emitter-extra
# or
yarn add event-emitter-extra

Require EventEmitterExtra:

// As commonjs module (nodejs, webpack)
const EventEmitterExtra = require('event-emitter-extra');

<!-- In browsers -->
<script src="./node_modules/event-emitter-extra/dist/globals.js"></script>

<!--  In modern browsers (No polyfills, smaller size) -->
<script src="./node_modules/event-emitter-extra/dist/globals.modern.js"></script>

Directly usage:

const ee = new EventEmitterExtra();

ee.on('greeting', function(name) {
    console.log(`Hello ${name}`);
});

ee.on(/gre/, function(name) {
    console.log('Regex is awesome');
});

ee.emit('greeting', 'world');
// => Hello world
// => Regex is awesome

Inheritence in ES6:

class myEventEmitter extends EventEmitterExtra {
    sayHello(name) {
        this.emit('hello', name)
    }
}

const ee = new myEventEmitter();

ee.on('hello', name => {
    console.log(`${name} is saying hello`);
});

ee.sayHello('world');
// => world is saying hello

Emit results:

const ee = new EventEmitterExtra();

// Emit result is false, because there is no listener yet
const result1 = ee.emit('greeting');
// result1 == false

// Add some listeners
ee.on('greeting', () => {
    return 'Hello from listener 1';
});

ee.on('greeting', () => {
    return 'Hello from listener 2';
});

// Emit again
const result2 = ee.emit('greeting');
// result2 == ['Hello from listener 1', 'Hello from listener 2']

Advanced promise flows with emitAsync:

const ee = new EventEmitterExtra();

ee
    .emitAsync('some-task')
    .then(() => {
        // This will be never called
    })
    .catch(err => {
        // err => 'No listener'
    });

// Add some listeners
ee.on('some-task', () => {
    return Promise.resolve('result 1');
});

ee.on('some-task', () => {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve('result 2');
        }, 1000);
    });
});

// Emit again
ee
    .emitAsync('some-task')
    .then((results) => {
        // reults == ['result 1', 'result 2']
    });

API

EventEmitterExtra.defaultMaxListeners

By default, a maximum of 10 listeners can be registered for any single event.

EventEmitterExtra.defaultMaxRegexListeners

Maximum number for regex listeners. Defaults to 10.

new EventEmitterExtra()

Creates new event emitter.

EventEmitterExtra.prototype.addListener(eventName, listener[, ttl])

Adds a new listener.

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>
• ttl: Number Optional times to listen. Defaults to 0 (no limit).

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.emit(eventName[, ...args])

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

• eventName: String|Array.<String>

Returns false if there is no listener for event. If there are listeners, it returns array of listener returns.

const ee = new EventEmitterExtra();
ee.on('test', _ => 'hello');
ee.on('test', _ => 'world');

const results = ee.emit('test');
console.log(results);
// => ['hello', 'world']

EventEmitterExtra.prototype.emitAsync(eventName[, ...args])

If listener functions return Promise, wait for them resolving.

const ee = new EventEmitterExtra();
ee.on('test', _ => 'hello');
ee.on('test', _ => Promise.resolve('world'));

ee
    .emit('test')
    .then((results) => {
        console.log(results);
        // => ['hello', 'world']
    });

EventEmitterExtra.prototype.eventNames()

Returns an array listing the events for which the emitter has registered listeners.

EventEmitterExtra.prototype.getMaxListeners()

Returns the current max listener value for the EventEmitter which is either set by ee.setMaxListeners(n) or defaults to EventEmitterExtra.defaultMaxListeners.

EventEmitterExtra.prototype.getMaxRegexListeners()

Returns the current max regex listener value for the EventEmitter which is either set by ee.setMaxRegexListeners(n) or defaults to EventEmitterExtra.defaultMaxRegexListeners.

EventEmitterExtra.prototype.listenerCount(eventName)

Returns number of listeners.

• eventName: String|RegExp

EventEmitterExtra.prototype.listeners(eventName)

Returns array of listener functions.

• eventName: String|RegExp

EventEmitterExtra.prototype.on(eventName, listener)

Alias for ee.addEventListener(eventName, listener).

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.once(eventName, listener)

Alias for ee.addEventListener(eventName, listener, 1).

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.many(eventName, ttl, listener)

Alias for ee.addEventListener(eventName, listener, ttl).

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>
• ttl: Times to listen

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.prependListener(eventName, listener[, ttl])

Adds the listener function to the beginning of the listeners array for the event named eventName.

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>
• ttl: Times to listen

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.prependOnceListener(eventName, listener)

Alias for ee.prependListener(eventName, listener, 1).

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.prependManyListener(eventName, ttl, listener)

Alias for ee.prependListener(eventName, listener, ttl).

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>
• ttl: Times to listen

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.removeAllListeners(eventName)

Removes all listeners, or those of the specified eventName. If eventName is not provided, all the event & regex listeners will be removed.

• eventName: String|RegExp|Array.<String|RegExp>

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.removeListener(eventName, listener)

Removes all listeners, or those of the specified eventName.

• eventName: String|RegExp|Array.<String|RegExp>
• listener: Function|Array.<Function>

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.setMaxListeners(n)

By default EventEmitterExtra does not allow you add listener if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. Obviously, not all events should be limited to just 10 listeners. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to 0 to indicate an unlimited number of listeners.

• n: Number

Returns EventEmitterExtra instance for chaining.

EventEmitterExtra.prototype.setMaxRegexListeners(n)

By default EventEmitterExtra does not allow you add regex listener if more than 10 regex listeners are added before.

• n: Number

Returns EventEmitterExtra instance for chaining.

Development

npm run build
npm run coverage
COVERALLS_SERVICE_NAME="" COVERALLS_REPO_TOKEN="" npm run coverage:coveralls
npm test
npm run test:browser
TRAVIS_BUILD_NUMBER="" npm run test:cloud