API

Constructors

All functions listed below create new sequences from non-sequence values. They are therefore called constructors.

nil

This constant represents a sequence containing no values.

Returns: SequenceType<*>

Example

const emptySequence = nil;
                              
console.log(...emptySequence);
// => Logs '' (nothing)

PureSequence

Creates a sequence which contains just the given value.

Returns: SequenceType<_T_>

Parameters

Example

const seq = PureSequence(1);
                            
console.log(...seq);
// => Logs '1'

Range

Creates a range of numbers between two inclusive boundaries, that implements the JS iteration protocols. First and second boundaries can be specified in arbitrary order, step size is always the third parameter.

Returns: SequenceType<_T_>

Parameters

Example

const range               = Range(3);
const [five, three, one]  = Range(1, 5, -2);
const [three, four, five] = Range(5, 3);
                                            
console.log(...range);
// => Logs '0, 1, 2, 3'

repeat

Returns a Sequence that will repeatedly yield the value of arg when iterated over. repeat will never be exhausted.

Returns: SequenceType<_T_>

Parameters

Example

const ones   = repeat(1);
const result = take(3)(ones);
                             
console.log(...result);
// => Logs '1, 1, 1'

replicate

replicate(n)(x) creates a Sequence of length n with x the value of every element.

Returns: SequenceType<_T_>

Parameters

Example

const trues = replicate(3)(true);
                                 
console.log(...trues);
// => Logs 'true, true, true'

Sequence

The incrementFunction should change the value (make progress) in a way that the ntilFunction function can recognize the end of the sequence.

Contract:

• incrementFunction & untilFunction should not refer to any mutable state variable (because of side effect) in the closure.

Returns: SequenceType<_T_>

Parameters

Example

const start      = 0;
const untilF     = x => x < 3;
const incrementF = x => x + 1;
const sequence   = Sequence(start, untilF, incrementF);
                                                       
console.log(...sequence);
// => Logs '0, 1, 2'

StackSequence

Creates a SequenceType on top of the given stack.

Returns: SequenceType<_T_>

Parameters

Example

const stack         = push(push(push(emptyStack)(1))(2))(3);
const stackSequence = StackSequence(stack);
                                                            
console.log(...stackSequence);
// => Logs: '3, 2, 1'

TupleSequence

Constructs a new SequenceType based on the given tuple.

Returns: SequenceType<_T_>

Parameters

Example

const [Triple]      = Tuple(3);
const triple        = Triple(1)(2)(3);
const tupleSequence = TupleSequence(triple);
                                            
console.log(...tupleSequence);
// => Logs '1, 2, 3'

Operators

All of the following functions operate on sequences and iterables. They all return a new sequence.

bind

Applies the given function to each element of the Iterable and flattens it afterward. Note: This operation adds a monadic API to the SequenceType.

Returns: SequenceType<_U_>

Parameters

Example

const numbers = [0, 1, 2, 3];
const bindFn  = el => take(el)(repeat(el));
const result  = bind(bindFn)(numbers);
                                           
console.log(...result);
// => Logs '1, 2, 2, 3, 3, 3'

catMaybes

The catMaybes function takes an iterable of maybes and returns a sequence of all the Just’s values.

Returns: SequenceType<_T_>

Parameters

Example

const maybes = [Just(5), Just(3), Nothing];
const result = catMaybes(maybes);
                                           
console.log(...result);
// => Logs '5, 3'

concat

Adds the second iterable to the first iterables end.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2];
const range   = Range(2);
const concatenated = concat(numbers)(range);
                                            
console.log(...concatenated);
// => Logs '0, 1, 0, 1, 2'

cons

Adds the given element to the front of an iterable.

Returns: SequenceType<_T_>

Parameters

Example

const numbers  = [1, 2, 3];
const element  = 0;
const consed = cons(element)(numbers);
                                      
console.log(...consed);
// => Logs '0, 1, 2, 3, 4'

cycle

Ties a finite iterable into a circular one, or equivalently, the infinite repetition of the original iterable.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2];
const cycled = cycle(numbers);
const result = take(6)(cycled);
                               
console.log(...result);
// => Logs '0, 1, 2, 0, 1, 2'

drop

Jumps over so many elements.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2, 3];
const dropped = drop(2)(numbers);
                                 
console.log(...dropped);
// => Logs '2, 3'

dropWhile

Discards all elements until the first element does not satisfy the predicate anymore.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2, 3, 4, 5];
const dropped = dropWhile(el => el < 2)(numbers);
                                                 
console.log(...dropped);
// => Logs '2, 3, 4, 5'

map

Transforms each element using the given function.

Returns: SequenceType<_U_>

Parameters

Example

