Nomenclature Processing Machine
    Wondering what’s next for npm?Check out our public roadmap! »

    PubSub

    4.0.0 • Public • Published

    Build npm version npm downloads npm license Coverage Status PRs Welcome dependencies Status devDependencies Status

    PubSub

    Javascript implementation of the Publish/Subscribe pattern.

    Install

    npm

    $ npm install PubSub

    Usage

    The library is exported in UMD, CommonJS, and ESM formats. You can import it the following ways:

    Using ESM import statement

    import PubSub from 'PubSub';

    Using CommonJS require statement

    const PubSub = require('PubSub');
    
    // If you use a bundler like Webpack, you may need to import it the following way 
    // as it might try to use the ESM module instead of the CommonJS.
    const PubSub = require('PubSub').default; 

    Old school browser global

    <script src="https://unpkg.com/PubSub"></script>

    API

    new PubSub([options])

    Creates a PubSub instance.

    Available options

    Param Type Default Description
    immediateExceptions1 boolean false Force immediate exceptions (instead of delayed exceptions).

    1 Before version 3.6.0 PubSub would fail to deliver your topics to all subscribers if one or more failed (see issue #4). As of version 3.6.0 PubSub handles this by delaying thrown exceptions by default. You can set immediateExceptions to true or any truthy value in order to maintain the stack trace for development reasons but this is not recommended for production.

    Public Methods

    subscribe(topic, callback, [once]) ⇒ number

    Subscribe to events of interest with a specific topic name and a callback function, to be executed when the topic/event is observed.

    Kind: instance method of PubSub
    Returns: number - The topic's token

    Param Type Default Description
    topic string The topic's name
    callback function Callback function to execute on event, taking two arguments: - {*} data The data passed when publishing an event - {object} The topic's info (name & token)
    [once] boolean false Checks if event will be triggered only one time

    Example

    const pubsub = new PubSub();
    
    const onUserAdd = pubsub.subscribe('user_add', (data, topic) => {
      console.log('User added');
      console.log('user data:', data);
    });

    subscribeOnce(topic, callback) ⇒ number

    Subscribe to events of interest setting a flag indicating the event will be published only one time.

    Kind: instance method of PubSub
    Returns: number - The topic's token

    Param Type Description
    topic string The topic's name
    callback function Callback function to execute on event, taking two arguments: - {*} data The data passed when publishing an event - {object} The topic's info (name & token)

    Example

    const pubsub = new PubSub();
    
    const onUserAdd = pubsub.subscribeOnce('user_add', (data, topic) => {
      console.log('User added');
      console.log('user data:', data);
    });

    publish(topic, [data]) ⇒ boolean

    Publishes a topic asynchronously, passing the data to its subscribers.
    Asynchronous publication helps in that the originator of the topics will not be blocked while consumers process them.
    For synchronous topic publication check publishSync.

    Kind: instance method of PubSub
    Returns: boolean - Returns true if topic exists and event is published; otheriwse false

    Param Type Description
    topic string The topic's name
    [data] ...* The data to be passed to its subscribers

    Example

    const pubsub = new PubSub();
    
    pubsub.publish('user_add', {
      firstName: 'John',
      lastName: 'Doe',
      email: 'johndoe@gmail.com'
    });

    publishSync(topic, [data]) ⇒ boolean

    Publishes a topic synchronously, passing the data to its subscribers.

    Kind: instance method of PubSub
    Returns: boolean - Returns true if topic exists and event is published; otheriwse false

    Param Type Description
    topic string The topic's name
    [data] ...* The data to be passed to its subscribers

    Example

    const pubsub = new PubSub();
    
    pubsub.publishSync('user_add', {
      firstName: 'John',
      lastName: 'Doe',
      email: 'johndoe@gmail.com'
    });

    unsubscribe(topic) ⇒ boolean | string

    Unsubscribes from a specific topic, based on the topic name, or based on a tokenized reference to the subscription.

    Kind: instance method of PubSub
    Returns: boolean | string - Returns false if topic does not match a subscribed event; otherwise the topic's name

    Param Type Description
    topic string | number Topic's name or subscription reference

    Example

    const pubsub = new PubSub();
    
    // Unsubscribe using the topic's name.
    pubsub.unsubscribe('user_add');
    
    // Unsubscribe using a tokenized reference to the subscription.
    pubsub.unsubscribe(onUserAdd);

    unsubscribeAll() ⇒ PubSub

    Clears all subscriptions whatsoever.

    Kind: instance method of PubSub
    Returns: PubSub - The PubSub instance.
    Example

    const pubsub = new PubSub();
    
    pubsub.subscribe('message1', () => {});
    pubsub.subscribe('message2', () => {});
    pubsub.subscribe('message3', () => {});
    pubsub.unsubscribeAll();
    pubsub.hasSubscribers(); // -> false

    hasSubscribers([topic]) ⇒ boolean

    Checks if there are subscribers for a specific topic. If topic is not provided, checks if there is at least one subscriber.

    Kind: instance method of PubSub
    Returns: boolean - Returns true there are subscribers; otherwise false

    Param Type Description
    [topic] string The topic's name to check

    Example

    const pubsub = new PubSub();
    
    pubsub.on('message', data => console.log(data));
    
    pubsub.hasSubscribers('message');
    // -> true

    subscribers() ⇒ object

    Gets all the subscribers as a set of key value pairs that represent the topic's name and the event listener(s) bound.

    Kind: instance method of PubSub
    Returns: object - A readonly object with all subscribers.
    Note: Mutating the result of this method does not affect the real subscribers. This is for reference only.
    Example

    const pubsub = new PubSub();
    
    pubsub.subscribe('message', listener);
    pubsub.subscribe('message', listener);
    pubsub.subscribe('another_message', listener);
    
    pubsub.subscribers();
    // -> Object { message: Array[2], another_message: Array[1] }

    subscribersByTopic(topic) ⇒ array

    Gets subscribers for a specific topic.

    Kind: instance method of PubSub
    Returns: array - A copy array of all subscribers for a topic if exist; otherwise an empty array
    Note: Mutating the result of this method does not affect the real subscribers. This is for reference only.

    Param Type Description
    topic String The topic's name to check for subscribers

    Example

    const pubsub = new PubSub();
    
    pubsub.subscribe('message', listener1);
    pubsub.subscribeOnce('message', listener2);
    pubsub.subscribe('another_message', listener1);
    
    pubsub.subscribersByTopic('message');
    // -> Array [{token: 0, once: false, callback: listener1()}, {token: 1, once: true, callback: listener2()}]
    
    pubsub.subscribersByTopic('another_message');
    // -> Array [{token: 2, once: false, callback: listener1()}]
    
    pubsub.subscribersByTopic('some_message_not_existing');
    // -> Array []

    alias(aliasMap) ⇒ PubSub

    Creates aliases for public methods.

    Kind: instance method of PubSub
    Returns: PubSub - The PubSub instance.

    Param Type Description
    aliasMap Object A plain object that maps the public methods to their aliases.

    Example

    const pubsub = new PubSub().alias({
      subscribe: 'on',
      subscribeOnce: 'once',
      publish: 'trigger',
      publishSync: 'triggerSync',
      unsubscribe: 'off',
      hasSubscribers: 'has'
    });

    Static methods

    PubSub.createInstance([options]) ⇒ PubSub

    Creates a PubSub instance. This is an alternative way to create a new instance if you don't prefer using the new keyword.

    Kind: static method of PubSub
    Returns: PubSub - The PubSub constructor.
    Example

    const pubsub = PubSub.createInstance();

    Changelog

    For API updates and breaking changes, check the CHANGELOG.

    More about Publish/Subscribe pattern

    License

    The MIT License (MIT)

    Install

    npm i PubSub

    DownloadsWeekly Downloads

    1,473

    Version

    4.0.0

    License

    MIT

    Unpacked Size

    95.6 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar