pubsubjs

micro pubsub library

PubsubJS

pubsubjs is Micro pubsub library which provides the observer pattern to JavaScript.

It works in the browser and server (Node).

In browser DownLoad pubsub.js, or install via bower

$ bower install pubsubjs

and then include single JavaScript file:

<script type="text/javascript" src="pubsub.js"></script>
<script type="text/javascript">
    var pubsub = Pubsub.create();
    ...
</script> 

On server install PubsubJS via npm first:

npm install pubsubjs

and then include it in your project with:

var pubsub = require('pubsubjs').create();

##What is Pubsub

Publish–subscribe is a messaging pattern where senders of messages, called publishers, do not program the messages to be sent directly to specific receivers, called subscribers. Published messages are characterized into classes, without knowledge of what, if any, subscribers there may be. Subscribers express interest in one or more classes, and only receives messages that are of interest, without knowledge of what, if any, publishers there are.

http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern

##Example Usage

For example, "The display of notifications and mail to desktop when mail arrives" can be written using PubsubJS as follows.

// Define the global subscriber use of pubsubjs 
pubsub.subscribe('mail.arrived', function (contextmailId) {
    mailer.display(mailId);
});
 
pubsub.subscribe('mail.arrived', function (contextmailId) {
    desktop.notice('a mail has arrived');
});
 
mailer.polling({
    onArrivedfunction (mailId) {
        pubsub.publish('mail.arrived', null, mailId);
    },
    …
});

Also, you may want to think subscriber publish as below.

pubsub.subscribe('mail.arrived', function (contextmailId) {
    mailer.display(mailId);
    pubsub.publish('mail.displayed'); // call 'mail.displayed' subscribers 
});
 
pubsub.subscribe('mail.arrived', function (contextmailId) {
    desktop.notice('a mail has arrived');
    pubsub.publish('descktop.noticed'); // call 'desktop.noticed' subscribers 
});
 
mailer.polling({
    onArrivedfunction (mailId) {
        pubsub.publish('mail.arrived', null, mailId);
    },
    …
});

When are notified first and a subscriber is performed.

It is realizable by using subscribeOnce.

var pubsub = PubSub.create()
  , actual = {a: 0}
  ;
 
pubsub.subscribeOnce('once', function () {
  actual.+= 1;
});
pubsub.publish('once');
pubsub.publish('once');
assert.strictEqual(1, actual.a); // pass 

You may think that you would like to remove subscriber at the time of some conditions. It is realizable by using unsubscribe.

var pubsub = PubSub.create()
  , actual = {a: 0}
  ;
 
var fn = function () {
  actual.+= 1;
  if (actual.> 1) {
    pubsub.unsubscribe('once', fn);
  }
};
 
pubsub.subscribe('event', fn);
pubsub.publish('event');
pubsub.publish('event');
pubsub.publish('event');
assert.strictEqual(2, actual.a); // pass 

pubsub#Context is the most useful API in this library. It is a bit more complex cases, there will often suffer from following situation.

// in jQuery 
pubsub.subscribe('favorite.add', function (contextid) {
    $.ajax({
        url: xxx,
        data: {id: id}
    }).done(function () {
        // Can not access the $(evt.currentTarget) here. 
    });
});
 
$(favoriteIcon).bind('click', function (evt) {
    var id = $(evt.currentTarget).data('id');
    pubsub.publish('favorite.add', null, id);
    // want to change the class when "favorite.add" is completed. 
    // ex. $(evt.currentTarget).addClass('is-added'); 
    // However, since the processing of "favorite.add" is async, 
    // I can not write it here. 
});

This can be solved by using the pubsub#Context.

// in jQuery 
pubsub.subscribe('favorite.add', function (contextid) {
    $.ajax({
        url: xxx,
        data: {id: id}
    }).done(function () {
        context.publish('favorite.added');
    });
});
 
$(favoriteIcon).bind('click', function (evt) {
    var target = $(evt.currentTarget),
        id = target.data('id'),
        localContext = pubsub.Context.create();
 
    localContext.subscribe('favorite.added', function (context) {
        target.addClass('is-added');
    });
 
    pubsub.publish('favorite.add', localContext, id);
});

You would think when you are developing, you want to know what kind of handler has been registered to any event.

It is a good idea to use the pubsub#dump of the API for debugging such a case.

var pubsub = PubSub.create()
  , actual
  ;
 
function a() {}
function b() {}
function c() {}
 
pubsub.subscribe('event1', a);
pubsub.subscribe('event1', b);
pubsub.subscribe('event2', c);
 
actual = pubsub.dump();
assert.deepEqual(actual, {event1: [a, b], event2: [c]});

If you want to check handlers that are registered to a particular event, it is preferable to provide an event name as an argument.

var pubsub = PubSub.create()
  , actual
  ;
 
function a() {}
function b() {}
function c() {}
 
pubsub.subscribe('event1', a);
pubsub.subscribe('event1', b);
pubsub.subscribe('event2', c);
 
actual = pubsub.dump('event1');
assert.deepEqual(actual, [a, b]);

Notice: This API is for debugging purposes only. Please do not use in production code.

##All API

  • Pubsub#create()
  • pubsub#publish(eventName, context/null, arg1, arg2...)
  • pubsub#subscribe(eventName, handler)
  • pubsub#subscribeOnce(eventName, handler)
  • pubsub#unsubscribe(eventName, [handler])
  • pubsub#dump([eventName])
  • pubsub#globalContext
  • pubsub#Context
  • Context#create()
  • context#publish(eventName, context/null, arg1, arg2...)
  • context#subscribe(eventName, handler)
  • context#subscribeOnce(eventName, handler)
  • context#unsubscribe(eventName, [handler])
  • context#dump([eventName])

##Contributors

##License:

(The MIT License)

Copyright (c) 2013 nazomikan https://github.com/nazomikan/PubsubJS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.