Event emitters with support for regular expressions. Inherits from Node's EventEmitter.
- Installation
- Overview
- Compatibility
- Class: PatternEmitter
- Instance Methods
- emitter.addListener(event | pattern, listener)
- emitter.emit(event, [arg1], [arg2], [...])
- emitter.listeners(event)
- emitter.matchingListeners(event)
- emitter.on(event | pattern, listener)
- emitter.once(event | pattern, listener)
- emitter.patternListeners(pattern)
- emitter.removeAllListeners(event | pattern)
- emitter.removeListener(event | pattern, listener)
- emitter.setMaxListeners(n)
- Class Methods
- Events
- Performance
Using npm, you can install pattern-emitter with npm install pattern-emitter.
You can also require it as a dependency in your package.json file:
"dependencies": {
"pattern-emitter": "1.0.x"
}
The PatternEmitter class both extends and is backwards compatible with EventEmitter when dealing with string event types. However, when registering a listener to a RegExp, it has the added benefit of listening to all events matching the expression, rather than that particular object. In addition, it exposes a new set of methods on top of the existing API for requesting details on those patterns and their listeners. As a result, getting started with this library is as simple as replacing instances of:
var Emitter = require('events').EventEmitter; // Node 0.10.x
var Emitter = require('events'); // Node 0.12.xwith:
var Emitter = require('pattern-emitter');Afterwards, you're ready to start listening to patterns.
var emitter = new Emitter();
var result;
emitter.on(/^example/, function(arg1, arg2) {
result = arg1 + ' ' + arg2;
});
emitter.emit('exampleEvent', "It's", 'that simple');
console.log(result); // "It's that simple"The use of PatternEmitter is backwards compatible with EventEmitter for all
who haven't been registering listeners to instances of RegExp. I suspect
that this covers a great majority of event use.
As with EventEmitter, when a PatternEmitter experiences an error, it emits
an error event. If no listeners exist for the event, then by default, a stack
trace is printed and the program is closed.
Furthermore, all PatternEmitters emit the newListener event when new listeners
are added, and removeListener when removed.
These string events are treated like any other, and may be caught by a listener
registered to a matching pattern, e.g. /.*/.
In the following examples, let emitter be an instance of PatternEmitter.
Furthermore, let pattern refer to any instance of RegExp, and event
all other values.
When a listener is invoked, it's given the event name as a property, which is
accessible via this.event.
Given a RegExp event type, stores the regular expression and registers the listener to any events matching the pattern. Otherwise, it behaves exactly as EventEmitter. As with EventEmitter.prototype.addListener, it emits a newListener' event on success. Returns an instance of itself.
emitter.addListener('userCreated', function(object) {
console.log('Listener:', this.event);
});
emitter.addListener(/user/, function(object) {
console.log('Pattern Listener:', this.event);
});
emitter.emit('userCreated', {id: 10, username: 'Alice'});
// Listener: userCreated
// Pattern Listener: userCreated
emitter.emit('userUpdated', {id: 19, username: 'Bob'});
// Pattern Listener: userUpdatedEmits an event to all listeners for the specified type. In addition, if type is a string, emits the event to all listeners whose patterns match. Returns true if any listeners existed, false otherwise.
emitter.addListener(/^namespace:entry:1\d{4}$/, function() {
// Handler for entries within the given range: 10000-19999
});
emitter.emit('namespace:entry:12345'); // true
emitter.emit('namespace:entry:20000'); // falseReturns an array of listeners for the given event.
emitter.addListener('foo:1:newBar', function() {
console.log('event listener');
});
emitter.addListener(/^foo:[0-9]+:newBar$/, function() {
console.log('pattern listener');
});
var listeners = emitter.listeners('foo:1:newBar');
console.log(listeners.length); // 1
listeners[0](); // 'event listener'Returns an array of listeners for the supplied event type, and whose patterns match the event if given a string.
emitter.addListener('foo:1:newBar', function() {
console.log('event listener');
});
emitter.addListener(/^foo:[0-9]+:newBar$/, function() {
console.log('pattern listener');
});
var listeners = emitter.matchingListeners('foo:1:newBar');
console.log(listeners.length); // 2
listeners[0](); // 'event listener'
listeners[1](); // 'pattern listener'An alias for addListener.
emitter.on(/.*/, function() {
// Listen to all events, including 'error', 'newListener',
// and 'removeListener'
});Adds a one time listener for an event or pattern. The listener is invoked only once after an event is fired, after which it is removed.
var counter = 0;
emitter.once(/foo:[0-9]+:updated$/, function() {
counter++;
});
emitter.emit('app:foo:81:updated');
emitter.emit('app:foo:92:updated');
console.log(counter); // 1Returns an array of pattern listeners for the specified RegExp.
emitter.on(/.*/, function() {
// Example pattern listener
});
emitter.on('/.*/', function() {
// Won't be included in the results below
});
var count = emitter.patternListeners(/.*/).length; // 1Removes all listeners for the specified event type. If given an instance of RegExp, it matches the RegExp object with the same expression. Emits a 'removeListener' event for each removed listener. Returns an instance of itself.
emitter.addListener(/foo:.*[0-9]+/, function() {});
emitter.addListener(/foo:.*[0-9]+/, function() {});
emitter.addListener('/foo:.*[0-9]+/', function() {});
var count = emitter.patternListeners(/foo:.*[0-9]+/).length; // 2
emitter.removeAllListeners(/foo:.*[0-9]+/);
count = emitter.patternListeners(/foo:.*[0-9]+/).length; // 0Removes the listener from the specified event type. If given an instance of RegExp, it matches any RegExp object with the same expression. Emits a 'removeListener' event on success. Returns an instance of itself.
var listener = function() {
// Example event listener
};
emitter.addListener(/foo:.*[0-9]+/, listener);
emitter.addListener(/foo:.*[0-9]+/, function() {});
var count = emitter.patternListeners(/foo:.*[0-9]+/).length; // 2
emitter.removeListener(/foo:.*[0-9]+/, listener);
count = emitter.patternListeners(/foo:.*[0-9]+/).length; // 1By default, PatternEmitters will print a warning once more than 10 listeners are added for a particular event. This may be used to modify that threshold. Setting to 0 will disable the threshold altogether.
emitter.setMaxListeners(1);
emitter.on(/^foo.*/, function() {});
emitter.on(/^foo.*/, function() {});
// (node) warning: possible EventEmitter memory leak detected. 2 listeners
// added. Use emitter.setMaxListeners() to increase limit.In the outline below, let pattern refer to any instance of RegExp, and
event all other values.
Returns the number of listeners for a given event. An alias for EventEmitter.listenerCount.
emitter.on('foo', function() {});
emitter.on(/foo/, function() {});
PatternEmitter.listenerCount(emitter, 'foo'); // 1Returns the number of listeners and pattern listeners registered to the emitter for the event type or a matching pattern.
emitter.on('foo', function() {});
emitter.on(/foo/, function() {});
PatternEmitter.matchingListenerCount(emitter, 'foo'); // 2Returns the number of listeners registered to the emitter for the specified pattern.
emitter.on('foo', function() {});
emitter.on(/foo/, function() {});
PatternEmitter.patternListenerCount(emitter, /foo/); // 1Like EventEmitter, instances of PatternEmitter emit events both when listeners
are added and removed. The events can be matched by pattern listeners, and as
such will include the name/type as a property, accessible via this.event.
The event is emitted any time a new listener is added to the emitter. The event is emitted just prior to the listener being added, to prevent recursion.
*event | patternfunctionlistener
emitter.on(/Listener/, function(pattern, listener) {
// this.event will equal 'newListener' when a new listener is added
});The event is emitted any time an existing listener is removed from the emitter. The event is emitted just prior to the listener being removed, to prevent recursion.
*event | patternfunctionlistener
emitter.on('removeListener', function(event, listener) {
// invoked when a listener is removed
});TL;DR: Likely not an issue unless you're invoking in excess of 1,000,000 listeners per second
Despite the ease of replacing EventEmitter throughout your application,
performance should be considered for any event-heavy code. This implementation
was done in an attempt to avoid copying a majority of the source in
node/lib/events.js, which resulted in a couple otherwise unnecessary
assignments and function calls when dealing with EventEmitter's default
behaviour.
To illustrate, consider the performance difference between both modules when only registering to string events, no regular expressions. Running benchmarks/eventEmitting.js:
$ node benchmarks/eventEmitting.js
EventEmitter x 208,424 ops/sec ±0.28% (102 runs sampled)
PatternEmitter x 164,004 ops/sec ±0.45% (101 runs sampled)
Each operation in the above benchmark is invoking 100 listeners: 10 for each of 10 different events. That is, 20,842,400 vs 16,400,400 invocations a second on my Macbook Air. So while a performance drop, it may not be a problem for your average node instance.
For testing PatternEmitter with its pattern matching behaviour, a second naive benchmark currently exists. With 100 pattern listeners, 10 for each of 10 different patterns, benchmarks/patternEmitting.js can be used:
$ node benchmarks/patternEmitting.js
PatternEmitter x 33,179 ops/sec ±0.26% (101 runs sampled)
Still, 3,317,900 invocations a second for simple, small regular expressions. Of course, your own numbers will vary depending on the complexity of the patterns.