CKTIS / JavaScript
Symbol.iterator — o protocolo de iteração síncrona
Symbol.iterator é o símbolo conhecido que identifica um método que cria um iterador. Permite que um objeto personalizado funcione com for...of e com a sintaxe spread de arrays. Um iterável fornece um iterador, que por sua vez fornece resultados sucessivos através de next().
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
iterable[Symbol.iterator]()
({ [Symbol.iterator]() { return iterator; } })Symbol.iterator é um símbolo conhecido, não uma função. É a chave do método [Symbol.iterator]() de um objeto iterável (iterable). Este método devolve um iterador utilizado, entre outros, por for...of e pela sintaxe spread de arrays ([...iterable]). A chave de cadeia "Symbol.iterator" não é a mesma chave.
Um iterável fornece este método, enquanto um iterador tem um método next(). Cada chamada a next() tem de devolver um objeto de resultado: done indica se a iteração terminou e value contém o elemento atual enquanto a iteração prossegue. Quando done: true, consumidores como for...of não processam value como um elemento. Ter apenas next() não torna um objeto iterável.
No exemplo, cada chamada a [Symbol.iterator]() cria um contador separado. Por isso, ambas as operações spread produzem 1,2,3. Um iterador não tem de ser, ele próprio, iterável; para o tornar iterável, pode fornecer [Symbol.iterator]() e devolver this. Devolver o mesmo iterador não garante que a iteração recomeça.
Um objeto comum não se torna iterável apenas por ter propriedades. Uma implementação inválida, como devolver um número em vez de um objeto a partir de next(), causa um TypeError quando o protocolo é utilizado. Este mecanismo é síncrono; o protocolo assíncrono utiliza o símbolo separado Symbol.asyncIterator.
Exemplos
const numbers = {
[Symbol.iterator]() {
let current = 1;
return {
next() {
if (current <= 3) {
return { value: current++, done: false };
}
return { done: true };
}
};
}
};
console.log([...numbers].join(','));
console.log([...numbers].join(','));Resultado
1,2,3 1,2,3
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.