xgbuils / iterum

Handling iterables like lazy arrays.

Iterum

iterum library provides a class for handling iterable transformations inspired in Array methods and lodash/fp functions. This library also supplies combinatorial functions like permutations, combinations, variations, product, power and powerSet that has a high computational cost but this library is able to support taking advantage of lazy evaluation.

Install

$ npm install iterum --save

Usage

const Iterum = require('iterum')
const {range} = Iterum

const iterable = range(1, Infinity) // (1 2 3 4 5 6 7 8...)
    .map(value => 2 * value) // (2 4 6 8 10 12 14 16...)
    .filter(value => value % 3 === 0 || value % 3 === 1) // (4 6 10 12 16...)
    .take(5) // (4 6 10 12 16)
    .concat([1, 2, 3]) // (4 6 10 12 16 1 2 3)

// converting to array:
[...iterable] // [4, 6, 10, 12, 16, 1, 2, 3]

// traversing values:
for (const val of iterable) {
    // ...
}

// creating an iterator that traverses the values
let iterator = iterable[Symbol.iterator]()
iterator.next() // {value: 4, done: false}
iterator.next() // {value: 6, done: false}
iterator.next() // {value: 10, done: false}
iterator.next() // {value: 12, done: false}
iterator.next() // {value: 16, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 3, done: false}
iterator.next() // {value: undefined, done: true}

Why Iterum?

Iterable interface has been introduced by ES2015. An object that implements this interface has a Symbol.iterator property with a generator value which arity is 0. For example we can create an obj variable that implements Iterable interface:

let obj = {
    [Symbol.iterator]: function* () {
        for (let i = 0; i <= 10; ++i) {
            yield i
        }
    }
}

Any object that implements the Iterable interface can use for..of statement and the spread operator. For example:

[...obj] // returns [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

for (let x of obj) {
  // x traverses all values between 0 and 10
}

Then, obj can be processed as an ordered list of values. However, unlike built-in iterables (Array, Set, Map, String, etc), obj is a lazy iterable. It means that, thanks to generators, obj does not store the computed values in memory and its values are computed just when are required. These are the essential features for implementing lazy evaluation.

It is even possible to create a new iterable without computing or storing obj values in memory. This is an example of creating a new iterable that iterates over the double of values generated by obj:

let doubleObj = {
    [Symbol.iterator]: function* () {
        for (const value of obj) {
            yield 2 * value
        }
    }
}

[...doubleObj] // returns [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

iterum is a library that takes advantage of these techniques to provide a collection of functions and methods that apply iterable transformations without traversing values. Then, using iterum, the previous example could be expressed thus:

const Iterum = require('iterum')

const obj = Iterum.range(0, 10) // (0 1 2 3 4 5 6 7 8 9 10)

const doubleObj = obj.map(e => 2 * e) // (0 2 4 6 8 10 12 14 16 18 20)

Features

• Functional & method chaining approach
• Maximizing support for infinite iterables
• No consumible iterables
• Combinatorial hight cost functions
• Thinking about modularity
• Thinking about performance

API Documentation

Support

• Node.js >=6
• ES2015 transpilers

Customized builds

Iterum allows to build just what you need. Read customized build section for more information.

License

MIT