pubsubtle v0.4.0

pubsubtle

Yet another publish/subscribe system for JavaScript.

npm install pubsubtle

Usage

var PubSub = require('pubsubtle');
var Q = require('q');

// Create an instance and provide a promise factory.
var pubsub = PubSub.create(Q.promise.bind(Q));

var obj = {};

var sub = pubsub.subscribe(obj, 'update', function () {
  console.log('obj was updated');
});

obj.foo = 42;

// Notify subscribers about a changed property on `obj`.
pubsub.publish(obj, 'update');

API

Publish/Subscribe

.create(createPromise)

Create a new publish/subscribe system. Publication made to this instance can only be received by subscriptions made to this very instance. The function createPromise must create a promise according to Promises/A+. Libraries that provide such a function are, among others, Q or when. Instead of adding an own dependency it makes more sense to let users of this library decide which promise library they want to use. This way we can avoid dependency on possibly multiple promise libraries which is not optimal when bundling code for browser usage.

#subscribe(target, topic, handler)

Subscribe to publications on some target and topic. Function handler will be called when a publication occurs. Handlers may return a promise that should be resolved or rejected once the handler is done. Returns an enabled subscription object.

#publish(target, topic, data)

Publish to target and topic using JavaScript's macrotask queue. All enabled subscriptions for this very target and topic will get there handlers called. Optionally, arbitrary data can be passed to each subscription handler. Returns a promise which will be resolved once all enabled subscription handlers are done. The promise will be rejected when publication is not possible (cf. #canPublish). When some handler returns nothing an automatically resolved promise will be used instead as if the handler had returned that promise itself. This is useful when a handler does not actually need a promise because of a simple synchronous task.

#priorityPublish(target, topic, data)

Analoguous to #publish except that JavaScript's microtask queue is used.

#propagate(target, topic, options)

Create a subscription which automatically calls #priorityPublish with a possibly different target options.target and topic options.topic. Returns the enabled subscription object. Propagation target and topic must not be the same (strict equality) as target and topic respectively as this would create an infinite loop. Because options.target defaults to target and options.topic defaults to topic, one of the two has to be specified. Option options.filter allows to filter publications before they are propagated which is the case when the filter returns truthy. Option options.isolate allows an array of subscriptions to be isolated from the propagation using #isolate.

This method is a shorthand for the following code except for error checking:

pubsub.subscribe(target, topic, function () {
  if (options.filter()) {
    pubsub.isolate(options.isolate, function () {
      pubsub.priorityPublish(options.target || target, options.topic || topic);
    });
  }
});

#isolate(subs, fn)

Isolate subscriptions subs from the execution of fn. All enabled subscriptions are disabled and re-enabled once the execution completes. Function fn must return a promise used to determine the execution's completion by either resolving or rejecting the promise. Initially disabled subscriptions remain disabled. Removed subscriptions are ignored as they are already disabled.

This function is useful if you want to avoid cyclic publications caused by an enabled subscriptions with same target and topic or if you just want to prevent certain subscriptions from receiving publications.

pubsub.isolate([ sub1, sub2, sub3 ], function () {
  // Subscription 1...3 are disabled at this point.
  return pubsub.publish(target, topic);
}).done(function () {
  // At this point subscriptions 1...3 will be enabled (assuming they were enabled in the beginning).
});

#canSubscribe(target, topic)

Check if a subscription on some target is possible. This is the case when target is a non-null object or function and topic is a non-empty string.

#canPublish(target, topic)

Check if a publication on some target and topic is possible. This is the case when there is currently no other publication on the very same (strict equality) target and topic in progress.

Subscription Object

A subscription object allows the subscriber to manipulate the subscription as well as remove it entirely.

#enable()

Enable the subscription, i.e. it will receive publication made after this call.

#disable()

Disable the subscription, i.e. it will not receive any publications made after this call.

#remove()

Remove the subscription and disable it. It will no longer receive any publications and cannot be added after this call.

#isEnabled

Check if the subscription is enabled.

#isRemoved

Check if the subscription has been removed.

Development

Testing is realized with Testem. To perform development testing run testem. When any source or test file changes all code is linted using JSHint, style checked using JSCS, and bundled using webpack.

License

Licensed under the AGPL 3.0.