lupomontero / porch

Promise Orchestrator: Easily process promise batches both sequentially and concurrently, controlling concurrency and throttling.

Porch

Process promise-based tasks in series and parallel, controlling concurrency and throttling.

Installation

npm install porch

Usage / API

Promise porch(tasks, concurrency, interval, failFast)

Arguments

• tasks (Array): An array of tasks, where each task is a function that expects no arguments and will return a Promise.
• concurrency (Number): Default: 1. Maximum number of tasks to run concurrently (in parallel).
• interval (Number): Default: 0. Interval between each batch of concurrent tasks.
• failFast (Boolean): Default: true. Whether to bail out when one of the promises fails. If set to false errors will be included in the results passed to then() instead of being passed independently via the catch() method.

Return value

A Promise that will resolve to an array with the results for each task. Results will be in the same order as in the input tasks array.

Examples

Series

Process each task after the other, sequentially. Each task will wait for the previous one to complete. Concurrency set to 1 (one task at a time).

import porch from 'porch';

const tasks = users.map(user => () => auth.deleteUser(user.localId);

porch(tasks)
  .then(console.log)
  .catch(console.error);

Batches

Process tasks in batches based on a given concurrency. In this example tasks will be processed in batches of 5 tasks each. Each batch waits for the previous one to complete and then performs its tasks in parallel.

porch(tasks, 5)
  .then(console.log)
  .catch(console.error);

Throttled

Same as example above but adding a 1000ms delay between batches.

porch(tasks, 5, 1000)
  .then(console.log)
  .catch(console.error);

failFast=false (don't bail out on errors)

Same as above, but in this case if a promise fails, processing will continue instead of stopping the whole thing. When failFast is set to false, errors will appear as the value/result for the relevant element in the results array (failed tasks/promises won't end up in the catch() method).

porch(tasks, 5, 1000, false)
  .then(console.log)

stream.Readable createStream(tasks, concurrency, interval, failFast)

Arguments

Same as porch().

Return value

A readable stream (stream.Readable) instead of a Promise. Each result will be emitted as a data event and the stream will operate in objectMode.

Examples

Handling each event independently... (old school)

import { createStrean } from 'porch';

createStream(tasks, 5, 1000, false)
  .on('error', err => console.error('error', err))
  .on('data', data => console.log('data', data))
  .on('end', _ => console.log('ended!'));

Piping to a writable stream

// This example assumes that tasks will resolve to string values so that the
// resulting stream can be directly piped to stdout.
createStream(tasks, 5, 1000, false).pipe(process.stdout);