Promise Cheat-Sheet

PromisePlayground.js

/**
 * This is from many sources. Important points:
 * - A promise will immediately start resolving when created unless it’s in a function being passed around.
 * - Note the special syntax when adding promises to arrays to avoid having the Promise begin resolving.
 * - Note the various patterns, series and parallel, with concurrency control.
 *
 * This work is licensed under the MIT License as follows:
 *
 * Copyright 2018 E.A.Soto <easoto@iss-pr.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 * documentation files (the "Software"), to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
 * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all copies or substantial portions
 * of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 */

/* jshint indent: 2 */
/* jshint esversion: 6 */ 

// SETUP

// We start with a function that returns a promise
function funcThatReturnsPromise(params) {
  return new Promise((resolve, reject) => {
    // Whatever work...
    // Eventually, resolve() or reject() as appropriate
  });
}

// Note the syntax to avoid starting to resolve the Promise!
// We want to deliberately start the promises when WE want, 
// not immediately!

// We then add the promise returning function(s) to an array
let promiseArray = [];
promiseArray.push(() => funcThatReturnsPromise(params));
promiseArray.push(() => funcThatReturnsPromise(params));
promiseArray.push(() => funcThatReturnsPromise(params));

// USAGE

// PATTERN 1
// To resolve all the promises, in series in this case
// Note the result of the Promise.each is the EXACT SAME promiseArray that was passed!
// So, this pattern is good for side effects, not to aggregate results of individual promises.
// See other examples for storing results
Promise.each(
  promiseArray, (aPromise, index, length) => {
  // This return is what will finally START to resolve the promise
  return aPromise();
}).then().catch();

// PATTERN 2 (Same as 1 but with results capture)
// To resolve all promises (series) AND capture the results for each for later inspection
let promiseResults = [];
Promise.each(
  promiseArray, (aPromise, index, length) => {
  // This return is what will finally START to resolve the promise
  return aPromise().then(result => {
    promiseResults[index] = result;
  });
}).then(() => {
  // promiseResults can now be iterated over to see individual results
}).catch();

// PATTERN 3
// To allow some concurrency when resolving (example = 3 concurrent)
// Order of promises is NOT guaranteed (see mapSeries if order is important!)
// Note that the same pattern above for "result capture" can be used here!
Promise.map(
  promiseArray,
  (aPromise, index, length) => {
    return aPromise();
  },
  { concurrency: 3 }
).then().catch();

// PATTERN 4
// To allow some concurrency when resolving (example = 3 concurrent)
// Order of promises is SERIAL within the concurrency
// Note that the same patter above for "result capture" can be used here!
Promise.mapSeries(
  promiseArray,
  (aPromise, index, length) => {
    return aPromise();
  }
).then().catch();