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