Documentation

PubSub

Javascript implementation of the Publish/Subscribe pattern.

Build Status npm version npm downloads npm license Code Climate Issue Count Codecov PRs Welcome Dependencies devDependency Status

Install

npm

$ npm install PubSub

Old school browser global

<script src="https://unpkg.com/PubSub@<YOUR_PREFERRED_VERSION>/dist/pubsub.min.js"></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 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

var pubsub = new PubSub();

var onUserAdd = pubsub.subscribe('user_add', function (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

var pubsub = new PubSub();

var onUserAdd = pubsub.subscribeOnce('user_add', function (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

var 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

var 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

var 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

var pubsub = new PubSub();

pubsub.subscribe('message1', function () {});
pubsub.subscribe('message2', function () {});
pubsub.subscribe('message3', function () {});
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

var pubsub = new PubSub();

pubsub.on('message', function (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

var 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

var 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

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

Static methods

PubSub.noConflict() ⇒ PubSub

Rolls back the global PubSub identifier and returns the current constructor function. This can be used to keep the global namespace clean, or it can be used to have multiple simultaneous libraries (including separate versions/copies of PubSub) in the same project without conflicts over the PubSub global identifier.

Kind: static method of PubSub
Returns: PubSub - The PubSub constructor.
Note: The PubSub.noConflict() static method only makes sense when used in a normal browser global namespace environment. It should not be used with CommonJS or AMD style modules.
Example

var EventEmitter = PubSub.noConflict();
var emitter = new EventEmitter();

Minify source code

$ npm run build

This will run the remove logging and uglify the code into dist/pubsub.min.js.

Test

To run the tests:

$ npm test

Changelog

For API updates and breaking changes, check the CHANGELOG.

More about Publish/Subscribe pattern

License

The MIT License (MIT)