How do async iterators and for await…of work?

The async protocols mirror the sync ones with promises.

• Async iterable: has a [Symbol.asyncIterator]() method.
• Async iterator: has next() (and optionally return() and throw()) that returns a promise for { value, done }.

for await (const x of source) works like this (spec: GetIterator with kind async, plus the shared loop body):

1. Look up source[Symbol.asyncIterator]. If it is missing, fall back to source[Symbol.iterator] and wrap the sync iterator in an AsyncFromSyncIterator, which awaits each value. That is why for await (const v of arrayOfPromises) yields resolved values.
2. Call next() and await the result, then read done and value.
3. Run the body. Only then ask for the next one. Iterations are strictly sequential, so a slow body delays the next pull, which is natural backpressure.
4. On break, return or a throw, call return() and await it (AsyncIteratorClose). A rejection from next() ends the loop with that error and does not call return().

It is only allowed where await is: async functions and module top level.

async function* is the easy way to write an async iterator. await and yield both work in the body. yield awaits its operand, and return does too. The generator object queues requests, so calling next() three times without waiting returns three promises that settle in order, and the body runs one step at a time.

Typical sources are paged APIs, ReadableStream, Node Readable streams, readline, and events.on. By default, leaving a Node Readable loop early destroys the stream (destroyOnReturn: false changes that).

Async iteration is not parallelism. For concurrency, start the work first and await the results (Promise.all).

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function* pages() {
  try {
    for (let page = 1; page <= 3; page++) {
      await sleep(10); // stands in for a network request
      yield [`item ${page}a`, `item ${page}b`];
    }
  } finally {
    console.log('connection closed');
  }
}

for await (const items of pages()) {
  console.log(items);
  if (items[0] === 'item 2a') break;
}
// → [ 'item 1a', 'item 1b' ]
// → [ 'item 2a', 'item 2b' ]
// → connection closed

for await (const value of [sleep(10).then(() => 'slow'), 'plain']) {
  console.log(value); // → slow
}                     // → plain

• Using for…of on an async iterable. It throws a TypeError because there is no [Symbol.iterator]. Use for await.
• Putting await in the loop body and expecting parallel work. Each iteration waits for the body before the next next(). Collect promises and use Promise.all if you want concurrency.
• Forgetting cleanup. A break calls return(); an async generator without try…finally will not release anything on its own, and a hand-written async iterator without return() is never told.
• Handing for await a sync iterable of promises and assuming all of them are watched. They are awaited one at a time, so a promise that rejects while an earlier one is pending has no handler until the loop reaches it. In Node 24 that unhandled rejection terminates the process before the loop can catch it.