io and deferreds

io can work with any deferred objects, which satisfy minimal requirements.

By default, it comes with a deferred made out of the standard Promise, but extensively tested with heya-async deferred objects: FastDeferred and Deferred.

Requirements

These are the requirements for a constructor of deferred:

• It should create an object when invoked as a constructor.
• It should have resolve(value) method, which returns a resolved promise.
• It should have reject(value) method, which returns a rejected promise.

The requirements for a deferred object:

• The object should have resolve(value) method, which resolves a promise.
• The object should have reject(value) method, which rejects a promise.
• The object should have a property named promise, which returns a promise, or be a valid promise object itself.

The promise is any then-able: an object, which exposes then() method. That method should accept at least two callbacks: the first is called for resolved promises, the second is called for rejected promises.

io.FauxDeferred

Below is the full implementation as an illustration of requirements:

function FauxDeferred () {
  var resolve, reject,
    promise = new Promise(function executor (res, rej) {
      resolve = res;
      reject  = rej;
    });
  return {
    resolve: resolve,
    reject:  reject,
    promise: promise
  };
}
if (typeof Promise != 'undefined') {
  FauxDeferred.Promise = Promise;
  FauxDeferred.resolve = function (value) { return Promise.resolve(value); };
  FauxDeferred.reject  = function (value) { return Promise.reject(value); };
}

Advanced requirements

io can take advantage of two things: progress updates, and cancellation of asynchronous operations. In order to do that, it assumes following requirements:

• A deferred object constructor may take one argument: a cancel function, which is called, when a cancellation is requested.
  • If a promise supports this functionality, it usually exposes cancel(reason) method. When it is called, the whole branch of promises (if any) is cancelled (rejected with a specific value), and a cancel function is called with reason, so an underlying asynchronous (e.g., I/O) operation can be terminated.
• A deferred object may expose progress(value) method.
  • If a progress report is available, XHR can send progress updates for upload and download communications.

A progress object has four properties:

• xhr — an underlying XHR object.
• options — an options object describing the I/O request.
• upload — a Boolean value, which indicates what progress we are reporting.
• event — an event object. See progress for details.

heya-async

heya-async comes with two implementations of deferred: FastDeferred and Deferred. They both support progress updates, and cancellation, small, fast, and extensively tested with io and on its own. Until Promise becomes widespread, they both are viable options for any asynchronous operations.

heya-async can work with standard promises too, and comes with several useful algorithms, which help orchestrating complex I/O requests.