README
![](http://roomkey.github.io/waiter/assets/logo.png)
Lightweight (1KB) dependency management built on jQuery Deferreds.
Dependencies
jQuery 1.5+
Getting Started
Include waiter.js anywhere after jQuery.
<script src="jquery.js"></script>
<script src="waiter.js"></script>
Waiter is built for modular applications. Module names associate a key to a payload, allowing you to delay execution of a function until dependencies are met. The payload can be anything: text, json, a function; often it will be a URL to a javascript file.
Before diving in, let's look at the two most important function signatures.
void
load
( Stringname
, Variedpayload
[, Objectoptions
]);
The load
method registers an object or URL, automatically loading it if necessary (via jQuery.ajax). The object or resource pointed to by the URL will be used to resolve the promise returned by waitFor
.
$.Promise
waitFor
( [ Arraynames
] [, Stringname*
] );
waitFor
accepts either an array of module names or a variable-length parameter list of names. These represent the dependencies that need to be loaded before the promise is resolved. Potential gotcha: notice that waitFor
accepts strings and returns a promise. First-time users may find themselves wrongly passing a function to waitFor
instead of attaching the function with .then()
.
Define and use a local module
In the example below, the function that depends on MyModule
will delay execution until it has loaded.
waiter.waitFor('MyModule').then(function WontRunUntilLoad(MyModule) {
var myModule = new MyModule({foo: 'bar'});
});
waiter.load('MyModule', function SomeConstructor(options) {
this.foo = options.foo;
});
Multiple modules
waiter.waitFor('MyModule1', 'MyModule2').then(function(MyModule1, MyModule2) {
var mod1 = new MyModule1(),
mod2 = new MyModule2();
});
Optionally pass an array instead of individual arguments:
var dependencies = ['MyModule1', 'MyModule2'];
waiter.waitFor(dependencies).then(...);
Define and use a remote module (or data)
waiter.load('config', '/my/config.json');
waiter.waitFor('config').then(function(config) {
console.log(config.foo);
});
Works with jsonp too
waiter.load('myJsonpSource', 'http://cross-domain.com/script', {dataType: 'jsonp'});
waiter.waitFor('myJsonpSource').then(function(data){
// do stuff with data
});
Optionally specify expected export
waiter.load('underscore', '//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.6.0/underscore-min.js', {exports: '_'});
waiter.waitFor('underscore', function(_) {
_.identity('foo');
});
Note that remote modules, data, and so on are all cached in memory. If the remote is expected to be dynamic, unload the module before calling it again:
waiter.unload('myData');
waiter.load('myData', 'http://my.dynamic-remote.com/');
TODO: Maybe a per module cache option?
Leverage $.Deferred callbacks
waiter.waitFor('myRemote')
.progress(progressFn)
.then(successFn)
.fail(failFn)
Middleware
waiter.waitFor('MyRemote').then(transformMyRemote).done(function(MyRemote) {
// do stuff with the transformed MyRemote
});
More examples
See our interactive examples file.
Configuration
Call the config()
method before using modules or at any time to overwrite values. See below for defaults:
waiter.config({
// default timeout for local modules, in ms
timeout: 15000,
// store custom timeouts in format 'module': timeout in ms
moduleTimeouts: {
'MyModule': 3000
},
// for remotes, each value represents one try, to run after the specified ms since previous try
retries: [5000, 8000, 5000],
// custom progress callback for slow remotes. this will be called once for
// every try after the first try in the 'retries' array above.
progressHandler: null,
// custom error handler
errorHandler: null,
// log errors to console
debug: true
});