npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@proc7ts/push-iterator

v3.1.2

Published

Push iteration protocol

Downloads

950

Readme

Push Iteration Protocol

NPM Build Status Code Quality Coverage GitHub Project API Documentation

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.

Instant Iteration

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.

Iteration Mode Hints

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.

Rationale

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.

Design Goals

  1. 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.

  2. Compatibility.

    • Push iterator implements Iterator interface.
    • Each function in this library handles JavaScript Iterator/Iterable objects in addition to push iterator/push iterable ones.
  3. Tree shaking support.

    The library API represented by functions. When tree-shaken, the unused ones get removed from bundles.

API

See the full API documentation.

Push Iterable Construction

Each of the following functions returns a push iterable instance:

Iteration

iterateIt(iterable, accept): PushIterator function iterates over the leading elements of the given iterable and returns its trailing iterator.

Iterable Consumption

Each of the following functions accepts either Iterable or push iterable:

Iterable Transformation

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.

Array Transformation

Each of the following functions accepts an array-like instance, and returns a push iterable:

Indexed List Transformation

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:

Utilities