es-get-iterator

What is es-get-iterator?

The es-get-iterator package is a utility for retrieving an iterator from a given object, array, string, or other iterable types in JavaScript. It abstracts away the differences between various iterable protocols and provides a unified way to iterate over values in different types of collections.

What are es-get-iterator's main functionalities?

Getting an iterator from an array

This feature demonstrates how to retrieve an iterator from an array and use it to access the first element.

const getIterator = require('es-get-iterator');
const array = [1, 2, 3];
const iterator = getIterator(array);
console.log(iterator.next().value); // 1

Getting an iterator from a string

This feature shows how to get an iterator from a string to iterate over its characters.

const getIterator = require('es-get-iterator');
const string = 'hello';
const iterator = getIterator(string);
console.log(iterator.next().value); // 'h'

Getting an iterator from a Map

This example demonstrates retrieving an iterator from a Map object to iterate over its key-value pairs.

const getIterator = require('es-get-iterator');
const map = new Map([[1, 'one'], [2, 'two']]);
const iterator = getIterator(map);
console.log(iterator.next().value); // [1, 'one']

Other packages similar to es-get-iterator

iterall

Iterall is a package that provides utilities for working with JavaScript iteration protocols. It offers similar functionality to es-get-iterator by allowing users to work with iterable objects in a consistent manner. However, iterall focuses more on providing a set of utilities for managing iterables rather than just retrieving iterators.

lodash

Lodash is a comprehensive utility library that, among its vast array of functionalities, includes methods for iterating over collections such as arrays, objects, and strings. While not exclusively focused on iteration like es-get-iterator, lodash offers more general-purpose utilities that can be used in conjunction with or as an alternative to es-get-iterator for certain use cases.

README

es-get-iterator

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

Changelog

v1.1.3 - 2023-01-12

Commits

• [actions] reuse common workflows c97cb76
• [actions] use node/install instead of node/run; use codecov action 6d09911
• [meta] use npmignore to autogenerate an npmignore file c7e0e85
• [Dev Deps] update eslint, @ljharb/eslint-config, aud, auto-changelog, es5-shim, object-inspect, tape 1353190
• [Refactor] extract logic to stop-iteration-iterator ab19956
• [Dev Deps] update eslint, @ljharb/eslint-config, aud, auto-changelog, es5-shim, object-inspect, safe-publish-latest, tape de2ae73
• [Tests] start testing more variants e059f33
• [actions] update codecov uploader c8ffcec
• [Dev Deps] update eslint, @ljharb/eslint-config, aud, es5-shim, has-bigints, object-inspect, tape 8cd2e87
• [Dev Deps] update eslint, @ljharb/eslint-config, aud, object-inspect, tape 7676030
• [actions] update checkout action bdbe6c9
• [Dev Deps] update @ljharb/eslint-config, aud, es6-shim 67cddd6
• [Tests] fix debug output issues in FF 24 a726fdc
• [Deps] update has-symbols, is-arguments, is-string 044907b
• [Deps] update get-intrinsic, has-symbols e492f8f
• [meta] use prepublishOnly script for npm 7+ eccda6b
• [Dev Deps] update object-inspect c24dfa5
• [Deps] update get-intrinsic 1bd68ce