Lazy asynchronous streams
Stream values produced over time without loading the complete sequence first.
JavaScript · Type Alias
AsyncGenerator
AsyncGenerator is the object produced by calling an async generator function. It is both an async iterable and async iterator, and its methods return promises.
How it works
An AsyncGenerator is the object produced whenever an async generator function is called. It is both asynchronously iterable and an async iterator: its next(), throw(), and return() operations produce promises, while the generator can pause at yield and resume around awaited work.
Syntax
async function* name(parameters) { statements }Returns
An object returned by an async generator function that conforms to both the async iterable and async iterator protocols; its generator methods return promises.
Key points
- Calling an async generator function creates the AsyncGenerator instance.
- The same object can supply an async iterator and be consumed as an async iterable.
- Operations such as next(), throw(), and return() complete asynchronously through promises.
- Its prototype relationship includes the hidden AsyncIterator base class.
- AsyncGenerator objects are produced by async generator functions rather than by a public constructor.
- The shared prototype is internal and is used by objects created from async generator functions.
Common mistakes
- Do not instantiate AsyncGenerator directly; obtain instances by calling an async generator function.
- Iterator operations are asynchronous, so handle their results as promises or consume the object with for await...of.
Example: Consume an async generator
async function* numbers() {
yield await Promise.resolve(1);
yield 2;
}
for await (const value of numbers()) {
console.log(value);
}Calling an async generator creates an AsyncGenerator. The loop requests values through next(), awaits each promise, and stops when done is true.
When to use it
Paginated or event-driven work
Combine await-based operations with incremental yield of results.
for await...of pipelines
Consume asynchronous sequences with automatic awaiting and completion handling.
Interview questions
QWhat is an AsyncGenerator?
An AsyncGenerator is returned by an async generator function. It implements both the async iterable and async iterator protocols, and its iterator methods return promises.
Follow-up: How is it normally consumed? Use for await...of, which repeatedly requests and awaits iterator results until the result object's done property is true.
QWhat does AsyncGenerator.prototype.next() return?
Calling next() requests the next sequence result and returns a promise. The fulfilled value is an iterator-result object containing value and done, where done indicates whether execution has finished.
Follow-up: What does passing an argument to next() do? The value is delivered to the suspended yield expression, allowing the generator to receive input when it resumes.
QHow do throw() and return() affect an async generator?
throw() behaves as though a throw statement were inserted at the generator's currently suspended position. The generator may catch the error, continue yielding, or remain rejected if the error is uncaught.
Follow-up: How does return() differ? It injects a return at the suspended position, finishes the generator, and permits cleanup in a finally block.
Related
AsyncGeneratorFunctionAsyncGenerator.prototype.next()AsyncGenerator.prototype.throw()AsyncGenerator.prototype.return()async function*for await...of