Event Bus


Simple event bus for your JavaScript application without any dependencies and with a low size footprint.

Installation:

$3

``
npm install --save eventing-bus
`

$3

`
yarn add eventing-bus
`

or for NPM:

`
npm install --save eventing-bus
`

Global event bus

By default exports in JavaScript are evaluated only once. This way we can ensure to have one global event bus without doing anything on our side.

There is also a possibility to define an event stream separately from the global bus.

Subscribing to events:

``javascript
import EventBus from 'eventing-bus'

const callback = (name) => { console.log(Hello, ${name}!) };

EventBus.on("exampleEventName", callback);
``

Publishing events:

``javascript
import EventBus from 'eventing-bus';

EventBus.publish("exampleEventName", "Watson");
/* After registering the subscription and publishing an event you should see
"Hello, Watson!" printed in your console. */
``

More than one event bus:

By default you have only one, singleton event bus instance which holds subscriptions from all parts of your application. But nothing stands on your way to create your own, private instances (for example, for each logically distinct part of your complex app):

``javascript
import EventStream from 'eventing-bus/lib/event_stream';

/ You can use EventStream both as a constructor and as a factory function. /
const privateBus = EventStream();
const newPrivateBus = new EventStream();
``

Those _streams_ created by you won't share any subscriptions, nor events.

Unregistering event handlers:

If you need to unregister a subscription – a typical case would be when cleaning after your UI library – you can do it in two ways:

#### Call value returned by #on

After registering an event handler, a return calue will be a function unregistering the specific handler.

``javascript
import EventBus from 'eventing-bus';

const subscription = EventBus.on('event', () => { console.log('test') })

EventBus.publish('event') // Console: 'test'

// This will unregister this (and only this) subscription.
subscription();

EventBus.publish('event') // No output in console
``

#### Use #unregisterCallback

In case you have no easy access to value returned by #on, you can just call #unregisterCallback. Additional benefit is that this function does not require knowing an event name. This way you can de-register every single usage of suck callback.

``javascript
import EventBus from 'eventing-bus';

const callback = () => { console.log('test') }

EventBus.on('eventA', callback)
EventBus.on('eventB', callback)

EventBus.publish('eventA') // Console: 'test'
EventBus.publish('eventB') // Console: 'test'

EventBus.unregisterCallback(callback)

EventBus.publish('eventA') // No output in console
EventBus.publish('eventB') // No output in console
``

Unregistering subscriptions in bulk:

Since by default EventBus is a singleton instance of the bus, there may be occasions where you need to unregister all subscriptions (most notably - during testing). It can be done by calling following methods:


#### #unregisterAllCallbacks

Removes all event handlers.

``javascript
import EventBus from 'eventing-bus';

EventBus.unregisterAllCallbacks();
``

#### #unregisterCallbacksForEvent

Remvoes all event handlers for specific event

``javascript
import EventBus from 'eventing-bus';

EventBus.on('exampleEvent', () => { console.log("EXAMPLE") });
EventBus.publish("exampleEvent"); // Logs EXAMPLE

EventBus.unregisterCallbacksForEvent('exampleEvent');

EventBus.publish("exampleEvent"); // Empty output
``

Compatibility

If you want to use this library on legacy browsers (IE <= 8 etc.), you need to
provide polyfills for Array.forEach and Array.filter` functions. Check out e.g.
es5-shim to read more.

Contributing

Feel free to report any issue or idea on the GitHub page of this project. If you report an issue, please try to provide reproducing steps or any piece of code that can reproduce the issue.