CKTIS / JavaScript
Protocolo de iteradores: next(), return(), value e done
Verifica `done`, e não `value`, para detetar o fim da iteração. Aprende a ler o valor final e quando é que `for...of` chama o método opcional `return()`.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const iterator = iterable[Symbol.iterator]();
const result = iterator.next();
// result.done: completion flag; result.value: element or completion value
// When stopping early during manual iteration, call the optional method if callable:
if (typeof iterator.return === "function") {
iterator.return();
}Um iterador síncrono é um objeto com um método next() que devolve um objeto de resultado (IteratorResult). Um objeto iterável tem um método [Symbol.iterator]() que devolve um iterador. Ter next() não basta para tornar um objeto iterável; um objeto gerador desempenha ambos os papéis. for...of obtém o iterador e chama next() sem argumentos. O significado de um eventual argumento depende da implementação do iterador.
Com done: false, value é um elemento, mesmo que seja undefined. done: true indica que a iteração terminou; value pode então conter um valor final que for...of não passa ao corpo do ciclo. Se done estiver ausente, é tratado como false; for...of converte a propriedade num valor booleano para a testar. Depois de o iterador se esgotar, as chamadas seguintes a next() devem continuar a indicar done: true, mas a linguagem não o impõe.
O método opcional return(value) assinala que quem o chama vai parar a iteração e permite ao iterador libertar recursos. Normalmente, o resultado contém done: true e o argumento passado como value. No entanto, um gerador pode devolver done: false se executar um yield em finally. Numa saída antecipada por break ou por uma exceção no corpo do ciclo, for...of chama return() sem argumentos, se existir, e ignora done e value do resultado. Não o chama se o iterador se esgotar normalmente ou se o próprio next() lançar uma exceção.
As chamadas manuais a next() não fecham automaticamente o iterador. Se parares antes do fim, chama return() se for invocável. for...of lança um TypeError se next() ou a chamada a return() durante o fecho devolver algo que não seja um objeto. Se o fecho tiver sido desencadeado por uma exceção no corpo do ciclo, a exceção original tem prioridade.
Exemplos
{
function* sequence() {
try {
yield undefined;
return "end";
} finally {
console.log("cleanup");
}
}
function show(label, { done, value }) {
console.log(`${label}: done=${done}, value=${value}`);
}
const full = sequence();
show("next", full.next());
show("next", full.next());
show("next", full.next());
for (const value of sequence()) {
console.log(`loop: ${value}`);
break;
}
const manual = sequence();
manual.next();
show("return", manual.return("stopped"));
}Resultado
next: done=false, value=undefined cleanup next: done=true, value=end next: done=true, value=undefined loop: undefined cleanup cleanup return: done=true, value=stopped
Três geradores distintos mostram o esgotamento normal com o valor final `end`, o fecho automático por `break` e a chamada explícita a `return("stopped")`. Cada gerador iniciado escreve `cleanup` no bloco `finally`.
Lições relacionadas
- JavaScript · Lição 8 · Avançado · Versão: 4