Async generator in TypeScript

For runtime behavior—async function*, for await..of, and the async iterator protocol—see Async iterators and for await..of.

TypeScript adds static types on top of JavaScript async generators. Values yielded, values passed back into yield, and the final return type can each be described separately.

AsyncGenerator yield, return, and next

AsyncGenerator<TYield, TReturn, TNext> parameterizes:

• TYield — type of values produced by yield
• TReturn — type passed to return() (defaults to void)
• TNext — type of argument sent into next() (defaults to unknown)

1
type Person = { name: string; title: string };
2

3
async function* getItems(
4
  items: Person[],
5
): AsyncGenerator<Person, void, unknown> {
6
  for (const item of items) {
7
    await new Promise((r) => setTimeout(r, 100));
8
    yield item;
9
  }
10
}

Typing for await..of consumers

Parameters typed as AsyncIterable<T> accept async generators, readable streams (where typings allow), and custom [Symbol.asyncIterator]() implementations:

1
async function renderOverTime(source: AsyncIterable<Person>) {
2
  for await (const item of source) {
3
    console.log(`${item.name} ${new Date().toLocaleTimeString()}`);
4
  }
5
}
6

7
await renderOverTime(getItems([{ name: "Ada", title: "Engineer" }]));

Use AsyncIterator<T, TReturn, TNext> when you hold the iterator object and call next() manually.

Inference and explicit annotations

TypeScript usually infers AsyncGenerator from async function* bodies. Annotate the return type when you implement an interface or export a public API surface:

1
interface LineSource {
2
  lines(): AsyncGenerator<string>;
3
}
4

5
class FileLines implements LineSource {
6
  async *lines() {
7
    yield "first";
8
  }
9
}

If yield types widen unexpectedly, add an explicit return type on the generator function or type the yield expression.

Strictness and Promise results

Each next() on an async iterator returns Promise<IteratorResult<TYield, TReturn>>. Under strict, handle done: true before using value:

1
async function first<T>(it: AsyncIterator<T>): Promise<T | undefined> {
2
  const { done, value } = await it.next();
3
  return done ? undefined : value;
4
}

Rejected promises from the iterator propagate to the await on next() or to for await..of—same as ordinary async functions.