frog-event-dispatcher

EventDispatcher

Install

npm i frog-event-dispatcher

bower i frog-event-dispatcher

Definitions for typescript:

...
  "dependencies": {
  	...
  	"frog-event-dispatcher": "github:mclaud53/event-dispatcher/event-dispatcher.d.ts#1.3.0"
  	...
  }
...

Usage

Simple example:

 
var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
// subscribe on event "SOME_EVENT"
dispatcher.addListener(function (e) {
    console.log('event received!');
}, this, 'SOME_EVENT');
 
// dispatch of event
dispatcher.dispatch(new fed.Event('SOME_EVENT', this)); // -> event received!

To listen several events in one listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.type);
}, this, ['EVENT_1', 'EVENT_2', 'EVENT_3']);
 
dispatcher.dispatch(new fed.Event('EVENT_1', this)); // -> EVENT_1
dispatcher.dispatch(new fed.Event('EVENT_2', this)); // -> EVENT_2
dispatcher.dispatch(new fed.Event('EVENT_3', this)); // -> EVENT_3

To listen all events in one listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.type);
}, this);
 
dispatcher.dispatch(new fed.Event('ANY_EVENT', this)); // -> ANY_EVENT

To listen all events except some:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    listener = function (e) {
        console.log(e.type);
    };
 
dispatcher.addListener(listener, this);
dispatcher.removeListener(listener, this, ['EXCLUDED_EVENT', 'EXLUDED_EVENT_TOO']);
 
dispatcher.dispatch(new fed.Event('ANY_EVENT', this)); // -> ANY_EVENT
dispatcher.dispatch(new fed.Event('EXCLUDED_EVENT', this)); // -> 

To add several listeners:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListeners([
    {
        listener: function (e) {
            console.log('first listener!');
        },
        scope: this,
        eventType: 'FIRST_EVENT'
    },
    {
        listener: function (e) {
            console.log('second listener!');
        },
        scope: this,
        eventType: 'SECOND_EVENT'
    },
    {
        listener: function (e) {
            console.log('third listener!');
        },
        scope: this,
        eventType: 'THIRD_EVENT'
    }
]);
 
dispatcher.dispatch(new fed.Event('FIRST_EVENT', this));  // -> first listener!
dispatcher.dispatch(new fed.Event('SECOND_EVENT', this)); // -> second listener!
dispatcher.dispatch(new fed.Event('THIRD_EVENT', this));  // -> second listener!

To set priority to the listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log('listener with priority 0');
}, this, 'SOME_EVENT');	
 
dispatcher.addListener(function (e) {
    console.log('listener with priority -100');
}, this, 'SOME_EVENT', {priority: -100});
 
dispatcher.addListener(function (e) {
    console.log('listener with priority 100');
}, this, 'SOME_EVENT', {priority: 100});
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this));
 
// -> listener with priority 100
// -> listener with priority 0
// -> listener with priority -100

Dispatch of cancellable event:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    e.preventDefault();
}, this, 'SOME_EVENT');
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this, 'cancellable'));
 
console.log(event.isDefaultPrevented); // -> true

Dispatch event with extra data:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.options);
}, this, 'SOME_EVENT');
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this, false, {extra: 'extra data'})); // -> { extra: 'extra data' }

Automatic removal of the listener after receiving the first event:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.type);
}, this, ['FIRST', 'SECOND'], {single: true});
 
dispatcher.dispatch(new fed.Event('FIRST', this)); // -> FIRST
dispatcher.dispatch(new fed.Event('SECOND', this)); // -> 

Addition of the deferred listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log('event received!');
}, this, null, {delay: true});
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this));
console.log('event dispatched!');
 
// -> event dispatched!
// -> event received!

Addition of the delayed listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    time = (new Date()).valueOf();
 
dispatcher.addListener(function (e) {
    var delay = (new Date()).valueOf() - time;
    console.log('event received! delay: ' + delay);
}, this, null, {delay: 100});
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this));
console.log('event dispatched!');
 
// -> event dispatched!
// -> event received! delay: 102

Addition of the buffered listener:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    time = (new Date()).valueOf();
 
dispatcher.addListener(function (e) {
    var delay = (new Date()).valueOf() - time;
    console.log('event received! delay: ' + delay);
}, this, null, {buffer: 100});
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this));
setTimeout(function () {
    dispatcher.dispatch(new fed.Event('SOME_EVENT', this));
}, 50);
 
// -> event received! delay: 152

To check whether listeners were added:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    listener = function (e) {};
 
console.log(dispatcher.hasListeners); // -> false
dispatcher.addListener(listener, this);
console.log(dispatcher.hasListeners); // -> true
dispatcher.removeListener(listener, this);
console.log(dispatcher.hasListeners); // -> false

To check there are listeners for an event:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    listener = function (e) {};
 
console.log(dispatcher.willDispatch('SOME_EVENT')); // -> false
dispatcher.addListener(listener, this, 'SOME_EVENT');
console.log(dispatcher.willDispatch('SOME_EVENT')); // -> true
dispatcher.removeListener(listener, this, 'SOME_EVENT');
console.log(dispatcher.willDispatch('SOME_EVENT')); // -> false

To check whether a listener is added

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    listener = function (e) {};
 
console.log(dispatcher.hasListener(listener, this)); // -> false
dispatcher.addListener(listener, this, 'SOME_EVENT');
console.log(dispatcher.hasListener(listener, this)); // -> true
dispatcher.removeListener(listener, this, 'SOME_EVENT');
console.log(dispatcher.hasListener(listener, this)); // -> false

