promise-settle-nice

Settle promises civilly - plays nicely with other APIs

Usage

To control the timing and rejection of promises, specifically when dealing with API calls using request

Table of Contents

• Usage
• Sequential Settle
  • Parameters
  • Example
• Interval Settle
  • Parameters
  • Example
• Single Settle
  • Parameters
  • Return Value
  • Example
• Using Request
  • Example

Sequential Settle

Settles promises sequentially.

Parameters for sequential settle

Takes one parameters:

1. An array of promises or values.

Returns an array of settled promises.

Example of sequentially settling promises

const Promise = require('bluebird'); // To generate promises
const sequentialSettle = require('promise-settle-nice').sequential;

/**
 * Generates a number of promises (half rejected, half resolved)
 * @param num is the number of promises to generate
 * @returns {Array} of promises
 */
const genPromises = (num) => {
  let promises = [];
  for (let i = 0; i < num; i++) {
    let promise = i % 2 === 0 ? Promise.reject(i) : Promise.resolve(i);
    // let promise = Promise.resolve(i);
    promises.push(promise);
  }
  return promises;
};

sequentialSettle(genPromises(15))
  .then(results => console.log(results)) // Results is an array of objects (see return section to understand the properties returned).
  .catch(err => console.error('Error:', err)); // Won't get here

Interval Settle

Settles an array of promises in timed intervals. Promises are grouped and then each group is given a delay, each consecutively longer than the previous. The settled promises are then compiled to a single array. Keep in mind that promise groups are not always executed sequentially (see Sequential Settle).

Parameters for interval settle

Takes in two parameters:

1. An array of promises or values.
2. A configuration object with the following properties:
   • size: how many promises to execute every interval.
   • time: the time interval to execute the promises.

Returns an array of settled promises.

Example of settling promises on an interval

const Promise = require('bluebird'); // To generate promises
Array.prototype.intervalSettle = require('promise-settle-nice').interval;

/**
 * Generates a number of promises (half rejected, half resolved)
 * @param num is the number of promises to generate
 * @returns {Array} of promises
 */
const genPromises = (num) => {
  let promises = [];
  for (let i = 0; i < num; i++) {
    let promise = i % 2 === 0 ? Promise.reject(i) : Promise.resolve(i);
    // let promise = Promise.resolve(i);
    promises.push(promise);
  }
  return promises;
};

intervalSettle(genPromises(15), { size: 3, time: 5 })
  .then(results => console.log(results)) // Results: [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 ]
  .catch(err => console.error('Error:', err)); // Won't get here

Single Settle

Settles a promise or value instead of rejecting.

Parameters for single settle

Takes only one parameter:

1. A promise or value.

Return value

The return value is an object with 4 properties:

1. isFulfilled: boolean.
2. isRejected: boolean.
3. value: the rejection reason or the fulfilled value.
4. original_value: the original promise request/value.

Example of settling a single promise

const settle = require('promise-settle-nice');
const val = 9;
const settled_promise = settle(val);
console.log(settled_promise); // Settled Promise: { isFulfilled: true, isRejected: false, value: 9, original_value: 9 }

Request

Adding .request after any of the above three functions will treat the values as request-promise options and will call the API specified in the options. This avoids getting uncaught API call errors.

Example of settling a single promise request

const settle = require('promise-settle-nice');
const rp = require('request-promise);

const options = {}; // request-promise options
const settled_request_promise = settle.request(options);
console.log(settled_promise); // Settled Promise: { isFulfilled: true, isRejected: false, value: {/* Your API response */}, original_value: {/* Your request options */} }