bach

What is bach?

The bach npm package is a tool for composing asynchronous functions in series or parallel. It is particularly useful for orchestrating tasks that need to be executed in a specific order or concurrently, often seen in build processes or complex workflows.

What are bach's main functionalities?

Series Execution

Executes tasks one after another. Each task will start only after the previous one has completed.

const { series } = require('bach');

function task1(cb) { console.log('Task 1'); cb(); }
function task2(cb) { console.log('Task 2'); cb(); }

const tasks = series(task1, task2);
tasks(function(err) { console.log('Done executing tasks in series.'); });

Parallel Execution

Executes tasks simultaneously. All tasks will start at the same time and run concurrently.

const { parallel } = require('bach');

function task1(cb) { console.log('Task 1'); cb(); }
function task2(cb) { console.log('Task 2'); cb(); }

const tasks = parallel(task1, task2);
tasks(function(err) { console.log('Done executing tasks in parallel.'); });

Settled Parallel Execution

Executes tasks in parallel and collects their results. Even if one task fails, the others will continue to execute.

const { parallel } = require('bach');

function task1(cb) { console.log('Task 1'); cb(null, 'result1'); }
function task2(cb) { console.log('Task 2'); cb(null, 'result2'); }

const tasks = parallel(task1, task2);
tasks(function(err, results) { console.log('Results:', results); });

Other packages similar to bach

async

The 'async' package provides a powerful collection of functions for working with asynchronous JavaScript. It offers more utilities than bach, such as map, filter, and reduce for collections, control flow functions, and utilities for working with functions. It is more feature-rich and can be considered heavier than bach.

run-parallel

The 'run-parallel' package is a simple module that runs an array of functions in parallel, but without any of the additional control flow features or utilities that 'async' provides. It is more focused and lightweight, similar to bach's parallel execution feature.

run-series

The 'run-series' package is similar to 'run-parallel' but for running tasks in series instead of parallel. It is a minimalistic tool that does one thing well, akin to bach's series execution feature.

README

bach

Compose your async functions with elegance.

Usage

With bach, it is very easy to compose async functions to run in series or parallel.

var bach = require('bach');

function fn1(cb) {
  cb(null, 1);
}

function fn2(cb) {
  cb(null, 2);
}

function fn3(cb) {
  cb(null, 3);
}

var seriesFn = bach.series(fn1, fn2, fn3);
// fn1, fn2, and fn3 will be run in series
seriesFn(function(err, res) {
  if (err) { // in this example, err is undefined
    // handle error
  }
  // handle results
  // in this example, res is [1, 2, 3]
});

var parallelFn = bach.parallel(fn1, fn2, fn3);
// fn1, fn2, and fn3 will be run in parallel
parallelFn(function(err, res) {
  if (err) { // in this example, err is undefined
    // handle error
  }
  // handle results
  // in this example, res is [1, 2, 3]
});

Since the composer functions return a function, you can combine them.

var combinedFn = bach.series(fn1, bach.parallel(fn2, fn3));
// fn1 will be executed before fn2 and fn3 are run in parallel
combinedFn(function(err, res) {
  if (err) { // in this example, err is undefined
    // handle error
  }
  // handle results
  // in this example, res is [1, [2, 3]]
});

Functions are called with async-done, so you can return a stream, promise, observable or child process. See async-done completion and error resolution for more detail.

// streams
var fs = require('fs');

function streamFn1() {
  return fs.createReadStream('./example')
    .pipe(fs.createWriteStream('./example'));
}

function streamFn2() {
  return fs.createReadStream('./example')
    .pipe(fs.createWriteStream('./example'));
}

var parallelStreams = bach.parallel(streamFn1, streamFn2);
parallelStreams(function(err) {
  if (err) { // in this example, err is undefined
    // handle error
  }
  // all streams have emitted an 'end' or 'close' event
});

// promises
var when = require('when');

function promiseFn1() {
  return when.resolve(1);
}

function promiseFn2() {
  return when.resolve(2);
}

var parallelPromises = bach.parallel(promiseFn1, promiseFn2);
parallelPromises(function(err, res) {
  if (err) { // in this example, err is undefined
    // handle error
  }
  // handle results
  // in this example, res is [1, 2]
});

