cruks-lib-event v1.8.1

(Reactive) Event Dispatcher

R.E.D. stands for Reactive Event Dispatcher.

Alongside standard event emitting mechanism, this library provides some additional utilities like compatibility with Reactive Extensions, event aggregator and generic event dispatching repository.

This library is partially modeled after symfony/EventDispatcher.

Examples

Basic usage

Dispatching events

var EventDispatcher = require("cruks-lib-event").EventDispatcher,
    eventDispatcher = new EventDispatcher();

eventDispatcher.getSupportedEvents = function () {
    return ["a"];
};

eventDispatcher.addListener("a", function (evt) {
    console.log("hello %s!", evt.data.place); // hello world
});

eventDispatcher.dispatch("a", { place: "world" });

Dispatching promises

var PromiseDispatcher = require("cruks-lib-event").PromiseDispatcher,
    promiseDispatcher = new PromiseDispatcher();

promiseDispatcher.getSupportedEvents = function () {
    return ["myevent"];
};

promiseDispatcher.addListener("myevent", function (evt) {
    setTimeout(function () {
        evt.resolve(1);
    }, 1000);
});

promiseDispatcher.addListener("myevent", function (evt) {
    evt.resolve(2);
});

promiseDispatcher.dispatch("myevent")
    .toPromise()
    .then(function (results) {
        // results are always aligned in order of listeners execution and
        // not in order of event resolving time
        results; // [1, 2]
    });

Advanced usage

Reactive Extensions compatibility

See also rxjs and compatibility tests.

var dispatcher = new MyEventDispatcher();

Rx.Observable
    .zip(
        dispatcher.observe("A"),
        dispatcher.observe("B"),
        function (evtA, evtB) {
            return evtA.data + ":" + evtB.data;
        }
    )
    .subscribe(function (data) {
        // "A1:B1" at first call
        // "A2:B2" at second call
        console.log(data);
    });

dispatcher.dispatch("A", "A1");
dispatcher.dispatch("A", "A2");

dispatcher.dispatch("B", "B1");
dispatcher.dispatch("B", "B2");

Exposing single module entry point using two combined modules

// module/a.js

var eventAggregator,
    eventDispatcherAB = require("foo").eventDispatcherAB,
    eventDispatcherC = require("bar").eventDispatcherC;

eventAggregator = new EventAggregator();

eventAggregator.add(eventDispatcherAB);
eventAggregator.add(eventDispatcherC);

module.exports = eventAggregator;

// module/b.js

var a = require("a");

// eventDispatcherAB is going to handle this
a.addListener("a", function () {});

// eventDispatcherAB is going to handle this
a.addListener("b", function () {});

// eventDispatcherC is going to handle this
a.addListener("c", function () {});

Observable

This package provides module that can turn any object into event dispatcher.

var Observable = require("cruks-lib-event").Observable,
    foo = {};

assert.notOk(Observable.isObservable(foo)); // false

foo = Observable.mixin(foo, ["greeting"]);

assert.ok(Observable.isObservable(foo)); // true

Observable(foo).addListener("greeting", function (evt) {
    console.log(evt.data, "world"); // hello world
});

Observable.dispatch(foo, "greeting", "hello");

Semantic Versioning

This repository follows Semantic Versioning convention.