# consequence

library providing functional helpers for generators

``npm install consequence``

# ConSequence.js

ConSequence.js - a library providing functional helpers for generators

# examples

``````// Generator containing the sequence of natural numbers.
function* nat() {
let i = 1;
while (true) {
yield i++;
}
}

// Sequence of all Mersenne numbers.
function mersenneNumbers() {
return cons.map(nat(), function (x) { return Math.pow(2, x) - 1 });
}

// Sequence of all Mersenne numbers that are prime.
function mersennePrimes() {
function isPrime(n) {
return cons.every(cons.range(2, n - 1), function (x) { return n % x });
}

return cons.filter(cons.drop(mersenneNumbers(), 1), isPrime);
}

cons.toArray(cons.take(mersennePrimes(), 3)); // [3, 7, 31];
``````

# methods

## fromArray(arr)

Utility function that creates a generator from a given array `arr`.

``````let g = cons.fromArray([1, 2]);
console.log(g.next().value, g.next().value); // prints 1 2
``````

## toArray(it)

Utility function that consumes the whole sequence `it` and returns an array containing all of its values.

``````function* g() {
yield 1;
yield 2;
yield 3;
}

cons.toArray(g()); // [1, 2, 3]
``````

## range(from, to)

Creates a generator containing an arithmetic progression starting with the value `from` up to including value `to`.

``````cons.toArray(cons.range(1, 3)); // [1, 2, 3]
``````

## map(it, fun)

Creates a generator containing the results of applying `fun` to all values of `it`.

``````function square(x) {
return x * x;
}

cons.toArray(cons.map(cons.range(1, 3), square)); // [1, 4, 9]
cons.toArray(cons.map([-1, -2, -3], square)); // [1, 4, 9]
``````

## filter(it, p)

Creates a generator containing values of `it` where the predicate `p` holds.

``````function odd(x) {
return x % 2;
}

cons.toArray(cons.filter(cons.range(1, 6), odd)); // [1, 3, 5]
cons.toArray(cons.filter([1, 2, 3, 4], odd)); // [1, 3]
``````

## reject(it, p)

Creates a generator containing values of `it` where the predicate `p` does not hold.

``````function odd(x) {
return x % 2;
}

cons.toArray(cons.reject(cons.range(1, 6), odd)); // [2, 4, 6]
cons.toArray(cons.reject([1, 2, 3, 4], odd)); // [2, 4]
``````

## compact(it)

Creates a generator containing all truthy values of `it`.

``````cons.toArray(cons.compact(cons.range(-1, 1))); // [-1, 1]
cons.toArray(cons.compact([1, "", 2, 0, true, false])); // [1, 2, true]
``````

## reduce(it, fun)

Consumes the whole sequence `it` and reduces all of its values down to a single value. `fun` is called on each step with the current reduction state and value as arguments.

``````function sum(it) {
return cons.reduce(it, function (acc, x) { return acc + x }, 0);
}

sum([2, 3, 4]); // 9
sum(cons.range(1, 3)); // 6
sum(cons.range(-1, 1)); // 0
``````

## each(it, fun)

Consumes the whole sequence `it` calling the given function `fun` for every value, passing the value as a single argument.

``````// Show alert boxes for numbers 1 to 3.
``````

## min(it)

Consumes the whole sequence `it` and returns the minimum value found or `+Infinity` for empty sequences.

``````cons.min(cons.range(1, 6)); // 1
cons.min([5, 1, 7]); // 1
``````

## max(it)

Consumes the whole sequence `it` and returns the maximum value found or `-Infinity` for empty sequences.

``````cons.max(cons.range(1, 6)); // 6
cons.max([5, 1, 7]); // 7
``````

## uniq(it)

Returns a generator containing all distinct values from the given sequence `it`.

``````function mod3(x) {
return x % 3;
}

cons.uniq(cons.map(cons.range(1, 9), mod3)); // [1, 2, 0]
cons.uniq(['a', 'b', 'a', 'c']); // ['a', 'b', 'c']
``````

## every(it, fun)

Returns `true` if the given predicate `fun` holds for all values of the given sequence `it`. Returns `true` as well for empty sequences.

``````function greaterThanZero(x) {
return x > 0;
}

cons.every(cons.range(1, 5), greaterThanZero); // true
cons.every([0, 1, 2, 3, 4], greaterThanZero); // false
cons.every([], greaterThanZero), true);
``````

## some(it, fun)

Returns `true` if the given predicate `fun` holds for at least one value of the given sequence `it`. Returns `false` for empty sequences.

``````function equalToZero(x) {
return x === 0;
}

cons.some(cons.range(1, 5), equalToZero); // false
cons.some([0, 1, 2, 3, 4], equalToZero); // true
cons.some([], equalToZero), false);
``````

## size(it)

Consumes the whole sequence `it` and returns the number of values found.

``````cons.size(cons.range(1, 5)); // 5
cons.size([1, 2, 3]); // 3
``````

## contains(it, val)

Returns `true` if the given value `val` is contained in the given sequence `it`, `false` otherwise.

``````cons.contains(cons.range(0, 5), 0); // true
cons.contains([1, 2, 3, 4, 5], 0); // false
``````

## find(it, fun)

Returns the first value of the given sequence `it` for which the given predicate `fun` holds.

``````function greaterThanThree(x) {
return x > 3;
}

cons.find(cons.range(1, 6), greaterThanThree); // 4
cons.find([3, 4, 5], greaterThanThree); // 4
cons.find([], greaterThanThree); // undefined
``````

## take(it, num)

Returns a generator containing the first `num` values from the given sequence `it`.

``````cons.take(cons.range(1, 6), 3); // [1, 2, 3]
cons.take([1, 2, 3], 2); // [1, 2]
``````

## drop(it, num)

Returns a generator containing all but the first `num` values from the given sequence `it`.

``````cons.drop(cons.range(1, 6), 3); // [4, 5, 6]
cons.drop([1, 2, 3], 1); // [2, 3]
``````

## flatten(it)

Flattens the given (nested) sequence `it`.

``````function* g() {
yield 1;
yield 2;
yield [3, 4];
}

cons.flatten([0, g()]); // [0, 1, 2, 3, 4]
cons.flatten([1, [2], [3, [[4]]]]); // [1, 2, 3, 4]
``````

## flatMap(it, fun)

Creates a generator containing the flattened results of applying `fun` to all values of `it`.

``````function map(x) {
return [x, [x]];
}

cons.flatMap(cons.range(1, 3), map); // [1, 1, 2, 2, 3, 3]
cons.flatMap([1, 2, 3], map); // [1, 1, 2, 2, 3, 3]
``````

# install

For node.js, with npm do:

``````npm install consequence
``````