Deferred 0.0.5

Instantiation

can be instantiated using new

var d;
d = new Deferred();
return expect(d).to.be.ok();

can be instantiated without the new operator

var d;
d = Deferred();
expect(d).to.be.ok();
return expect(d.then).to.be.a('function');

Integrity

Cannot be fulfilled (i.e. resolved or rejected) more than once

var d;
d = Deferred();
d.resolve();
return expect(d.resolve).to.throwException(/already completed/i);

Synchronously call listeners when they are added if promise is already fullfilled

var failureCallback, successCallback, willFail, willSucceed;
successCallback = sinon.spy();
willSucceed = Deferred();
willSucceed.resolve("win!");
willSucceed.then(successCallback);
expect(successCallback.calledOnce).to.be(true);
failureCallback = sinon.spy();
willFail = Deferred();
willFail.reject("Ohno!");
willFail.fail(failureCallback);
return expect(failureCallback.calledOnce).to.be(true);

Notifies always-listeners after then/success/fail listeners

var d, spyAlways, spySuccess;
spyAlways = sinon.spy();
spySuccess = sinon.spy();
d = Deferred();
d.then(spySuccess);
d.then(function() {
  return expect(spyAlways.called).to.be(false);
});
d.always(spyAlways);
d.always(function() {
  return expect(spySuccess.called).to.be(true);
});
return d.resolve();

Notifies listeners in the order they are added

var d, i, spies;
spies = (function() {
  var _i, _results;
  _results = [];
  for (i = _i = 0; _i < 10; i = ++_i) {
    _results.push(sinon.spy());
  }
  return _results;
})();
d = Deferred();
d.then(spies[0]);
d.then(function() {
  return expect(spies[0].called).to.be(true);
});
d.then(function() {
  return expect(spies[1].called).to.be(false);
});
d.then(function() {
  return expect(spies[2].called).to.be(false);
});
d.then(spies[1]);
d.then(function() {
  return expect(spies[0].called).to.be(true);
});
d.then(function() {
  return expect(spies[1].called).to.be(true);
});
d.then(function() {
  return expect(spies[2].called).to.be(false);
});
d.then(spies[2]);
d.then(function() {
  return expect(spies[0].called).to.be(true);
});
d.then(function() {
  return expect(spies[1].called).to.be(true);
});
d.then(function() {
  return expect(spies[2].called).to.be(true);
});
return d.resolve();

Deferred API

notifies listeners with the argument list passed to resolve

var d, spy;
spy = sinon.spy();
d = Deferred();
d.then(spy);
d.resolve("hipp", "hopp");
return expect(spy.calledWith("hipp", "hopp")).to.be(true);

notifies then/success-listeners when resolved

var d, spy;
spy = sinon.spy();
d = Deferred();
d.then(spy);
d.resolve("hepp");
return expect(spy.calledWith("hepp")).to.be(true);

notifies fail-listeners when rejected

var d, spy;
spy = sinon.spy();
d = Deferred();
d.fail(spy);
d.reject("oh noes");
return expect(spy.calledWith("oh noes")).to.be(true);

notifies progress listeners when notified

var d, spy;
spy = sinon.spy();
d = Deferred();
d.progress(spy);
d.notify("oh noes");
expect(spy.calledWith("oh noes")).to.be(true);
d.notify("oh noes !!");
expect(spy.calledWith("oh noes !!")).to.be(true);
return expect(spy.calledTwice).to.be(true);

notifies progress listeners added later

var d, spy;
spy = sinon.spy();
d = Deferred();
d.notify("tick 1");
d.notify("tick 2");
d.notify("tick 3");
d.progress(spy);
expect(spy.calledWith("tick 1")).to.be(true);
expect(spy.calledWith("tick 2")).to.be(true);
expect(spy.calledWith("tick 3")).to.be(true);
return expect(spy.calledThrice).to.be(true);

resolves immediately if Deferred.when is called without any arguments

var d, spy;
d = Deferred();
spy = sinon.spy();
Deferred.when().then(spy);
return expect(spy.calledOnce).to.be(true);

notifies always-listeners when resolved

var d, spy;
d = Deferred();
spy = sinon.spy();
d.always(spy);
d.resolve("hepps");
return expect(spy.calledWith("hepps")).to.be(true);

notifies always-listeners when rejected

var d, spy;
d = Deferred();
spy = sinon.spy();
d.always(spy);
d.reject("oh no!");
return expect(spy.calledWith("oh no!")).to.be(true);

notifies the correct listeners added with then() upon resolve

var d, spyComplete, spyFailure, spyProgress, spySuccess;
spySuccess = sinon.spy();
spyFailure = sinon.spy();
spyProgress = sinon.spy();
spyComplete = sinon.spy();
d = Deferred();
d.then(spySuccess, spyFailure, spyProgress, spyComplete);
d.notify("tick tack");
d.resolve("Yay");
expect(spyProgress.calledWith("tick tack")).to.be(true);
expect(spySuccess.calledWith("Yay")).to.be(true);
expect(spyFailure.called).to.be(false);
return expect(spyComplete.called).to.be(true);

