Turns an iterable object, iterator object or a generator function into an iterator that is also iterable and adds methods to easily operate on the values. These methods can be chained until a consumer is called.

• TypeError: Throws when the input cannot be converted to an iterator.

Takes two or more iterables and creates an iterator over their values in sequence. It will first iterate over the values from the first iterable, then the second and so on.

const a1 = [1, 2];
const a2 = [3, 4];

const iter = chain(a1, a2);

iter.next(); // { value: 1, done: false };
iter.next(); // { value: 2, done: false };
iter.next(); // { value: 3, done: false };
iter.next(); // { value: 4, done: false };
iter.next(); // { value: undefined, done: true };

Repeats an iterable indefinitely. When the iterable is done, it will start again from the beginning.

const a = [1, 2];

const iter = cycle(a);

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 1, done: false }
// etc.

Creates an iterator which gives the current index as well as the value. The index starts at 0.

const a = ['a', 'b', 'c'];

const iter = enumerate(a);

iter.next(); // { value: [0, 'a'], done: false }
iter.next(); // { value: [1, 'b'], done: false }
iter.next(); // { value: [2, 'c'], done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which yields only the values that satisfy the predicate.

const a = [1, 2, 3, 4, 5, 6];
const isEven = x => x % 2 === 0;

const iter = filter(a, isEven);

iter.next(); // { value: 2, done: false }
iter.next(); // { value: 4, done: false }
iter.next(); // { value: 6, done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator that both filters and maps. When the mapped value is null or undefined, it is skipped, otherwise it will be yielded.

const a = [1, 2, 3, 4, 5, 6];
const squareOdd = x => {
  if (x % 2 === 0) {
    return null;
  }
  return x * x;
};

const iter = filterMap(a, squareOdd);

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 9, done: false }
iter.next(); // { value: 25, done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which works like map, but flattens nested structures. The map function has to return an iterable instead of just a value. Consequently all values of the returned iterables are yielded.

function* valNtimes(val, n) {
  for (let i = 0; i < n; i++) {
    yield val;
  }
}
const a = [1, 2, 3];

const iter = flatMap(a, x => valNtimes(x, x));

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 3, done: false }
iter.next(); // { value: 3, done: false }
iter.next(); // { value: 3, done: false }
iter.next(); // { value: undefined, done: true }

const strings = ['abc', 'xyz'];

// Strings are also iterable and therefore valid return values
const iter = flatMap(strings, s => s);

iter.next(); // { value: 'a', done: false }
iter.next(); // { value: 'b', done: false }
iter.next(); // { value: 'c', done: false }
iter.next(); // { value: 'x', done: false }
iter.next(); // { value: 'y', done: false }
iter.next(); // { value: 'z', done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which ends after the first null or undefined value is encountered. An iterator could potentially yield null or undefined before being done and continue yielding more values afterwards.

// Yields even numbers or null
function* alternate() {
 let i = 0;
 while (true) {
   if (i % 2 === 0) {
     yield i;
   } else {
     yield null;
   }
   i += 1;
 }
}

const iter = alternate();

iter.next(); // { value: 0, done: false }
iter.next(); // { value: null, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: null, done: false }
// Would continue indefinitely

const fused = fuse(iter);

fused.next(); // { value: 4, done: false }
// Stops after it encounters null or undefined
fused.next(); // { value: undefined, done: true }

// This also ends the original iterator
iter.next(); // { value: undefined, done: true }

Creates an iterator which calls the given function with each value before passing the value on. When chaining a lot of iterables it might be useful to check out what's happening with the values. This is intended for debugging purposes.

const a = [1, 2, 4, 3];

const sum1 = iter(a)
  .filter(x => x % 2 === 0)
  .fold(0, (sum, i) => sum + i);

// Could be helpful to see what values make it through the chain
// Just add inspect() between the steps
const sum2 = iter(a)
  .inspect(x => console.log(`about to filter: ${x}`))
  .filter(x => x % 2 === 0)
  .inspect(x => console.log(`made it through filter: ${x}`))
  .fold(0, (sum, i) => sum + i);

about to filter: 1
about to filter: 2
made it through filter: 2
about to filter: 4
made it through filter: 4
about to filter: 3

Creates an iterator which transforms each value into a new one.

const a = [1, 2, 3];

const iter = map(a, x => x * 2);

