Push iteration protocol is a faster alternative to traditional JavaScript iteration protocol.
It extends Iterator interface with special method [PushIterator__symbol](accept?)
, where PushIterator__symbol
is a special symbol. This method pushes iterated elements to accept
callback, until there is no more elements,
or accept
function returns true
(to suspend iteration) or false
(to stop it).
The method returns a push iterator instance to continue iteration with. If accept
returned false
then further
iteration won't be possible with returned iterator.
When called without accept
parameter it just returns an iterator.
Another method it extends Iterator with is isOver()
, that checks whether iteration is over.
It is quite common to just iterate over Iterable instantly rather constructing its Iterator. The library supports
this. For that, a [PushIterator__symbol]
method may be defined for Iterable in addition to [Symbol.iterator]
one.
When the library function encounters such method, it calls it to iterate over elements instead of constructing a new
iterator.
The [PushIterator__symbol](accept?, mode?)
method of PushIterable
interface accepts optional iteration mode hint
as second parameter. The latter used to optimize iteration algorithm. Such hints provided by iterable consumption
methods.
For example, an itsEach function sets this hint to PushIterationMode.All
to inform the iterable implementation that
all of its elements will be consumed. This allows to select the fastest iteration strategy without any intermediate
checks.
Another example is itsEvery function. It sets this hint to PushIterationMode.Only
to inform the iterable
implementation that only some of its elements will be consumed, and then iteration will be aborted. This allows to
select iteration strategy that does not support suspend and resume.
Another mode is PushIterationMode.Next
. It is typically set by Iterator.next()
compatibility method. It informs that
only the next element will be consumed, after which the iteration will be suspended.
The default mode is PushIterationMode.Some
. With this mode it is possible to suspended, resumed, or abort iteration.
Performance!
Traditional iteration protocol implies a call to next()
method and creation of IteratorResult
object on each
iteration step. The push iteration protocol avoids that.
See benchmarking results for performance comparison.
JavaScript engines optimize native iteration heavily in some situations, especially for arrays. Still, in non-trivial cases push iteration protocol demonstrates better performance, especially when it deals with push iterators rather with raw ones.
Performance.
Push iterators are faster. Still, a lot of the code base relies on raw iterators and arrays. The library contains performance optimizations to deal with it.
Compatibility.
Tree shaking support.
The library API represented by functions. When tree-shaken, the unused ones get removed from bundles.
See the full API documentation.
Each of the following functions returns a push iterable instance:
overArray(array)
- Creates a push iterable over elements of array-like structure.overElementsOf(...iterables)
- Creates a push iterable over elements of other iterables.overEntries(object)
- Creates a push iterable over the property key/value entries of the given
object.overIndexed(indexed)
- Creates a push iterable over items of indexed list.overIterable(iterable)
- Creates a push iterable over elements of the given raw iterable.overIterator(() => Iterator)
- Creates a push iterable over elements of iterator created by the
given function.overKeys(object)
- Creates a push iterable over keys of the given object.overMany(...values)
- Creates a push iterable over many values.overNone()
- Returns a push iterable iterator without elements.overOne(value)
- Creates a push iterable over one value.reverseArray(array)
- Creates a push iterable over elements of array-like structure in reverse
order.iterateIt(iterable, accept): PushIterator
function iterates over the leading elements of the given
iterable and returns its trailing iterator.
Each of the following functions accepts either Iterable or push iterable:
itsEach(iterable, action)
- Performs the given action
for each element of the given iterable
.itsElements(iterable[, convert])
- Creates a new, shallow-copied array instance containing elements
of the source iterable optionally converted by the given converter function. This is an Array.from()
function
analog optimized for push iterables.itsEmpty(iterable): boolean
- Checks whether the given iterable
is empty.itsEvery(iterable, test): boolean
- Tests whether all elements of the given iterable
pass the test
implemented by the provided function.itsFind(iterable, search): R | undefined
- Searches for the value in iterable
.itsFirst(iterable): T | undefined
- Extracts the first element of the given iterable
, if any.itsIterator(iterable)
- Starts iteration over the given iterable
. Always returns a push iterator.itsMatch(iterable, test): T | undefined
- Extracts the first element matching the given condition from
iterable
.itsReduction(iterable, reducer, initialValue): T
- Applies a function against an accumulator and
each element of the given iterable
to reduce elements to a single value.itsSome(iterable, test): boolean
- Tests whether at least one element of the given iterable
passes the
test implemented by the provided function.Each of the following functions accepts either Iterable or push iterable, and returns a push iterable:
filterIt(source, test)
- Creates a push iterable with all source
iterable elements that pass the test
implemented by provided function.flatMapIt(source, convert?)
- First maps each element of the source
iterable using a mapping
function, then flattens the result into new push iterable.mapIt(source, convert)
- Creates a push iterable with the results of calling a provided function on every
element of the source
iterable.valueIt(source, valueOf)
- Creates a push iterable with the values of elements of the source
iterable.
A more effective combination of mapIt/filterIt.Each of the following functions accepts an array-like instance, and returns a push iterable:
filterArray(array, test)
- Creates a push iterable with all array
elements that pass the test
implemented by provided function.flatMapArray(array, convert?)
- First maps each element of the source array
using a mapping
function, then flattens the result into new push iterable.mapArray(array, convert)
- Creates a push iterable with the results of calling a provided function on
every element of the given array
.valueArray(array, valueOf)
- Creates a push iterable with the values of elements of the given array
.
A more effective combination of mapArray/filterIt.An indexed list of items is an object with two properties:
length
contains the length of the list,item(index: number): T | null | undefined
returns the item value under the given index.Each of the following functions accepts an indexed list of items, and returns a push iterable:
filterIndexed(indexed, test)
- Creates a push iterable with all items of the given indexed list
that pass the test implemented by the provided function.flatMapIndexed(indexed, convert?)
- First maps each item of the source indexed list using
a mapping function, then flattens the result into new push iterable.mapIndexed(array, convert)
- Creates a push iterable with the results of calling a provided function
on every item of the given indexed list.valueIndexed(array, convert)
- Creates a push iterable with the values of items of the given indexed
list. A more effective combination of mapIndexed/filterIt.isPushIterable(iterable)
- Checks whether the given iterable or iterator conforms to push
iteration protocol.iteratorOf(iterable)
- Creates iterator over elements of the given iterable
.makePushIterable(iterate)
- Creates a push iterable implementation.makePushIterator(forNext)
- Creates a push iterator implementation.Generated using TypeDoc