CKTIS / JavaScript
Symbol.asyncIterator — protokół iteracji asynchronicznej
Symbol.asyncIterator to wbudowany symbol wskazujący metodę, która udostępnia iterator asynchroniczny obiektu. Dzięki niej for await...of może pobierać kolejne wartości, oczekując na wyniki next().
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
Symbol.asyncIterator
object[Symbol.asyncIterator]()
async *[Symbol.asyncIterator]() { /* yield values */ }Symbol.asyncIterator jest standardowym symbolem używanym jako klucz właściwości, a nie funkcją wywoływaną bezpośrednio. Metoda object[Symbol.asyncIterator]() zwraca iterator asynchroniczny — sam obiekt iteratora, nie obietnicę iteratora. Mechanizm należy do ECMAScript od wydania ECMAScript 2018 (ES2018); nie jest interfejsem Web API.
Obiekt iterowalny asynchronicznie udostępnia tę metodę, natomiast iterator asynchroniczny udostępnia metodę next(), która zwraca obietnicę spełnianą obiektem wyniku. Brak właściwości done jest traktowany tak samo jak done: false. Zapis done: true oznacza koniec iteracji; w takim wyniku można pominąć właściwość value. Zapis async *[Symbol.asyncIterator]() tworzy metodę generatora asynchronicznego, który obsługuje ten protokół automatycznie.
Pętla for await...of najpierw szuka Symbol.asyncIterator. Jeśli metoda jest nieobecna lub ma wartość null, korzysta z Symbol.iterator i adaptuje iterator synchroniczny. Zwykłe for...of nie korzysta z Symbol.asyncIterator. Metody fabrykującej iterator nie deklaruj jako zwykłego async: zwróciłaby obietnicę zamiast iteratora.
W przykładzie każde wywołanie metody tworzy nowy generator, a pętla zbiera wartości kolejno. Obsługę składni i symbolu trzeba sprawdzić w docelowym środowisku; sama obecność Symbol.asyncIterator ani użycie Node 24 w repozytorium nie dowodzą zgodności przeglądarki.
Przykłady
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);Wynik
1, 2, 3
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.