Async Generators

## Two suspension mechanisms in one function JavaScript has two ways for a function to pause. A generator (`function*`) pauses at `yield` and hands a value to whoever pulls the next one; it can emit many values, but it has no way to wait — writing `await` inside a `function*` body is a syntax error. An `async function` can pause at `await` while a promise settles, but it produces exactly one result: the single promise it returns. `async function*` is the union of the two. Its body may use `await` to wait for asynchronous work and `yield` to emit a value, as many times as it likes. That is precisely the shape of a producer that has to *ask* for each batch of data — a paginated API, a polling loop, a chunked read — and wants to hand items out as they arrive instead of collecting everything first. ```js async function* doubled(values) { for (const v of values) { const resolved = await Promise.resolve(v); // legal only in an async generator yield resolved * 2; } } ``` ## What calling it returns Calling an async generator function runs none of the body — exactly like a sync generator. It returns an **async generator object**. That object implements the async iterator protocol: - `next(v)` — resume the body, returning a promise for the next result; - `return(v)` — ask the body to finish early, as if a `return` executed at the suspended `yield`; - `throw(e)` — inject an exception at the suspended `yield`; - `[Symbol.asyncIterator]()` — returns the object itself, which is what makes it directly usable with `for await...of`. ## The promise-wrapped result record A sync generator's `next()` returns the record `{ value, done }` immediately. An async generator's `next()` returns a **Promise** that fulfils with that record. The whole record is inside the promise — not just the value: ```js const it = doubled([1, 2]); console.log(it.next().done); // undefined — next() gave you a Promise it.next().then((r) => console.log(r)); // { value: 4, done: false } ``` Reading `.value` or `.done` off the unawaited call is the single most common beginner bug here, and it fails silently: you get `undefined`, not an error, so a `while (!it.next().done)` loop spins forever. ## Yielded values are awaited for you Inside an async generator, the operand of `yield` is implicitly awaited before it is delivered. `yield fetchThing()` therefore emits the *resolved* value, and if that promise rejects, the rejection surfaces as a rejected `next()` promise rather than as a promise handed to the consumer. This differs from a sync generator, where yielding a promise hands the promise object itself out and leaves unwrapping to the consumer. ## Return values and completion `return x` in the body produces `{ value: x, done: true }` on the promise for that resumption. As with sync generators, a `for await...of` loop discards that final value — if the total or a summary matters, yield it as a regular item or expose it another way. ## Consuming one The everyday consumer is `for await...of`, which calls `next()`, awaits it, and stops when `done` is `true`: ```js for await (const n of doubled([1, 2])) console.log(n); // 2, then 4 ``` You can also drive it by hand with `await it.next()` in a loop, which is what you do when you need to interleave other logic between pulls. ## Why the shape matters Because the body only advances when someone asks for the next value, an async generator is *lazy*: the fetch for item two does not happen until the consumer has taken item one. That is what makes it a good fit for large or unbounded sequences — memory stays bounded to whatever one step holds, and the consumer can stop at any point without the producer having done the remaining work. ## Version note Async generators, the async iterator protocol, and `for await...of` are all ES2018 features and are available in every current browser and Node release; no transpilation or flag is needed on a modern baseline.