Pub/Sub library providing wildcard subscriptions, complex message handling, etc. Works server and client-side.
npm install postal
> See the changelog for information on if the current version of postal has breaking changes compared to any older version(s) you might be using. Version 0.11+ removed the dependency on ConduitJS and significantly improved publishing performance. Version 1.0+ added an optional embedded-and-customized-lodash build.
``javascriptdata
var subscription = postal.subscribe({
channel: "orders",
topic: "item.add",
callback: function(data, envelope) {
// is the data published by the publisher.envelope
// is a wrapper around the data & contains`
// metadata about the message like the channel, topic,
// timestamp and any other data which might have been
// added by the sender.
}
});
The publisher might do something similar to this:
`javascript`
postal.publish({
channel: "orders",
topic: "item.add",
data: {
sku: "AZDTF4346",
qty: 21
}
});
While the above code snippets work just fine, it's possible to get a more terse API if you want to hang onto an ChannelDefinition instance - which is really a convenience wrapper around publishing and subscribing on a specific channel (instead of having to specify it each time):
`javascript
var channel = postal.channel("orders");
var subscription = channel.subscribe("item.add", function(data, envelope) {
/do stuff with data /
});
channel.publish("item.add", {
sku: "AZDTF4346",
qty: 21
});
`
postal is not an event emitter - it's not meant to be mixed into an instance. Instead, it's a stand alone "broker" – a message bus*.
postal uses an envelope* to pass messages. This means you get a consistent method signature in ALL of your subscriber callbacks. Most eventing libs take what I call the "0-n args approach", and what gets passed to the subscriber in those libs is solely at the mercy/whim of the developer that wrote the code emitting the event.
Most "event aggregator" libs are single channel - which can lead to event name collision, and reduce the performance of matching an event to the correct subscribers. postal is multi-channel*.
postal's design strongly discourages publishing behavior (functions/methods)! This is intentional. In an observer-subject scenario, it's common to pass callbacks on the event data. This is an anti-pattern when it comes to messaging (and I'd argue is often an anti-pattern even in Observer pattern scenarios). A postal envelope should be serializable and then de-serializable with no loss of fidelity*.
* postal can work across frame and web worker boundaries (by utilizing the postal.federation and postal.xframe plugins).
* postal's built-in topic logic supports hierarchical wildcard topic bindings - supporting the same logic as topic bindings in the AMQP spec. And if you don't like that approach, you can easily provide your own bindings resolver.
* If you're using a client-side binding framework, and either don't have - or don't like - the request/communication abstractions provided, then grab a library like amplify.js or reqwest. Then, instead of tightly coupling them to your application, have the request success/error callbacks publish messages with the appropriate data and any subscribers you've wired up can handle applying the data to the specific objects/elements they're concerned with.
* Do you need two view models to communicate, but you don't want them to need to know about each other? Have them subscribe to the topics about which they are interested in receiving messages. From there, whenever a view model needs to alert any listeners of specific data/events, just publish a message to the bus. If the other view model is present, it will receive the notification.
* Want to wire up your own binding framework? Want to control the number of times subscription callbacks get invoked within a given time frame? Want to keep subscriptions from being fired until after data stops arriving? Want to keep events from being acted upon until the UI event loop is done processing other events? Postal.js gives you the control you need in these kinds of scenarios via the options available on the SubscriptionDefinition object.
* postal.js is extensible. Plugins like postal.when can be included to provide even more targeted functionality to subscribers. Postal.federation provides the core bits needed to federate postal instances running in different environments (currently the only federation plugin available is postal.xframe for federating between windows in the browser, but more plugins are in the works). These - and more - are all things Postal can do for you.
These four concepts are central to postal:
* channels should be provided to allow for logical partitioning of "topics"
* topics should be hierarchical and allow plain string or wildcard bindings
* messages should include envelope metadata
* subscriber callbacks should get a consistent method signature
Most eventing libraries focus on providing Observer Pattern utilities to an instance (i.e. - creating an event emitter), OR they take the idea of an event emitter and turn it into an event aggregator (so a single channel, stand alone emitter that acts as a go-between for publishers and subscribers). I'm a big fan of the Observer Pattern, but its downside is that it requires a direct reference to the subject in order to listen to events. This can become a big source of tight coupling in your app, and once you go down that road, your abstractions tend to leak, if not hemorrhage.
postal is not intended to replace Observer pattern scenarios. Inside a module, where it makes sense for an observer to have a direct reference to the subject, by all means, use the Observer pattern. However - when it comes to inter-module communication (view-to-view, for example), inter-library communication, cross frame communication, or even hierarchical state change notifications with libraries like ReactJS, postal is the glue to help your components communicate without glueing them with tight coupling.
Here are four examples of using Postal. All of these examples - AND MORE! - can run live here. Be sure to check out the wiki for API documentation and conceptual walk-throughs.
`javascript
// This gets you a handle to the default postal channel...
// For grins, you can get a named channel instead like this:
// var channel = postal.channel( "DoctorWho" );
var channel = postal.channel();
// subscribe to 'name.change' topics
var subscription = channel.subscribe( "name.change", function ( data ) {
$( "#example1" ).html( "Name: " + data.name );
} );
// And someone publishes a name change:
channel.publish( "name.change", { name : "Dr. Who" } );
// To unsubscribe, you:
subscription.unsubscribe();
// postal also provides a top-level ability to subscribe/publish
// used primarily when you don't need to hang onto a channel instance:
var anotherSub = postal.subscribe({
channel : "MyChannel",
topic : "name.change",
callback : function(data, envelope) {
$( "#example1" ).html( "Name: " + data.name );
}
});
postal.publish({
channel : "MyChannel",
topic : "name.change",
data : {
name : "Dr. Who"
}
});
`
The symbol represents "one word" in a topic (i.e - the text between two periods of a topic). By subscribing to ".changed", the binding will match name.changed & location.changed but not changed.companion.
`javascript`
var chgSubscription = channel.subscribe( "*.changed", function ( data ) {
$( "
} );
channel.publish( "name.changed", { type : "Name", value : "John Smith" } );
channel.publish( "location.changed", { type : "Location", value : "Early 20th Century England" } );
chgSubscription.unsubscribe();
The # symbol represents 0-n number of characters/words in a topic string. By subscribing to "DrWho.#.Changed", the binding will match DrWho.NinthDoctor.Companion.Changed & DrWho.Location.Changed but not Changed.
`javascript`
var starSubscription = channel.subscribe( "DrWho.#.Changed", function ( data ) {
$( "
} );
channel.publish( "DrWho.NinthDoctor.Companion.Changed", { type : "Companion Name", value : "Rose" } );
channel.publish( "DrWho.TenthDoctor.Companion.Changed", { type : "Companion Name", value : "Martha" } );
channel.publish( "DrWho.Eleventh.Companion.Changed", { type : "Companion Name", value : "Amy" } );
channel.publish( "DrWho.Location.Changed", { type : "Location", value : "The Library" } );
channel.publish( "TheMaster.DrumBeat.Changed", { type : "DrumBeat", value : "This won't trigger any subscriptions" } );
channel.publish( "Changed", { type : "Useless", value : "This won't trigger any subscriptions either" } );
starSubscription.unsubscribe();
`javascript`
var dupChannel = postal.channel( "Blink" ),
dupSubscription = dupChannel.subscribe( "WeepingAngel.#", function( data ) {
$( '
}).distinctUntilChanged();
// demonstrating multiple channels per topic being used
// You can do it this way if you like, but the example above has nicer syntax (and much less overhead)
dupChannel.publish( "WeepingAngel.DontBlink", { value:"Don't Blink" } );
dupChannel.publish( "WeepingAngel.DontBlink", { value:"Don't Blink" } );
dupChannel.publish( "WeepingAngel.DontEvenBlink", { value:"Don't Even Blink" } );
dupChannel.publish( "WeepingAngel.DontBlink", { value:"Don't Close Your Eyes" } );
dupChannel.publish( "WeepingAngel.DontBlink", { value:"Don't Blink" } );
dupChannel.publish( "WeepingAngel.DontBlink", { value:"Don't Blink" } );
dupSubscription.unsubscribe();
* Write a plugin. Need more complex behavior that the built-in SubscriptionDefinition doesn't offer? Write a plugin that you can attach to the global postal object. See postal.when for an example of how to do this. You can also write plugins that extend the ChannelDefinition and SubscriptionDefinition prototypes - see postal.request-response for an example of this.bindingResolver
* Write a custom federation plugin, to federate instances of postal across a transport of your choice.
* You can also change how the matches subscriptions to message topics being published. You may not care for the AMQP-style bindings functionality. No problem! Write your own resolver object that implements a compare and reset method and swap the core version out with your implementation by calling: postal.configuration.resolver = myWayBetterResolver.
It's also possible to extend the monitoring of messages passing through Postal by adding a "wire tap". A wire tap is a callback that will get invoked for any published message (even if no actual subscriptions would bind to the message's topic). Wire taps should _not_ be used in lieu of an actual subscription - but instead should be used for diagnostics, logging, forwarding (to a websocket publisher or a local storage wrapper, for example) or other concerns that fall along those lines. This repository used to include a console logging wiretap called postal.diagnostics.js - you can now find it here in it's own repo. This diagnostics wiretap can be configured with filters to limit the firehose of message data to specific channels/topics and more.
* postal depends on lodash.js
* The standard postal build output (lib/postal.js) is what you would normally use if you're already using lodash in your app.lib/postal.lodash.js
* The build output might be of interest to you if these things are true:npm install
* You're using webpack, browserify or another bundler/loader capable of loading CommonJS modules.
* You only need the specific bits of lodash used by postal and don't need the full lib.
* postal uses gulp.js for building, running tests and examples.
* To build
* run (to install all deps)bower install
* run (yep, we're using at least one thing only found on bower in the local project runner)npm run build
* run (this is just an alias for gulp at the moment, which you can also use) - then check the lib folder for the outputnpm test
* To run tests & examples
* Tests are node-based: (or npm run test-lodash to test the custom lodash build output)npm start
* To run browser-based examples:
* run
* navigate in your browser to
* if you want to see test coverage or plato reports be sure to run and gulp report` (respectively) in order to generate them, as they are not stored with the repo.