A collection of utility functions for JavaScript iterables and iterators inspired by Rust's Iterator trait, Rust's slice primitive, and third-party crate Itertools. Useful for lazily evaluating sequences or streams of data.
Each utility function is accompanied by an equivalent under the exported async
object which supports async iterables.
- selfIterable
- collect
- zip
- zipLongest
- enumerate
- skip
- take
- chain
- chunks
- chunksExact
- windows
- partition
- forEach
- map
- filter
- reduce
- interleave
- interleaveShortest
- intersperse
Modifies the given object which conforms to the iterator protocol so that it is itself iterable. Required only if you need to pass an iterator to one of the below utility functions and it does not already implement the Symbol.iterator
method (or Symbol.asyncIterator
if using the async variant).
Based on the collect
method for Rust's std::iter::Iterator
, JavaScript's Array.from
, and JavaScript's Promise.all
A shorthand for Array.from
, or for the async variant a version of Promise.all
which accepts an async iterable such as a readable Node.js stream.
Based on the zip
method for Rust's std::iter::Iterator
Returns an iterator where each value is an array of each given iterable's current value. If any iterable runs out of values before the others, its value is considered to be undefined
.
collect( zip( [ "a", "b", "c" ], [ 1, 2, 3 ] ) )
// => [ [ "a", 1 ], [ "b", 2 ], [ "c", 3 ] ]
collect( zip( [ "a", "b" ], [ 1, 2, 3, 4 ] ) )
// => [ [ "a", 1 ], [ "b", 2 ] ]
Based on the zip_longest
method from Itertools
Like zip
, but continues until all iterables are exhausted. The value of an exhausted iterable is represented as undefined
.
collect( zip_longest( [ "a", "b", "c" ], [ 1, 2, 3 ] ) )
// => [ [ "a", 1 ], [ "b", 2 ], [ "c", 3 ] ]
collect( zip_longest( [ "a" ], [ 1, 2, 3 ] ) )
// => [ [ "a", 1 ], [ undefined, 2 ], [ undefined, 3 ] ]
Based on the chain
method for Rust's std::iter::Iterator
Returns an iterable which acts as a concatenation of all given iterables.
collect( chain( [ "a", "b", "c" ], [ 1, 2, 3 ] ) )
// => [ "a", "b", "c", 1, 2, 3 ]
Based on the enumerate
method for Rust's std::iter::Iterator
Returns an iterator whose values are array pairs, the first of each pair being the zero-based index of the value and the second being the current value from the iterable.
collect( enumerate( [ "foo", "bar", "baz" ], 2 ) )
// => [ [ 0, "foo" ], [ 1, "bar" ], [ 2, "baz" ] ]
Based on the skip
method for Rust's std::iter::Iterator
Returns an iterator which has dropped the first numItemsToSkip
items.
collect( skip( [ "a", "b", "c", "d" ], 2 ) )
// => [ "c", "d" ]
Based on the take
method for Rust's std::iter::Iterator
Returns an iterable that stops after the first numItemsToTake
items.
collect( take( [ "a", "b", "c", "d" ], 2 ) )
// => [ "a", "b" ]
Based on Rust's std::slice::Chunks
Returns an iterator whose values are non-overlapping partitions of the iterable, each containing at most chunkSize
items.
collect( chunks( [ 1, 2, 3, 4 ], 2 ) )
// => [ [ 1, 2 ], [ 3, 4 ] ]
collect( chunks( [ 1, 2, 3, 4 ], 3 ) )
// => [ [ 1, 2, 3 ], [ 1 ] ]
Based on Rust's std::slice::ChunksExact
Returns an iterator whose values are non-overlapping partitions of the iterable, each containing exactly chunkSize
items. Any remaining items which do not fit in a full partition are omitted (as many as chunkSize - 1
items).
collect( chunksExact( [ 1, 2, 3, 4 ], 2 ) )
// => [ [ 1, 2 ], [ 3, 4 ] ]
collect( chunksExact( [ 1, 2, 3, 4 ], 3 ) )
// => [ [ 1, 2, 3 ] ]
Based on Rust's std::slice::Windows
Returns an iterator whose values are overlapping partitions of the iterable, each containing exactly chunkSize
items.
collect( windows( [ 1, 2, 3, 4 ], 2 ) )
// => [ [ 1, 2 ], [ 2, 3 ], [ 3, 4 ] ]
collect( windows( [ 1, 2, 3, 4 ], 3 ) )
// => [ [ 1, 2, 3 ], [ 2, 3, 4 ] ]
Based on the partition
method for Rust's std::iter::Iterator
Returns two iterators: one containing the values for which partitioner
returned true
and one for all other values.
const [ evens, odds ] = partition( [ 1, 2, 3, 4, 5 ], value => ( value % 2 ) == 0 )
collect( evens )
// => [ 2, 4 ]
collect( odds )
// => [ 1, 3, 5 ]
Based on the interleave
method from Itertools
Returns alternating values from the given iterables in the order they are given until reaching the end of all given iterables.
collect( interleave( [ "a", "b", "c" ], [ 1, 2, 3 ] ) )
// => [ "a", 1, "b", 2, "c", 3 ]
collect( interleave( [ "a", "b" ], [ 1, 2, 3, 4 ] ) )
// => [ "a", 1, "b", 2, 3, 4 ]
Based on the interleaveShortest
method from Itertools
Like interleave
, but stops after the first exhausted iterable.
collect( interleaveShortest( [ "a", "b", "c" ], [ 1, 2, 3 ] ) )
// => [ "a", 1, "b", 2, "c", 3 ]
collect( interleaveShortest( [ "a", "b" ], [ 1, 2, 3, 4 ] ) )
// => [ "a", 1, "b", 2 ]
Based on the intersperse
method from Itertools
Returns an iterator containing all values from the given iterable, inserting separator
between each value.
collect( intersperse( [ 1, 2, 3 ], "a" ) )
// => [ 1, "a", 2, "a", 3 ]
collect( intersperse( [ 1 ], "a" ) )
// => [ 1 ]
Based on JavaScript's Array.prototype.forEach
A version of Array.prototype.forEach
which can be applied to any iterable.
Based on JavaScript's Array.prototype.map
A version of Array.prototype.map
which can be applied to any iterable. Returns an iterable containing the mapped values.
Based on JavaScript's Array.prototype.filter
A lazy version of Array.prototype.filter
which can be applied to any iterable. Returns an iterable containing only the values which passed the filter callback.
Based on JavaScript's Array.prototype.reduce
A version of Array.prototype.reduce
which can be applied to any iterable. Returns the result of the reduction.