defer.coffee

# defer can be placed in front of any function call that takes
# a callback as its last paramater.

# instead of this:
myFunc: (callback) ->
  someFunction 1, 2, 3, (result) ->
    doSomeThingWith(result)
    callback(true)

# you will write this:
myFunc: (callback) ->
  result: defer someFunction(1, 2, 3)
  doSomeThingWith(result)
  callback(true)

# You can also receive multiple arguments, like so:
myFunc: (callback) ->
  [error, result]: defer someFunction(1, 2, 3)
  return callback(false) if error
  doSomeThingWith(result)
  callback(true)

# defer can be used in comprehensions, branches, switches,
# wherever you need. for example:

getItems: (ids, callback) ->
  callback(defer store.getItem(id) for id in ids)

# this translates (roughly) into the following manual code:

getItems: (ids, callback) ->
  results: []
  iterate: ->
    if ids.length == 0
      callback(results)
      return
    id: remaining.shift()
    store.getItem id, (item) ->
      results.push(item)
      iterate()
  iterate()

# pretty awkward for a simple list comprehension, eh? good thing `defer` exists!

javascript_compiled.js

// for illustration (and if you aren't sure how something works),
// here's the compiled javascript of the above deferred code:

(function(){
  var getItems, myFunc;


  // defer can be placed in front of any function call that takes
  // a callback as its last paramater.
  // instead of this:
  myFunc = function(callback) {
    return someFunction(1, 2, 3, function(result) {
      doSomeThingWith(result);
      return callback(true);
    });
  };


  // you will write this:
  myFunc = function(callback) {
    var _a;
    someFunction(1, 2, 3, function(_a) {
      var result;
      result = _a;
      doSomeThingWith(result);
      return callback(true);
    });
  };


  // You can also receive multiple arguments, like so:
  myFunc = function(callback) {
    var _a;
    someFunction(1, 2, 3, function(_a) {
      var _b, error, result;
      _b = arguments;
      error = _b[0];
      result = _b[1];
      if (error) {
        return callback(false);
      }
      doSomeThingWith(result);
      return callback(true);
    });
  };


  // defer can be used in comprehensions, branches, switches,
  // wherever you need. for example:
  getItems = function(ids, callback) {
    var _a, _c, _d, _e, _f, _h, _i, _j, _k, _l, _m, id;
    (function(_b) {
      _c = (function() {
        _j = []; _l = ids;
        for (_k = 0, _m = _l.length; _k < _m; _k++) {
          _a = _l[_k];
          _j.push(_a);
        }
        return _j;
      })();
      _d = [];
      (function(_g) {
        _h = function() {
          if (!(_c.length > 0)) {
            return _g(undefined);            //break;
          }
          id = _c.shift();
          store.getItem(id, function(_o) {
            _f = _o;
            _d.push(_f);
            return _h(undefined);            //continue;
            return undefined;
          });
        };
        return _h(undefined);
        return _g(undefined);
      })(function(_n) {
        _n;
        return _b(_d);
      });
    })(function(_i) {
      return callback(_i);
    });
  };
})();