Wondering what’s next for npm?Check out our public roadmap! »

event-resource
TypeScript icon, indicating that this package has built-in type declarations

1.2.1 • Public • Published

event-resource

Build Status

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.

This method will be called on all chained children as well. This method will return the number of unsubscribed listener functions.

removeSource

Signature: eventResource.removeSource(source: EventEmitter) : number

Pass in an EventEmitter source object. All listeners listening to this source will be unsubscribed from the source and removed from this EventResource.

This method will be called on all chained children as well. This method will return the number of unsubscribed listener functions.

removeEvents

Signature: eventResource.removeEvents(eventName: string) : number

Pass in an event name string. All listeners listening to this event name on any sources will be unsubscribed from that source and removed from this EventResource.

This method will be called on all chained children as well. This method will return the number of unsubscribed listener functions.

removeSourceEvents

Signature: eventResource.removeSourceEvents(source: EventEmitter, eventName: string) : number

Pass in an event name string and an EventEmitter source object. All listeners listening to this event name on this source will be unsubscribed from that source and removed from this EventResource.

This method will be called on all chained children as well. This method will return the number of unsubscribed listener functions.

removeListenersMatching

Signature: eventResource.removeListenersMatching(matchFn: ([source: EventEmitter, eventName: string, listenerFn: (any) => any]) => boolean) : number

This is an advanced function. Call it if you want to remove certain event listeners matching a custom predicate.

Your matchFn will be called with a triple (an array) of types EventEmitter, string, (any) => any or source, eventName, listenerFn. If you return true, that listener will be removed from the source and from the EventResource.

This method will be called on all chained children as well. This method will return the number of unsubscribed listener functions.

License

MIT license. See LICENSE file.

Install

npm i event-resource

DownloadsWeekly Downloads

2

Version

1.2.1

License

MIT

Last publish

Collaborators

  • avatar
  • avatar
  • avatar