iterum

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #go #golang #machine-learning #linux #docker #nodejs #windows #security #ios #open-source

(★ 29)

Handling iterables like lazy arrays.

iterum Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Iterum

[![travis ci][1]][2]
[![npm version][3]][4]
[![Coverage Status][5]][6]
[![Dependency Status][7]][8]

`iterum` library provides a class for handling iterable transformations inspired in [Array methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) and [lodash/fp](https://github.com/lodash/lodash/wiki/FP-Guide) functions. This library also supplies combinatorial functions like [permutations](doc/API.md#permutations), [combinations](doc/API.md#combinations), [variations](doc/API.md#variations), [product](doc/API.md#product), [power](doc/API.md#power) and [powerSet](doc/API.md#powerset) that has a high computational cost but this library is able to support taking advantage of lazy evaluation.

## Install

``` bash
$ npm install iterum --save
```

## Usage
``` javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) 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:

``` javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) statement and the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator). For example:

``` javascript
[...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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#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`:

``` javascript
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:

``` javascript
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](doc/features.md)
- [Functional & method chaining approach
](doc/features.md)
- [Maximizing support for infinite iterables](doc/features.md)
- [No consumible iterables](doc/features.md)
- [Combinatorial hight cost functions](doc/features.md)
- [Thinking about modularity](doc/features.md)
- [Thinking about performance](doc/features.md)

## [API Documentation](doc/API.md)

## Support
- Node.js >=6
- ES2015 transpilers

## Customized builds
`Iterum` allows to build just what you need. Read [customized build section](doc/customized_builds.md) for more information.

## License
MIT

[1]: https://travis-ci.org/xgbuils/iterum.svg?branch=master
  [2]: https://travis-ci.org/xgbuils/iterum
  [3]: https://badge.fury.io/js/iterum.svg
  [4]: https://badge.fury.io/js/iterum
  [5]: https://coveralls.io/repos/github/xgbuils/iterum/badge.svg?branch=master
  [6]: https://coveralls.io/github/xgbuils/iterum?branch=master
  [7]: https://david-dm.org/xgbuils/iterum.svg
  [8]: https://david-dm.org/xgbuils/iterum

iterum

iterum Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

iterum

iterum Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README