func-generators

Functional transformations and helpers for JavaScript generator functions

This library provides a handful of functions for creating and transforming generator functions.

The subtle difference between operating on generator functions as opposed to operating on iterable objects is that operating on an iterable object is not a pure operation ― certain iterable values can only be iterated once. By contrast, transforming generator functions can be a pure operation with no side effects.

For example:

var gen = genTimes(10);           // create a generator that prduces the numbers 0 - 9

var gOdds = genFilter(x => x % 2 === 1, gen);  // create a generator that produces odds from 1 - 9
var gEvens = genFilter(x => x % 2 === 0, gen); // create a generator that produces evens from 0 - 8

var odds = Array.from(gOdds());   // [1, 3, 5, 7, 9];
var evens = Array.from(gEvens()); // [0, 2, 4, 6, 8];

As we can see here, we are able to apply multiple transformations to the same generator function without affecting any of the others.

Several of the functions in this library are curried and are indicated as Curried when this is the case.

As such, they should work nicely with Ramda's compose() or any similar compose() operation:

const firstMultipleOfTen = compose(
    genHead,
    genFilter(x => x % 10 === 0)
);

firstMultipleOfTen(genInfinite(35));    // 40

API Reference

Generator transformations

genMap(f, gen)

Curried

(a -> b) -> Generator a -> Generator b

Returns a new generator with the values of gen transformed via f

Example:

genMap(x => x * x, genInfinite()); // generator for 0, 1, 4, 9, 16, ...

genFilter(pred, gen)

Curried

(a -> Boolean) -> Generator a -> Generator a

Returns a new generator with only the values in gen that produce a true value when pred is applied to them.

Example:

genFilter(x => x % 3 === 0, genInfinite()); // generator for 0, 3, 6, 9, 12, ...

genZip(gen1, gen2)

Curried

Generator a -> Generator b -> Generator [a, b]

Returns a new generator of length-2 arrays containing the sequential values of gen1 and gen2

The length of the resulting generator will be the shorter of the lengths of gen1 and gen2.

Example:

genZip(genInfinite(), genInfinite(1));   // generator for [0, 1], [1, 2], [2, 3], ...

genTake(count, gen)

Curried

Number -> Generator a -> Generator a

Returns a new generator which produces the first count values produced by gen, or all of the values produced by gen, whichever is fewer.

Example:

genTake(3, genInfinite());   // generator for 0, 1, 2

genDrop(count, gen)

Curried

Number -> Generator a -> Generator a

Returns a new generator which produces the same values as gen, but without the first count values. If count is greater than the number of values produced by gen, the resulting generator will produce no values.

Example:

genDrop(4, genInfinite());   // generator for 4, 5, 6, 7, 8, ...

Generator convergence

genHead(gen)

Generator a -> a

Executes gen and returns the first value that it produces.

Returns undefined if gen does not produce any values.

Example:

genHead(genInfinite(7));    // 7

genLast(gen)

Generator a -> a

Executes gen and returns the last value that it produces.

Returns undefined if gen does not produce any values.

Caution: Will block until gen finishes producing values and will block indefinitely if gen does not terminate.

Example:

genLast(genTimes(6));    // 5

genLength(gen)

Generator a -> Number

Executes gen and returns the total number of values that it produces.

Caution: Will block until gen finishes producing values and will block indefinitely if gen does not terminate.

Example:

genLength(genTimes(6));    // 6

genToArray(gen)

Generator a -> [a]

Executes gen and returns an array of all values that it generates.

Caution: Will block until gen finishes producing values and will block indefinitely if gen does not terminate.

Example:

genToArray(genTimes(6));    // [0, 1, 2, 3, 4, 5]

Generator creation

genInfinite(start = 0, step = 1)

(Number?, Number?) -> Generator Number

Creates a generator which produces numbers indefinitely starting at start in increments of step.

Example:

genInfinite(5, 2);    // generator for 5, 7, 9, 11, 13, ...

genTimes(count, start = 0, step = 1)

(Number, Number?, Number?) -> Generator Number

Creates a generator which produces count numbers starting from start in increments of step.

Example:

genTimes(6, 10, 5);   // generator for 10, 15, 20, 25, 30, 35

genFrom(iterable)

Iter a -> Generator a

Creates a generator which produces the values produced by iterable.

Note: If iterator has side-effects or is impure (e.g. it can only be iterated once, etc.), then any generator returned from this function will ultimately have similar side-effects.

Example:

genFrom([1, 3, 4, 6]);   // generator for 1, 3, 4, 6

genTransform(update, start)

Curried

(a -> a) -> a -> Generator a

Creates a generator which produces the results of repeatedly applying update to successive values starting from start.

By default, the created generator will produce an infinite series of values, but it is possible to terminate the series by returning genStop from update.

Example:

genTransform(x => x + 'a', '');   // generator for '', 'a', 'aa', 'aaa', ...

genTransform(x => x > 128 ? genStop : x * 2, 1);  // generator for 1, 2, 4, 8, 16, 32, 64, 128