es-promise-ext

Native promise extensions for javascript and typescript.

[!IMPORTANT] This library extend the native objects Promise.prototype. This may lead to collision with other libraries or the latest version of ECMAScript.

Table of Contents

1. Installation
2. Usage
3. Functions
4. Advanced Usage
5. Test
6. License

Installation

Under your project folder, run the follow command in the terminal.

npm i --save es-promise-ext

Usage

Prototype Version

// For Promise prototype
// Import at the entry point of the project, such as index.ts
import from "es-promise-ext"

Promise.resolve(1)
  .delay(500)
  .then(value => {
    // do something
  });

Clean Version - (Non prototype pollution)

// For non-pollution
// Import at the .ts file where you are going to use
import { delay, ... } from "es-promise-ext/clean"

Promise.resolve(1)
  .then(delay(500))
  .then(value => {
    // do something
  });

Functions

Promise

Creates a Promise that is resolved with an array, an object or a Map of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

$${\color{gray}Parameters}$$

| Param | Type | Desc| | - | - | - | | values | Promise[] | an array of provided promise for resolving. |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any[] | a new promise for resolved results. |

$${\color{gray}Example}$$

Promise.allWith(
  [
    Promise.resolve(1),
    Promise.resolve(2),
    Promise.resolve(3)
  ]
) 
// return [1,2,3] in the subsequent promise

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | values | object | an object of provided promise for resolving. |

${\color{gray}Return}$

| Type | Desc| | - | - | | object | a new promise for resolved results. |

${\color{gray}Example}$

Promise.allWith(
  {
    someNumber: Promise.resolve(1),
    someString: Promise.resolve('test'),
    someBoolean: Promise.resolve(true)
  }
)     
// return the resolved object in the subsequent promise

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | values | Map | a Map of provided promise for resolving. |

${\color{gray}Return}$

| Type | Desc| | - | - | | Map | a new promise for resolved results. |

${\color{gray}Example}$

Promise.allWith(
  new Map(
    Object.entries({
      someNumber: Promise.resolve(1),
      someString: Promise.resolve('test'),
      someBoolean: Promise.resolve(true)
    })
  )
)     
// return the resolved object in the subsequent promise

Start promise after delaying.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | millisecond | number | a time for the delay. |

${\color{gray}Example}$

Promise.delay(300)  // return a void promise after delay 300 ms

Creates a Promise that is resolved sequentially with a result when all of the provided Promises resolve, or rejected when any Promise is rejected.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function[] | an array of async functions. | | options | object (Optional) | - | | options.canceller | object | set canceller.cancelled = true stopping the sequence | | options.progress | (subResult, step, total) => any | to show the progress and the sub result | | options.initValue | any | the initial value which pass to the first async function |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result of last resolved promise |

${\color{gray}Example}$

Promise.reduce(
  [
    plus(5),
    minus(2),
  ],
  {
    canceller: { cancelled: false }, 
    // set to true later
    progress: (subResult, step, total) => 
      { 
        console.log(subResult) 
        console.log(`${((step+1) / total)}%`)
      },
    initValue: 1
  }
)     
// return 4 in the subsequent promise

Starts a promise with an asynchronous function that has retry tolerance.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunction | function | an asynchronous function or promise that holds the result. | | count | number (Optional; default = 3) | a positive integer between 0 and 30 indicating the number of retries. | | delay | number (Optional; default = 100) | the time in milliseconds to wait between retries. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | The result within a promise after retries. |

${\color{gray}Example}$

Promise.retry(asyncFunction); 
Promise.retry(promise); 
Promise.retry(asyncFunction, 5, 1000); 
Promise.retry(promise, 5, 1000); 

Creates a Promise that is resolved sequentially with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function[] | an array of async functions. | | options | object (Optional) | - | | options.canceller | object | set canceller.cancelled = true stopping the sequence | | options.progress | (subResult, step, total) => any | to show the progress and the sub result | | options.skipIfError | boolean | - |

${\color{gray}Return}$

| Type | Desc| | - | - | | any[] | the result of resolved promise in an array |

${\color{gray}Example}$

