Promise-enhancements NPM

Promise-Enhancements

This library enhances the Promise base class by adding many various additional functions: (with examples)

Installation

Standard npm install:

npm install promise-enhancements

API

Static functions

Promise.retry(fn, options):

Retry function for repeated validation on Promise Other options: {times: 1, delay: 500, printErrors: false, errorPrefix: ''}
async function worksFifthTime() {
    const c = window.count = (window.count || 0) + 1
    if (c > 4) return 'Yay'
    throw 'Nay'
}
Promise.retry(worksFifthTime, {retries: 2}) // Error: Nay, Nay
Promise.retry(worksFifthTime, {retries: 8}) // Yay

Promise.firstSuccess(arr):
Like Promise.map, but will yield at the first success. It will fail if all cases are rejections
```
Promise.firstSuccess([
    Promise.reject(10),
    Promise.reject(20),
]) // = Error: 10, 20
```
Promise.firstSuccess( Promise.reject(10), 20, Promise.reject(30), ) // = 20
Promise.sync(tasks)
Runs an array of async functions in sequence (where the output of the previous callback is the input for the next)
```
const increment = n => n+1
const getServerCount = async domain => /* returns a number */
```
Promise.sync('domain.com', getServerCount, increment, increment) // Output: 'domain.com', 10, 11, 12

Dynamic functions

<promise>.returns(value):

Uses the value provided as the argument as the seed for the next step

Promise.resolve(1)
    .then(add1)
    .returns(0)
    .then(add1) // = await add1(0) = 1
// While all steps in the chain ran, the next element after return uses the new value

<promise>.sleep(value):

Sleeps on current step in the chain

Promise.resolve('//computername')
    .then(restartComputer)
    .return('//computername')
    .sleep(10e3) // 10s
    .then(checkIfOnline)

<promise>.print(value):

Uses the value provided as the argument as the seed for the next step

Promise.resolve(1)
    .print('Starting Chain with 1')
    .then(add1)
    .print(v => `New Value = ${v}`)       // Callback print syntax
    .print('Ending Chain', console.error) // Prints as an error

<promise>.map(value):
Same usage as Array.map but on promises! Same as <promise>.then(arr => Promise.all(arr.map(callback)).
```
Promise.resolve([1,2,3,4,5])
    .map(i => i**2)
    .map(fetchGithubUserByID) // Async task
    .map(i => i.user.image)
```
// Fetches github profile images for Users: 1, 4, 9, 16, and 25
<promise>.sync(callback):
Like <promise>.map but each task runs in sequence. Task = callback(input[task_index]) where task_index = 0..(input.length)
```
Promise.resolve(['jon', 'ally', 'ap'])
    .sync(restartComputer)
```
// Restart('jon'), if success only then restart('ally'), etc