JavaScript Iterator : Iterable

An Iterator is an Object that returns a sequence of values. Since Iterators are Iterables, you can use for (var value of iterator) {} to easily loop over the values in an iterator. Calling an ECMAScript 2015 generator function (function*() {}) returns an Iterator. You may create your own Iterable object by assigning the Symbol.iterator property to an object with a next() method.

ECMAScript 2015 Spec

Instance Indexers

this[Symbol.iterator] : Function<Iterator>

Returns a method that returns this.

Example:

// Arrays are a built in Iterable object
var iterable = ['a', 'b', 'c'];

var iterator = iterable[Symbol.iterator]();
var iteratorIterator = iterator[Symbol.iterator]();

console.log(iterator === iteratorIterator);
console.log();

for (var x of iterable) {
  console.log(x);
}
console.log();

// Since Iterators are also Iterables, you can use for-of loops with them.
for (var x of iterator) {
  console.log(x);
}

Run

Results:

Instance Methods

next([yieldValue : Object]) : Object

return : {

value	Object
done	Boolean

}

Returns an object containing the next value in the iterator. If all items have been returned, done will be true. For generator functions, yieldValue is returned to the generator from the yield statement.

Example:

// Generator functions create iterators when called
var generator = function*() {
  yield 'foo';
  var yieldValue = yield 'bar';
  console.log('generator yieldValue = ' + yieldValue);
  console.log();
};

// Usually you will iterate over it using for (... of ...)
// which will call next() for you automatically
for (var item of generator()) {
  console.log(item);
}

// You can also get the iterator and manually call next()
var iterator = generator();

console.dir(iterator.next());
console.dir(iterator.next());
console.dir(iterator.next('passed to next'));

// You can create iterable objects manually
var myIterable = { };
myIterable[Symbol.iterator] = function() {
  var count = 0;
  return { 
    next: function() {
      if (count >= 2) return { value: undefined, done: true };
      count++;
      return { value: 'my item' + count, done: false };
    }
  }
};

// Using for (... of ...) calls the next() defined above
for (var item of myIterable) {
  console.log(item);
}

// You can also call it manually
iterator = myIterable[Symbol.iterator]();

console.dir(iterator.next());
console.dir(iterator.next());
console.dir(iterator.next());

Run

Results:

home license contribute feedback