promise-aggregator v1.0.3

promise-aggregator

A tool for aggregating promises that should resolve within a specified time.

Examples

Get Result Values

The aggregator returns an array of aggregator-results. You can get just the values by using mapping the array.

const aggregator = require('promise-aggregator');

// create some promises
const p1 = doSomethingAsync();
const p2 = doSomethingAsync();

const promise = aggregator([p1, p2])
    .then(results => results.map(result => result.value);

Timeout

const aggregator = require('promise-aggregator');

// create some promises
const p1 = doSomethingAsync();
const p2 = doSomethingAsync();

const promise = aggregator([p1, p2], {
    timeout: 3000
});

// shorthand equivalent
// const promise = aggregator([p1, p2], 3000);

Timeout with Optional Promise and Defaults

const aggregator = require('promise-aggregator');

// create some promises
const p1 = doSomethingAsync();
const p2 = doSomethingAsync();

const promises = [
    Object.assign(p1, { required: false }),
    Object.assign(p2, { default: 5 })
];

const promise = aggregator(promises, 3000);

Progress Callback

const aggregator = require('promise-aggregator');

// create some promises
const p1 = doSomethingAsync();
const p2 = doSomethingAsync();

const promise = aggregator([p1, p2], {
    progress: (err, value, state, done) => {
        // ...
    }
});

// shorthand equivalent
// const promise = aggregator([p1, p2], (err, value, state, done) => {
//     ...
// });

API

Signature aggregator( promises [, options ]) : Promise

Parameters

• promises - An array of promise objects. These objects can be augmented by adding properties that will affect the way the aggregator resolves each promise:

  • default - Specify a value to resolve to if the promise does not resolve within the specified timeout.

  • required - A required promise must resolve within the timeout (although it may have a default). Failure to do so will cause the promise to reject with an error code: PA_PROMISE_TIMEOUT. Defaults to true.

• options - Optional configuration options. Can be a Number, Function, or Object.

  If a Number then the number will signify the number of milliseconds to wait before timeout. This is shorthand for setting the timeout value.

  If a Function then the function will be used as the progress callback function. This is shorthand for setting the progress function.

  If an Object then these are the options:

  • final - A Boolean signifying whether the progress function should continue to be called after timeout. This value must be accompanied by a timeout value and progress function to do anything.

  • progress - A Function that will be called each time a promise resolves (or rejects if settle is true). The function will receive these parameters:

    1. error - The promise rejection reason if rejected.

    2. value - The promise resolve value if resolved.

    3. state - An object with state properties that can be used to evaluate current progress.

    4. done - A function that if called will cause the aggregator promise to resolve immediately with its current results. If this function is provided a parameter then it will cause the aggregator promise to reject immediately.

       (err, value, state, done) => {
           done(); // resolve aggregator promise immediately
       });

       (err, value, state, done) => {
           done(Error(''); // reject aggregator promise immediately
       });

  • settle - A Boolean specifying whether to await all promises when a rejection occurs or to reject immediately. Set to true to allow all promises to finish. Defaults to false.

  • timeout - The number of milliseconds to allow the aggregator to collect results.

Returns a Promise that resolves to an array of results.

Progress State

A progress function receives a state object as it's third parameter. The state object has the following properties:

• complete - A function that can be called to determine which promises have completed (are not pending). This function takes any number of parameters where each parameter is the index of the promise to check for completion.

  aggregator([p0, p1, p2], (err, value, state, done) => {
  
      // determine if promises p0 and p2 have completed
      if (state.complete(0, 2)) { ... }
  
      // determine if promises p0, p1, and p2 have completed
      if (state.complete(0, 1, 2) { ... }
  
  });

• incomplete - A function that can be called to determine which promises are pending. This function takes any number of parameters where each parameter is the index of the promise to check for completion.

  aggregator([p0, p1, p2], (err, value, state, done) => {
  
   // determine if promises p0 and p2 are pending
   if (state.incomplete(0, 2)) { ... }
  
   // determine if promise p1 is pending
   if (state.complete(1) { ... }
  
  });

• pending - The number of pending promises.

• results - A current copy of the aggregator-results.

Aggregator Results

The aggregator returns a promise that resolves to an array of objects. The objects have the following properties:

• default - A Boolean that will be set to true if the promise was resolved by using the default value.

• error - null if no error occurred or if the promise was rejected (and the aggregator was told to settle the promises) then this value will contain the rejection reason.

• pending - A boolean specifying whether the promise is still pending.

• success - A boolean specifying whether the promise resolved successfully. Will be false if the promise was rejected.

• value - The value that the promise resolved to. Will be undefined if success === false.