ni-pubsub-composite

Composite function to add the publish–subscribe pattern to an object.

Install using npm

$ npm install ni-pubsub-composite --save

Usage

// Import the Module
import pubsubComposite from 'ni-pubsub-composite'

// Create an object or have one already
const someObject = {};

// Add publish–subscribe pattern to object
pubsubComposite(someObject);

API

• .subscribe(topic, callback, [once]) ⇒ number
• .publish(topic, [data]) ⇒ boolean
• .unsubscribe(topic) ⇒ boolean | string
• .unsubscribeAll() ⇒ PubSub
• .hasSubscribers([topic]) ⇒ Boolean
• .subscribers() ⇒ object
• .alias(aliasMap) ⇒ PubSub

new PubSub()

Creates a PubSub instance.

pubSub.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 this: {PubSub}

| 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);
});

pubSub.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 this: {PubSub}

| 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 onUserAdd = pubsub.subscribeOnce('user_add', function (data, topic) {
  console.log('User added');
  console.log('user data:', data);
});

pubSub.publish(topic, [data]) ⇒ boolean

Publishes a topic, passing the data to its subscribers.

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

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

Example

pubsub.publish('user_added', [{
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]'
}]);

pubSub.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 this: {PubSub}

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

Example

// Unsubscribe using the topic's name.
pubsub.unsubscribe('user_add');

// Unsubscribe using a tokenized reference to the subscription.
pubsub.unsubscribe(onUserAdd);

pubSub.unsubscribeAll() ⇒ PubSub

Clears all subscriptions whatsoever.

Kind: instance method of PubSub Returns: PubSub - The PubSub instance. this: {PubSub} Example

var pubsub = new PubSub();
...
...
pubsub.unsubscribeAll();

pubSub.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 this: {PubSub}

| 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

pubSub.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. this: {PubSub} 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] }

pubSub.alias(aliasMap) ⇒ PubSub

Creates aliases for public methods.

Kind: instance method of PubSub Returns: PubSub - The PubSub instance. this: {PubSub}

| 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'
});