Async iteration & async generators

Values that arrive later

Looping over an array is easy. Every value is already there, so the loop can take them one after another.

Many lists of values are not like that. The values come one at a time, and you have to wait for each one:

• A server sends page 1 of results, then later page 2.
• A download arrives in small pieces. Each piece is called a chunk.
• A chat gets a new message only when someone sends it.

Async iteration is how JavaScript loops over values that arrive later. ("Async" means "it can wait". "Iteration" means "going through values one by one".) Your code asks for the next value. It gets a promise: an object that gives you the value once it is ready. The loop waits for that promise, uses the value, then asks again.

In this lesson you will:

• build an object that gives values later, by hand;
• step through a for await...of loop, line by line;
• load pages from a pretend server, one page at a time;
• read a real stream of chunks in this page;
• collect all the values into an array with Array.fromAsync;
• pick the right kind of loop for everyday tasks.

A protocol is a set of rules that objects agree to follow. You met the normal loop rules in the Iteration protocols lesson. Here is a quick reminder:

• An iterable is an object you can loop over, like an array. It has a method called Symbol.iterator.
• That method gives back an iterator: an object with a next() method.
• Each next() call gives back a result, { value, done }. value is the next value. done is true when there are no more.

The async rules change only two things:

• The method is called Symbol.asyncIterator instead of Symbol.iterator.
• next() gives back a promise. The promise then gives you the { value, done } result.

The table puts the two sets of rules side by side. Read each row across: the normal version first, then the async version.

The lab below follows the rules by hand, with no shortcuts. The mailbox object holds two letters. Its next() method gives back a promise each time.

The second example shows one more thing. for await...of can also loop over a normal array. It waits for each promise in the array before the loop body runs.

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 loop that uses async values. You don't call next() yourself. The loop does it for you, every turn:

1. It calls next() and gets a promise.
2. It waits until the promise gives the result.
3. It runs the loop body with the value.
4. It goes back to step 1, until done is true.

So the loop body runs for one value at a time, in order. The next turn starts only when the body has finished.

The values in the example below come from an async generator. It is a function written as async function* that gives out values one at a time. (The next section explains it in full.) Two words you need now:

• yield gives out one value and pauses the function there.
• finally marks a block of code that always runs when the function stops, for any reason. It is a good place for cleanup, such as closing a connection.

Every async generator also has a return() method. Calling it stops the generator for good. The code below calls it by hand.

async function* orders() {
  try {
    yield "first";
    yield "second";
  } finally {
    console.log("closed");
  }
}

const iterator = orders();
console.log((await iterator.next()).value);
await iterator.return();

Line 10 makes the generator. Line 11 calls next() once, waits, and prints first. Line 12 calls return(). The generator stops, and its finally block prints closed. second is never given out.

You rarely call return() yourself. When you leave a for await loop early with break, the loop calls return() for you.

Step through the run below. Choose whether the loop takes all three letters or breaks after the first one. Watch line 7: the cleanup line runs in both cases, because the 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 next() by hand, like the mailbox, shows how the rules work. But most code uses an async generator instead. You write it as async function*: the word async, the word function, and a star.

Here is what happens when you use one:

• Calling the function does not run its code yet. It only gives you an object that follows the async rules.
• The code starts when someone asks for the first value, with next() or a for await loop.
• Inside, await waits for data. yield gives out one value.
• After a yield, the code pauses. It goes on only when the next value is asked for.

What if code calls next() several times without waiting for the answers? The generator puts the requests in a line. It answers them one by one, in order. It never runs two parts of its code at the same time.

A generator can also fail. In the code below, the generator gives out one value and then throws an error.

async function* statuses() {
  yield "paid";
  throw new Error("payment service unavailable");
}

try {
  for await (const status of statuses()) {
    console.log(status);
  }
} catch (error) {
  console.log(error.message);
}

The first turn gets paid, so line 8 prints it. On the next turn, line 3 throws an error. The loop stops. Line 11, inside the catch block, prints the error's message.

Notice where the try is. It wraps the whole loop, not just the body. The error comes from the generator, so a try inside the body would not catch it.

Many servers don't send a long list all at once. They send it in pages: page 1 has the first few items, page 2 the next few, and so on. This is called pagination.

Each page also says whether there is another page. In the code below, that is hasMore. You only know if you need page 2 after page 1 arrives. So the pages must be loaded one after another. An async generator fits this well.

The lab code has two async generators:

• pages() loads one page at a time. It stops when a page says hasMore is false.
• items() loops over those pages and gives out each item on its own. yield* gives out every item of a list, one by one.

The code that uses items() sees one item at a time. It never has to think about pages.

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 loaded. The cleanup row shows that the finally block still ran.

A stream is data that arrives in chunks over time. In the browser, a stream is a ReadableStream object. For example, the body of a fetch response is a stream.

There are two ways to read the chunks:

• Newer browsers let you loop over a stream with for await...of.
• Older browsers need a reader: you call reader.read() again and again until it says done.

So real code should first check which way the browser supports. This check is called feature detection.

In the code, each chunk is raw bytes. TextEncoder turns text into bytes, and TextDecoder turns bytes back into text.

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);

The lab makes a stream inside this page. When the page loads, it checks whether your browser can loop over a stream directly. Then it shows which way it used to read the chunks. For download progress bars and more, see the Streams & progress lesson.

Sometimes you don't want to handle each value as it arrives. You just want all of them in one array. Array.fromAsync() does that:

• Give it an async generator, and it collects every value the generator gives out.
• Give it a normal array of promises, and it waits for each promise and collects the results.
• Either way, it gives back a promise. Use await to get the finished array.

Array.fromAsync works in current browsers and in Node 22 and later. If you must support older ones, check that it exists first.

The lab code uses a helper, wait(value, ms). It waits ms milliseconds, then gives back value.

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(""));

When does each task start? The code below makes the promises first, then loops over them. step() records when each task starts and when it is done.

const events = [];
async function step(name) {
  events.push("start " + name);
  await Promise.resolve();
  events.push("done " + name);
  return name;
}

const tasks = [step("A"), step("B")];
for await (const task of tasks) console.log(task);
console.log(events.join(" | "));

Line 9 calls step("A") and step("B") to build the array. Both tasks start right there, before the loop begins. Line 10 then prints A and B, in array order. Line 11 prints start A | start B | done A | done B: both had started before either one was done.

An async generator is different. It starts the next task only when the loop asks for the next value. When tasks don't depend on each other, starting them all together is faster. The Promise combinators lesson and the Sequential vs parallel lesson explain Promise.all, which does that.

Where you will use this

Use async iteration when values arrive one by one and you want to handle each as it comes. Common cases in websites:

• loading search results page by page;
• reading a response from fetch chunk by chunk;
• handling a large uploaded file in pieces;
• turning live chat messages into a loop.

It is not always the right tool. Sort each task below by the simplest loop that does the job.

Common misconceptions

Read each code example carefully before you choose. Every choice has an explanation, so read the ones you didn't pick too.

Key takeaways

• An object you can loop over with for await has a Symbol.asyncIterator method. Its next() gives back a promise for { value, done }.
• for await...of waits for each value in turn. You can use it inside async functions and at the top level of a module. It also works on normal arrays of promises.
• async function* is the usual way to make values that arrive later. Its finally block runs when it ends normally, when it throws, and when the loop uses break.
• Loading pages from a server and reading streams are two common uses.
• Use Array.fromAsync to collect all the values into an array. Use Promise.all when tasks don't depend on each other and can run together.

Up next: Generators for control flow. You will send values both ways between a generator and the code that runs it.