Iteration protocols

O protocolo iterável (iterable protocol)

O protocolo iterável permite que objetos JavaScript definam ou personalizem seu comportamento de iteração, como valores em um loop do construtor for..of. Alguns tipos built-in são built-in iterables com um comportamento de iteração padrão, tal como Array ou Map, enquanto outros tipos (como Object) não são assim.

Para ser iterável, um objeto deve implementar o método @@iterator, o que significa que o objeto (ou um dos objetos acima de sua cadeia de protótipos) deve ter uma propriedade com uma chave @@iterator que está disponível via constante Symbol.iterator:

Sempre que um objeto precisa ser iterado (como no início de um loop for..of), o método @@iterator é chamado sem argumentos e o retorno do iterador é usado para obter os valores a serem iterados.

O protocolo iterador (iterator protocol)

O protocolo iterador define uma maneira padrão de produzir uma sequência de valores (finito ou infinito).

Um objeto é um iterador quando implementa um método next() com a semântica adiante:

var myIterator = {
  next: function () {
    // ...
  },
  [Symbol.iterator]: function () {
    return this;
  },
};

Exemplos de uso do protocolo de iteração

Uma String é um exemplo de um objeto iterable built-in:

var someString = "hi";
typeof someString[Symbol.iterator]; // "function"

O iterador padrão de uma string retorna as posições dos caracteres de uma string um por um:

var 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 }

Alguns construtores built-in, como spread syntax, usam o mesmo protocolo de iteração interiormente:

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

Podemos redefinir o comportamento de iteração fornecendo nosso próprio @@iterator:

var 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
  };
};

Observe como redefinir @@iterator afeta o comportamento built-in que faz uso do protocolo de iteração:

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

Exemplos de Iteráveis

Iteráveis Built-in

String, Array, TypedArray, Map and Set são todos iteráveis internos, porque cada um dos seus objetos protótipos implementa um método @@iterator.

Iteráveis definidos pelo usuário

Nós podemos fazer nossos próprios iterables assim:

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

Built-in APIs que aceitam iteráveis

Existem muitas APIs que aceitam iteráveis, por exemplo: Map([iterable]), WeakMap([iterable]), Set([iterable]) e WeakSet([iterable]):

var 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

Veja também Promise.all(iterable), Promise.race(iterable) e Array.from().

Sintaxe que espera iteráveis

Some statements and expressions expect iterables, for example the for-of loops, 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"

Iteráveis não bem formados

If an iterable's @@iterator method doesn't return an iterator object, then it's a non-well-formed iterable. Using it as such is likely to result in runtime exceptions or buggy behavior:

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

Iterator examples

Simple iterator

function makeIterator(array) {
    var nextIndex = 0;

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

var 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() {
    var index = 0;

    return {
       next: function(){
           return {value: index++, done: false};
       }
    };
}

var it = idMaker();

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

Com um gerador

function* makeSimpleGenerator(array) {
    var nextIndex = 0;

    while (nextIndex < array.length) {
        yield array[nextIndex++];
    }
}

var gen = makeSimpleGenerator(['yo', 'ya']);

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



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

var gen = idMaker();

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

Com uma classe ES2015

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 we would like 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);  //'0' '1' '2' '3' '4' '5'
}

Um objeto gerador um iterador ou iterável?

Um objeto gerador é tanto iterador quanto iterável:

var 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]

Especificações

Veja também

• Para mais informações sobre generators ES2015, consulte a documentação de function*.