To suspend a dispatching of events:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.type);
}, this, ['FIRST', 'SECOND']);
 
console.log(dispatcher.suspended); // -> false
dispatcher.suspend('To enqueue the suspended events');
console.log(dispatcher.suspended); // -> true
 
dispatcher.dispatch(new fed.Event('FIRST', this)); // -> 
 
// Warning! The cancellable events can't be suspended
dispatcher.dispatch(new fed.Event('SECOND', this, 'cancellable')); // -> SECOND 
 
dispatcher.resume(); // -> FIRST
console.log(dispatcher.suspended); // -> false

To clear queue of the suspended events:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log(e.type);
}, this, ['FIRST', 'SECOND']);
 
dispatcher.suspend('To enqueue the suspended events');
 
dispatcher.dispatch(new fed.Event('FIRST', this)); // -> 
dispatcher.dispatch(new fed.Event('SECOND', this)); // -> 
 
dispatcher.purgeQueue();
 
dispatcher.resume(); // -> 

To remove all listeners:

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log('first listener');
}, this);
 
dispatcher.addListener(function (e) {
    console.log('second listener');
}, this);
 
dispatcher.purgeListeners();
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this)); // -> 

To remove all listeners by scope:

var fed = require('frog-event-dispatcher'),
    scope1 = {},
    scope2 = {},
    dispatcher = new fed.EventDispatcher();
 
dispatcher.addListener(function (e) {
    console.log('first listener');
}, scope1);
 
dispatcher.addListener(function (e) {
    console.log('second listener');
}, scope2);
 
dispatcher.purgeListeners(scope1);
 
dispatcher.dispatch(new fed.Event('SOME_EVENT', this)); // -> second listener

To proxy events from other dispatcher:

var fed = require('frog-event-dispatcher'),
    first = new fed.EventDispatcher(),
    second = new fed.EventDispatcher();
 
first.addListener(function (e) {
    console.log('event received!');
}, this);
 
first.relay(second);
 
second.dispatch(new fed.Event('SOME_EVENT', this)); // -> event received!

To stop proxying of events from other dispatcher:

var fed = require('frog-event-dispatcher'),
    first = new fed.EventDispatcher(),
    second = new fed.EventDispatcher();
 
first.addListener(function (e) {
    console.log('event received!');
}, this);
 
first.relay(second);
 
second.dispatch(new fed.Event('SOME_EVENT', this)); // -> event received!
 
first.unrelay(second);
 
second.dispatch(new fed.Event('SOME_EVENT', this)); // ->

To stop proxying of events from all dispatchers:

var fed = require('frog-event-dispatcher'),
    first = new fed.EventDispatcher(),
    second = new fed.EventDispatcher();
 
first.addListener(function (e) {
    console.log('event received!');
}, this);
 
first.relay(second);
 
second.dispatch(new fed.Event('SOME_EVENT', this)); // -> event received!
 
first.purgeDispatchers();
 
second.dispatch(new fed.Event('SOME_EVENT', this)); // ->

To check whether events are dispatching from a dispatcher:

var fed = require('frog-event-dispatcher'),
    first = new fed.EventDispatcher(),
    second = new fed.EventDispatcher();
 
console.log(first.relayed(second)); // -> false
first.relay(second);
console.log(first.relayed(second)); // -> true
first.unrelayAll([second]);
console.log(first.relayed(second)); // -> false

To send event with multiple targets (Added in release 1.2.0):

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    event;
 
dispatcher.addListener(function (e) {
    console.log('first listener');
}, this, 'EVENT:FIRST');
 
dispatcher.addListener(function (e) {
    console.log('second listener');
}, this, 'EVENT:SECOND');
 
event = new fed.Event({
    EVENT: ['FIRST', 'SECOND'] // The same as ['EVENT:FIRST', 'EVENT:SECOND']
}, this, false);
 
dispatcher.dispatch(event);
 
// -> first listener
// -> second listener

To add listener with extra data (Added in release 1.2.1):

var fed = require('frog-event-dispatcher'),
    dispatcher = new fed.EventDispatcher(),
    event;
 
dispatcher.addListener(function (e, extra) {
    console.log(extra);
}, this, 'EVENT:FIRST', {extra: 'first listener'});
 
dispatcher.addListener(function (e, extra) {
    console.log(extra);
}, this, 'EVENT:SECOND', {extra: 'second listener'});
 
event = new fed.Event({
    EVENT: ['FIRST', 'SECOND'] // The same as ['EVENT:FIRST', 'EVENT:SECOND']
}, this, false);
 
dispatcher.dispatch(event);
 
// -> first listener
// -> second listener

Cross relay events (Added in release 1.2.2)

var fed = require('frog-event-dispatcher'),
    firstDispatcher = new fed.EventDispatcher(),
    secondDispatcher = new fed.EventDispatcher(),
    event = new fed.Event(['FIRST', 'SECOND'], this);
 
firstDispatcher.addListener(function (e, extra) {
    console.log('first listener');
}, this, 'FIRST');
 
secondDispatcher.addListener(function (e, extra) {
    console.log('second listener');
}, this, 'SECOND');
 
firstDispatcher.relay(secondDispatcher);
secondDispatcher.relay(firstDispatcher);
 
firstDispatcher.dispatch(event);
// -> first listener
// -> second listener
 
secondDispatcher.dispatch(event);
// -> second listener
// -> first listener

License

MIT