Nocturnal Prancing Mosquito

    @evercoder/pubsub

    1.0.0 • Public • Published

    pubsub

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

    Usage

    npm install --save @evercoder/pubsub

    API Reference

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

    Available options:

    • strict: (Boolean, default false) deprecates some ways of using pubsub that we found were promoting error-prone code patterns and restricts the message bus to a subset of its API. See Strict Mode.
    import pubsub from '@evercoder/pubsub';
    
    let bus = new pubsub();

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

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

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

    Note: Although the library supports multiple arguments, we plan to deprecate 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, default false) whether the listener should unsubscribe itself from the event after being called once.
    • 👎 recoup (Boolean, default false) whether the listener should be immediately executed if the event already happened before the subscription.

    § 👎 bus.recoup(event, listener, thisArg) is a shortcut for calling sub() with the recoup: true option.

    Note: This option will be deprecated.

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

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

    Note: Currently, when listener is omitted, all listeners on that particular event are unsubscribed. We plan to deprecate this feature.

    Strict mode

    In strict mode, the following patterns log a warning:

    pub()-ing an event with multiple arguments

    Always use a single argument for the payload.

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

    sub()-ing to multiple events via a space-separated string

    Always use an array 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() { ... });

    sub(): using thisArg;

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

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

    Storing thisArg in the pubsub instance may create memory leaks.

    Using recoup()

    Find an alternative where you can use a simple sub().

    Similar to storing thisArg for sub(), storing the arguments with which pub was called, so that listeners could listen to that event retroactively, can create memory leaks or subtle inconsistencies in state.

    unsub() called without a listener

    Always provide the listener you wish to unsubscribe.

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

    Keywords

    none

    Install

    npm i @evercoder/pubsub

    DownloadsWeekly Downloads

    5

    Version

    1.0.0

    License

    none

    Unpacked Size

    10.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • danburzo
    • darung
    • adig