newsflash.js
v0.1.1
Published
A Multi-Event enabled Pub-Sub module
Downloads
4
Readme
newsflash.js
A Multi-Event enabled Pub-Sub implementation
Overview
Newsflash.js is a Multi-Event enabled, Pub-Sub event-aggregator. In short, this means you can register an event handler to only run once multiple events 'foo' AND 'bar' have been published.
It has all the standard features you'd expect to see in a pub-sub implementation:
on(event, handler)
off(event, handler)
once(event, handler)
emit(event, data)
Motivation
Does the following scenario sound familiar:
You need to run function foo()
only if
bar
has already happenedbaz
has already happenedIf any of these happened without the other - don't trigger
foo()
.
If you've ever had to implement this, you probably ended up saving some state-data in a shared scope, or worse - using timers.
Newsflash.js
to the rescue! No need to manage shared state-date or timers. It's as simple as registering an event handler - for multiple events.
Usage
Using the example above, where we need to run foo()
- but only if both bar
and baz
have occured, we can now do this:
function foo(){
// I need both 'bar' and 'baz' to run
}
var subscription = on(['bar', 'baz'], foo);
// At some later point, 'bar' occurs
emit('bar');
// At an even later point, 'baz' occurs
emit('baz');
// At this point, 'foo()' gets called
It's that simple.
A few notes to be aware of:
You can of course subscribe to 'bar' and 'baz' separtely, as each of them stands as a single event on it's own.
A multi-event only gets called after a full-events-cycle is complete. This simply means that anytime you want to trigger the multi-event function
foo()
, you have to emit BOTHbar
andbaz
(and all over again the next time you want to triggerfoo()
).There's a shortcut for triggering multi-events (in case you need to run
foo()
immediately at some point):
// 'foo()' gets called immediately
// Also, if 'bar' or 'baz' have any event handlers on their own, they will also be triggered
emit(['bar', 'baz']);
- A multi-event is simply denoted as an array of events:
['even1', 'event2', ..., 'eventN']
API
on(event, handler)
Registers handler
as a callback to run every time event
is triggered. This function will return a subscription-id
which can be used at a later point to un-subscribe to the event.
event
As aString
, a single event to register to.
As anArray
of strings, a multi-event to register to. The order of the events in the array does not matter (it gets normalized internally).handler
Function callback that will get called whenever the event is published. If any data was published with the event, the callback will get this data as its only argument.
Example (single event):
var subscription = on('foo', function(){
console.log('event "foo" fired');
});
// later, when we're done with this event:
// off('foo', subscription);
Example (multi-event):
var subscription = on(['foo', 'bar'], function(){
console.log('multi-event "foo, bar" fired');
});
// later, when we're done with this multi-event:
// off(['foo', 'bar'], subscription);
off(event, subscription)
Un-subscribe the handler associated with subscription
from event
. The subscription
is created and returned by the on(...)
API.
event
As aString
, a single event to un-subscribe to.
As anArray
of string, a multi-event to un-subscribe to. The order of the events in the array does not matter (it gets normalized internally).subscription
The subscription-id that was generated when theevent
was registered.
Example (single event):
// Assuming we got '1234' from an earlier call to 'on(...)'
off('foo', '1234');
Example (multi-event):
// Assuming we got '1234' from an earlier call to 'on(...)'
off(['foo', 'bar'], '1234');
once(event, handler)
Same as on(...)
only the handler
will only get triggered once, and will then be removed from the event
. Any subsequent publications to event
will NOT trigger handler
(it has been deleted).
event
As aString
, a single event to register to.
As anArray
of strings, a multi-event to register to. The order of the events in the array does not matter (it gets normalized internally).handler
Function callback that will get called ONLY ONE TIME, once the event is published. If any data was published with the event, the callback will get this data as the only argument.
Example (single event):
var subscription = once('foo', function(){
console.log('event "foo" fired');
});
Example (multi-event):
var subscription = once(['foo', 'bar'], function(){
console.log('multi-event "foo, bar" fired');
});
emit(event, data)
Emits event
, passing any received data
to the registered handler(s).
event
As aString
, a single event to emit.
As anArray
of strings, a multi-event to emit. The order of the events in the array does not matter (it gets normalized internally).data
(optional) Any type of data that you want to pass to a registered event handler.
Example (single event, no data):
emit('foo');
Example (multi-event, string-data):
emit(['foo', 'bar'], 'newsflash is awesome!');