Coder Social home page Coder Social logo

iterum's Introduction

Iterum

travis ci npm version Coverage Status Dependency Status

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)

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

iterum's People

Contributors

xgbuils avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

Forkers

benji6

iterum's Issues

Iterum methods don't create a standalone iterator [0.4.0]

Example:

var Iterum = require('iterum')
var Range = Iterum.Range

var it = Iterum(Range(3, 5))
var mapIt = it.map(function (value) {
    return 2 * value
})

mapIt.next() // {value: 6, done: false}
mapIt.next() // {value: 8, done: false}
it.next() // {value: 5, done: false}
it.next() // {value: undefined, done: false}

If next method of mapIt is called, next method of it is affected.

removing `fromIndex` arguments.

includes and indexOf has fromIndex arguments which don't make sense.

In Array approach it is useful to have better performance. But in lazy approach doing iterum.drop(fromIndex).includes(...) is the same.

cartesian performance

I found es-iter library that implements similar methods to this library. But there are mutables. For example:

const Iter = require('es-iter')
var a = new Iter([1, 2, 3])
var b = a.map(e => 2 * e)
[...a] // returns [1, 2, 3]
[...b] // however it returns [] because has been consumed previously

However, I found some performance problems in Iterum#cartesian method vs Iter#product method. When a cartesian product of large number of iterables is calculated, it takes a lot of time:

I will try to solve this issue.

https://jsperf.com/iterum-vs-es-iter-cartesian-product

implement `combinations` method

I would like to implement a method that returns the combinations of n values that produces an iterable. For example:

Iterum([1, 2, 3, 4]).combinations(2) /*
    (1 2)
    (1 3)
    (1 4)
    (2 3)
    (2 4)
    (3 4)
) */

I don't know what is the best order to produce values yet

0.7.0 features

  • add Cartesian constructor
  • add How to customize Iterum build (just import what you need!).
  • change from value methods/transform methods to eager methods/lazy methods

implement `power` method

I would like to implement a power method that do the cartesian product of an iterable n times:

Iterum([0, 1]).power(3) /* (
    (0 0 0)
    (1 0 0)
    (0 1 0)
    (1 1 0)
    (0 0 1)
    (1 0 1)
    (0 1 1)
    (1 1 1)
) */ 

This method produces the same result like:

Iterum.product([0, 1], [0, 1], [0, 1])

However, Iterum.product cannot produce a cartesian product of infinite iterables and Iterum.power can.

Iterum([0, 1]).power(Infinity) /* (
    (0, 0, 0, 0, 0, ...)
    (1, 0, 0, 0, 0, ...)
    (0, 1, 0, 0, 0, ...)
    (1, 1, 0, 0, 0, ...)
    ...
) */

Implement lazy cartesian product

Now, cartesian method does not allow to be used with infinite iterables. If cartesian returns an iterable of iterables, this method will be able to be lazy.

remove default behaviour of Iterum functions if first parameter is not an iterable.

Now, the Iterum functions behaves like lodash library.

For example:

_.every(null, function (x) {
    x > 3
}) // returns true

It returns true because convert no arrays like null to empty arrays. Iterum does the same, but I don't want to mantain more this behaviour. If function requires an iterable an is not passed an iterable it will throw an error.

release 2

I would like to do some breaking changes.

First of all, I prefer that methods that returns lazy iterables of arrays (zip, cartesian, permutations) return iterables of iterables to achieve a real laziness. For example, is not possible to do permutations or cartesian product of potentially infinite iterables.

At second point, I want to use memoization. For example, if we have:

const iterable = Iterum([1, 2, 4, 8, 16, 32, 64, 128])

and then we need to do:

const slice = iterable.slice(6)
const result = slice.concat(slice)
[...result]

The first iterable is traversed twice.

I don't want this behaviour.

Finally, there are some methods like map, reduce, every, etc. that I would like to simplify thus:

  1. removing the context parameter and,
  2. Allowing the value parameter on callback functions.

The reason is that point 1 can be acomplished using bind and point 2 can be achieved using zip combined with other methods. For example:

const iterable = Iterum([1, 3, 5, 7]).map((e, i) => 2 * e + i)
// would be implemented thus:
const {range} = Iterum
const iterable = Iterum([1, 3, 5, 7]).zip(range(0, Infinity)).map(([e, i]) => 2 * e + i)

0.9.0 features

All methods except build and toArray (and forEach?) should return Iterum instances. .every, .indexOf, .reduce, .reduceRight and .some that return other type of values. They should return a generator that builds an iterator with one iteration with the same value that returns in [email protected]

Release 1.0

I would like to implement a new release using ES2015 features.

The current package just allows manipulate generators with 0-arity. There are some similar data structure in es2015: iterables

Iterables are objects that wraps a generator of 0-arity in Symbol.iterator property. Then:

  • Iterum(generator) constructor will be deprecated and Iterum(iterable) will be the new constructor.
  • Iterum instance will also be an iterable.
  • new ES2015 Array inmutable methods will be implemented in Iterum prototype.
  • Support for node >=6

Then, new branch dev-1.0 has been created and I will be happy to receive any suggestions and constributions.

Thanks.

Add benchmarks

As @benji6 said on issue #8, it's interesting to collect some benchmarks before doing the next major release.

Iterum does not work with babel

I found that Iterum library does not work with babel. The problem is that instanceof operator is not transformed taking in account that any instanceof operator might be calculated using [Symbol.hasInstance] method in es2015.

I will create a PR to solve this tomorrow.

implement zipLongest & transposeLongest

Implement zipLongest and transposeLongest that do the same as zip and transpose but applying transposition until the longest iterable is finished and filling iterables that produces less values with undefined.

See es-iter#longZip

0.6.0 features

  1. Methods & Iterum constructors require arguments validation
  2. Is it important to implement reduce method and other kind of method that Array implements?
  3. add travis ci

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.