Skip to content
Get an iterator for any JS language value. Works robustly across all environments, all versions.
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github [meta] add `funding` field; create FUNDING.yml Nov 25, 2019
test [Tests] add string coverage for a lone surrogate not followed by a pr… Jan 11, 2020
.eslintignore
.eslintrc Initial implementation Nov 23, 2019
.gitignore Only apps should have lockfiles Nov 22, 2019
.npmrc [meta] add `auto-changelog` Nov 25, 2019
.nycrc Initial tests. Nov 23, 2019
.travis.011.yml [Fix] fix bugs in pre-Symbol environments Nov 27, 2019
.travis.yml [Fix] fix bugs in pre-Symbol environments Nov 27, 2019
CHANGELOG.md v1.0.2 Dec 16, 2019
LICENSE Initial commit Nov 22, 2019
README.md [Docs] Add modern browser example for Rollup Dec 16, 2019
index.js [Fix] fix bugs in pre-Symbol environments Nov 27, 2019
node.js [Fix] fix bugs in pre-Symbol environments Nov 27, 2019
package.json [Deps] update `is-map`, `is-set`, `es-abstract`, `is-string` Jan 11, 2020

README.md

es-get-iterator Version Badge

Build Status dependency status dev dependency status License Downloads

npm badge

Get an iterator for any JS language value. Works robustly across all environments, all versions.

In modern engines, value[Symbol.iterator]() is sufficient to produce an iterator (an object with a .next method) for that object. However, older engines:

  • may lack Symbol support altogether
  • may have Symbol.iterator but not implement it on everything it should, like arguments objects
  • may have Map and Set, but a non-standard name for the iterator-producing method (.iterator or ['@@iterator'], eg)
  • may be old versions of Firefox that produce values until they throw a StopIteration exception, rather than having iteration result objects
  • may be polyfilled/shimmed/shammed, with es6-shim or core-js or similar

This library attempts to provide an abstraction over all that complexity!

In node v13+, exports is used to provide a lean implementation that lacks all the complexity described above, in combination with the browser field so that bundlers will pick up the proper implementation.

Targeting browsers with Symbol support

If you are targeting browsers that definitely all have Symbol support, then you can configure your bundler to replace require('has-symbols')() with a literal true, which should allow dead code elimination to reduce the size of the bundled code.

With @rollup/plugin-replace

// rollup.config.js

import replace from '@rollup/plugin-replace';

export default {
	...
	plugins: [
		replace({
			"require('has-symbols')()": 'true',
			delimiters: ['', '']
		})
	]
};

Example

var getIterator = require('es-get-iterator');
var assert = require('assert');

var iterator = getIterator('a 💩');
assert.deepEqual(
	[iterator.next(), iterator.next(), iterator.next(), iterator.next()],
	[{ done: false, value: 'a' }, { done: false, value: ' ' }, { done: false, value: '💩' }, { done: true, value: undefined }]
);

var iterator = getIterator([1, 2]);
assert.deepEqual(
	[iterator.next(), iterator.next(), iterator.next()],
	[{ done: false, value: 1 }, { done: false, value: 2 }, { done: true, value: undefined }]
);

var iterator = getIterator(new Set([1, 2]));
assert.deepEqual(
	[iterator.next(), iterator.next(), iterator.next()],
	[{ done: false, value: 1 }, { done: false, value: 2 }, { done: true, value: undefined }]
);

var iterator = getIterator(new Map([[1, 2], [3, 4]]));
assert.deepEqual(
	[iterator.next(), iterator.next(), iterator.next()],
	[{ done: false, value: [1, 2] }, { done: false, value: [3, 4] }, { done: true, value: undefined }]
);

Tests

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

You can’t perform that action at this time.