Generator Utilities

A utility library for generating and processing sequences based on ES6 generators.

Usage

Install the package in your project

npm install --save generator-utilities

Use require or import to use the generator functions you need.

import { iterate, range } from "generator-utilities";

Or

const { iterate, range } = require("generator-utilities");

Alternatively, if you use the default import, you can take advantage of the chainable iterator functionality.

import { default as chain } from "generator-utilities";

Or

const chain = require("generator-utilities").default;

See below for explaination of how chaining works.

Purpose

This contains many generator functions for a range of utilities that are primarily divided into two categories: sequence generators and chainable generators. The sequence generators will take their input, if any, and use it to produce a sequence of values. The chainable generators take as input an iterable object and other parameters and yield (possibly modified) values until either some condition has been met, or the source iterator stops yielding values.

For example, the range generator yields a sequence of values between a start and end value.

for (value of range(-10, 11)) {
    console.log(value);
}

This will log the integers from -10 up to but not including 11. i.e. -10, -9, -8, ..., 8, 9, 10.

The take generator is a chainable generator that takes as input an iterable object, such as another generator or an Array, and yields the specified number of values. The counter sequence generator in this example will yield an infinite series of values from 0.

[...take(counter(), 10)]; // --> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

The reason these are called chainable generators is because they can be used together via the chain export.

let it = chain.range(1, 10).map(n => n**2);
[...it]; // --> [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

The chain export provides access to all sequence and chainable generators, and automatically exposes all chainable generators on each iterator returned in the chain.

Base Iterators

The base iterators simply yield values from a given source object without modifying them in any way.

Generator	Purpose
iterate	Yeilds all values from the given object. Works with iterators, Arrays or Array-like objects.
reverse	Yields values in reverse from the given object. Works with Arrays or Array-like objects.
safeIterate	Like iterate, but wraps a given iterator in a way that prevents a call to return() from being propagated to the wrapped iterator.

Illustrating how safeIterate works

e.g. Withinout safeIterate:

let a = counter();
for (let value of a) {
    if (value > 10) break;
}
a.next(); // --> { done: true }

With safeIterate:

let b = counter();
for (let value of safeIterate(b)) {
    if (value >= 10) break;
}
b.next(); // --> { value: 11, done: false }

Note: Take care with safeIterate. Use it only where you are sure that you don't want a call to return() to be propagated to the wrapped iterator, which ordinarily allows for cleanup procedures to occur when you are finished with it, such as closing open files.

Sequence Generators

Generator	Purpose
combination	Given a finite sequence of values, yields arrays with unique combinations of the specified size.
counter	Yields values starting from the given start value, or 0, incrementing by the specified step.
random	Yields random integers or floating point numbers, optionally in a given range.
range	Yields values from start up to but not including end, optionally incrementing by the specified step.
repeat	Given a generator function or iterable object, yields all values from it and then repeats.
permute	Given an Array or Array-like or finitely iterable object, yields arrays with unique permutations of all items.
permutation	Given an Array or Array-like or finitely iterable object, yields arrays of the specified size, k, with unique permutations of k items.
series	Given an initial set of n values and a function, yields values in a series that can be calculated from the n previous values. (see fibonacci series).
shuffle	Given an array, yields each value in a random order.
symbols	Yields unique Symbol values.
thueMorse	Yields binary values in the Thue-Morse sequence.
collatz	Given an initial starting value, yields all values in the Collatz sequence until it reaches 1.
fibonacci	Generates values in the fibonacci sequence, not exceeding the MAX_SAFE_INTEGER.
fizzBuzz	Starting from 1, yields values in the FizzBuzz sequence.

Chainable Generators

Generator	Purpose
chunk	Yields arrays with n values from the given iterator.
compact	Removes falsey (false, 0, NaN, "", null, undefined) values and yeilds all other values from the given iterator.
concat	Yields all values from all given iterators in order
dedupe	Removes duplicate values that equal the previously yielded value
difference	Yield values that are not included in a given reference array
differenceBy	Like difference, but maps each value in the given reference array before comparing with values from the generator.
differenceWith	Yields values that are not included in the given reference array, compared using the given comparison function.
drop	Ignore n values from the given iterator and yield all subsequent values.
dropUntil	Ignore values from the given iterator until a specified condition function returns true, and yield all subsequent values.
dropWhile	Ignore values from the given iterator while a given condition function returns true
everyNth	Yield every nth value from the given iteratable.
filter	Yield values from the given iterable that pass a given condition.
flatten	Recursively iterate and yield values from nested iterables, up to a specified depth.
forEach	Invoke a callback for each value prior to yielding the original value.
fuzz	Yield values from the given iterator that have been mapped according to the rules of FizzBuzz.
interlace	Alternately yield values from each of the given iterators.
link	Link a custom generator function into a chainable sequence. The custom generator function must accept an iterable as its first parameter.
map	Invokes a callback with each value from the given iteratable and yields the results.
modulo	Yields the value (mod n) from the given iterable using Euclidian division. The result is always positive.
pluck	Yield values of the specified property from objects yielded by the given iteratable.
take	Yield n values from the given iterable.
takeUntil	Yield values from the given iterable until a given condition returns true.
takeWhile	Yield values from the given iterable while a given condition returns true.
unzip	Yields arrays ungrouped values from a finite set of groups.
zip	Groups values from multiple iterables.