Promise.sequence(
  [
    () => Promise.resolve(1),
    () => Promise.resolve(2),
    () => Promise.resolve(3),
  ],
  {
    canceller: { cancelled: false }, 
    // set to true later
    progress: (subResult, step, total) => 
      { 
        console.log(subResult) 
        console.log(`${((step+1) / total)}%`)
      },
    skipIfError: true
  }
)     
// return [1,2,3] in the subsequent promise

Start promise with a function, which Promise.resolve() does not support.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunction | function | an async function which will be called and pass the result in promise |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result of the resolved promise |

${\color{gray}Example}$

Promise.then(3)          // return 3 in a promise
Promise.then(() => 3)    // return 3 in a promise
Promise.then(async () => Promise.resolve(3))    // return 3 in a promise

Call the async function with time out limit.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function | an async function or promise which will be called and pass the result in promise | | millisecond | number (Optional; default = 1000) | the time limit for the time out. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result of the resolved promise |

${\color{gray}Example}$

Promise.timeOut(asyncFunction, 300)          
Promise.timeOut(promise, 300)          
// return a promise within 300 ms, otherwise reject with time out error

Starts a promise with an asynchronous function that use a callback.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | wrappedAsyncFunctionWithCallback | function | an asynchronous function that will be called, returning a result in callback. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result returned from callback |

${\color{gray}Example}$

Promise.wrap(asyncFunction)      
// for asyncFunction accepting the callback as 1st parameter   

Promise.wrap(cb => asyncFunction(1, 2, cb))          
// for other asyncFunction accepting the callback as the rest parameter

Promise.prototype

Creates a Promise that is resolved with an array, an object or a Map of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

$${\color{gray}Parameters}$$

| Param | Type | Desc| | - | - | - | | values | Promise[] | an array of provided promise for resolving. |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any[] | a new promise for resolved results. |

$${\color{gray}Example}$$

Promise.resolve()
  .all(
    [
      Promise.resolve(1),
      Promise.resolve(2),
      Promise.resolve(3)
    ]
  ) 
// return [1,2,3] in the subsequent promise

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | values | object | an object of provided promise for resolving. |

${\color{gray}Return}$

| Type | Desc| | - | - | | object | a new promise for resolved results. |

${\color{gray}Example}$

Promise.resolve()
  .all(
    {
      someNumber: Promise.resolve(1),
      someString: Promise.resolve('test'),
      someBoolean: Promise.resolve(true)
    }
  )     
// return the resolved object in the subsequent promise

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | values | Map | a Map of provided promise for resolving. |

${\color{gray}Return}$

| Type | Desc| | - | - | | Map | a new promise for resolved results. |

${\color{gray}Example}$

Promise.resolve()
  .all(
    new Map(
      Object.entries({
        someNumber: Promise.resolve(1),
        someString: Promise.resolve('test'),
        someBoolean: Promise.resolve(true)
      })
    )
  )     
// return the resolved object in the subsequent promise

Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.

$${\color{gray}Parameters}$$

| Param | Type | Desc| | - | - | - | | values | Promise[] | an array of provided promise for resolving. |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any[] | a new promise for resolved results. |

$${\color{gray}Example}$$

Promise.resolve()
  .allSettled(
    [
      Promise.resolve(1),
      Promise.reject(2),
    ]
  ) 
// return [{status: 'fulfilled', value: 1},{status: 'rejected', value: 2}] in the subsequent promise

Start promise after delaying.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | millisecond | number | a time for the delay. |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any | A value which pass through within a promise. |

${\color{gray}Example}$

Promise.resolve('a')
  .delay(300)  
  .then(doSomething)  
  // return 'a' in a promise after delay 300 ms

Start promise after delaying.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | logger | function (Optional; default = console.log) | a logging tool | | ...args | any[] (Optional) | the rest of arguments |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any | A value which pass through within a promise. |

${\color{gray}Example}$

Promise.resolve('a')
  .log()  
  .then(doSomething)  
  // return 'a' in a promise after delay 300 ms

Promise.resolve('a')
  .log(console.debug, 'My value is:')  
  .then(doSomething)  
  // return 'a' in a promise after delay 300 ms

