jquery-waiter

Lightweight (1KB) dependency management built on jQuery Deferreds.

##### Dependencies

jQuery 1.5+

Getting Started

Include waiter.js anywhere after jQuery.

``html


`

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__( _String_ __name__ , _Varied_ __payload__ [, _Object_ __options__ ]);

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__( [ _Array_ __names__ ] [, _String_ __name*__ ] );

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.

`js
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

`js
waiter.waitFor('MyModule1', 'MyModule2').then(function(MyModule1, MyModule2) {
var mod1 = new MyModule1(),
mod2 = new MyModule2();
});
`
Optionally pass an array instead of individual arguments:

`js
var dependencies = ['MyModule1', 'MyModule2'];

waiter.waitFor(dependencies).then(...);
`

#### Define and use a remote module (or data)

`js
waiter.load('config', '/my/config.json');

waiter.waitFor('config').then(function(config) {
console.log(config.foo);
});
`

##### Works with jsonp too

`js
waiter.load('myJsonpSource', 'http://cross-domain.com/script', {dataType: 'jsonp'});
waiter.waitFor('myJsonpSource').then(function(data){
// do stuff with data
});
`

##### Optionally specify expected export

`js
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:

`js
waiter.unload('myData');
waiter.load('myData', 'http://my.dynamic-remote.com/');
`
TODO: Maybe a per module cache option?

#### Leverage $.Deferred callbacks

`js
waiter.waitFor('myRemote')
.progress(progressFn)
.then(successFn)
.fail(failFn)
`

##### Middleware

`js
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:

`js
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

});
``