A tiny <1KB pub-sub-based event library that lets you send custom message within and cross the window! It's written in ES6 and makes use of the awesome Broadcast Channel API.
Demo: pub-sub.lekschas.de
npm -i -D pub-sub-es
import createPubSub from 'pub-sub-es';
// Creates a new pub-sub event listener stack.
const pubSub = createPubSub();
// Subscribe to an event
const myEmojiEventHandler = msg => console.log(`🎉 ${msg} 😍`);
pubSub.on('my-emoji-event', myEmojiEventHandler);
// Publish an event
pubSub.publish('my-emoji-event', 'Yuuhuu'); // >> 🎉 Yuuhuu 😍
// Unsubscribe
pubSub.unsubscribe('my-emoji-event', myEmojiEventHandler);
pub-sub-es
exports the factory function (createPubSub
) for creating a new pub-sub service by default and a global pub-sub service (globalPubSub
). The API is the same for both.
Creates a new pub-sub instances
Arguments:
-
options
is an object for customizing pubSub. The following properties are understood:-
async
: whentrue
, events are published asynchronously to decouple the process of the originator and consumer. -
caseInsensitive
: whentrue
, event names are case insensitive -
stack
: is an object holding the event listeners and defaults to a new stack when being omitted.
-
Returns: a new pub-sub service
Publishes or broadcasts an event with some news or payload
Arguments:
-
event
is the name of the event to be published. -
news
is an arbitrary value that is being broadcasted. -
options
is an object for customizing the behavior. The following properties are understood:-
async
: overrides the globalasync
flag for a single call. -
isNoGlobalBroadcast
: overrides the globalisGlobal
flag for a single call.
-
Subscribes a handler to a specific event
-
event
is the name of the event to be published. -
handler
is the handler function that is being called together with the broadcasted value. -
times
is the number of times the handler is invoked before it's automatically unsubscribed.
Returns: an object of form { event, handler }
. This object can be used to automatically unsubscribe, e.g., pubSub.unsubscribe(pubSub.subscribe('my-event', myHandler))
.
Unsubscribes a handler from listening to an event
-
event
is the name of the event to be published. Optionally,unsubscribe
accepts an object of form{ event, handler}
coming fromsubscribe
.
Removes all currently active event listeners and unsets the event times.
Note: this endpoint is not available on the global pub-sub because it could have undesired side effects. You need to unsubscribe global event listeners manually instead.
The global pub-sub instance is created when pub-sub-es.js
is loaded and provides a way for
global messaging within and between contexts. It utilizes the Broadcast Channel API, which is currently not available in all browsers. If you need to support more browsers you have to load a polyfill. PubSubES is not taking care of that! Also, when sending sending objects from one context to another you have to make sure that they are clonable. For example, trying to broadcast a reference to a DOM element will fail.
You might have come across the awesome PubSubJS library and wonder which one to choose. First of all, both are tiny, have no dependencies, and offer async event broadcasting. The two main features that PubSubES offers are:
-
Auto-unsubscribable event listening: via
pubSub.subscribe(eventName, eventHandler, t)
you can make theeventHandler
unsubscribed fromeventName
automatically aftereventName
was broadcastedt
times. -
Between-context messaging: PubSubES supports the new Broadcast Channel API so you can send events between different browser contexts, e.g., tabs.