es6-iterator

What is es6-iterator?

The es6-iterator package provides an implementation of the ECMAScript 6 (ES6) iteration protocols. It includes the iterator interface, which allows JavaScript objects to define or customize their iteration behavior. This package is useful for creating custom iterable objects and for using iterators in environments that do not fully support ES6 features.

What are es6-iterator's main functionalities?

Creating custom iterators

This code sample demonstrates how to create a simple iterator that produces a sequence of numbers from 0 to 4. The iterator has a 'next' method that conforms to the iterator protocol.

{"next": function() { return this._current < this._end ? {value: this._current++, done: false} : {done: true}; }, "_current": 0, "_end": 5}

Using for-of loops with custom iterators

This code sample shows how to use a for-of loop with a custom iterator created by the es6-iterator package. The 'createIterator' function would return an iterator over the array [1, 2, 3], and the for-of loop would log each value to the console.

var it = createIterator([1, 2, 3]); for (var value of it) { console.log(value); }

Implementing iterable protocol

This code sample illustrates how to implement the iterable protocol by adding a '[Symbol.iterator]' method that returns the object itself, which must also have a 'next' method to be a valid iterator.

{"[Symbol.iterator]": function() { return this; }, "next": function() { /* ... */ }}

Other packages similar to es6-iterator

iterall

Iterall is a minimal zero-dependency utility for using JavaScript's iteration protocols. It provides functions to check if an object is an iterator or iterable and to convert an iterable into an iterator. It is similar to es6-iterator but focuses more on utility functions for handling existing iterators and iterables.

core-js

Core-js is a modular standard library for JavaScript, which includes polyfills for ECMAScript features. It provides robust implementations of ES6 features, including iterators and iterables. While es6-iterator focuses solely on iterators, core-js offers a wide range of polyfills and is more comprehensive.

README

es6-iterator

ECMAScript 6 Iterator interface

Installation

$ npm install es6-iterator

To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: Browserify, Webmake or Webpack

API

Constructors

Iterator(list) (es6-iterator)

Abstract Iterator interface. Meant for extensions and not to be used on its own.

Accepts any list object (technically object with numeric length property).

Mind it doesn't iterate strings properly, for that use dedicated StringIterator

var Iterator = require('es6-iterator')
var iterator = new Iterator([1, 2, 3]);

iterator.next(); // { value: 1, done: false }
iterator.next(); // { value: 2, done: false }
iterator.next(); // { value: 3, done: false }
iterator.next(); // { value: undefined, done: true }

ArrayIterator(arrayLike[, kind]) (es6-iterator/array)

Dedicated for arrays and array-likes. Supports three iteration kinds:

• value (default) - Iterates values
• key - Iterates indexes
• key+value - Iterates keys and indexes, each iteration value is in [key, value] form.

var ArrayIterator = require('es6-iterator/array')
var iterator = new ArrayIterator([1, 2, 3], 'key+value');

iterator.next(); // { value: [0, 1], done: false }
iterator.next(); // { value: [1, 2], done: false }
iterator.next(); // { value: [2, 3], done: false }
iterator.next(); // { value: undefined, done: true }

May also be used for arguments objects:

(function () {
  var iterator = new ArrayIterator(arguments);

  iterator.next(); // { value: 1, done: false }
  iterator.next(); // { value: 2, done: false }
  iterator.next(); // { value: 3, done: false }
  iterator.next(); // { value: undefined, done: true }
}(1, 2, 3));

StringIterator(str) (es6-iterator/string)

Assures proper iteration over unicode symbols.
See: http://mathiasbynens.be/notes/javascript-unicode

var StringIterator = require('es6-iterator/string');
var iterator = new StringIterator('f🙈o🙉o🙊');

iterator.next(); // { value: 'f', done: false }
iterator.next(); // { value: '🙈', done: false }
iterator.next(); // { value: 'o', done: false }
iterator.next(); // { value: '🙉', done: false }
iterator.next(); // { value: 'o', done: false }
iterator.next(); // { value: '🙊', done: false }
iterator.next(); // { value: undefined, done: true }

Function utilities

forOf(iterable, callback[, thisArg]) (es6-iterator/for-of)

Polyfill for ECMAScript 6 for...of statement.

var forOf = require('es6-iterator/for-of');
var result = [];

forOf('🙈🙉🙊', function (monkey) { result.push(monkey); });
console.log(result); // ['🙈', '🙉', '🙊'];

Optionally you can break iteration at any point:

var result = [];

forOf([1,2,3,4]', function (val, doBreak) {
  result.push(monkey);
  if (val >= 3) doBreak();
});
console.log(result); // [1, 2, 3];

get(obj) (es6-iterator/get)

Return iterator for any iterable object.

var getIterator = require('es6-iterator/get');
var iterator = get([1,2,3]);

iterator.next(); // { value: 1, done: false }
iterator.next(); // { value: 2, done: false }
iterator.next(); // { value: 3, done: false }
iterator.next(); // { value: undefined, done: true }

isIterable(obj) (es6-iterator/is-iterable)

Whether obj is iterable

var isIterable = require('es6-iterator/is-iterable');

isIterable(null); // false
isIterable(true); // false
isIterable('str'); // true
isIterable(['a', 'r', 'r']); // true
isIterable(new ArrayIterator([])); // true

validIterable(obj) (es6-iterator/valid-iterable)

If obj is an iterable it is returned. Otherwise TypeError is thrown.

Method extensions

iterator.chain(iterator1[, …iteratorn]) (es6-iterator/#/chain)

Chain multiple iterators into one.

Tests

$ npm test

Changelog

2.0.3 (2017-10-17)

Bug Fixes

• configurability of toStringTag (b99f692)

<a name="2.0.2"></a>