Pubit-as-promised

Responsible publish/subscribe. Hide the event publisher, only exposing the event emitter. Now with added Q promise goodness! Now, now you can listen to wildcard event names!

Why is this cool?

Most pub/sub frameworks conflate the role of publisher and emitter. This means that if someone gets ahold of your emitter object, they can not only subscribe to events, but also fake out all other subscribers by emitting an artificial event:

 
// server.js
process.on("exit", cleanupServerStuff);
 
// thirdParty.js
process.emit("exit");
// uh oh, now the server stuff's been all cleaned up!

With pubit-as-promised, the publisher and emitter are separate, allowing you to keep the publisher private while exposing emitter functionality. Here's a hypothetical implementation of a process module using pubit-as-promised, including the use of the new Q promise return value of publish:

var pubit = require("pubit-as-promised");
 
var publish = pubit.makeEmitter(exports);
 
exports.exit = function (exitCode) {
  publish.when("exit", exitCode).done(function () {
    window.close();
  });
};

An example of a subscriber that returns a promise looks like this:

var process = require("./process");
 
process.on("exit", function () {
  return sendLogsToCloudAsync();
});

This module only exports the emitter interface (on, off, and once); the publish function is kept private.

Aren't you being paranoid?

There's some argument as to what role encapsulation has to play in JavaScript. Some might say, “if you don't want the event to be emitted outside the emitter … don't emit the event outside the emitter.”

But encapsulation isn't about being paranoid. It's about hiding complexity: exposing a solution, without requiring the consumer to grok the gory details of the problem. An emitter by itself is simple and easy to interface with, but when you add knobs for publishing or introspection, you're no longer solving a problem, but instead creating option paralysis and fragility. Someone should be able to understand that an object emits events, without worrying about who could be publishing those events in the first place.

Pubit-as-promised is ポカヨケ.

Promises and Pub/Sub?

Sure. Why not? One of the deficiencies in the original pubit was the inability to return a value. It was a true publish only system. With pubit-as-promised you now have the ability for subscribers to asynchronously return values to the publisher. Think of the possibilities. Imagine a system where a publisher send out a lunch order and subscribers could return what they wanted to eat. The order would be places when all subscribers answered (i.e. fulfilled their promise).

Another example (show below) is a voting system. The publisher sends out a list of candidates, then waits for each vote to be fulfilled (again a promise). The publisher then tallies the votes and publishes the winner. The sample code is shown here:

// The publisher.
publish.when("vote", candidates).done(function(votes) {
    var winner = tallyVotes(votes);
    publish("winner", winner);
});
 
// Each subscriber.
voter.on("vote", function(candidates) {
    var deferred = Q.defer();
 
    voter.once("winner", displayWinner);
 
    function onsubmit(myChoice) {
        deferred.resolve(myChoice);
    }
 
    setupForm(onSubmit, candidates);
    return deferred.promise;
});

Wildcard and RegExp Events

There is a new method called onMatch that you can use to listen to multiple events. This is especially useful for setuping up a single logger. The pattern may be a string with a wildcard (i.e. "*") or a Regular Expression. See the API reference for further details.

// Log every event.
var unsubscribe = emitter.onMatch("ui.*", function (eventName) {
  console.log("%s Event %s was published", new Date().toISOString(), eventName);
})
 
publish("ui.list.add"); // This will be logged above.
publish("ui.session.signin"); // This will not.
 
// And when you no longer want to listen, simply call the returned unsubscribe function.
unsubscribe();

More docs and examples

• Check out a simple example of using pubit-as-promised for responsible pub/sub.
• Be sure to check out the listener helper examples to get a look at a nice feature pubit-as-promised provides to solve a common use case.
• If you like that sort of thing, we also have an API reference.
• Perhaps most educational would be checking out the unit tests—they're very readable, I promise! Run them with npm test if you'd like.