TypeScript Reference ยท Utility Types
TypeScript AsyncIterable and AsyncGenerator types
Reference for AsyncIterable, AsyncIterator, AsyncIterableIterator and AsyncGenerator in TypeScript: typing for await loops, async function* and streams.
These built-in types describe values you walk through with for await ... of. AsyncIterable<T> is anything that can produce an AsyncIterator<T> through [Symbol.asyncIterator](). AsyncIterator<T> has a next() method that returns a promise of { value, done }. AsyncGenerator<T, TReturn, TNext> is what an async function* returns: an iterator that is also iterable and can be sent values.
Reach for AsyncIterable<T> in parameter types, because it accepts async generators, Node streams, and any custom object with the right method. Use AsyncGenerator as the return type of your own async function* when you want to be explicit.
async function* ticks(n: number): AsyncGenerator<number, void, undefined> { for (let i = 1; i <= n; i++) yield i; }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
interface AsyncIterable<T, TReturn = any, TNext = any> { [Symbol.asyncIterator](): AsyncIterator<T, TReturn, TNext>; } interface AsyncIterator<T, TReturn = any, TNext = any> { next(...[value]: [] | [TNext]): Promise<IteratorResult<T, TReturn>>; return?(value?: TReturn | PromiseLike<TReturn>): Promise<IteratorResult<T, TReturn>>; throw?(e?: any): Promise<IteratorResult<T, TReturn>>; } interface AsyncGenerator<T = unknown, TReturn = any, TNext = any> extends AsyncIteratorObject<T, TReturn, TNext> { next(...[value]: [] | [TNext]): Promise<IteratorResult<T, TReturn>>; return(value: TReturn | PromiseLike<TReturn>): Promise<IteratorResult<T, TReturn>>; throw(e: any): Promise<IteratorResult<T, TReturn>>; [Symbol.asyncIterator](): AsyncGenerator<T, TReturn, TNext>; }
| Name | Description |
|---|---|
T |
Type of each yielded value. |
TReturn |
Type of the final return value (the value when done is true). |
TNext |
Type of the argument you may pass to next(); it becomes the result of yield inside the generator. |
Returns: next() resolves to { value: T, done: false } while there are items and { value: TReturn, done: true } at the end.
Edge cases:
for awaitignoresTReturn; only manualnext()calls see it.- Breaking out of a
for awaitcallsreturn()on the iterator, which runs the generator'sfinallyblocks. for awaitalso accepts ordinary iterables and awaits each element, as the second example shows.- Older libraries declared
AsyncIterableIterator<T>for objects that are both iterator and iterable; modern async generators useAsyncGenerator.
Usage notes
- An
async function*with no explicit annotation is inferred asAsyncGenerator<Yielded, Returned, any>. - To consume two sources at once, do not interleave
for awaitloops; usePromise.raceovernext()calls or a merge helper. - Errors thrown inside the generator reject the
next()promise and end the loop with an exception you cantry/catch. - Node readable streams,
readlineinterfaces andevents.on()areAsyncIterables, so the same function signature accepts them. - Keep
TNextasundefinedunless you really use two-way communication;anyhides mistakes.