JavaScript Object Inflation with Dependency Injection
This project is inspired by Angular.JS' dependency injection, Express.JS' middleware, and PHP's spl_autoload_register.
Bicycle Pump combines the following:
-
inflation: taking a plain JavaScript Object and transforming it (usually with a constructor Function)
-
injection: requesting something (usually a Function or module) by an identifying token
Our use case involves:
-
we have just retrieved a JavaScript Object from storage, or the network
-
we want to register a number of inflator Functions (a.k.a. Inflators)
-
each Inflator should be given the Object one-by-one, until it is inflated
-
Inflators decide for themselves whether they are appropriate or not
This gives us a way to decouple our code, and also allows downstream consumers of our projects to enhance and extend our projects at runtime.
BicyclePump
is installed in the global namespace, unless it detects AMD or CommonJS module usage.
Note: this notation is JSDoc3, where #
indicates an instance member, .
indicates a static member, and ~
indicates an inner class or member.
- @param {Object}
obj
- @param {BicycleBump~inflatorDone}
done
- @param {BicycleBump~inflatorNext}
next
This is the definition of an Inflator. Each Inflator accepts an Object obj
as its first parameter. Inflators are always asynchronous, so they are expected to call done()
or next()
when finished, rather than return a value.
Inflators should interrogate obj
and determine how to proceed:
- call
next()
if this Inflator cannot handle thisobj
, passing to the next Inflator - call
done()
when no other Inflator should be given a turn
For example:
function anInflator(obj, done, next) {
if (!obj || typeof obj !== 'object') {
done(new Error('Object cannot be inflated'));
return;
}
if (!obj.name) {
// this Inflator needs a "name" property
next(); // try the next Inflator
return;
}
done(new NamedObject(obj));
}
- @param {Object|Error} [
result
] (optional)
This is the function called by an Inflator when no other Inflator should be tried.
If the Object was not inflated successfully, or should never be, then result
should be falsey or an Error.
Otherwise, result
should be the successfully inflated result.
This is the function called by an Inflator when the next Inflator should have a turn. This signals that the current Inflator determined that it was not suitable.
- @param {BicycleBump~inflator}
fn
Registers an Inflator function. e.g.
var myInflators = new BicyclePump();
myInflators.addInflator(function (obj, done, next) {/* ... */})
- @param {BicycleBump~inflator}
fn
If the provided Inflator was registered, unregister it so that it would be called.
- @return {Array.<BicycleBump~inflator>}
- @param {Object}
obj
- @param {BicycleBump~inflationDone} [
callback
] (optional) - @return {Promise} but only if environment offers ES6 Promises
This is for consumers that have an Object and need it inflated. When invoked, each registered Inflator will be called one-by-one, newest registrations first (Last-In-First-Out). e.g.
var myInflators = new BicyclePump();
myInflators.addInflator(function third(obj, done, next) {/* ... */});
myInflators.addInflator(function second(obj, done, next) {/* ... */});
myInflators.addInflator(function first(obj, done, next) {/* ... */});
myInflators.inflate({ /* ... */ });
- @param {Error}
err
- @param {Object}
result
This is a CommonJS-style callback, in that err
will be falsey if there were no errors.
This is governed by the BSD 3-clause license.