es-iterator-helpers

es-iterator-helpers

An ESnext spec-compliant sync iterator helpers shim/polyfill/replacement that works as far down as ES3.

This package implements the es-shim API “multi” interface. It works in an ES3-supported environment and complies with the iterator helpers spec and the iterator sequencing spec.

Because the Iterator.prototype methods depend on a receiver (the this value), the main export in each subdirectory takes the iterator to operate on as the first argument.

The main export of the package itself is simply an array of the available directory names. It’s sole intended use is for build tooling and testing.

Supported things

• Iterator constructor
• Iterator.prototype
• Iterator.concat
• Iterator.from
• Iterator.zip
• Iterator.zipKeyed
• Iterator.prototype.constructor
• Iterator.prototype.drop
• Iterator.prototype.every
• Iterator.prototype.filter
• Iterator.prototype.find
• Iterator.prototype.flatMap
• Iterator.prototype.forEach
• Iterator.prototype.map
• Iterator.prototype.reduce
• Iterator.prototype.some
• Iterator.prototype.take
• Iterator.prototype.toArray

Environments where this is needed

• node v22, Chrome >= v122: has a bug
• node < v22, Chrome < v122, Safari <= v17.1, Firefox <= v125: not implemented
• all environments lack Iterator.concat, Iterator.zip, Iterator.zipKeyed

Getting started

npm install --save es-iterator-helpers

Usage/Examples

Using explicit imports:

const map = require('es-iterator-helpers/Iterator.prototype.map');
const toArray = require('es-iterator-helpers/Iterator.prototype.toArray');
const assert = require('assert');

const iterator = [1, 2, 3].values();

const mapped = map(iterator, (x) => x + 10);
assert.deepEqual(
	mapped.next(),
    {
        done: false,
        value: 11,
    }
);
assert.deepEqual(
    toArray(mapped),
    [12, 13]
);

Shim using require:

require('es-iterator-helpers/auto'); // shim all of the methods

require('es-iterator-helpers/Iterator.prototype.map/auto'); // shim the “map” method

Shim using import syntax:

import 'es-iterator-helpers/auto'; // shim all of the methods

import 'es-iterator-helpers/Iterator.prototype.map/auto'; // shim the “map” method

Tests

Simply clone the repo, npm install, and run npm test

Changelog

v1.2.1 - 2024-12-20

Commits

• [Tests] Iterator.concat: add most of the tests from https://github.com/tc39/test262/pull/4326 2e340da
• [Fix] Iterator.concat: rewrite implementation to match updated spec text 1a70fd3
• [Fix] IteratorZip AO: allow an empty list of iterators 265e566
• [actions] split out node 10-20, and 20+ 3cc9db0
• [Fix] IteratorHelperPrototype: in pre-proto envs, use same .return impl da02ab6
• [Deps] update call-bind, es-abstract, get-intrinsic, gopd, has-proto, internal-slot, iterator.prototype, safe-array-concat e9eefab
• [Tests] Iterator.zip: nullish non-function Symbol.iterator does not throw c6b0705
• [Refactor] use call-bound directly 92afc5a
• [Deps] update gopd, has-proto, has-symbols 7f8a1c0
• [readme] add missing info for Iterator.zip, Iterator.zipKeyed dd80b2f
• [Dev Deps] update @es-shims/api 1e9857c
• [Deps] update es-abstract c8157da
• [Deps] update es-abstract 256de0e
• [Dev Deps] update object-inspect 2f8544b