https://github.com/xgbuils/iterum
Handling iterables like lazy arrays.
https://github.com/xgbuils/iterum
functional inmutable iterable iterator lazy-evaluation
Last synced: 5 days ago
JSON representation
Handling iterables like lazy arrays.
- Host: GitHub
- URL: https://github.com/xgbuils/iterum
- Owner: xgbuils
- Created: 2016-02-16T22:18:21.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-08-02T21:21:33.000Z (over 8 years ago)
- Last Synced: 2025-11-17T02:03:50.685Z (2 months ago)
- Topics: functional, inmutable, iterable, iterator, lazy-evaluation
- Language: JavaScript
- Homepage:
- Size: 557 KB
- Stars: 29
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-nodejs-precise - iterum - square)]() | Build generator pipelines using Array-like methods. | (Packages / Control flow Generators)
- awesome-nodejs-new - iterum - Build generator pipelines using Array-like methods. (Packages / Control flow)
README
# 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