Repository files navigation

pubsub is a small, fast JavaScript library that implements thePublish/Subscribe pattern for web applications.

npminstall--save @evercoder/pubsub

§new pubsub(options) creates a new message bus.

Available options:

• strict: (Boolean, defaultfalse) deprecates some ways of usingpubsub that we found were promoting error-prone code patterns and restricts the message bus to a subset of its API. SeeStrict Mode.

importpubsubfrom'@evercoder/pubsub';letbus=newpubsub();

§ bus.pub(event,payload, ...additional_args) — publish an event.

bus.pub('my-event',{myprop:myvalue});

Allpub() arguments after the event are forwarded as-is as arguments to the listeners.

Note: Although the library supports multiple arguments, we plan todeprecate this feature.

§ bus.sub(event(s),listener,thisArg,options) — subscribe a listener to an event.

bus.sub('my-event',function(payload){console.log(payload.myrop);// ⇒ myvalue});

Available options:

• once (Boolean, defaultfalse) whether the listener should unsubscribe itself from the event after being called once.
• 👎recoup (Boolean, defaultfalse) whether the listener should be immediately executed if the event already happened before the subscription.

§ 👎 bus.recoup(event,listener,thisArg) is a shortcut for callingsub() with therecoup: true option.

Note: This optionwill be deprecated.

§ bus.once(event,listener,thisArg) is a shortcut for callingsub() with theonce: true option.

§ bus.unsub(event,listener) — unsubscribe a listener from an event.

Note: Currently, whenlistener is omitted, all listeners on that particular event are unsubscribed. We plan todeprecate this feature.

In strict mode, the following patterns log a warning:

Always use a single argument for the payload.

Handling multiple arguments means the library needs to manipulate thearguments object to properly forward them to the listeners. Renouncing this will allow us to make a faster library by leveraging browser code optimizations.

Always use anarray of events as the first argument to subscribe to many events at once.

A previous version of the library did not support arrays and used space-separated strings. When using statically analyzable event names, it made you use an awkward construct:

bus.sub([EVENT_A,EVENT_B].join(''),function(){ ...});

Instead, bind the listener manually withbind() or using an arrow function.

bus.sub('myevent',function(){this.doSomething();}.bind(this));// orbus.sub('myevent',()=>{this.doSomething();});

StoringthisArg in thepubsub instance may create memory leaks.

Find an alternative where you can use a simplesub().

Similar to storingthisArg forsub(), storing the arguments with whichpub was called, so that listeners could listen to that event retroactively, can create memory leaks or subtle inconsistencies in state.

Always provide the listener you wish to unsubscribe.

The default behavior here (unsubscribingall listeners from the event) may cause hard-to-trace bugs ifunsub() silently receives an undefined reference to a listener.