iter.next(); // { value: 2, done: false }
iter.next(); // { value: 4, done: false }
iter.next(); // { value: 6, done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which yields the values in reverse order. The given iterable needs to be fully consumed before the values can be yielded in reverse, hence it will result in an infinite loop if it is called on an infinite iterator.

const a = [1, 2, 3];

const iter = reverse(a);

iter.next(); // { value: 3, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 1, done: false }
iter.next(); // { value: undefined, done: false }

Creates an iterator which accumulates a value. This is similar to fold or reduce, but instead of creating a single value, it yields each step of the accumulator, making the last value equivalent to the output of fold or reduce.

const a = [1, 2, 3];

const iter = scan(a, 1, (acc, x) => acc * x);

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 6, done: false }
iter.next(); // { value: undefined, done: false }

Creates an iterator that skips the first n values.

const a = [1, 2, 3, 4];

const iter = skip(a, 2);

iter.next(); // { value: 3, done: false }
iter.next(); // { value: 4, done: false }
iter.next(); // { value: undefined, done: false }

Creates an iterator which skips values until the predicate becomes false.

const a = [1, 3, 6, 11, 13, 2, 4];

const iter = skipWhile(a, x => x < 10);

iter.next(); // { value: 11, done: false }
iter.next(); // { value: 13, done: false }
// This would be false, but skipWhile already stopped after the first false
iter.next(); // { value: 2, done: false }
iter.next(); // { value: 4, done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which yields the first n values of the iterable.

const a = [1, 2, 3];

const iter = take(a, 2);

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: undefined, done: true }

// Often used for infinite iterators
function* naturalNumbers() {
  let i = 0;
  while (true) {
    yield i;
    i += 1;
  }
}

const iter = take(naturalNumbers(), 3);

iter.next(); // { value: 0, done: false }
iter.next(); // { value: 1, done: false }
iter.next(); // { value: 2, done: false }
iter.next(); // { value: undefined, done: true }

Creates an iterator which yields values while the predicate is true.

const a = [1, 3, 6, 11, 13, 2, 4];

const iter = takeWhile(a, x => x < 10);

iter.next(); // { value: 1, done: false }
iter.next(); // { value: 3, done: false }
iter.next(); // { value: 6, done: false }
iter.next(); // { value: undefined, done: true }
// There are more values below 10 but takeWhile stops after the first false

Creates an iterator which yields a pair of values that correspond to a value from the first and the second iterable, and stops when one of the two iterables is done.

const a1 = [1, 2, 3];
const a2 = [4, 5, 6];

const iter = zip(a1, a2);

iter.next(); // { value: [1, 4], done: false }
iter.next(); // { value: [2, 5], done: false }
iter.next(); // { value: [3, 6], done: false }
iter.next(); // { value: undefined, done: true }

// This can be used to zip an infinite iterator to a finite one
function* naturalNumbers() {
  let i = 0;
  while (true) {
    yield i;
    i += 1;
  }
}
const a = ['a', 'b', 'c'];

const iter = zip(naturalNumbers(), a);

iter.next(); // { value: [0, 'a'], done: false }
iter.next(); // { value: [1, 'b'], done: false }
iter.next(); // { value: [2, 'c'], done: false }
iter.next(); // { value: undefined, done: true }

Tests if every value of the iterable satisfies the predicate. When all values satisfy the predicate it returns true, otherwise false. Once the predicate returns false for any value, the result will be false no matter what else happens and therefore it stops processing additional values (short-circuiting). An empty iterable returns true.

const a = [1, 2, 3];

all(a, x => x > 0); // true
all(a, x => x < 2); // false

Tests if any value of the iterable satisfies the predicate. When any value satisfies the predicate it returns true, otherwise false. Once the predicate returns true for any value, the result will be true no matter what else happens and therefore it stops processing additional values (short-circuiting). An empty iterable returns false.

const a = [1, 2, 3];

any(a, x => x > 0); // true
any(a, x => x > 5); // false

Transforms the iterable into a collection. By default an array is constructed unless a transformation function is supplied.

function* helloWorld() {
  yield 'hello';
  yield ' ';
  yield 'world';
}

collect(helloWorld()); // ['hello', ' ', 'world']

// Custom function to create a collection out of an iterable
function concatIter(iter) {
  let str = '';
  for (const val of iter) {
    str += val;
  }
  return str;
}
const a = [1, 2, 3, 4];

