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

[xgbuils]

A posible solution is implementing a iterator method clone. But I think that is complex to do it because when you create a iterator using a function:

function naturalsCreator () {
    var a = 0;
    return function () {
        return {
            value: a,
            done: false
        }
    }
}
var it = Iterum(naturalsCreator()) 

It's difficult to restart enviroment of function.

I think would be best create API based on generators and reject this API.

[xgbuils]

A generator is a function that returns an iterator. Providing methods in prototype of Generator class, it is difficult because it's necessary a Generator constructor with a function parameter that creates a Generator instance and this is complex to do. I think that it's better to create a Iterum class which instances wrap a generator. This iterum class will have methods .map, .filter, .concat, etc. that will be return Iterum instance. If I want to get the generator, I will call .build method that will be return the transformed generator:

var generator = Iterum(Range(1, 6))
    .filter(function (value) {
        return value % 2 === 0
    })
    .map(function (value) {
        return value * 5
    })
    .slice(1)
    .build()
var iterator = generator()

iterator.next() // {value: 20, done: false}
iterator.next() // {value: 30, done: false}
iterator.next() // {value: undefined, done: true}

About methods like .toArray, .some, .every, .indexOf will return values that are not instance of Iterum. Then it won't be possible to chain them:

var generator = Iterum(Range(1, 6))
    .filter(function (value) {
        return value % 2 === 0
    })
    .map(function (value) {
        return value * 5
    })
    .slice(1)
    .every(function (value) {
        return value % 10 === 0
    }) // true

[xgbuils]

Generators with or without parameters?

Firstly, I thought there is no problem to pass generators with arity greater than 0 to Iterum constructor. For example, given a Range(start, end, incr) generator with arity 3. I could pass to Iterum constructor and mantain the same arity through methods. For example:

var generator = Iterum(Range)
    .filter(function (value) {
        return value % 2 === 0
    })
    .map(function (value) {
        return value * 5
    })
    .slice(1)
    .build()
var iterator = generator(1, 6, 1) // calling generator with parameters `1, 6, 1` 

iterator.next() // {value: 20, done: false}
iterator.next() // {value: 30, done: false}
iterator.next() // {value: undefined, done: true}

When .filter, .map or .slice are called it's expectable to built generator keeping the same parameters. But .concat method receives a generator with its arity. What must be the arity of generator result?

1. A concatenarion of arguments of two generators:

var generator = Iterum(Range)
    .concat(Range)
    .build()

var generator(0, 2, 1, 3, 0, -1)
iterator.next() // {value: 0, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 3, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 0, done: false}
iterator.next() // {value: undefined, done: true}

This solution has the problem with the generators with variable number of parameters.

2. Two array arguments. The first array is the list of arguments of first generator. The second array is the list of arguments of second generator:

var generator = Iterum(Range)
    .concat(Range)
    .build()

var generator([0, 2, 1], [3, 0, -1])
iterator.next() // {value: 0, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 3, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 0, done: false}
iterator.next() // {value: undefined, done: true}

But, if there are two concat calls what is the best option?

var generator = Iterum(Range)
    .concat(Empty)
    .concat(Value)
    .build()
var generator([0, 2, 1], [], [5]) // this?
// or
var generator([[0, 2, 1, []], [5]]  // this?

Besides, .toArray, .some, .every or .indexOf methods can't be called if arguments of generator are not passed.

For all that I think that is better avoid generators with arity greater than 0.

[xgbuils]

Apology of using generators without arguments

Iterum library can provide built-in functions that return usual generators with 0-arity. For example is posible to implement Range function that provides generator with 0 arity. and when is called returns a range iterator:

var Range = function (start, end, incr) {
    return function () {
        inc || (inc = 1)
        var sign = inc > 0 ? 1 : -1
        var value = a - inc
        return {
            next: function () {
                value += inc
                var done = (b - value) * sign < 0
                return {
                    value: done ? undefined : value,
                    done: done
                }
            }
        }
    }
}

var generator = Iterum(Range(9, 7, -1))
    .concat(Range(2, 3))
    .build()
var iterator = generator()

iterator.next() // {value: 9, done: false}
iterator.next() // {value: 8, done: false}
iterator.next() // {value: 7, done: false}
iterator.next() // {value: 2, done: false}
iterator.next() // {value: 3, done: false}
iterator.next() // {value: undefined, done: true}

In this way, is possible to call some, every or toArray methods:

var array = Iterum(Range(9, 7, -1))
    .concat(Range(2, 3))
    .toArray() // [9, 8, 7, 2, 3]

If you want to build generator with parameters, you also can do it:

function generatorWithParams(a) {
    return Iterum(Range(0, a))
        .concat(Range(a - 1, 0))
        .build()()
}

var it1 = generatorWithParams(1)
var it2 = generatorWithParams(2)

it1.next() // {value: 0, done: false}
it1.next() // {value: 1, done: false}
it1.next() // {value: 0, done: false}
it1.next() // {value: undefined, done: true}

it2.next() // {value: 0, done: false}
it2.next() // {value: 1, done: false}
it2.next() // {value: 2, done: false}
it2.next() // {value: 1, done: false}
it2.next() // {value: 0, done: false}
it2.next() // {value: undefined, done: true}

[xgbuils]

It's good to have a built-in functions such as Range, List, Repeat, Value, Empty. But I think that it's important to allow that user be able to provide their functions to Iterum. I think that it's weird to forbide that user don't pass generators with arguments in Iterum constructor. Another approach is allow this and assume that the rest of parameters are used to bind generator with them. For example:

function exponentGenerator(n) {
    var index = 0
    return {
        next: function () {
            var result = {
                value: Math.pow(index, n),
                done: false
            }
        }
    }
}

var gen = Iterum(exponentGenerator, 3).build()

var iterator = gen()
iterator.next() // {value: 0, done: false}
iterator.next() // {value: 1, done: false}
iterator.next() // {value: 8, done: false}
iterator.next() // {value: 27, done: false}
iterator.next() // {value: 64, done: false}
//...

[xgbuils]

Pending to write: clone method
Pending: concat with customized generators & args

[xgbuils]

Finally I chose to implement inmutables transform methods and clone function is not required.