podium
Node (semi) compatible event emitter with extra features.
podium is an event emitter with support for tags, filters, channels, event update cloning,
arguments spreading, and other features useful when building large scale applications.
While node's native EventEmitter
is strictly focused on maximum performance,
it lacks many features that do not belong in the core implementation. podium is not restricted by
node's performance requirement as it is designed for application layer needs where its overhead
is largely insignificant as implementing these features will have similar cost on top of the native emitter.
Lead Maintainer - Eran Hammer
new Podium(events)
This creates a new event emitter.
const Podium = require('podium');
const podiumObject = new Podium();
const podiumObject2 = new Podium('event1');
podium.registerEvent(events)
Registers an event event1
to emitter.
podiumObject.registerEvent('event1');
podiumObject.registerEvent({
name: 'event1',
shared: true
});
Using different parameters
podium.on(criteria, listener)
Subscribe a handler to an event. Handler can be seen as a function which will be called when the event occurs.
podiumObject.registerEvent('event1');
podiumObject.on('event1', function(update) {
console.log('inside autonomous listener without name! data:', update);
});
const listener1 = function() {
console.log('listener1 called');
}
podiumObject.on('event1', listener1);
podium.addListener(criteria, listener)
Same as podium.on()
.
podiumObject.addListener('event1', listener1);
podium.once(criteria, listener)
Same as calling podium.on()
with the count option set to 1. Whenever we call emit()
, listener1
will get fired
but also get removed, so that it won't get fired on call to emit()
.
podiumObject.once('event1', listener1);
podium.emit(criteria, data, [callback])
Emits an event update to all the subscribed listeners.
podiumObject.emit('event1', 'here we can send any data to listeners.');
podium.removeListener(name, listener)
Removes all listeners subscribed to a given event name matching the provided listener method.
podiumObject.removeListener('event1', listener1);
podium.removeAllListeners(name)
Removes all listeners subscribed to a given event name.
podiumObject.removeAllListeners('event1');
podium.hasListeners(name)
Returns whether an event has any listeners subscribed.
if (podiumObject.hasListeners('event1')){
console.log('this event has some listeners left');
}
else{
console.log('this event has no listeners');
}
podium.registerPodium(podiums)
Registers a podium object(emitter) to another podium object(source). Whenever any event gets registered on emitterObject
it gets registered on sourceObject
as well. But the reverse is not true.
const source1Object = new Podium('test');
const source2Object = new Podium('test');
const emitterObject = new Podium(source1Object);
emitterObject.registerPodium(source2Object);
const listener1 = function(){
console.log('listener1 called');
}
const listener2 = function(){
console.log('listener1 called');
}
emitterObject.on('test', listener1);
source1Object.on('test', listener2);
source1Object.emit('test', 1);
emitterObject.emit('test', 2);
Cookbook
channels
const Podium = require('podium');
const podiumObject = new Podium();
podiumObject.registerEvent([
{
name: 'event1',
channels: ['ch1', 'ch2', 'ch3', 'ch4'],
},
{
name: 'event2',
channels: ['ch1', 'ch2']
}
]);
const listener1 = (data) => {
console.log('listener1 called', data);
};
const listener2 = (data) => {
console.log('listener2 called', data);
};
podiumObject.on({
name: 'event1',
channels: ['ch1']
}, listener1);
podiumObject.on({
name: 'event1',
channels: ['ch3', 'ch4']
}, listener2);
podiumObject.on({ name: 'event1', channels: 'ch2' }, (data) => {
console.log('auto', data);
});
var arr = [0, 1, 2, 3, 4, 4, 5];
podiumObject.emit({
name: 'event1',
channel: 'ch3'
}, arr, function(err){
if (err){
console.log('callback error');
}
else{
console.log('callback returned true!');
}
});
clone
const Podium = require('podium');
const podiumObject = new Podium();
podiumObject.registerEvent([
{
name: 'event1',
channels: ['ch1', 'ch2'],
clone: true
},
{
name: 'event2',
channels: ['ch1', 'ch2']
}
]);
const listener1 = (data) => {
data[0] = 55;
console.log('listener1 called', data);
};
const listener2 = (data) => {
data[0] = 100;
console.log('listener2 called', data);
};
podiumObject.on({
name: 'event1',
channels: ['ch1']
}, listener1);
podiumObject.on({
name: 'event2',
channels: ['ch1']
}, listener2);
var arr = [0, 1, 2, 3, 4, 4, 5];
console.log('initially: ', arr);
podiumObject.emit({
name: 'event1',
channel: 'ch1'
}, arr, function(err){
if (err){
console.log('callback 1 error');
}
else {
console.log('callback 1 returned true!');
}
});
console.log('after event1, ch1: ', arr);
podiumObject.emit({
name: 'event2',
channel: 'ch1'
}, arr, function(err){
if (err){
console.log('callback 2 error');
}
else {
console.log('callback 2 returned true!');
}
});
console.log('after event2, ch1: ', arr);
spread
const Podium = require('podium');
const podiumObject = new Podium();
podiumObject.registerEvent([
{
name: 'event1',
channels: ['ch1', 'ch2'],
spread: true
},
{
name: 'event2',
channels: ['ch1', 'ch2']
}
]);
const listener1 = (data1, data2, data3, data4) => {
console.log('listener1 called', data1, data2, data3, data4);
};
const listener2 = (data) => {
data[0] = 100;
console.log('listener2 called', data);
};
podiumObject.on({
name: 'event1',
channels: ['ch1']
}, listener1);
podiumObject.on({
name: 'event2',
channels: ['ch1']
}, listener2);
var arr = [0, 1, 2, 3, 4, 4, 5];
console.log('initially: ', arr);
podiumObject.emit({
name: 'event1',
channel: 'ch1'
}, arr, function(err){
if (err){
console.log('callback 1 error');
}
else {
console.log('callback 1 returned true!');
}
});
console.log('after event1, ch1: ', arr);
podiumObject.emit({
name: 'event2',
channel: 'ch1'
}, arr, function(err){
if (err){
console.log('callback 2 error');
}
else {
console.log('callback 2 returned true!');
}
});
console.log('after event2, ch1: ', arr);
shared
const Podium = require('podium');
const podiumObject = new Podium();
podiumObject.registerEvent([
{
name: 'event1',
channels: ['ch1', 'ch2'],
}
]);
podiumObject.registerEvent([
{
name: 'event1',
channels: ['ch1', 'ch2'],
shared: true
}
]);
const listener2 = (data) => {
console.log('listener2 called', data);
};
podiumObject.on({
name: 'event1',
channels: ['ch1']
}, listener2);
var arr = [0, 1, 2, 3, 4, 4, 5];
podiumObject.emit({
name: 'event1',
channel: 'ch1'
}, arr, function(err){
if (err){
console.log('callback 1 error');
}
else {
console.log('callback 1 returned true!');
}
});
tag-filter
const Podium = require('podium');
const emitter = new Podium('test');
const updates = [];
emitter.on('test', (data) => updates.push({ id: 1, data }));
emitter.on({ name: 'test', filter: ['a', 'b'] }, (data) => updates.push({ id: 2, data }));
emitter.on({ name: 'test', filter: 'b' }, (data) => updates.push({ id: 3, data }));
emitter.on({ name: 'test', filter: ['c'] }, (data) => updates.push({ id: 4, data }));
emitter.on({ name: 'test', filter: { tags: ['a', 'b'], all: true } }, (data) => updates.push({ id: 5, data }));
emitter.emit({ name: 'test', tags: 'a' }, 1);
emitter.emit({ name: 'test', tags: ['b'] }, 2);
emitter.emit({ name: 'test', tags: ['d'] }, 3);
emitter.emit({ name: 'test', tags: ['a'] }, 4);
emitter.emit({ name: 'test', tags: ['a', 'b'] }, 5);
emitter.emit('test', 6, () => {
console.log(updates);
});
count
const Podium = require('podium');
const podiumObject = new Podium();
podiumObject.registerEvent('event1');
const listener1 = function(data) {
console.log('listener1 called', data);
};
podiumObject.on({
name: 'event1',
count: 2
}, listener1);
podiumObject.emit('event1', 'emit 1');
podiumObject.emit('event1', 'emit 2');
podiumObject.emit('event1', 'emit 3');
API
The full API is available in the API documentation.