diff --git a/README.md b/README.md index 8cd3765..bc43662 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Postal.js -## Version 0.6.0 +## Version 0.6.2 (Dual Licensed [MIT](http://www.opensource.org/licenses/mit-license) & [GPL](http://www.opensource.org/licenses/gpl-license)) ## What is it? Postal.js is an in-memory message bus - very loosely inspired by [AMQP](http://www.amqp.org/) - written in JavaScript. Postal.js runs in the browser, or on the server-side using Node.js. It takes a familiar "eventing-style" paradigm most JavaScript developers are already used to and extends it by providing "broker" and subscriber implementations which are more sophisticated than what you typically find in simple event delegation. @@ -120,6 +120,9 @@ postal.channel( { topic: "WeepingAngel.DontBlink" } ) dupSubscription.unsubscribe(); ``` +## More References +Please visit the [postal.js wiki](https://github.com/ifandelse/postal.js/wiki) for API documentation, discussion of concepts and links to blogs/articles on postal.js. + ## How can I extend it? There are four main ways you can extend Postal: @@ -128,7 +131,7 @@ There are four main ways you can extend Postal: * You can write an entirely new bus implementation if you wanted. The postal `subscribe`, `publish` and `addWiretap` calls all simply wrap a concrete implementation provided by the `postal.configuration.bus` object. For example, if you wanted a bus that stored message history in local storage and pushed a dump of past messages to a new subscriber, you'd simply write your implementation and then swap the default one out by calling: `postal.configuration.bus = myWayBetterBusImplementation`. * You can also change how the `bindingResolver` matches subscriptions to message topics being published. You may not care for the inverted RabbitMQ-style bindings functionality (postal currently inverts the treatment of asterisk and hash wildcard symbols compared to AMQP). 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 includes a console logging wiretap called postal.diagnostics.js. This diagnostics wiretap can be configured with filters to limit the firehose of message data to specific channels/topics and more. +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](https://github.com/ifandelse/postal.diagnostics). This diagnostics wiretap can be configured with filters to limit the firehose of message data to specific channels/topics and more. ## Can I contribute? Please - by all means! While I hope the API is relatively stable, I'm open to pull requests. (Hint - if you want a feature implemented, a pull request gives it a much higher probability of being included than simply asking me.) As I said, pull requests are most certainly welcome - but please include tests for your additions. Otherwise, it will disappear into the ether. diff --git a/build-all.sh b/build-all.sh index 9f25c8c..5a877ba 100755 --- a/build-all.sh +++ b/build-all.sh @@ -1,26 +1,17 @@ #!/bin/sh anvil -b build-browser.json -anvil -b build-browser-diags.json mv ./lib/standard/postal.amd.js ./lib/amd/postal.js mv ./lib/standard/postal.amd.min.js ./lib/amd/postal.min.js -mv ./lib/standard/postal.diagnostics.amd.js ./lib/amd/postal.diagnostics.js -mv ./lib/standard/postal.diagnostics.amd.min.js ./lib/amd/postal.diagnostics.min.js -mv ./lib/standard/postal.diagnostics.node.js ./lib/node/diags/postal.diagnostics.js mv ./lib/standard/postal.node.js ./lib/node/postal.js -rm ./lib/standard/postal.diagnostics.node* rm ./lib/standard/postal.node* mv ./lib/standard/postal.standard.js ./lib/standard/postal.js mv ./lib/standard/postal.standard.min.js ./lib/standard/postal.min.js -mv ./lib/standard/postal.diagnostics.standard.js ./lib/standard/postal.diagnostics.js -mv ./lib/standard/postal.diagnostics.standard.min.js ./lib/standard/postal.diagnostics.min.js cp ./lib/standard/postal.* ./example/standard/js cp ./lib/amd/postal.* ./example/amd/js/libs/postal cp ./lib/amd/postal.js ./example/node/client/js/lib -cp ./lib/amd/postal.diagnostics.js ./example/node/client/js/lib -cp ./lib/node/diags/postal.diagnostics.js ./example/node/messaging cp ./lib/node/postal.js ./example/node/messaging \ No newline at end of file diff --git a/build-browser-diags.json b/build-browser-diags.json deleted file mode 100644 index 3092bb8..0000000 --- a/build-browser-diags.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "source" : "src/diags", - "output" : "lib/standard", - "lint" : {}, - "uglify" : {}, - "extensions" : { - "uglify" : "min" - } -} \ No newline at end of file diff --git a/lib/amd/postal.diagnostics.js b/lib/amd/postal.diagnostics.js deleted file mode 100644 index 168df84..0000000 --- a/lib/amd/postal.diagnostics.js +++ /dev/null @@ -1,89 +0,0 @@ -// This is the amd module version of postal.diagnostics.js -// If you need the standard lib version, go to http://github.com/ifandelse/postal.js -define( [ "postal", "underscore" ], function ( postal, _, undefined ) { - - var filters = [], - applyFilter = function ( filter, env ) { - var match = 0, possible = 0; - _.each( filter, function ( item, key ) { - if ( env[key] ) { - possible++; - if ( _.isRegExp( item ) && item.test( env[key] ) ) { - match++; - } - else if ( _.isObject( env[key] ) && !_.isArray( env[key] ) ) { - if ( applyFilter( item, env[key] ) ) { - match++; - } - } - else { - if ( _.isEqual( env[key], item ) ) { - match++; - } - } - } - } ); - return match === possible; - }; - - // this returns a callback that, if invoked, removes the wireTap - var wireTap = postal.addWireTap( function ( data, envelope ) { - if ( !filters.length || _.any( filters, function ( filter ) { - return applyFilter( filter, envelope ); - } ) ) { - if ( !JSON ) { - throw "This browser or environment does not provide JSON support"; - } - try { - console.log( JSON.stringify( envelope ) ); - } - catch ( exception ) { - try { - var env = _.extend( {}, envelope ); - delete env.data; - console.log( JSON.stringify( env ) + "\n\t" + "JSON.stringify Error: " + exception.message ); - } - catch ( ex ) { - console.log( "Unable to parse data to JSON: " + exception ); - } - } - } - } ); - - postal.diagnostics = postal.diagnostics || {}; - - postal.diagnostics.console = { - clearFilters : function () { - filters = []; - }, - removeFilter : function ( filter ) { - filters = _.filter( filters, function ( item ) { - return !_.isEqual( item, filter ); - } ); - }, - addFilter : function ( constraint ) { - if ( !_.isArray( constraint ) ) { - constraint = [ constraint ]; - } - _.each( constraint, function ( item ) { - if ( filters.length === 0 || !_.any( filters, function ( filter ) { - return _.isEqual( filter, item ); - } ) ) { - filters.push( item ); - } - } ); - - }, - getCurrentFilters : function () { - return filters; - }, - removeWireTap : function () { - if ( wireTap ) { - wireTap(); - } - } - }; - - - -} ); \ No newline at end of file diff --git a/lib/amd/postal.diagnostics.min.js b/lib/amd/postal.diagnostics.min.js deleted file mode 100644 index 46a5dc2..0000000 --- a/lib/amd/postal.diagnostics.min.js +++ /dev/null @@ -1 +0,0 @@ -define(["postal","underscore"],function(a,b,c){var d=[],e=function(a,c){var d=0,f=0;return b.each(a,function(a,g){c[g]&&(f++,b.isRegExp(a)&&a.test(c[g])?d++:b.isObject(c[g])&&!b.isArray(c[g])?e(a,c[g])&&d++:b.isEqual(c[g],a)&&d++)}),d===f},f=a.addWireTap(function(a,c){if(!d.length||b.any(d,function(a){return e(a,c)})){if(!JSON)throw"This browser or environment does not provide JSON support";try{console.log(JSON.stringify(c))}catch(f){try{var g=b.extend({},c);delete g.data,console.log(JSON.stringify(g)+"\n "+"JSON.stringify Error: "+f.message)}catch(h){console.log("Unable to parse data to JSON: "+f)}}}});a.diagnostics=a.diagnostics||{},a.diagnostics.console={clearFilters:function(){d=[]},removeFilter:function(a){d=b.filter(d,function(c){return!b.isEqual(c,a)})},addFilter:function(a){b.isArray(a)||(a=[a]),b.each(a,function(a){(d.length===0||!b.any(d,function(c){return b.isEqual(c,a)}))&&d.push(a)})},getCurrentFilters:function(){return d},removeWireTap:function(){f&&f()}}}) \ No newline at end of file diff --git a/lib/node/diags/.npmignore b/lib/node/diags/.npmignore deleted file mode 100644 index fed5fed..0000000 --- a/lib/node/diags/.npmignore +++ /dev/null @@ -1,11 +0,0 @@ -build-browser-diags.json -build-browser.json -build-all.sh -nodetesthost.js -example -node_modules -spec -src -ext -lib/browser -lib/amd \ No newline at end of file diff --git a/lib/node/diags/package.json b/lib/node/diags/package.json deleted file mode 100644 index ca128ab..0000000 --- a/lib/node/diags/package.json +++ /dev/null @@ -1,47 +0,0 @@ -{ - "name" : "postal.diagnostics", - "description" : "Wiretap add-on for postal.js allowing configurable console.logging output of messages being published through postal's message bus.", - "version" : "0.6.1", - "homepage" : "http://github.com/ifandelse/postal.js", - "repository" : { - "type" : "git", - "url" : "git://github.com/ifandelse/postal.js.git" - }, - "author" : { - "name" : "Jim Cowart", - "email" : "WhyNotJustComment@OnMyBlog.com", - "url" : "http://freshbrewedcode.com/jimcowart" - }, - "contributors": [ - { - "name" : "Jim Cowart", - "email" : "WhyNotJustComment@OnMyBlog.com", - "url" : "http://freshbrewedcode.com/jimcowart" - } - ], - "bugs" : { - "email" : "PleaseJustUseTheIssuesPage@github.com", - "url" : "http://github.com/ifandelse/postal.js/issues" - }, - "directories" : { "lib" : "./" }, - "main" : "./postal.diagnostics.js", - "engines" : { - "node" : ">=0.4.0" - }, - "dependencies" : { - "underscore" : ">=1.1.7", - "postal" : ">=0.6.0" - }, - "bundleDependencies" : [ "underscore", "postal" ], - "devDependencies" : {}, - "licenses" : [ - { - "type" : "MIT", - "url" : "http://www.opensource.org/licenses/mit-license.php" - }, - { - "type" : "GPL", - "url" : "http://www.opensource.org/licenses/gpl-3.0.html" - } - ] -} diff --git a/lib/node/diags/postal.diagnostics.js b/lib/node/diags/postal.diagnostics.js deleted file mode 100644 index b9f1222..0000000 --- a/lib/node/diags/postal.diagnostics.js +++ /dev/null @@ -1,85 +0,0 @@ -module.exports = function ( _, postal ) { - var filters = [], - applyFilter = function ( filter, env ) { - var match = 0, possible = 0; - _.each( filter, function ( item, key ) { - if ( env[key] ) { - possible++; - if ( _.isRegExp( item ) && item.test( env[key] ) ) { - match++; - } - else if ( _.isObject( env[key] ) && !_.isArray( env[key] ) ) { - if ( applyFilter( item, env[key] ) ) { - match++; - } - } - else { - if ( _.isEqual( env[key], item ) ) { - match++; - } - } - } - } ); - return match === possible; - }; - - // this returns a callback that, if invoked, removes the wireTap - var wireTap = postal.addWireTap( function ( data, envelope ) { - if ( !filters.length || _.any( filters, function ( filter ) { - return applyFilter( filter, envelope ); - } ) ) { - if ( !JSON ) { - throw "This browser or environment does not provide JSON support"; - } - try { - console.log( JSON.stringify( envelope ) ); - } - catch ( exception ) { - try { - var env = _.extend( {}, envelope ); - delete env.data; - console.log( JSON.stringify( env ) + "\n\t" + "JSON.stringify Error: " + exception.message ); - } - catch ( ex ) { - console.log( "Unable to parse data to JSON: " + exception ); - } - } - } - } ); - - postal.diagnostics = postal.diagnostics || {}; - - postal.diagnostics.console = { - clearFilters : function () { - filters = []; - }, - removeFilter : function ( filter ) { - filters = _.filter( filters, function ( item ) { - return !_.isEqual( item, filter ); - } ); - }, - addFilter : function ( constraint ) { - if ( !_.isArray( constraint ) ) { - constraint = [ constraint ]; - } - _.each( constraint, function ( item ) { - if ( filters.length === 0 || !_.any( filters, function ( filter ) { - return _.isEqual( filter, item ); - } ) ) { - filters.push( item ); - } - } ); - - }, - getCurrentFilters : function () { - return filters; - }, - removeWireTap : function () { - if ( wireTap ) { - wireTap(); - } - } - }; - - -}; \ No newline at end of file diff --git a/lib/standard/postal.diagnostics.js b/lib/standard/postal.diagnostics.js deleted file mode 100644 index eeeb2ca..0000000 --- a/lib/standard/postal.diagnostics.js +++ /dev/null @@ -1,89 +0,0 @@ -// This is the standard lib version of postal.diagnostics.js -// If you need the amd-module style version, go to http://github.com/ifandelse/postal.js -(function ( postal, _, undefined ) { - - var filters = [], - applyFilter = function ( filter, env ) { - var match = 0, possible = 0; - _.each( filter, function ( item, key ) { - if ( env[key] ) { - possible++; - if ( _.isRegExp( item ) && item.test( env[key] ) ) { - match++; - } - else if ( _.isObject( env[key] ) && !_.isArray( env[key] ) ) { - if ( applyFilter( item, env[key] ) ) { - match++; - } - } - else { - if ( _.isEqual( env[key], item ) ) { - match++; - } - } - } - } ); - return match === possible; - }; - - // this returns a callback that, if invoked, removes the wireTap - var wireTap = postal.addWireTap( function ( data, envelope ) { - if ( !filters.length || _.any( filters, function ( filter ) { - return applyFilter( filter, envelope ); - } ) ) { - if ( !JSON ) { - throw "This browser or environment does not provide JSON support"; - } - try { - console.log( JSON.stringify( envelope ) ); - } - catch ( exception ) { - try { - var env = _.extend( {}, envelope ); - delete env.data; - console.log( JSON.stringify( env ) + "\n\t" + "JSON.stringify Error: " + exception.message ); - } - catch ( ex ) { - console.log( "Unable to parse data to JSON: " + exception ); - } - } - } - } ); - - postal.diagnostics = postal.diagnostics || {}; - - postal.diagnostics.console = { - clearFilters : function () { - filters = []; - }, - removeFilter : function ( filter ) { - filters = _.filter( filters, function ( item ) { - return !_.isEqual( item, filter ); - } ); - }, - addFilter : function ( constraint ) { - if ( !_.isArray( constraint ) ) { - constraint = [ constraint ]; - } - _.each( constraint, function ( item ) { - if ( filters.length === 0 || !_.any( filters, function ( filter ) { - return _.isEqual( filter, item ); - } ) ) { - filters.push( item ); - } - } ); - - }, - getCurrentFilters : function () { - return filters; - }, - removeWireTap : function () { - if ( wireTap ) { - wireTap(); - } - } - }; - - - -})( postal, _ ); \ No newline at end of file diff --git a/lib/standard/postal.diagnostics.min.js b/lib/standard/postal.diagnostics.min.js deleted file mode 100644 index 8e73e2f..0000000 --- a/lib/standard/postal.diagnostics.min.js +++ /dev/null @@ -1 +0,0 @@ -(function(a,b,c){var d=[],e=function(a,c){var d=0,f=0;return b.each(a,function(a,g){c[g]&&(f++,b.isRegExp(a)&&a.test(c[g])?d++:b.isObject(c[g])&&!b.isArray(c[g])?e(a,c[g])&&d++:b.isEqual(c[g],a)&&d++)}),d===f},f=a.addWireTap(function(a,c){if(!d.length||b.any(d,function(a){return e(a,c)})){if(!JSON)throw"This browser or environment does not provide JSON support";try{console.log(JSON.stringify(c))}catch(f){try{var g=b.extend({},c);delete g.data,console.log(JSON.stringify(g)+"\n "+"JSON.stringify Error: "+f.message)}catch(h){console.log("Unable to parse data to JSON: "+f)}}}});a.diagnostics=a.diagnostics||{},a.diagnostics.console={clearFilters:function(){d=[]},removeFilter:function(a){d=b.filter(d,function(c){return!b.isEqual(c,a)})},addFilter:function(a){b.isArray(a)||(a=[a]),b.each(a,function(a){(d.length===0||!b.any(d,function(c){return b.isEqual(c,a)}))&&d.push(a)})},getCurrentFilters:function(){return d},removeWireTap:function(){f&&f()}}})(postal,_) \ No newline at end of file diff --git a/src/diags/postal.diagnostics.amd.js b/src/diags/postal.diagnostics.amd.js deleted file mode 100644 index eb41ded..0000000 --- a/src/diags/postal.diagnostics.amd.js +++ /dev/null @@ -1,7 +0,0 @@ -// This is the amd module version of postal.diagnostics.js -// If you need the standard lib version, go to http://github.com/ifandelse/postal.js -define( [ "postal", "underscore" ], function ( postal, _, undefined ) { - - //import("postal.diagnostics.js"); - -} ); \ No newline at end of file diff --git a/src/diags/postal.diagnostics.js b/src/diags/postal.diagnostics.js deleted file mode 100644 index 34241c9..0000000 --- a/src/diags/postal.diagnostics.js +++ /dev/null @@ -1,82 +0,0 @@ -var filters = [], - applyFilter = function ( filter, env ) { - var match = 0, possible = 0; - _.each( filter, function ( item, key ) { - if ( env[key] ) { - possible++; - if ( _.isRegExp( item ) && item.test( env[key] ) ) { - match++; - } - else if ( _.isObject( env[key] ) && !_.isArray( env[key] ) ) { - if ( applyFilter( item, env[key] ) ) { - match++; - } - } - else { - if ( _.isEqual( env[key], item ) ) { - match++; - } - } - } - } ); - return match === possible; - }; - -// this returns a callback that, if invoked, removes the wireTap -var wireTap = postal.addWireTap( function ( data, envelope ) { - if ( !filters.length || _.any( filters, function ( filter ) { - return applyFilter( filter, envelope ); - } ) ) { - if ( !JSON ) { - throw "This browser or environment does not provide JSON support"; - } - try { - console.log( JSON.stringify( envelope ) ); - } - catch ( exception ) { - try { - var env = _.extend( {}, envelope ); - delete env.data; - console.log( JSON.stringify( env ) + "\n\t" + "JSON.stringify Error: " + exception.message ); - } - catch ( ex ) { - console.log( "Unable to parse data to JSON: " + exception ); - } - } - } -} ); - -postal.diagnostics = postal.diagnostics || {}; - -postal.diagnostics.console = { - clearFilters : function () { - filters = []; - }, - removeFilter : function ( filter ) { - filters = _.filter( filters, function ( item ) { - return !_.isEqual( item, filter ); - } ); - }, - addFilter : function ( constraint ) { - if ( !_.isArray( constraint ) ) { - constraint = [ constraint ]; - } - _.each( constraint, function ( item ) { - if ( filters.length === 0 || !_.any( filters, function ( filter ) { - return _.isEqual( filter, item ); - } ) ) { - filters.push( item ); - } - } ); - - }, - getCurrentFilters : function () { - return filters; - }, - removeWireTap : function () { - if ( wireTap ) { - wireTap(); - } - } -}; - diff --git a/src/diags/postal.diagnostics.node.js b/src/diags/postal.diagnostics.node.js deleted file mode 100644 index 8b4ac13..0000000 --- a/src/diags/postal.diagnostics.node.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = function ( _, postal ) { - //import("postal.diagnostics.js"); -}; \ No newline at end of file diff --git a/src/diags/postal.diagnostics.standard.js b/src/diags/postal.diagnostics.standard.js deleted file mode 100644 index 643ff28..0000000 --- a/src/diags/postal.diagnostics.standard.js +++ /dev/null @@ -1,7 +0,0 @@ -// This is the standard lib version of postal.diagnostics.js -// If you need the amd-module style version, go to http://github.com/ifandelse/postal.js -(function ( postal, _, undefined ) { - - //import("postal.diagnostics.js"); - -})( postal, _ ); \ No newline at end of file