Iteration protocols

A couple of additions to ECMAScript 2015 aren't new built-ins or syntax, but protocols. These protocols can be implemented by any object respecting some conventions.

There are two protocols: The iterable protocol and the iterator protocol.

The iterable protocol

The iterable protocol allows JavaScript objects to define or customize their iteration behavior, such as what values are looped over in a for...of construct. Some built-in types are built-in iterables with a default iteration behavior, such as Array or Map, while other types (such as Object) are not.

In order to be iterable, an object must implement the @@iterator method, meaning that the object (or one of the objects up its prototype chain) must have a property with a @@iterator key which is available via constant Symbol.iterator:

Whenever an object needs to be iterated (such as at the beginning of a for...of loop), its @@iterator method is called with no arguments, and the returned iterator is used to obtain the values to be iterated.

Note that when this zero-argument function is called, it is invoked as a method on the iterable object. Therefore inside of the function, the this keyword can be used to access the properties of the iterable object, to decide what to provide during the iteration.

This function can be an ordinary function, or it can be a generator function, so that when invoked, an iterator object is returned. Inside of this generator function, each entry can be provided by using yield.

The iterator protocol

The iterator protocol defines a standard way to produce a sequence of values (either finite or infinite), and potentially a return value when all values have been generated.

An object is an iterator when it implements a next() method with the following semantics:

// Satisfies both the Iterator Protocol and Iterable
let myIterator = {
    next: function() {
        // ...
    },
    [Symbol.iterator]: function() { return this }
}

Examples using the iteration protocols

A String is an example of a built-in iterable object:

let someString = 'hi'
typeof someString[Symbol.iterator]          // "function"

String's default iterator returns the string's code points one by one:

let iterator = someString[Symbol.iterator]()
iterator + ''                               // "[object String Iterator]"
 
iterator.next()                             // { value: "h", done: false }
iterator.next()                             // { value: "i", done: false }
iterator.next()                             // { value: undefined, done: true }

Some built-in constructs, such as the spread syntax, use the same iteration protocol under the hood:

[...someString]                              // ["h", "i"]

We can redefine the iteration behavior by supplying our own @@iterator:

let someString = new String('hi')            // need to construct a String object explicitly to avoid auto-boxing

someString[Symbol.iterator] = function() {
  return { 
    // this is the iterator object, returning a single element (the string "bye")
    next: function() {
      if (this._first) {
        this._first = false 
        return { value: 'bye', done: false }
      } else {
        return { done: true }
      }
    },
    _first: true
  }
}

Notice how redefining @@iterator affects the behavior of built-in constructs that use the iteration protocol:

[...someString]                              // ["bye"]
someString + ''                              // "hi"

Iterable examples

Built-in iterables

String, Array, TypedArray, Map and Set are all built-in iterables, because each of their prototype objects implements an @@iterator method.

User-defined iterables

You can make your own iterables like this:

let myIterable = {}
myIterable[Symbol.iterator] = function* () {
    yield 1 
    yield 2 
    yield 3 
};
[...myIterable]  // [1, 2, 3]

Built-in APIs accepting iterables

There are many APIs that accept iterables. Some examples include:

• Map([iterable])
• WeakMap([iterable])
• Set([iterable])
• WeakSet([iterable])

let myObj = {}
new Map([[1, 'a'], [2, 'b'], [3, 'c']]).get(2)                // "b"
new WeakMap([[{}, 'a'], [myObj, 'b'], [{}, 'c']]).get(myObj)  // "b"
new Set([1, 2, 3]).has(3)                                // true
new Set('123').has('2')                                  // true
new WeakSet(function* () {
    yield {} 
    yield myObj 
    yield {} 
}()).has(myObj)                                          // true

See Also

• Promise.all(iterable)
• Promise.race(iterable)
• Array.from(iterable)

Syntaxes expecting iterables

Some statements and expressions expect iterables, for example the for...of loops, the spread operator, yield*, and destructuring assignment:

for(let value of ['a', 'b', 'c']) {
    console.log(value)
}
// "a"
// "b"
// "c"

[...'abc']  // ["a", "b", "c"]

function* gen() {
  yield* ['a', 'b', 'c'] 
}

gen().next()  // { value:"a", done:false }

[a, b, c] = new Set(['a', 'b', 'c']) 
a // "a"

Non-well-formed iterables

If an iterable's @@iterator method doesn't return an iterator object, then it's considered a non-well-formed iterable. 

Using one is likely to result in runtime exceptions or buggy behavior:

let nonWellFormedIterable = {}
nonWellFormedIterable[Symbol.iterator] = () => 1
[...nonWellFormedIterable] // TypeError: [] is not a function

Iterator examples

Simple iterator

function makeIterator(array) {
    let nextIndex = 0
    
    return {
       next: function() {
           return nextIndex < array.length ?
               {value: array[nextIndex++], done: false} :
               {done: true};
       }
    }
}

let it = makeIterator(['yo', 'ya']) 

console.log(it.next().value)  // 'yo'
console.log(it.next().value)  // 'ya'
console.log(it.next().done)   // true

Infinite iterator

function idMaker() {
    let index = 0
    
    return {
       next: function(){
           return {value: index++, done: false}
       }
    }
}

let it = idMaker()

console.log(it.next().value)  // '0'
console.log(it.next().value)  // '1'
console.log(it.next().value)  // '2'
// ...

With a generator

function* makeSimpleGenerator(array) {
    let nextIndex = 0
    
    while (nextIndex < array.length) {
        yield array[nextIndex++]
    }
}

let gen = makeSimpleGenerator(['yo', 'ya'])

console.log(gen.next().value)  // 'yo'
console.log(gen.next().value)  // 'ya'
console.log(gen.next().done)   // true



function* idMaker() {
    let index = 0
    while (true) {
        yield index++
    }
}

let gen = idMaker()

console.log(gen.next().value)  // '0'
console.log(gen.next().value)  // '1'
console.log(gen.next().value)  // '2'
// ...

With ES2015 class

class SimpleClass {
  constructor(data) {
    this.index = 0 
    this.data = data
  }

  [Symbol.iterator]() {
    return {
      next: () => {
        if (this.index < this.data.length) {
          return {value: this.data[this.index++], done: false}
        } else {
          this.index = 0  // If you want to iterate over this again without forcing manual update of the index
          return {done: true}
        }
      }
    }
  }
}

const simple = new SimpleClass([1,2,3,4,5])

for (const val of simple) {
  console.log(val)   //'1' '2' '3' '4' '5' 
}

Is a generator object an iterator or an iterable?

A generator object is both iterator and iterable:

let aGeneratorObject = function* () {
    yield 1 
    yield 2 
    yield 3 
}()

typeof aGeneratorObject.next
// "function", because it has a next method, so it's an iterator

typeof aGeneratorObject[Symbol.iterator]
// "function", because it has an @@iterator method, so it's an iterable

aGeneratorObject[Symbol.iterator]() === aGeneratorObject
// true, because its @@iterator method returns itself (an iterator), so it's an well-formed iterable

[...aGeneratorObject]
// [1, 2, 3]

Specifications

See also

• For more information on ES2015 generators, see the function* documentation.