Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Symbol.asyncIterator — o protocolo de iteração assíncrona

Symbol.asyncIterator é um símbolo incorporado que identifica o método que fornece o iterador assíncrono de um objeto. Permite que for await...of obtenha valores sucessivos enquanto aguarda os resultados 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

Symbol.asyncIterator
object[Symbol.asyncIterator]()
async *[Symbol.asyncIterator]() { /* yield values */ }

Symbol.asyncIterator é um símbolo conhecido utilizado como chave de propriedade, não uma função a invocar diretamente. O método object[Symbol.asyncIterator]() devolve um iterador assíncrono — o próprio objeto iterador, não uma promessa de um iterador. Este mecanismo faz parte de ECMAScript desde ECMAScript 2018 (ES2018); não é uma API Web.

Um objeto iterável assíncrono disponibiliza este método, enquanto um iterador assíncrono disponibiliza next(), que devolve uma promessa que se resolve com um objeto de resultado. Se a propriedade done não estiver presente, o resultado é interpretado como se tivesse done: false. Um resultado com done: true assinala o fim da iteração e pode omitir a propriedade value. A sintaxe async *[Symbol.asyncIterator]() define um método gerador assíncrono que trata automaticamente deste protocolo.

O ciclo for await...of procura primeiro Symbol.asyncIterator. Se o método não existir ou tiver o valor null, utiliza Symbol.iterator e adapta o iterador síncrono. Um ciclo normal for...of não utiliza Symbol.asyncIterator. Não declares a fábrica do iterador como um método async simples: devolveria uma promessa em vez de um iterador.

No exemplo, cada chamada ao método cria um novo gerador e o ciclo recolhe os valores pela ordem. Verifica o suporte da sintaxe e do símbolo no ambiente de destino; nem a mera presença de Symbol.asyncIterator nem a utilização de Node 24 no repositório comprovam a compatibilidade com navegadores.

Exemplos

const numbers = {
  async *[Symbol.asyncIterator]() {
    yield 1;
    yield 2;
    yield 3;
  }
};

async function main() {
  const values = [];
  for await (const value of numbers) {
    values.push(value);
  }
  console.log(values.join(', '));
}

main().catch(console.error);

Resultado

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.

Fontes