Creates a Promise that is resolved sequentially with a result when all of the provided Promises resolve, or rejected when any Promise is rejected.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function[] | an array of async functions. | | options | object (Optional) | - | | options.canceller | object | set canceller.cancelled = true stopping the sequence | | options.progress | (subResult, step, total) => any | to show the progress and the sub result | | options.initValue | any | the initial value which pass to the first async function |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result of last resolved promise |

${\color{gray}Example}$

Promise.resolve()
  .reduce(
    [
      plus(5),
      minus(2),
    ],
    {
      canceller: { cancelled: false }, 
      // set to true later
      progress: (subResult, step, total) => 
        { 
          console.log(subResult) 
          console.log(`${((step+1) / total)}%`)
        },
      initValue: 1
    }
  )     
// return 4 in the subsequent promise

Reject with error in the promise chain.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | reason | any | the reason of the error |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | never | the error which throw in the promise |

${\color{gray}Example}$

Promise.resolve()
  .reject('a')  
  .catch(error => console.error(error))

Resolve the value in the promise chain.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | value | any | the value which would be like to pass through |

$${\color{gray}Return}$$

| Type | Desc| | - | - | | any | the value which pass through within a promise|

${\color{gray}Example}$

Promise.resolve()
  .resolve('a')  
  .then(doSomething)      
// return 'a' in the subsequent promise

Starts a promise with an asynchronous function that has retry tolerance.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunction | function | an asynchronous function or promise that holds the result. | | count | number (Optional; default = 3) | a positive integer between 0 and 30 indicating the number of retries. | | delay | number (Optional; default = 100) | the time in milliseconds to wait between retries. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | The result within a promise after retries. |

${\color{gray}Example}$

Promise.resolve().retry(asyncFunction); 
Promise.resolve().retry(promise); 
Promise.resolve().retry(asyncFunction, 5, 1000); 
Promise.resolve().retry(promise, 5, 1000); 

Creates a Promise that is resolved sequentially with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function[] | an array of async functions. | | options | object (Optional) | - | | options.canceller | object | set canceller.cancelled = true stopping the sequence | | options.progress | (subResult, step, total) => any | to show the progress and the sub result | | options.skipIfError | boolean | - |

${\color{gray}Return}$

| Type | Desc| | - | - | | any[] | the result of resolved promise in an array |

${\color{gray}Example}$

Promise.resolve().sequence(
  [
    () => Promise.resolve(1),
    () => Promise.resolve(2),
    () => Promise.resolve(3),
  ],
  {
    canceller: { cancelled: false }, 
    // set to true later
    progress: (subResult, step, total) => 
      { 
        console.log(subResult) 
        console.log(`${((step+1) / total)}%`)
      },
    skipIfError: true
  }
)     
// return [1,2,3] in the subsequent promise

Call the async function with time out limit.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | asyncFunctions | function | an async function or promise which will be called and pass the result in promise | | millisecond | number (Optional; default = 1000) | the time limit for the time out. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result of the resolved promise |

${\color{gray}Example}$

Promise.resolve().timeOut(asyncFunction, 300)          
Promise.resolve().timeOut(promise, 300)          
// return a promise within 300 ms, otherwise reject with time out error

Starts a promise with an asynchronous function that use a callback.

${\color{gray}Parameters}$

| Param | Type | Desc| | - | - | - | | wrappedAsyncFunctionWithCallback | function | an asynchronous function that will be called, returning a result in callback. |

${\color{gray}Return}$

| Type | Desc| | - | - | | any | the result returned from callback |

${\color{gray}Example}$

Promise.resolve()
  .wrap(asyncFunction)      
// for asyncFunction accepting the callback as 1st parameter   

Promise.resolve()
  .wrap(cb => asyncFunction(1, 2, cb))          
// for other asyncFunction accepting the callback as the rest parameter

Advanced Usage

Clean Import - (Non prototype pollution)

// For non-pollution
import { promiseWrap, delay, ... } from "es-promise-ext/clean"

promiseWrap(callback => someCallbackFunction(1, callback))
  .then(delay(500))
  .then(value => {
    // do something
  });

Specifc Function - (To avoid collision with other libraries)

import "es-promise-ext/prototype/delay"
import "es-promise-ext/wrap"

Promise.wrap(callback => someCallbackFunction(1, callback))
  .delay(500)
  .then(value => {
    // do something
  });

Test

npm run test

License

• MIT License