Async iterators and for await..of

This chapter follows Generators in JavaScript.

Synchronous iterators assume each next() can return immediately. Async iterators return a Promise for each step, so producers can wait on I/O, timers, or other async work between values.

Async iterator protocol

An async iterator exposes next() returning Promise<{ value, done }>. An async iterable implements [Symbol.asyncIterator]() and returns a fresh async iterator.

You can also implement the protocol by hand:

1
const asyncIterable = {
2
  async *[Symbol.asyncIterator]() {
3
    yield 1;
4
    yield 2;
5
  },
6
};

for await..of

for await..of loops over async iterables (and sync iterables in async functions). Each iteration awaits the next result:

1
async function logAll(source) {
2
  for await (const value of source) {
3
    console.log(value);
4
  }
5
}
6

7
await logAll(asyncIterable);

Use for await..of inside async functions or at the top level in modules that support top-level await. Plain for..of on an async iterable does not await promises between steps.

Async generator functions

async function* combines generators with await. The returned object is both an async iterator and an async iterable:

1
async function* readLines(urls) {
2
  for (const url of urls) {
3
    const res = await fetch(url);
4
    const text = await res.text();
5
    for (const line of text.split("\n")) {
6
      if (line.trim()) yield line;
7
    }
8
  }
9
}
10

11
for await (const line of readLines(["/api/a", "/api/b"])) {
12
  console.log(line);
13
}

Rules mirror sync generators: yield produces a value, yield* delegates to another iterable, and return() / throw() on the iterator can finish early.

When to choose async iteration

Reach for async iterables when:

• Values arrive over time and each step may await
• You want lazy consumption (process one page or chunk before fetching the next)
• A library exposes Symbol.asyncIterator (Node readable streams in modern modes, some database drivers)

For a single future value, a Promise is simpler. For push streams with many subscribers and operators, see Observables in JavaScript.

Error handling and cleanup

If for await..of throws or breaks out of the loop, the runtime calls iterator.return() when present—same idea as sync for..of. Async generators run finally blocks when iteration ends.

Wrap the loop in try/catch when the producer can reject (network failures, parser errors):

1
async function consume(source) {
2
  try {
3
    for await (const chunk of source) {
4
      process(chunk);
5
    }
6
  } catch (err) {
7
    console.error("Iteration failed", err);
8
  }
9
}

For typing async generators in TypeScript, see Async generator in TypeScript.

Continue with Iterator helpers.