@ssense/promise-pool

@ssense/promise-pool

Promise Pool

class Pool

The idea behind a promise pool is that you want to handle a large volume of promises but you do not want to use Promise.all because it is an all or nothing approach. The promise pool allows you to execute a large number of promises concurrently and if any promise is to fail it will continue the execution of the promises uninterupted.
Also you can specify the number of promises that should be run in parallel to prevent overwhelming the function that is servicing your asynchronous requests. (see examples here)

Methods

Method	Returns	Description
constructor(generator: PromiseGenerator, max: number)	PromisePool	Creates a new instance of PromisePool
onResolved(callback: (data: any, index: number) => void)	PromisePool	Adds a callback called every time a promise in the pool is resolved
onRejected(callback: (err: Error, index: number) => void)	PromisePool	Adds a callback called every time a promise in the pool is rejected
run()	Promise<PromisePoolStats>	Starts the pool of promises, returning statistics about execution when finished

Details

constructor(generator: PromiseGenerator, max: number)

Creates a new instance of PromisePool

Parameters

Name	Type	Required	Description
generator	PromiseGenerator	Yes	Function that should return a promise on each call, or null if all promises are executed
max	number	Yes	Maximum number of parallel promises to run

onResolved(callback: (data: any, index: number) => void)

Adds a callback called every time a promise in the pool is resolved

Parameters

Name	Type	Required	Description
callback	Function	Yes	Function called every time a promise in the pool is resolved, receiving in parameter the promise return value, as well as the promise index in the pool

Return value

Type	Description
PromisePool	The current PromisePool instance

onRejected(callback: (err: Error, index: number) => void)

Adds a callback called every time a promise in the pool is rejected

Parameters

Name	Type	Required	Description
callback	Function	Yes	Function called every time a promise in the pool is rejected, receiving in parameter the error, as well as the promise index in the pool

Return value

Type	Description
PromisePool	The current PromisePool instance

run()

Starts the pool of promises, returning statistics about execution when finished

Return value

Type	Description
Promise<PromisePoolStats>	Statistics about current pool execution

PromisePoolStats properties

Name	Type	Required	Description
resolved	number	Yes	Number of resolved promises after current pool run
rejected	number	Yes	Number of rejected promises after current pool run
duration	number	Yes	Current pool run duration in milliseconds

Examples

import { Pool } from '@ssense/promise-pool';

// Create sample PromiseGenerator, throwing an error one time out of two
let i = 0;
const generator = (): any => {
    i += 1;
    if (i > 10) {
        // Return null after 10 runs, which will stop the promise pool
        return null;
    }

    return new Promise<number>((resolve, reject) => {
        const current = i;
        setTimeout(() => {
            return current % 2 === 0 ? resolve(current) : reject(new Error(current.toString()));
        }, 2);
    });
};

// Create a new promise pool, calling the above generator, and running 2 promises in parallel max
const pool = new Pool(generator, 2);

// Start the pool and wait for it to finish
const result = await pool.run();

// "result" contains the pool statistics with the current structure:
// {
//   resolved: 5,
//   rejected: 5,
//   duration: <total execution time in milliseconds>
// }