A function loops through every page of a paginated HTTP API, pushing each page's items into one array, and returns that array once the last page arrives. How would you restructure it as an async generator, and what does that change for the caller?

## The eager version and what it costs The conventional shape is a loop that accumulates: ```js async function fetchAll(fetchPage) { const out = []; let cursor = null; do { const page = await fetchPage(cursor); out.push(...page.items); cursor = page.nextCursor; } while (cursor); return out; } ``` This returns a promise for one array. Its caller therefore waits for every request to finish before it can touch a single item, and the process holds the entire collection at once. With forty pages of a thousand rows, that is forty round trips of latency before anything is displayed and forty thousand objects resident — even if the caller only wanted the first match. ## The lazy version The restructuring is small. Mark the function `async function*` and replace accumulation with `yield`: ```js async function* paginate(fetchPage) { let cursor = null; do { const page = await fetchPage(cursor); for (const item of page.items) yield item; cursor = page.nextCursor; } while (cursor); } ``` Nothing about the request logic changed. What changed is *when* the body runs: it advances only when the consumer asks for another item, and it suspends again at each `yield`. ## What the caller sees ```js for await (const item of paginate(fetchPage)) { process(item); } ``` - **Time to first result** falls from the sum of all requests to the first request. For a UI or a log tail that is the difference between a spinner and a stream. - **Peak memory** is one page plus whatever the consumer keeps, rather than the whole collection. That is what makes an *unbounded* source expressible at all — an endless feed has no array form. - **Early exit is free.** If the consumer stops after finding what it wanted, the generator is suspended mid-loop and the requests for the remaining pages are never issued. In the eager version, the work was already paid for. - **Errors arrive positionally.** A failure fetching page seven rejects the `next()` promise for the item the consumer was pulling at that moment, so it throws out of the `for await...of` loop after six pages' worth of items were already processed. That is usually what you want for streaming, but the consumer must now decide what to do with a half-consumed sequence — a partial-failure question the array version never posed. ## Choosing the granularity Yield items or yield pages? Yielding *items* gives the cleanest consumer (`for await (const user of users())`) and hides pagination entirely. Yielding *pages* is better when the consumer batches — writing a thousand rows per database insert, for example — because rebatching individual items downstream is wasted work. Some APIs expose both: an item-level generator implemented on top of a page-level one. ## The costs, stated plainly You lose the array. `.length`, `.map`, indexing, and passing the result to something expecting an array all stop working. A caller that truly needs the whole set writes its own collection loop, which is the eager version restored — and that is fine; the point is that the *producer* no longer forces that choice on everyone. You also lose the option to fan the page requests out concurrently *inside* the plain shape: the generator body awaits page N before it can compute the cursor for page N+1, so cursor-based pagination is inherently sequential either way. If the API exposes numbered pages and a total count, concurrency becomes possible, but that is then a deliberate design with its own concurrency-limit question — not something the generator gives you for free. Finally, if the fetching step holds a resource — a cursor, a connection, an open handle — laziness means the resource stays open across the consumer's processing time, and it must be released with `try`/`finally` so an early exit does not leak it. ## When the eager version is still right Small, bounded results consumed in full. If the endpoint returns three pages and every caller needs all of them, an array is simpler, is trivially cacheable, and lets callers use ordinary array methods. Laziness is a tool for volume, latency, and early exit — not a default virtue.