notifies the correct listeners added with then() upon reject

var d, spyComplete, spyFailure, spyProgress, spySuccess;
spySuccess = sinon.spy();
spyFailure = sinon.spy();
spyProgress = sinon.spy();
spyComplete = sinon.spy();
d = Deferred();
d.then(spySuccess, spyFailure, spyProgress, spyComplete);
d.notify("tick");
d.notify("tack");
d.reject("Bam!");
expect(spyProgress.calledWith("tick")).to.be(true);
expect(spyProgress.calledWith("tack")).to.be(true);
expect(spyProgress.calledTwice).to.be(true);
expect(spyFailure.calledWith("Bam!")).to.be(true);
expect(spySuccess.called).to.be(false);
return expect(spyComplete.called).to.be(true);

can be queried about state

var reject, resolve;
expect(Deferred().state()).to.be('pending');
resolve = Deferred();
resolve.resolve("fantastic");
expect(resolve.state()).to.be('resolved');
reject = Deferred();
reject.reject("not so good");
return expect(reject.state()).to.be('rejected');

Promise API

Lacks mutators

var promise;
promise = Deferred().promise();
expect(promise).not.to.have.property('reject');
expect(promise).not.to.have.property('resolve');
return expect(promise).not.to.have.property('notify');

notifies listeners as it should

var d, promise, spyComplete, spyFailure, spyProgress, spySuccess;
spySuccess = sinon.spy();
spyFailure = sinon.spy();
spyProgress = sinon.spy();
spyComplete = sinon.spy();
d = Deferred();
promise = d.promise();
promise.then(spySuccess, spyFailure, spyProgress, spyComplete);
promise.progress(spyProgress);
promise.always(spyComplete);
d.notify("tick");
d.notify("tack");
d.reject("Bam!");
expect(spyProgress.calledWith("tick")).to.be(true);
expect(spyProgress.calledWith("tack")).to.be(true);
expect(spyProgress.callCount).to.be(4);
expect(spyFailure.calledWith("Bam!")).to.be(true);
expect(spySuccess.called).to.be(false);
return expect(spyComplete.calledTwice).to.be(true);

allows for registering listeners using both deferred api and promise api

var deferredSpy, promiseSpy;
deferredSpy = sinon.spy();
promiseSpy = sinon.spy();
Deferred().then(deferredSpy).promise().then(promiseSpy).resolve("Hooray!");
expect(deferredSpy.calledWith("Hooray!")).to.be(true);
return expect(promiseSpy.calledWith("Hooray!")).to.be(true);

Chainability

Resolves only when all chained promises gets resolved

var d1, d2, d3, spy;
d1 = Deferred();
d2 = Deferred();
d3 = Deferred();
spy = sinon.spy();
Deferred.when(d1, d2, d3).then(spy);
expect(spy.called).to.be(false);
d1.resolve();
expect(spy.called).to.be(false);
d2.resolve();
expect(spy.called).to.be(false);
d3.resolve();
return expect(spy.called).to.be(true);

does not resolve if one of the chained promises gets rejected

var d1, d2, d3, spy;
d1 = Deferred();
d2 = Deferred();
d3 = Deferred();
spy = sinon.spy();
Deferred.when(d1, d2, d3).then(spy);
d1.resolve();
d2.reject();
d3.resolve();
return expect(spy.called).to.be(false);

passes only rejected values to fail listeners (in the order they were added)

var d1, d2, d3, spy;
d1 = Deferred();
d2 = Deferred();
d3 = Deferred();
spy = sinon.spy();
Deferred.when(d1, d2, d3).fail(spy);
d3.resolve("yay3");
d2.reject("ouch!", "abc");
d1.resolve("yay1", "yay1.1");
return expect(spy.calledWith(void 0, ['ouch!', "abc"], void 0)).to.be(true);

allows for creating a new chain (which only can be resolved by its individual promises)

var d1, d2, spy;
d1 = Deferred();
d2 = Deferred();
spy = sinon.spy();
Deferred.chain().join(d1).join(d2).then(spy);
d1.resolve();
d2.resolve();
return expect(spy.called).to.be(true);

Any call to Deferred.when returns a chain

var d1, d2, d3, d4, spy;
d1 = Deferred();
d2 = Deferred();
d3 = Deferred();
d4 = Deferred();
spy = sinon.spy();
Deferred.when(d1, d2).join(d3, d4).then(spy);
d3.resolve('d3');
d4.resolve('d4');
d2.resolve('d2');
d1.resolve('d1');
return expect(spy.calledWith(['d1'], ['d2'], ['d3'], ['d4'])).to.be(true);