Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
async function* ticks(n: number): AsyncGenerator<number, void, undefined> {
  for (let i = 1; i <= n; i++) yield i;
}

Try it

TypeScript An async generator consumed with for await

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.

TypeScript A custom AsyncIterable

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

TypeScript
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 await ignores TReturn; only manual next() calls see it.
  • Breaking out of a for await calls return() on the iterator, which runs the generator's finally blocks.
  • for await also 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 use AsyncGenerator.

Usage notes

  • An async function* with no explicit annotation is inferred as AsyncGenerator<Yielded, Returned, any>.
  • To consume two sources at once, do not interleave for await loops; use Promise.race over next() calls or a merge helper.
  • Errors thrown inside the generator reject the next() promise and end the loop with an exception you can try/catch.
  • Node readable streams, readline interfaces and events.on() are AsyncIterables, so the same function signature accepts them.
  • Keep TNext as undefined unless you really use two-way communication; any hides mistakes.