Async iteration & async generators

Values that arrive later

Arrays are easy to loop over because every value is already in memory. Many real sequences are not like that. A server sends page one before page two, a stream produces chunk one before chunk two, and a reader may need to wait before the next value exists.

Async iteration is JavaScript’s protocol for those sequences over time. It says: “ask me for the next value, and I’ll return a promise that settles when the value is ready.” The consumer still sees a simple loop, but each turn can wait.

You will build the protocol by hand, step through a for await...of loop, hide paginated requests in async generators, read a real in-page stream, collect values with Array.fromAsync, and choose the right tool for common tasks.

A normal iterable has a Symbol.iterator method. An async iterable has a Symbol.asyncIterator method. The iterator it returns has a next() method, and that method returns a promise for the familiar iterator result: { value, done }.

The lab below writes the protocol without generator syntax. It also shows a useful edge case: for await...of can consume a normal sync iterable, such as an array, and await each value that comes out of it.

1const mailbox = {2  letters: ["invoice", "postcard"],3  index: 0,4  [Symbol.asyncIterator]() {5    return this;6  },7  next() {8    if (this.index === this.letters.length) {9      return Promise.resolve({ done: true });10    }11    const value = this.letters[this.index++];12    return Promise.resolve({ value, done: false });13  },14};15 16for await (const letter of mailbox) {17  console.log(letter);18}

1const tasks = [2  Promise.resolve("wake"),3  Promise.resolve("brew"),4  "sip",5];6 7for await (const task of tasks) {8  console.log(task);9}

for await...of is the consumer side. Behind the friendly syntax, the loop asks for the next value, awaits the promise, runs the body, then asks again. That means loop bodies run one at a time, in order.

Step through the recorded run. Switch between consuming all values and breaking early. Notice that line 6 runs either way because the async generator has a finally block.

1async function* letters() {2  try {3    yield await Promise.resolve("A");4    yield await Promise.resolve("B");5    yield await Promise.resolve("C");6  } finally {7    console.log("cleanup");8  }9}10for await (const letter of letters()) {Run11  console.log(letter);12  if (false) break;13}

Async generators: async function*

Writing the protocol by hand is useful for understanding it, but most code uses async function*. Calling an async generator function creates an async iterator. Its body does not run immediately; it starts when the consumer asks for the first value.

Inside the body, await waits for data and yield hands one value to the consumer. The generator pauses at that yield until the consumer asks again. If code calls next() repeatedly before previous calls settle, the async generator queues those requests and still runs its body in order.

Paginated APIs are a perfect async-generator example. A response gives you some items and a hint about whether another page exists. The next request depends on the previous response, so a sequential loop is the honest shape.

1async function fetchPage(page, pageSize) {2  const response = await fakeApi(page, pageSize);3  return response.json();4}5 6async function* pages(pageSize) {7  try {8    for (let page = 1; ; page += 1) {9      const data = await fetchPage(page, pageSize);10      yield data;11      if (!data.hasMore) return;12    }13  } finally {14    console.log("closed pagination cursor");15  }16}17 18async function* items(pageSize) {19  for await (const page of pages(pageSize)) {20    yield* page.items;21  }22}

Try stopping after fewer items than the total. The request log shows which pages were never fetched, and the cleanup row shows the finally block running.

Browser streams also produce a sequence over time. Fetch responses, compression tools, and file APIs can expose ReadableStream chunks. Some environments let you consume a stream directly with for await...of. Others require the older reader.read() loop, so production code should feature detect.

1const stream = new ReadableStream({2  start(controller) {3    controller.enqueue(new TextEncoder().encode("alpha"));4    controller.enqueue(new TextEncoder().encode(" beta"));5    controller.close();6  },7});8 9let text = "";10for await (const chunk of stream) {11  text += new TextDecoder().decode(chunk, { stream: true });12}13console.log(text);

This lab builds a stream inside the page. It checks stream async iteration after mount, then reports whether your browser used direct iteration or the fallback reader loop. For more download-progress patterns, see the Streams & progress lesson.

Sometimes you do not want to handle each value as it arrives. You want all of them in an array. Array.fromAsync(iterable) returns a promise for an array containing every value from an async iterable, or every awaited value from a sync iterable. It is available in modern browsers and Node 22+, so feature-check if you target older runtimes.

1async function* oneByOne() {2  yield await wait("A", 30);3  yield await wait("B", 30);4  yield await wait("C", 30);5}6 7const fromGenerator = await Array.fromAsync(oneByOne());8const promises = [wait("A", 30), wait("B", 30), wait("C", 30)];9const fromPromises = await Array.fromAsync(promises);10const allAtOnce = await Promise.all(promises);11console.log(fromGenerator.join(""));12console.log(fromPromises.join(""));13console.log(allAtOnce.join(""));

The timing lesson is subtle: collecting an async generator pulls one value at a time. An array of promises may already have started all its work. For truly independent operations, the Promise combinators lesson and Sequential vs parallel lesson explain why Promise.all is often faster.

Where you will use this

Async iteration appears whenever code needs a clean consumer for a producer that waits. Real front-end examples include loading search results page by page, reading a streamed response from fetch, processing uploaded file chunks, or adapting a WebSocket into a sequence of messages.

But it is not the only tool. Sort each task by the simplest honest loop shape.

Common misconceptions

Read the code carefully. The explanations are the important part, especially for the choices you do not pick.

Key takeaways

• An async iterator has Symbol.asyncIterator and a next() method that returns a promise for { value, done }.
• for await...of awaits each value, works in async functions and module top level, and also accepts sync iterables.
• async function* is the usual way to write async iterables; finally runs on normal finish, errors, or early break.
• Paginated APIs and streams are natural async-iteration use cases.
• Use Array.fromAsync to collect values, but use Promise.all for independent parallel work.

Up next: Generators for control flow, where generators send values both ways and become a foundation for coroutine patterns.