const numbers = [0, 1, 2];
const mapped  = map(el => el * 2)(numbers);
                                           
console.log(...numbers);
// => Logs '0, 2, 4'

mconcat

Flatten an iterable of iterables.

Returns: SequenceType<_T_>

Parameters

Example

const ranges = map(x => Range(x))(Range(2));
const result = mconcat(ranges);
                                            
console.log(...result);
// => Logs '0, 0, 1, 0, 1, 2'

pipe

Transforms the given iterable using the passed operators.

Returns: SequenceType<_T_> | *

Parameters

Example

const piped = pipe(
               retainAll(n => n % 2 === 0),
               map(n => 2*n),
               drop(2)
             )([0,1,2,3,4,5]);
                                           
console.log(...piped);
// => Logs '0, 4, 8'

rejectAll

Only keeps elements which do not fulfil the given predicate.

Returns: SequenceType<_T_>

Parameters

Example

const filtered = rejectAll(el => el % 2 === 0)([0, 1, 2, 3, 4, 5]);

console.log(...filtered);
// => Logs '1, 3, 5'

retainAll

Only keeps elements which fulfil the given predicate.

Returns: SequenceType<_T_>

Parameters

Example

const filtered = retainAll(el => el % 2 === 0)([0, 1, 2, 3, 4, 5]);

console.log(...filtered);
// => Logs '0, 2, 4'

reverse$

Processes the iterable backwards.

Returns: SequenceType<_T_>

Parameters

Example

const reversed = reverse$([0, 1, 2]);
                                   
console.log(...reversed);
// => Logs '2, 1, 0'

snoc

Adds the given element to the end of the iterable. It is the opposite of cons

Returns: SequenceType<_T_>

Parameters

Example

const snocced = snoc(7)([0, 1, 2, 3]);
                                      
console.log(...snocced);
// => Logs '0, 1, 2, 3, 7'

take

Stop after so many elements.

Returns: SequenceType<_T_>

Parameters

Example

const taken   = take(2)([0,1,2,3]);
                                   
console.log(...taken);
// => Logs '0, 1'

takeWhile

Proceeds with the iteration until the predicate becomes true.

Returns: SequenceType<_T_>

Parameters

Example

const dropped = takeWhile(el => el <= 2)([0, 1, 2, 3, 4 ,5]);
                                                               
console.log(...result);
// => Logs '0, 1, 2'

zip

Zip takes two iterables and returns an iterable of corresponding pairs.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2],
const range   = Range(3, 5);
const zipped  = zip(numbers)(range);
                                         
forEach$(x => console.log(...x))(zipped);
// => Logs '0 3, 1 4, 2 5'

zipWith

Generalises zip by zipping with the function given as the first argument.

Returns: SequenceType<_T_>

Parameters

Example

const numbers = [0, 1, 2];
const range   = Range(2, 4);
const zipped  = zipWith((i,j) => [i,j])(numbers)(range);
console.log(...zipped);
                                                        
// => Logs '[0,2], [1,3], [2,4]'

Terminal operations

All of the following operations transform an iterable into a single value.

eq$

Checks the equality of two non-infinite iterables.

Note: Two iterables are considered as equal if they contain or create the exactly same values in the same order. Use ["=="] defined on the SequencePrototype to perform a comparison in a more readable form.

Returns: Boolean

Parameters

Example

const numbers = [0, 1, 2, 3];
const range   = Range(3);
const result  = eq$(numbers)(range);
                                    
console.log(result);
// => Logs 'true'

foldr

Performs a reduction on the elements from right to left, using the provided start value and an accumulation function, and returns the reduced value.

Since foldr reduces the iterable from right to left, it needs O(n) memory to run the function. Therefore reduce$ is the better alternative for most cases

Returns: _T_

Parameters

Example

const numbers = [0, 1, 2, 3, 4, 5];
const result  = foldr$((cur, acc) => cur + acc, 0)(numbers);
                                                            
console.log(result);
// => Logs '15'

forEach$

Executes the callback for each element.

Returns: void

Parameters

Example

const container = [];
forEach$(cur => container.push(cur))([0, 1, 2, 3, 4];);
                                              
console.log(...container);
// => Logs '0, 1, 2, 3, 4'

head

Return the next value without consuming it. undefined when there is no value.

Returns: _T_

Parameters

Example

const numbers = [1, 2, 3, 4];
const result  = head(numbers);
                              
console.log(result);
// => Logs '1'

isEmpty

Returns true, if the iterables head is undefined.

Returns: Boolean

Parameters

Example

const empty     = []
const result = isEmpty(empty);
                              
console.log(result);
// Logs 'true'

max$

Returns the largest element of a non-empty iterable.

Note:

