jquery-waiter

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( 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.

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 
  
});