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://cdn.jsdelivr.net/npm/PubSub@latest/dist/PubSub.umd.min.js"></script>

API

• PubSub
  • new PubSub([options])
  • instance
    • .subscribe(topic, callback, [once]) ⇒ <code>number</code>
    • .subscribeOnce(topic, callback) ⇒ <code>number</code>
    • .publish(topic, [...data]) ⇒ <code>boolean</code>
    • .publishSync(topic, [...data]) ⇒ <code>boolean</code>
    • .unsubscribe(topic) ⇒ <code>boolean</code> | <code>string</code>
    • .unsubscribeAll() ⇒ <code>PubSub</code>
    • .hasSubscribers([topic]) ⇒ <code>boolean</code>
    • .subscribers() ⇒ <code>object</code>
    • .subscribersByTopic(topic) ⇒ <code>array</code>
    • .alias(aliasMap) ⇒ <code>PubSub</code>
  • static
    • .createInstance([options]) ⇒ <code>PubSub</code>

<a name="new_PubSub_new"></a>

new PubSub([options])

Creates a PubSub instance.

Available options

| Param | Type | Default | Description | | --- | --- | --- | --- | | immediateExceptions¹ | <code>boolean</code> | <code>false</code> | Force immediate exceptions (instead of delayed exceptions). |

¹ 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

<a name="PubSub+subscribe"></a>

subscribe(topic, callback, [once]) ⇒ <code>number</code>

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 <code>PubSub</code>
Returns: <code>number</code> - The topic's token

| Param | Type | Default | Description | | --- | --- | --- | --- | | topic | <code>string</code> | | The topic's name | | callback | <code>function</code> | | 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] | <code>boolean</code> | <code>false</code> | 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);
});

<a name="PubSub+subscribeOnce"></a>

subscribeOnce(topic, callback) ⇒ <code>number</code>

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

Kind: instance method of <code>PubSub</code>
Returns: <code>number</code> - The topic's token

| Param | Type | Description | | --- | --- | --- | | topic | <code>string</code> | The topic's name | | callback | <code>function</code> | 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);
});

<a name="PubSub+publish"></a>

publish(topic, [data]) ⇒ <code>boolean</code>

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 <code>PubSub</code>
Returns: <code>boolean</code> - Returns true if topic exists and event is published; otheriwse false

| Param | Type | Description | | --- | --- | --- | | topic | <code>string</code> | The topic's name | | [data] | <code>...*</code> | 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'
});

<a name="PubSub+publishSync"></a>

publishSync(topic, [data]) ⇒ <code>boolean</code>

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

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

| Param | Type | Description | | --- | --- | --- | | topic | <code>string</code> | The topic's name | | [data] | <code>...*</code> | 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'
});

<a name="PubSub+unsubscribe"></a>

unsubscribe(topic) ⇒ <code>boolean</code> | <code>string</code>

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

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

| Param | Type | Description | | --- | --- | --- | | topic | <code>string</code> | <code>number</code> | 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);

<a name="PubSub+unsubscribeAll"></a>

unsubscribeAll() ⇒ <code>PubSub</code>

Clears all subscriptions whatsoever.

Kind: instance method of <code>PubSub</code>
Returns: <code>PubSub</code> - The PubSub instance.
Example

const pubsub = new PubSub();

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

<a name="PubSub+hasSubscribers"></a>

hasSubscribers([topic]) ⇒ <code>boolean</code>

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 <code>PubSub</code>
Returns: <code>boolean</code> - Returns true there are subscribers; otherwise false

| Param | Type | Description | | --- | --- | --- | | [topic] | <code>string</code> | The topic's name to check |

Example

const pubsub = new PubSub();

pubsub.on('message', data => console.log(data));

pubsub.hasSubscribers('message');
// -> true

<a name="PubSub+subscribers"></a>

subscribers() ⇒ <code>object</code>

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 <code>PubSub</code>
Returns: <code>object</code> - 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] }

<a name="PubSub+subscribersByTopic"></a>

subscribersByTopic(topic) ⇒ <code>array</code>

Gets subscribers for a specific topic.

Kind: instance method of <code>PubSub</code>
Returns: <code>array</code> - 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 | <code>String</code> | 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 []

<a name="PubSub+alias"></a>

alias(aliasMap) ⇒ <code>PubSub</code>

Creates aliases for public methods.

Kind: instance method of <code>PubSub</code>
**Re