collect(helloWorld(), concatIter); // 'hello world'
collect(a, concatIter); // '1234'

Consumes an iterable, counting the number of iterations and returning it. As the iterable needs to be fully consumed, it will result in an infinite loop if is is called on an infinite iterator.

const a = [1, 2, 3, 4, 5];

count(a); // 5

Searches for a value in the iterable that satisfies the predicate. If any of the values satisfies the predicate, the value will be returned, otherwise it returns undefined.

const a = [1, 2, 3, 4, 5];

find(a, x => x === 4); // 4
find(a, x => x > 4); // 5
find(a, x => x > 10); // undefined

Applies a function to each value, producing a single, final value. This is similar to reduce, except that an initial value needs to be supplied.

const a = [1, 2, 3];

const sum = fold(a, 0, (acc, x) => acc + x); // 6
const sumOffset = fold(a, 10, (acc, x) => acc + x); // 16

Applies a function to each value of the iterable and consumes it. This has the same effect as simply using a for-of loop, which should be preferred over this.

const a = [1, 2, 3];

forEach(a, console.log);

1
2
3

Joins all values of the iterable into a string separated with the provided separator. This will automatically convert the values to a string. The default separator is ','.

const customToString = {
  toString() {
    return 'custom toString';
  }
};
const a = ['hello', 99, [1, 2], {}, customToString];

join(a); // 'hello,99,1,2,[object Object],custom toString'
join(a, ' - '); // 'hello - 99 - 1,2 - [object Object] - custom toString'

Consumes an iterable and returns the last value.

const a = [1, 2, 3, 4, 5];

last(a); // 5
last([]); // undefined

Returns the maximum value of an iterable. If two values are equally maximum, the last value is returned.

const a = [1, 2, 3];

max(a); // 3
max([]); // undefined

Returns the minimum value of an iterable. If two values are equally minimum, the first value is returned.

const a = [1, 2, 3];

min(a); // 1
min([]); // undefined

Returns the nth value of an iterable. Like most indexing operations, The count starts from zero (i.e. nth(iter, 0) returns the first value). If n is greater than or equal the number of values in the iterable, it returns undefined.

const a = [1, 2, 3];

nth(a, 2); // 2
nth(a, 5); // undefined

Creates two arrays, where the first array contains all values for which the predicate is true and the second contains all values for which it is false.

const a = [1, 2, 3, 4, 5];
const isEven = x => x % 2 === 0;

const [even, odd] = partition(a, isEven);
even; // [2, 4]
odd;  // [1, 3, 5]

Searches for a value in the iterable that satisfies the predicate and returns its index. If no value satisfies the predicate, -1 is returned.

const a = [1, 2, 3, 4, 5];

position(a, x => x === 4); // 3
position(a, x => x > 4); // 4
position(a, x => x > 10); // -1

Multiplies all values of the iterable together.

const a = [1, 2, 3, 4];

product(a); // 24

Applies a function to each value, producing a single, final value. This similar to fold, but uses the first value of the iterable as initial value if no initial value is given and the order of the parameters is swapped to mimic Array.prototype.reduce. Note that the initial value is not run through the function but taken as is.

const a = [2, 4, 6];

reduce(a, (acc, x) => acc + x); // 12
reduce(a, (acc, x) => acc + x, 10); // 22

// If no initial value is provided, the first value is not built with the
// given function, but simply given as the accumulator to the first call.
reduce(a, (acc, x) => acc + x * 3) // 32
reduce(a, (acc, x) => acc + x * 3, 0) // 36

Sums all values of the iterable.

const a = [1, 2, 3, 4];

sum(a); // 10

Converts an iterable of pairs into two arrays, where each contains the values of the respective position in the pair.

const a = [[0, 'a'], [1, 'b']];

const [left, right] = unzip(a);
left;  // [0, 1]
right; // ['a', 'b']

Adds methods that call the respective functions on the iterator which can be chained as long as the functions return another iterator.

Turns an iterable object into an iterator and adds methods to easily operate on the values.

Turns a generator function into an iterator and adds methods to easily operate on the values.

Turns an iterator object into an iterable iterator and adds methods to easily operate on the values. Usually an iterator is iterable as well, but it is not a requirement.

Checks whether the given object is a generator function.

Checks whether the given object is iterable.

Checks whether the given object is an iterator.