@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>
// }