AsyncIterable

AsyncIterable is a concept in JavaScript and related environments that represents objects which can be consumed asynchronously through iteration. An AsyncIterable follows the AsyncIterable protocol, enabling a sequence of values to be produced lazily and awaited as they become available.

In practice, an AsyncIterable must expose a method keyed by Symbol.asyncIterator. This method returns an AsyncIterator, an object whose next() method yields a Promise for the next iteration result. Each result is an object with properties value and done, where done indicates whether the sequence has completed. The iterator may also provide optional return() and throw() methods to allow cleanup or error handling if iteration is stopped prematurely. This design supports asynchronous data sources like streams, remote data, or any computation that arrives over time.

The primary way to consume an AsyncIterable is with the for await...of loop, which automatically awaits each next value. AsyncIterables are closely tied to asynchronous generators, which are a concise way to create them using an async function with yield statements. An async generator function returns an AsyncIterable, and consuming code can use for await...of to process yielded values as they become available.

Creating custom AsyncIterables typically involves defining the [Symbol.asyncIterator] method to return an object whose next() returns a Promise for the next value. They are especially useful for streaming data, batch processing, or interfacing with APIs that deliver data asynchronously.

See also: AsyncIterator, asynchronous generators, for await...of, streams.