All errors are caught in a domain and passed to the final callback as the first argument.

function success(cb) {
  setTimeout(function() {
    cb(null, 1);
  }, 500);
}

function error() {
  throw new Error('Thrown Error');
}

var errorThrownFn = bach.parallel(error, success);
errorThrownFn(function(err, res) {
  if (err) {
    // handle error
    // in this example, err is an error caught by the domain
  }
  // handle results
  // in this example, res is [undefined]
});

When an error happens in a parallel composition, the callback will be called as soon as the error happens. If you want to continue on error and wait until all functions have finished before calling the callback, use settleSeries or settleParallel.

function success(cb) {
  setTimeout(function() {
    cb(null, 1);
  }, 500);
}

function error(cb) {
  cb(new Error('Async Error'));
}

var parallelSettlingFn = bach.settleParallel(success, error);
parallelSettlingFn(function(err, res) {
  // all functions have finished executing
  if (err) {
    // handle error
    // in this example, err is an error passed to the callback
  }
  // handle results
  // in this example, res is [1]
});

API

series(fns..., [extensions])

Takes a variable amount of functions (fns) to be called in series when the returned function is called. Optionally, takes an extensions object as the last argument.

Returns an invoker(cb) function to be called to start the serial execution. The invoker function takes a callback (cb) with the function(error, results) signature.

If all functions complete successfully, the callback function will be called with all results as the second argument.

If an error occurs, execution will stop and the error will be passed to the callback function as the first parameter. The error parameter will always be a single error.

parallel(fns..., [extensions])

Takes a variable amount of functions (fns) to be called in parallel when the returned function is called. Optionally, takes an extensions object as the last argument.

Returns an invoker(cb) function to be called to start the parallel execution. The invoker function takes a callback (cb) with the function(error, results) signature.

If all functions complete successfully, the callback function will be called with all results as the second argument.

If an error occurs, the callback function will be called with the error as the first parameter. Any async functions that have not completed, will still complete, but their results will not be available. The error parameter will always be a single error.

settleSeries(fns..., [extensions])

Takes a variable amount of functions (fns) to be called in series when the returned function is called. Optionally, takes an extensions object as the last argument.

Returns an invoker(cb) function to be called to start the serial execution. The invoker function takes a callback (cb) with the function(error, results) signature.

All functions will always be called and the callback will receive all settled errors and results. If any errors occur, the error parameter will be an array of errors.

settleParallel(fns..., [extensions])

Takes a variable amount of functions (fns) to be called in parallel when the returned function is called. Optionally, takes an extensions object as the last argument.

Returns an invoker(cb) function to be called to start the parallel execution. The invoker function takes a callback (cb) with the function(error, results) signature.

All functions will always be called and the callback will receive all settled errors and results. If any errors occur, the error parameter will be an array of errors.

extensions

The extensions object is used for specifying functions that give insight into the lifecycle of each function call. The possible extension points are create, before, after and error. If an extension point is not specified, it defaults to a no-op function.

extensions.create(fn, index)

Called at the very beginning of each function call with the function (fn) being executed and the index from the array/arguments. If create returns a value (storage), it is passed to the before, after and error extension points.

If a value is not returned, an empty object is used as storage for each other extension point.

This is useful for tracking information across an iteration.

extensions.before(storage)

Called immediately before each function call with the storage value returned from the create extension point.

extensions.after(result, storage)

Called immediately after each function call with the result of the function and the storage value returned from the create extension point.

extensions.error(error, storage)

Called immediately after a failed function call with the error of the function and the storage value returned from the create extension point.

License

MIT

Changelog

2.0.0 (2022-08-25)

⚠ BREAKING CHANGES

• Rework extension helper to get options
• change flatten to Array.prototype.slice.apply
• Normalize repository, dropping node <10.13 support (#34)

Features

• Reflect concurrency option in documentation (2c47259)
• Remove ES5 utility dependencies (1c631cb)
• Remove node assert usage (a1ba61d)

Miscellaneous Chores

• change flatten to Array.prototype.slice.apply (1c631cb)
• Normalize repository, dropping node <10.13 support (#34) (1c631cb)
• Rework extension helper to get options (89857b6)