Higher-Order Iterator

The iterator which takes iterators as arguments and returns an iterator.

Iterators and Generators Guide

Install

$ npm install --save ho-iter

Usage

const hoi = require('ho-iter');

const entries1 = hoi({ foo: 'bar' });
const entries2 = hoi({ baz: 42 });

const keys = [];
const values = [];

for (let [key, value] of hoi.series(entries1, entries2)) {
    keys.push(key);
    values.push(value);
}

console.log(`keys: ${keys}`);
console.log(`values: ${values}`);

// ➜ keys: [foo, baz]
// ➜ values: [bar, 42]

API

Create iterator:

• hoi(iterable)
• hoi(iterator)
• hoi(object)
• hoi(number|boolean|symbol|regexp|function)

Helpers:

• value(value)
• isIterable(iterable)
• isIterator(iterator)
• series(...iterables)
• evenly(...iterables)
• reverse(iterable)

hoi(iterable)

Creates iterator for iterable object.

Uses Iterable protocol to create iterator.

Iterable data structures:

• Array
• TypedArray
• Set, WeakSet
• Map, WeakMap
• String
• arguments

Example 1. Create iterator with array items.

const hoi = require('ho-iter');

const iter = hoi([1, 2, 3, 4]);

for (let item of iter) {
    console.log(item);
}

// ➜ 1
// ➜ 2
// ➜ 3
// ➜ 4

Example 2. Create iterator with set values.

const hoi = require('ho-iter');

const set = new Set([1, 2, 3, 4]);
const iter = hoi(set);

for (let item of iter) {
    console.log(item);
}

// ➜ 1
// ➜ 2
// ➜ 3
// ➜ 4

Example 3. Create iterator with map entries.

const hoi = require('ho-iter');

const map = new Map();

map.set('key1', 'val1');
map.set('key2', 'val2');

const iter = hoi(map);

for (let [key, val] of iter) {
    console.log(`key: ${key}, val: ${val}`);
}

// ➜ key: key1, val: val1
// ➜ key: key2, val: val2

Example 3. Create iterator with string characters.

const hoi = require('ho-iter');

const iter = hoi('Iterate me!');

for (let char of iter) {
    console.log(char);
}

// ➜ I
// ➜ t
// ➜ e
// ➜ r
// ➜ a
// ➜ t
// ➜ e
// ➜
// ➜ m
// ➜ e
// ➜ !

Important: If you want to create iterator with integral string use hoi.value(string) helper.

const hoi = require('ho-iter');

const iter = hoi.value("Don’t touch me!");

for (let item of iter) {
    console.log(item);
}

// ➜ Don’t touch me!

Example 4. Creates iterator with arguments.

const hoi = require('ho-iter');

const iter = hoi.value("Don't touch me!");

function foo(arg1, arg2) {
    const iter = hoi(arguments);

    for (let arg of iter) {
        console.log(arg);
    }
}

foo('bar', 'baz');

// ➜ bar
// ➜ baz

Example 5. Create empty iterator.

If value is not specified, returns empty iterator.

The empty iterator just returns done for each call.

const hoi = require('ho-iter');

const iter = hoi();

iter.next();

// ➜ { done: true, value: null }

hoi(iterator)

Provides specified iterator or creates iterator by Iterable protocol.

Important: If iterator does not support Iterable protocol then hoi(iterator) does not clone specified iterator.

const hoi = require('ho-iter');

function makeIterator(array) {
    let nextIndex = 0;

    return {
        next() {
            return nextIndex < array.length ?
                { value: array[nextIndex++], done: false } :
                { done: true };
        }
    }
}

const iter = makeIterator([1, 2, 3]);

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

const hoIter = hoi(iter); // iterator will not be clonned

// ➜ { done: true }

hoi(object)

Creates an iterator whose elements are arrays corresponding to the enumerable property [key, value] pairs found directly upon object.

The ordering of the properties is the same as that given by looping over the property values of the object manually.

This is reminiscent of the Object.entries method or Map[iterator].

Important: Object does not Iterable protocol in ES2015.

const hoi = require('ho-iter');

const iter = hoi({
    foo: 'bar',
    baz: 42
});

for (let [key, val] of iter) {
    console.log(`key: ${key}, val: ${val}`);
}

// ➜ key: foo, val: bar
// ➜ key: baz, val: 42

Important: If you want to create iterator with integral object use hoi.value(object) helper.

const hoi = require('ho-iter');

const iter = hoi.value({ foo: 'bar' });

for (let item of iter) {
    console.log(item);
}

// ➜ { foo: 'bar' }

hoi(number|boolean|symbol|regexp|function)

If value is not iterable then throws error:

It is impossible to create iterator: `value` is not iterable object.

Not iterable data structures:

• Number
• Boolean
• Symbol
• Function
• RegExp

const hoi = require('ho-iter');

const iter = hoi(null);

// It is impossible to create iterator: `null` is not iterable object.

Use hoi.value(value) to create iterator with one value.

Helpers

• value(value)
• isIterable(iterable)
• isIterator(iterator)
• series(...iterables)
• evenly(...iterables)
• reverse(iterable)

value(value)

Creates iterator with specified value.

If value is not specified, returns empty iterator.

Example:

const hoi = require('ho-iter');

const iter = hoi.value(123);

iter.next(); // { value: 123, done: false }
iter.next(); // { value: null, done: true }

isIterable(iterable)

Returns true if the specified object implements the Iterator protocol via implementing a Symbol.iterator.

Example:

const isIterable = require('ho-iter').isIterable;

isIterable([1, 2, 3]); // true
isIterable(123); // false

isIterator(iterator)

Returns true if the specified object is iterator.

const isIterator = require('ho-iter').isIterator;

const generator = function *() {};
const iterator = generator();

isIterator(generator) // false
isIterator(iterator) // true

series(...iterables)

Returns an Iterator, that traverses iterators in series.

This is reminiscent of the concatenation of arrays.

Example:

const series = require('ho-iter').series;

const arr1 = [1, 2];
const arr2 = [3, 4];

const set1 = new Set([1, 2]);
const set2 = new Set([3, 4]);

[].concat(arr1, arr2);

// ➜ [1, 2, 3, 4]

for (let item of series(set1, set2)) {
    console.log(item);
}

// ➜ 1 2 3 4

evenly(...iterables)

Returns an Iterator, that traverses iterators evenly.

This is reminiscent of the traversing of several arrays.

Example:

const evenly = require('ho-iter').evenly;

const arr1 = [1, 2];
const arr2 = [3, 4];

const set1 = new Set([1, 2]);
const set2 = new Set([3, 4]);

for (let i = 0; i < arr1.length; i++) {
    console.log(arr1[i]);
    console.log(arr2[i]);
}

// ➜ 1 3 2 4

for (let item of evenly(set1, set2)) {
    console.log(item);
}

// ➜ 1 3 2 4

reverse(iterator)

Returns an reversed Iterator.

Important: incompatible with infinite iterator. Don't use infinite iterator, otherwise reverse method will fall into endless loop loop.

This is reminiscent of the reversing of an array.

Example:

const reverse = require('ho-iter').reverse;

const arr = [1, 2, 3, 4];
const set = new Set([1, 2, 3, 4]);

for (let i = arr.length; i >= 0; i--) {
    console.log(arr[i]);
}

// ➜ 4 3 2 1

for (let item of reverse(set)) {
    console.log(item);
}

// ➜ 4 3 2 1

License

MIT © Andrew Abramov