theatre-events v1.1.9

Theatre Events

This library is a part of the Theatre module. You can use it ase is or with a complete Theatre installation.

About

Theatre Events is a short but complete implementation of a standard ÈventDispatcher, EventEmitter and EventBroadcaster. It can be use as a standalone module in any project to start helping you building robust events system.

Installation

npm install theatre-events --save

Quick Start

This module brings 3 usefull and flexible components: the EventDispatcher, the EventBroadcaster and the EventEmitter. Both cames with a synchronous and asynchronous implementation.

EventDispatcher: Synchronous

import {SynchronousEventDispatcher} from 'theatre-events';

let dispatcher = new SynchronousEventDispatcher();

// Register also supports symbols
dispatcher.addEventListener('My Event', (myPayload) => {
    console.log(myPayload);
});

// This command will log "{name: 'test'}"
dispatcher.dispatch('My Event', {name: 'test'});

EventDispatcher: Asynchronous

import {AsynchronousEventDispatcher} from 'theatre/events';

let dispatcher = new AsynchronousEventDispatcher();

dispatcher.addEventListener('send email', (emailPayload) => {
    sendMail(emailPayload);
});

// The dispatch method will not be blocking, so you can send your email
// and do other stuff during the mail is processed
dispatcher.dispatch('send email', {
    subject: 'Do you heard about theatre components ?',
}).then(d => console.log('The email has been sent')).catch(console.error);

Event Emitter: Synchronous

It is quite the same API as an EventDispatcher.

import {SynchronousEventEmitter} from 'theatre-events';

// You can pass an instance of a `SynchronousEventDispatcher`. If you do so,
// the event emitter will be a simple wrap of the dispatcher.
let emitter = new SynchronousEventEmitter();

emitter.on('test', (payload) => {
    payload.name = 'test';
});

let data = {};
emitter.emit('test', data);

console.log(data.name);

Event Emitter: Asynchronous

import {AsynchronousEventEmitter} from 'theatre-events';

let emitter = new AsynchronousEventEmitter();

emitter.on('test', (payload) => {
    payload.name = 'test';
});

let data = {};
emitter.emit('test', data).then(() => {
    console.log(data.name);
}).catch(console.error);

Event Broadcaster: Synchronous

Event broadcaster is very similar to an event dispatcher but it don't use named event.

import {SynchronousEventBroadcaster} from 'theatre-events';

let broadcaster = new SynchronousEventBroadcaster();

broadcaster.subscribe((data) => {
    data.name ='test';
});

let data = {};
broadcaster.broadcast(data);

console.log(data.name);

Event Broadcaster: Asynchronous

import {AsynchronousEventBroadcaster} from 'theatre-events';

let broadcaster = new AsynchronousEventBroadcaster();

broadcaster.subscribe((data) => {
    data.name ='test';
});

let data = {};
broadcaster.broadcast(data).then(() => {
    console.log(data.name);
}).catch(console.error);

Event listener priority

You can control the execution priority of your listeners:

import {SynchronousEventDispatcher, LOW_PRIORITY, HIGH_PRIORITY} from 'theatre-events';

let dispatcher = new SynchronousEventDispatcher();

function sendLast() {
    console.log('Must be the last event');
}

function sendFirst() {
    console.log('Must be the first');
}

// You can also assign an integer. The highest the integer is
// the latest it will be triggered. By default you can use:
// LOW_PRIORITY = 255
// NORMAL_PRIORITY = 0
// HIGH_PRIORITY = -255
sendLast.priority = LOW_PRIORITY;
sendFirst.priority = HIGH_PRIORITY;

dispatcher.addEventListener('send message', sendLast);
dispatcher.addEventListener('send message', sendFirst);

dispatcher.dispatch('test');