promiso

Promiso

Powerful promise utilities for any JS environment - because who uses callbacks in 2018?

Installation

npm i promiso

Requirements

• ES5-compatible environment
• ES6-compatible Promise defined globally (try es6-promise polyfill)

Usage

Standard promises

const promiso = require('promiso');

// Double a number after 1 second.
const slowDouble = (number) => {
  return new Promise((resolve) => {
    setTimeout(() => resolve(number * 2), 1000);
  });
};

const numbers = [1, 2, 3, 4];

promiso.mapLimit(numbers, 2, slowDouble)
  .then((doubled) => {
    // 4 items limited to 2 concurrent executions, so this should fire after about 2 seconds.
    console.log(doubled); // [2, 4, 6, 8]
  });

async/await

const promiso = require('promiso');

// Helper function for async/await.
const sleep = (time) => new Promise((resolve) => setTimeout(resolve, time));

// Triple a number after 1 second.
const slowTriple = async (number) => {
  await sleep(1000);
  return number * 3;
};

const numbers = [1, 2, 3, 4, 5, 6];

const main = async () => {
  const tripled = await promiso.mapLimit(numbers, 3, slowTriple);
  // 6 items limited to 3 concurrent executions, so this should complete after about 2 seconds.
  console.log(tripled); // [3, 6, 9, 12, 15, 18]
};

main();

With TypeScript

Promiso is transpiled from TypeScript with type definitions, so it should work out of the box with TypeScript :-)

API

Actual docs coming soon :-)

See the documentation for the original async library, but Promiso offers these improvements:

• An "async function" in Promiso is any function that always returns a promise. This includes ES2017's true async functions - even if they have been transpiled!
• Whenever Promiso expect an async function, you can instead use a synchronous function and obtain the same result without any errors. Normal guarantees about concurrent executions will not apply, since only one synchronous function can be running at a time.
• You can even mix and match async and sync functions or use functions that only sometimes return promises (with the same caveats mentioned above).
• Promiso library functions do not accept callbacks. They instead return promises that resolve or reject accordingly.

The following functions are available (with support planned for every function available in async):

• concat
• concatLimit
• concatSeries
• map
• mapLimit
• mapSeries
• parallel
• parallelLimit
• series