Esquire
Esquire is a light weight, asynchronous injection framework for JavaScript.
The full API documentation is avaiblable
here.
Modules
Module definitions are shared, on a per global scope basis; in other words,
the same module is defined only once per window
if running in a browser,
or global
if running under Node.JS
.
Modules are defined by a name
, a list of dependencies, and a constructor
function:
Esquire.define("myModuleName", ['myFirstDependency', 'anotherDependency'], function(first, another) {
});
Constructors can return immediately (with a result), or can return a
then-able Promise
which will eventually resolve to the required instance.
Module Injection
Direct injection of a module is supported through the inject(...)
method,
which will return a Promise
to its return value:
new Esquire().inject(['dependencyName'], function(dependency) {
}).then(function(result) {
}, function(failure) {
});
Module Requirement
Modules can also be directly required by the caller, and will be returned
wrapped into a Promise
:
new Esquire().require('requestedModule')
.then(function(result) {
});
Multiple modules can also be requested simultaneously (both specifying module
names as arguments or an array of string
s):
new Esquire().require('firstModule', 'secondModule')
.then(function(result) {
});
Static vs. per-instance injection
In the examples above, a call to new Esquire()
will create a new injector
and with it, new modules instances are created. Each module instance is only
available to its injector, and never shared across.
On the other hand the global esquire(...)
method will allow to access a per
global scope shared injector.
When calling esquire(...)
with a callback function as its last parameter,
the method will behave like inject(...)
, thus dependencies will be resolved
and passed to callback method, and its return value (if any) will be returned.
esquire(['dependencyName'], function(dependency) {
}).then(function(result) {
});
If no callback function was given, the esquire(...)
method will behave like
require(...)
and simply return the required dependencies.
esquire('requestedModule')
.then(function(result) {
});
Timeouts
As module creation is asynchronous, it might be useful to specify a timeout
when creation should fail.
By default the timeout is 2000 ms (2 sec), but a different timeout can be
specified at construction time. The minimum timeout is 100 ms.
new Esquire(60000).require('foo')
.then(function(foo) {
});
Loading
While optional, loading of external scripts is also supported, with the same
Promise
mechanism (especially useful in browser environments).
And as Promise
s can be easily chained, constructs like the following can
be quite useful:
Esquire.load("myOtherScript.js")
.then(function() {
return esquire("moduleFromMyOtherScript");
})
.then(function(myModule) {
});