To determine the largest element, a comparator function is used. This function compares two elements by default with the < (LT) operator, where on the left side is the current largest element when processing the iterable. If needed, a different comparator can also be passed as a second argument to max$ and will then be used to determine the largest element.

Returns: _T_

throws: Error, if the given Iterable is empty

Parameters

Example

const numbers = [1, 3, 0, 5];
const maximum = max$(numbers);
                              
console.log(maximum);
// => Logs '5'

safeMax$

Returns the largest element of an iterable.

See the note to max$.

Returns: MaybeType<_T_>

Parameters

Example

const numbers = [1, 3, 0, 5];
const maybeMax = safeMax$(numbers);
                                                 
maybeMax
 (_ => console.log("iterable was empty, no max!")
 (x => console.log(x));
// => Logs '5'

min$

Returns the smallest element of a non-empty iterable

See the Note to max$.

throws: Error, if the given Iterable is empty

Returns: MaybeType<_T_>

Parameters

Example

const numbers = [1, 3, 0, 5];
const minimum = min$(numbers);
                              
console.log(minimum);
// => Logs '0'

safeMin$

Returns the smallest element of an iterable.

See the Note to max$.

Returns: MaybeType<_T_>

Parameters

Example

const numbers  = [0, 1, 2, 3];
const maybeMin = safeMin$(numbers);
                                                 
maybeMin
 (_ => console.log("iterable was empty, no min!")
 (x => console.log(x));
// => Logs '0'

reduce$ / foldl$

Performs a reduction on the elements, using the provided start value and an accumulation function, and returns the reduced value.

Note: foldl$ is an alias for reduce$

Returns: _T_

Parameters

Example

const number = [0, 1, 2, 3, 4, 5];
const res = foldl$((acc, cur) => acc + cur, 0)(numbers);
                                                        
console.log(res);
// => Logs '15'

show

Transforms the passed iterable into a String.

Returns: String

Parameters

Example

const numbers = [0, 1, 2, 3, 4, 5];
const text    = show(numbers, 3);
                                   
console.log(text);
// => Logs '[0,1,2]'

uncons

Removes the first element of this iterable.

Returns: Pair<_T_, SequenceType<_T_> the head and the tail as a pair

Parameters

Example

const numbers       = [0, 1, 2, 3, 4];
const [head, tail]  = uncons(numbers);
                                             
console.log("head:", head, "tail:", ...tail);
// => Logs 'head: 0 tail: 1 2 3 4'

The Prototype of the Sequence

Some functions are also available via the prototype of the sequence.

and

This is the same as bind.

Applies the given function to each element of the sequence and flattens it afterward. Note: This operation adds a monadic API to the SequenceType.

Returns: SequenceType<_U_>

Parameters

Example

const numbers = Range(3);
const bindFn  = el => take(el)(repeat(el));
const result  = numbers.and(bindFn);
                                           
console.log(...result);
// => Logs '1, 2, 2, 3, 3, 3'

fmap

This is the same as map.

Transforms each element using the given function.

Returns: SequenceType<_U_>

Parameters

Example

const numbers = Range(2);
const mapped  = numbers.fmap(el => el * 2);
                                           
console.log(...numbers);
// => Logs '0, 2, 4'

empty

This is the same as nil.

This functions returns a sequence containing no values.

Returns: SequenceType<*>

Example

const emptySequence = Range(3).empty();
                              
console.log(...emptySequence);
// => Logs '' (nothing)

pure

This is the same as PureSequence.

Creates a sequence which contains just the given value.

Returns: SequenceType<_T_>

Parameters

Example

const seq = Range(3).pure(1);
                            
console.log(...seq);
// => Logs '1'

toString

This is the same as show.

Transforms this sequence into a String.

Returns: String

Parameters

Example

const numbers = Range(6);
const text    = range.toString(3);
                                   
console.log(text);
// => Logs '[0,1,2]'

pipe

This is the same as pipe.

Transforms this sequence using the passed operators.

Returns: SequenceType<_T_> | *

Parameters

Example

const numbers = Range(5);
const piped   = numbers.pipe(
                 retainAll(n => n % 2 === 0),
                 map(n => 2*n),
                 drop(2)
               );
                                           
console.log(...piped);
// => Logs '0, 4, 8'

==

This is the same as eq$.

Checks the equality of this iterable with the given iterable.

Note: Two iterables are considered as equal if they contain or create the exactly same values in the same order. Use ["=="] defined on the SequencePrototype to perform a comparison in a more readable form.

Returns: Boolean

Parameters

Example

const numbers = [0, 1, 2, 3];
const range   = Range(3);
const result  = range ["=="] (numbers);
                                    
console.log(result);
// => Logs 'true'