Main algorithms

This module provides a function that takes a deferred constructor and returns a set of promise aggregating functions. If these functions need to create promises internally, they will use the provided constructor. If no constructor is passed (or it is null or undefined), a standard Promise will be used.

Following functions are returned:

• all() — similar to standard Promise.all(). Returns an array of results, or fails with a first failed promise.
  • par() — collects all results into an array, both normal values, and errors. Never fails.
    • Use case: collect all I/O results regardless if they failed or not.
    • Use case: wait for all asynchronous operations to finish regardless of their outcome.
  • seq() — run asynchronous operations sequentially one after another.
    • Use case: run operations, which depend on previous asynchronous results.
• Race asynchronous operations determing a winner:
  • race() AKA one() — similar to standard Promise.race(). Resolves or fails with the first fulfilled promise.
  • any() — resolves with a first resolved promise. Failed promises are ignored unless all of them have failed. In the latter case it fails with the value of the first one in the array.
    • Use case: use the first successful I/O request, ignore services that failed.

Example:

var io = require('heya-io');

var par = require('heya-async').par;

par(
  io.get('http://www.google.com/'),
  io.get('http://www.yahoo.com/')
).then(function (results) {
  console.log('Both operations are finished.');
  results.forEach(function (result) {
    if (result instanceof io.FailedIO) {
      console.log('Error:', result.xhr.statusCode);
    } else {
      console.log('Got something!');
    }
  });
});

If operations are based on cancellable promises like async.Deferred or async.FastDeferred, the resulting promise can be cancelled, which trigger cancelling all related promises as well. In short, it is possible to cancel in one go all promises that are being composed.

All functions can use different implementations of promises internally. If you want to use these algorithms with async.Deferred or async.FastDeferred, consider using async.Deferred-ext or async.FastDeferred-ext modules respectively.

Module

The module function returns an object with five properties: all, par, any, one, and race. Each property is a function described below. race and one alias the same function.

Note: all algorithms may attempt to cancel unneeded promises, if they support cancellation, to indicate that there is no need in their result. Obviously standard Promise does not support such feature, so no cancellation is performed. Progress signals are ignored even if supported by underlying promises.

all()

var promise = all(val1, ... , valN);

or

var promise = all([val1, ..., valN], Deferred);

The first version assumes that internally the standard Promise is used. The second version takes an array, and an optional Deferred argument to specify what to use internally (usually async.Deferred or async.FastDeferred).

This algorithm was standardized as Promise.all().

Accepts a list of promises and non-promise values of any type either as separate arguments or as a single argument of the type Array. Returns a promise that resolves to the array containing only non-promise values — the ones the promises have resolved to, and originals, where non-promises were passed in — in the same order, after all passed in promises have resolved. Any resolved promises passed into the call will be replaced with their values. If all arguments are non-promises or resolved promises, a resolved promise will be returned.

If any of the promises is rejected, the resulting promise will also be rejected. If a rejected promise is passed in, the returned value will also be a rejected promise. In either case, any promises in the list that have not yet been resolved, will be cancelled with the reason taken from the rejection's value. If the returned promise is cancelled, all as yet unresolved promises in the list are also cancelled with the same reason.

par()

var promise = par(val1, ... , valN);

or

var promise = par([val1, ..., valN], Deferred);

The first version assumes that internally the standard Promise is used. The second version takes an array, and an optional Deferred argument to specify what to use internally (usually async.Deferred or async.FastDeferred).

Accepts a list of promises and non-promise values of any type either as separate arguments or as a single argument of the type Array. Returns a promise that resolves to the array containing only non-promise values — the ones the promises have resolved to, and originals, where non-promises were passed in — in the same order, after all passed in promises have resolved. Any resolved promises passed into the call will be replaced with their values. If all arguments are non-promises or resolved promises, a resolved promise will be returned.

If any of the promises is rejected, it is replaced in the list with the value it was rejected with. Note that it is not possible to tell afterwards whether a promise has been rejected or resolved, unless the determination can be made based on the resulting value (e.g. with an instanceof Error check). The returned promise is never rejected. If the returned promise is cancelled, all as yet unresolved promises in the list are also cancelled with the same reason.

any()

var promise = any(val1, ... , valN);

or

var promise = any([val1, ..., valN], Deferred);

The first version assumes that internally the standard Promise is used. The second version takes an array, and an optional Deferred argument to specify what to use internally (usually async.Deferred or async.FastDeferred).

Accepts a list of promises and non-promise values of any type either as separate arguments or as a single argument of the type Array. Returns a promise that resolves to the value of the first of the arguments to resolve. If non-promises or resolved promises are present in the list, a resolved promise will be returned with one of their values. If all promises passed into the call are rejected, the resulting promise is also rejected with the value passed into the last rejected argument.

Any of the promises still unresolved when the final result becomes resolvable will be cancelled. If the returned promise is cancelled, all as yet unresolved promises in the list are also cancelled with the same reason.

race() or one()

var promise = race(val1, ... , valN);

or

var promise = race([val1, ..., valN]);

The first version assumes that internally the standard Promise is used. The second version takes an array, and an optional Deferred argument to specify what to use internally (usually async.Deferred or async.FastDeferred).

This algorithm was standardized as Promise.race().

Accepts a list of promises and non-promise values of any type either as separate arguments or as a single argument of the type Array. Returns a promise that resolves to the value of the first of the arguments to resolve or rejects with the value of the first of the promises to reject. If non-promises or resolved (or rejected) promises are present in the list, a resolved (or rejected) promise will be returned with one of their values. If both non-promise values (or resolved promises) and rejected promises are present in the list, the returned value may be either a resolved or a rejected promise.

Any of the promises still unresolved when the final result is determined, will be cancelled. If the returned promise is cancelled, all as yet unresolved promises in the list are also cancelled.