Asynchronous sequences
Consume values produced over time, such as results from an async generator.
JavaScript · Type Alias
AsyncIterator
AsyncIterator is an object whose next() method returns a promise for an iterator result. Built-in async iterators inherit from AsyncIterator.prototype, which makes them usable as async iterables.
How it works
AsyncIterator describes objects whose next() method returns a promise for an iterator result. Built-in async iterators inherit from AsyncIterator.prototype, whose Symbol.asyncIterator method returns the iterator itself so it can also be used as an async iterable.
Key points
- An AsyncIterator supplies next(), and calling it produces a promise rather than an immediate iterator result.
- The promise from next() fulfills with an iterator result, typically containing value and done properties.
- The prototype makes the iterator async iterable by returning the same object from Symbol.asyncIterator().
- Because it is also async iterable, the object works with language constructs that expect an async iterable.
- Concrete async iterator kinds can define their own next() behavior on distinct prototypes.
- A for await...of loop is the standard syntax for consuming built-in async iterators asynchronously.
Common mistakes
- AsyncIterator is not typically obtained by directly constructing a value; built-in async iterators inherit from its prototype.
- In core JavaScript, async generators are the main built-in source of AsyncIterator objects; other examples may come from web APIs.
Example: Consume an async iterator
async function* numbers() {
yield 1;
yield 2;
}
for await (const number of numbers()) {
console.log(number);
}An async generator produces an AsyncIterator, which can be consumed directly by a for await...of loop.
When to use it
Streaming consumption
Process stream-like data with for await...of while each value becomes available.
Custom async iteration
Implement a custom object that exposes asynchronous next() operations.
Interview questions
QWhat is an AsyncIterator?
An AsyncIterator is an object whose next() method returns a promise that fulfills with an iterator result. Its prototype also supplies Symbol.asyncIterator(), allowing the object to be consumed as an async iterable.
Follow-up: How is it normally consumed? Use for await...of, which obtains the async iterator through Symbol.asyncIterator() and awaits each result from next().
QWhat does Symbol.asyncIterator do on AsyncIterator.prototype?
AsyncIterator.prototype[Symbol.asyncIterator]() returns the current iterator object. This makes an async iterator also satisfy the async iterable protocol without creating a separate wrapper.
Follow-up: Why does this matter in practice? Syntax such as for await...of can call the method automatically and iterate the same object.
QHow do async generators relate to AsyncIterator?
Async generator functions return AsyncIterator objects. Those objects can be passed directly to for await...of, which repeatedly awaits next() until the returned result has done set to true.
Follow-up: Can for await...of consume synchronous iterables too? Yes; if no async iterator exists, it falls back to a synchronous iterator and wraps its results asynchronously.
Related
AsyncGeneratorAsyncIterator.prototypeAsyncIterator.prototype[Symbol.asyncIterator]()Symbol.asyncIteratorfor await...of