event-resource

JavaScript: Manage event handlers as a resource: prevent leaks, double-listens, and exert more control over event handlers.

Install

npm install --save event-resource

Use

The purpose of this library is to reduce the cognitive overhead of managing event handlers by allowing you to group event handlers into common resources. This will help prevent memory leaks (especially in the case of long-running processes that use shared event emitters) and generally reduce cognitive overload, with minimal overhead:

Instead of:

var a, b, c, d;
 
a = function () { /* ... */ };
b = function () { /* ... */ };
c = function () { /* ... */ };
d = function () { /* ... */ };
 
emitter1.on('data', a);
emitter1.on('error', b);
emitter2.on('data', c);
emitter2.on('error', d);
 
// ...
 
// handle cleanup later:
function cleanup () {
  emitter1.removeListener('data', a);
  emitter1.removeListener('error', b);
  emitter2.removeListener('data', c);
  emitter2.removeListener('error', d);
}

Do this:

var EventResource = require('event-resource');
 
var myResource = new EventResource();
 
myResource.on(emitter1, 'data', function () { /* ... */ });
myResource.on(emitter1, 'error', function () { /* ... */ });
myResource.on(emitter2, 'data', function () { /* ... */ });
myResource.on(emitter2, 'error', function () { /* ... */ });
 
// clean up later...
function cleanup () {
  myResource.clean();
}

Chain resources

You can chain resources together. Cleaning up a parent resource will clean all children as well.

var parentResource = new EventResource();
var childResource = new EventResource();
 
parentResource.chain(childResource);
 
// also cleans child
parentResource.clean();

You can also chain resources by passing a parent to the child during construction:

var parentResource = new EventResource();
var childResource = new EventResource(parentResource);
 
// also cleans child
parentResource.clean();

Removing listeners

You can also remove specific listeners before cleanup, in a variety of ways. All of these cascade all will remove the listeners in the resource and any chained resources:

// Remove all listeners listening to a source
er.removeSource(anEmitter);
 
// Remove all listeners listening to this event, at any source
er.removeEvents('data');
 
// Remove all listeners listening to this event and source
er.removeSourceEvents(anEmitter, 'data');
 
// Remove a specific listener (identical to EventEmitter `removeListener`)
er.removeListener(anEmitter, 'data', listenerFn);

API

`EventResource` (constructor)

Signature: new EventResource(parent?: EventResource)

Create a new EventResource with an optional parent. If you provide a parent, the constructor will parent.chain(this).

`on`

Signature: eventResource.on(source: EventEmitter, eventName: string, listener: (any) => any) : void

Subscribes to the eventName event on the source EventEmitter object.

Similar to calling source.on(eventName, listener). Will keep track of all sources, events, and listeners for you.

`once`

Signature: eventResource.once(source: EventEmitter, eventName: string, listener: (any) => any) : void

Subscribes to the eventName event on the source EventEmitter object, but the event will only fire once.

Similar to calling source.once(eventName, listener). Will keep track of all sources, events, and listeners for you.

`clean`

Signature: eventResource.clean() : void

Unsubscribes all events that this EventResource is aware of. This EventResource cannot be used at all after it is cleaned (further calls to on, once, chain, etc will fail).

`chain`

Signature: eventResource.chain(child: EventResource) : void

Pass in another EventResource that will become a child of this EventResource. When clean and any remove* functions are called on this EventResource, they will also be called on chained children EventResources. The opposite is not true - those functions called on children will not affect parents.

`removeListener`

Signature: eventResource.removeListener(source: EventEmitter, eventName: string, listenerFn: (any) => any) : number

This is identical to the canonical EventEmitter.removeListener function. The function subscribed to the eventName on the source object will be unsubscribed, and removed from this EventResource.