Envoy.js is a simple wrapper for Backbone.Events which provides a convenient global mediator object (window.envoy
) and adds a reverse pub/sub pattern dubbed offer/solicit.
Since it uses Backbone.Events (and some Underscore methods) it requires both Backbone.js and Underscore.js.
Usage is simple:
envoy.offer('named_key', { any: 'value' });
var result = envoy.solicit('named_key');
You can offer multiple items using the same key, and calling envoy.solicit
on that key will retrieve all those items.
envoy.offer('multiple_values', { something: 'good' });
envoy.offer('multiple_values', { more: 'surprises' });
var results = envoy.solicit('multiple_values');
That's the basic premise. Envoy.js also adds a few extra conveniences, and exposes just three methods: envoy.offer()
, envoy.solicit()
, and envoy.withdraw()
.
envoy.offer(key, callback, namespace);
key
(required): Each key can be used by multiple offers. It's probably best to use a string, but technically this could be any value.callback
(required): If it's a function, it will be called and the result will be returned duringenvoy.solicit
. All other types will be returned directly.namespace
(optional): A way to separate values that share the same key. If included in a call toenvoy.solicit
, the namespace will act as a filter and will only return offers with the same namespace.
envoy.withdraw(key, namespace);
key
(required): Withdraw all offers made for this key.namespace
(optional): Only withdraw offers that match the given key & namespace.
envoy.solicit(key ...);
key
(required): Get offers for this key.- These three arguments are all optional and can be combined in any order after
key
:first_result
: Boolean value. If present (andtrue
) then only the first offer (FIFO) will be returned.namespace
: String. Only return offers with this namespace.callback
: Function. If present, invoke this function using the returned offers as the only argument.
// Meanwhile in the kitchen
envoy.offer('breakfast', 'greasy bacon', 'meat');
envoy.offer('breakfast', function() {
return 'delicious eggs';
}, 'almost-meat');
envoy.offer('breakfast', { cheeses: ['cheddar', 'gouda', '6pool'] });
// sorry, you're too fat for bacon
envoy.withdraw('breakfast', 'meat');
// store the result as a var
var breakfast = envoy.solicit('breakfast');
// or just run a callback on the result
envoy.solicit('breakfast', function(foods) {
_.each(foods, function(food) {
console.log('Eating ' +food+ '...');
});
});
envoy
can also be used as a simple global key/value store if you don't need the enhanced functionality of offer/solicit.
Simply use: envoy.store(key, value);
to store a global value of any data type, then envoy.fetch(key);
to retrieve it.
Storing a key will overwrite any previous key of the same name.
Use envoy.erase(key);
to remove a key/val pair.
Also, envoy.rouse(key);
will invoke and return the result of any stored functions. What's neat is that it will also deep traverse a stored object or array, maintaining indexes and invoking all functions along the way.
Both envoy.rouse()
and envoy.fetch()
accept a second, optional parameter which will be returned if the result is undefined: envoy.fetch('nonexistant', 'oh well, use this then')
.