README.md

Functions chaining library

A callThru() function chains several passes. Each pass is a function to call. Each pass produces arguments for the next function call.

Normally, the value returned from function call is passed as a single argument to the next one:

import { callThru } from '@proc7ts/call-thru';

callThru(
  (a, b) => a + b,
  sum => `The sum is ${sum}`,
)(2, 9); // The sum is 11

Additionally, a pass may return a NextCall instance that is responsible for calling the next pass.

There are several NextCall implementations available. For example, a nextArgs() one can be used to pass multiple arguments to the next function:

import { callThru, nextArgs } from '@proc7ts/call-thru';

callThru(
  (a, b) => nextArgs(b, a),
  (b, a) => [b, a],
)('foo', 'bar'); // ['bar', 'foo']

A NextCall instance is a no-arg function returning itself. Thus it can be chained as a pass:

import { callThru, nextArgs } from '@proc7ts/call-thru';

callThru(nextArgs('foo', 'bar'), (a, b) => [a, b])(); // ['foo', 'bar']

nextArgs()

Constructs arguments for the next function call.

import { callThru, nextArgs } from '@proc7ts/call-thru';

callThru(
  () => nextArgs('foo', 'bar'),
  (a, b) => [a, b],
)(); // ['foo', 'bar']

passAsync()

Constructs asynchronous call chain pass.

import { callThru, passAsync } from '@proc7ts/call-thru';

callThru(passAsync(), () => {
  throw Error('Failed');
})().catch(e => console.log(e));

nextEach()

Creates an next call that invokes subsequent passes for each item in the given iterable.

import { callThru, nextEach } from '@proc7ts/call-thru';

for (const n of callThru(
  (...args) => nextEach(args),
  n => n * n,
)(1, 2, 3)) {
  console.log(n); // 1, 4, 9
}

This can be combined with e.g. passIf():

import { callThru, nextEach, passIf } from '@proc7ts/call-thru';

for (const n of callThru(
  (...args) => nextEach(args),
  passIf((n: number) => n > 1),
  n => n * n,
)(1, 2, 3)) {
  console.log(n); // 4, 9
}

passFlat()

Constructs flattening call chain pass.

The next pass is expected to return an iterable of iterables. This pass then converts it to plain iterable.

import { callThru, nextEach, passFlat } from '@proc7ts/call-thru';

for (const n of callThru(
  passFlat(),
  (...args) => nextEach(args),
  n => Array<string>(n).fill(`${n}`),
)(1, 2)) {
  console.log(n); // '1', '2', '2'
}

nextFlatEach()

Creates a next call that invokes subsequent passes for each item in the given iterable and flattens the result.

The next pass is expected to return an iterable for each of the items.

This is an equivalent of passFlat() followed by a pass returning nextEach().

import { callThru, nextFlatEach } from '@proc7ts/call-thru';

for (const n of callThru(
  (...args) => nextFlatEach(args),
  n => Array<string>(n).fill(`${n}`),
)(1, 2)) {
  console.log(n); // '1', '2', '2'
}

passIf()

Constructs conditional call chain pass.

If the given test function fails the rest of the passes in chain would be skipped and the final call chain outcome will be undefined. Otherwise the next pass in chain will be called with the same arguments.

import { callThru, passIf } from '@proc7ts/call-thru';

const confirmGreater = callThru(
  passIf((a: number, b: number) => a > b),
  () => 'greater',
);

confirmGreater(2, 1); // 'greater'
confirmGreater(1, 2); // undefined

nextReturn()

Constructs a next call that skips the rest of the chain and returns the given value.

import { callThru, nextReturn } from '@proc7ts/call-thru';

const confirmGreater = callThru((a, b) => (a > b ? 'greater' : nextReturn(false)));

confirmGreater(2, 1); // 'greater'
confirmGreater(1, 2); // false

nextSkip()

Constructs a next call that skips the rest of the chain.

This has the same effect as nextReturn(undefined).

import { callThru, nextSkip } from '@proc7ts/call-thru';

const confirmGreater = callThru((a, b) => (a > b ? 'greater' : nextSkip()));

confirmGreater(2, 1); // 'greater'
confirmGreater(1, 2); // undefined