# How to expose paged results as an async iterator in TypeScript

> Wrap a cursor-paged list call in an async generator, so callers loop with for await, stop early without a stray request, and never handle a cursor.

Source: https://voxgig.com/howto/paged-results-as-an-async-iterator-in-typescript

- Audience: library-maintainer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Write an async generator that fetches a page, yields its items, and asks for the next page only when the loop needs it. When a caller breaks out of for await, the loop calls the generator's return(), so call abort() on an AbortController in its finally block and attach a rejection handler to each request as it starts. The same generator wraps clients from sdkgen, Kiota, and OpenAPI Generator, because none of the three yields across pages.

---
## You will need

Node 22.18 or later, which [runs `.ts` files by stripping their types](https://nodejs.org/api/typescript.html),
and a list endpoint described in OpenAPI. Verified 2026-11-21 against Node 22.23.5,
@voxgig/sdkgen 4.44.3, Kiota 1.39.0, and OpenAPI Generator 7.27.0. The document, `api.json`,
pages seven products behind `data`, `next_cursor`, and `has_more`. `server.ts` serves it on
`127.0.0.1` and refuses an unknown cursor or a `limit` outside 1 to 100. Run `npm ci` in the
sample directory first, for the Kiota runtime packages.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern auto-pagination](https://buildwithfern.com/learn/sdks/current/deep-dives/auto-pagination) | You generate with Fern and can annotate each list operation with `x-fern-pagination` | Remote generation needs a login or guest session, local needs Docker or Podman, and each paged operation needs an annotation | You cannot add vendor extensions to the document |
| [hand-written async generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) | Any client, generated or not, and you want to own early exit and cancellation | About fifty lines of code you test yourself, plus one page function per client | Your generator already emits an iterator whose shape you accept |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/middleware) | One request-builder shape across C#, Go, Java, Python, and TypeScript clients | No paging helper, and no cancellation signal until you add a middleware and a request option | You want cancellation without touching the HTTP layer |
| [OpenAPI Generator](https://openapi-generator.tech/docs/generators/typescript-fetch/) | You want `typescript-fetch` output that runs on the platform `fetch` alone | No paging helper, so each list method gets a page function written by hand | You want one iterator shape generated for every list method |
| [sdkgen paging feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | The SDK comes from sdkgen and you want its cursor handling in every target | Reads the cursor for you, yields one page per call, and sends an undeclared `page` parameter | The API rejects query parameters its document does not declare |

Voxgig maintains sdkgen. The table lists it as one of five options and ranks none of them.

Fern is the only generator here whose documentation promises an iterator, a `Page<T>` that implements
`AsyncIterable`. That row reads Fern's current documentation, which configures SDKs in
`sdk-config.yml`, and its [CLI](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands)
generates on Fern's service unless you run it locally in Docker or Podman. The three generators run on
this page leave the loop to you. OpenAPI Generator passes a signal through with no extra code, Kiota needs a
middleware for it, and sdkgen tracks the cursor for you.

## Write the generator that owns the cursor

`iterPages` takes one function, `fetchPage(cursor, signal)`, which returns a page's items and the
next cursor. It holds the only copy of the cursor and the only `AbortController`.

```ts title="iterate.ts"
export async function* iterPages<T>(
  fetchPage: FetchPage<T>,
  options: IterateOptions = {},
): AsyncGenerator<T[], void, undefined> {
  const controller = new AbortController()
  const outer = options.signal
  const forward = () => controller.abort(outer?.reason)
  if (outer?.aborted) forward()
  else outer?.addEventListener('abort', forward, { once: true })

  // A prefetch can fail while the caller is still working on the page before
  // it, or after the finally block aborts it. Nothing awaits it yet in either
  // case, so mark the rejection observed as the request starts. The promise
  // itself stays rejected, and the next `await pending` still throws.
  const start = (cursor: string | null): Promise<Page<T>> => {
    const request = fetchPage(cursor, controller.signal)
    request.catch(() => {})
    return request
  }

  const seen = new Set<string>()
  let pending: Promise<Page<T>> | null = start(null)
  try {
    while (pending !== null) {
      const page: Page<T> = await pending
      pending = null
      if (page.next !== null) {
        if (seen.has(page.next)) throw new Error(`the API returned cursor ${page.next} twice`)
        seen.add(page.next)
      }
      if (options.prefetch && page.next !== null) pending = start(page.next)
      yield page.items
      if (!options.prefetch && page.next !== null) pending = start(page.next)
    }
  } finally {
    // Runs when the pages run out, when a page fails, and when the caller
    // breaks out of its loop, which calls return() on this generator.
    outer?.removeEventListener('abort', forward)
    controller.abort(new Error('iteration stopped'))
  }
}
```

Without `prefetch`, the next request starts after the caller has taken the last item of a page,
so a loop that stops early costs nothing. With it, the next page loads while the caller works,
and the `finally` block has a request to cancel. A caller's own `signal` is forwarded, so
aborting it ends the loop and the request together. `start()` gives each request a rejection handler
as it begins, so a prefetch that fails while the caller works still reaches the caller's `catch`.

The `seen` set turns a server that hands back the same cursor into an error instead of an endless
loop.

## Return an object callers can loop over

Items are a second generator over the pages, and `paginated` puts both behind one object.

```ts title="iterate.ts"
export async function* iterItems<T>(
  fetchPage: FetchPage<T>,
  options: IterateOptions = {},
): AsyncGenerator<T, void, undefined> {
  for await (const page of iterPages(fetchPage, options)) {
    yield* page
  }
}
```

A `break` in the caller's loop calls `return()` on `iterItems`, and leaving its own `for await`
calls `return()` on `iterPages`, so the `finally` block runs at the bottom of the chain.[^1]
`paginated` builds a fresh generator on every iteration. Iterating the same `list()` twice
starts from page one both times, which a test pins.

## Feed the generator from the sdkgen paging feature

`generate.sh` scaffolded the sdkgen project with `--target ts --feature paging` and committed the
compiled SDK. The [paging feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
reads `next_cursor` and `has_more` into `ctrl.paging`, the control object passed as the second
argument, and sends `ctrl.paging.cursor` on the next call.

```ts title="clients.ts"
export function sdkgenPages(base: string): FetchPage<Product> {
  const client = new GearshopSDK({ base, feature: { paging: { active: true, limit: LIMIT } } })
  return async (cursor, signal) => {
    const ctrl: any = { paging: cursor === null ? {} : { cursor, hasMore: true }, signal }
    const entities = await client.Product().list({}, ctrl)
    return {
      items: entities.map((entity: any) => entity.data()),
      next: ctrl.paging.hasMore ? ctrl.paging.cursor : null,
    }
  }
}
```

Each call builds its own `ctrl` from the cursor, so two loops never share a position. `signal`
travels in `ctrl.signal`, and cancelling it rejects the call with an error whose `code` is
`request_aborted`. The SDK's own `stream('list')` yields the items of one call, three products
from one request on this document, so it does not replace the generator.

## Pass the signal through Kiota and OpenAPI Generator clients

OpenAPI Generator's `typescript-fetch` output takes a `RequestInit` as the second argument of
every operation, so the signal reaches `fetch` unchanged. Its generator page lists no paging
option, and the page function's body is two lines.

```ts title="clients.ts"
export function oagPages(base: string): FetchPage<Product> {
  const api = new oag.DefaultApi(new oag.Configuration({ basePath: base }))
  return async (cursor, signal) => {
    const page = await api.listProducts({ limit: LIMIT, cursor: cursor ?? undefined }, { signal })
    return { items: page.data, next: page.hasMore ? page.nextCursor ?? null : null }
  }
}
```

Kiota generated `client.products.get()` returning the whole `ProductPage`, with no paging helper,
and the concepts list of its documentation has no page on pagination.[^2] Adding Microsoft's
`x-ms-pageable` extension to `api.json` left the TypeScript output unchanged. Microsoft Graph's SDKs
add a [`PageIterator`](https://learn.microsoft.com/en-us/graph/sdks/paging) in their own core
libraries, but it follows `@odata.nextLink`, which this API never sends. Kiota's fetch adapter
builds the request from the method, headers, and body alone, with no signal. Kiota's [middleware page](https://learn.microsoft.com/en-us/openapi/kiota/middleware)
gives the substitute: a handler with `execute(url, requestInit, requestOptions)`, added with
`handlers.unshift(...)` before `KiotaClientFactory.create`.

```ts title="clients.ts"
class AbortSignalHandler implements Middleware {
  next: Middleware | undefined
  execute(url: string, init: RequestInit, options?: Record<string, RequestOption>): Promise<Response> {
    const option = options?.[ABORT_KEY] as AbortSignalOption | undefined
    if (option) init.signal = option.signal
    return this.next!.execute(url, init, options)
  }
}
```

Each call passes `options: [new AbortSignalOption(signal)]`. A test builds the same client without
the handler, aborts the signal, and still gets the page back, because the server never sees the
request cancelled.

## Check it worked

`demo.ts` runs a full loop, an `iterPages()` loop, and a loop that stops at the third product,
over each client.

```bash
node demo.ts
```

```text output
sdkgen: 7 products, 3 requests
  GET /v1/products?limit=3&page=1
  GET /v1/products?cursor=cur_0003&limit=3
  GET /v1/products?cursor=cur_0006&limit=3
  iterPages(): pages of 3, 3, 1
  break after 3 products: 1 request
OpenAPI Generator: 7 products, 3 requests
  GET /v1/products?limit=3
  GET /v1/products?limit=3&cursor=cur_0003
  GET /v1/products?limit=3&cursor=cur_0006
  iterPages(): pages of 3, 3, 1
  break after 3 products: 1 request
Kiota: 7 products, 3 requests
  GET /v1/products?limit=3
  GET /v1/products?cursor=cur_0003&limit=3
  GET /v1/products?cursor=cur_0006&limit=3
  iterPages(): pages of 3, 3, 1
  break after 3 products: 1 request
```

Every client reaches all seven, and stopping at three costs `1 request`. sdkgen's first request
carries `page=1`, a parameter `api.json` does not declare, because the feature sends a page
number until a response returns a cursor. The test that matters asserts the single request:

```ts title="iterate.test.ts"
  test(`${name}: stopping after three items makes exactly one request`, async (t) => {
    const api = await serve(t)
    const taken: string[] = []
    for await (const product of shop(pagesFor(api.base)).products.list()) {
      taken.push(product.id)
      if (taken.length === 3) break
    }
    await sleep(50)
    assert.deepEqual(taken, ['prd_101', 'prd_102', 'prd_103'])
    assert.equal(api.requests.length, 1)
  })
```

```bash
node --test iterate.test.ts
```

```text output
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The process exits with code 1 on a `GearshopError` whose `code` is `request_aborted`, after a
caller stopped early. A prefetching generator aborted its next request in `finally` but left
that promise with no handler and nothing awaiting it. Attach `.catch(() => {})` when the request starts, as
`start()` in `iterPages` does. A handler attached in `finally` comes too late for a prefetch that fails
while the caller is still working on the page before it, and a test pins that case.

```bash
node pitfall.ts
```

```text output
naive prefetch, abort in finally
  requests sent: 2, cancelled in flight: 1
  unhandled rejections: request_aborted
iterate.ts with prefetch: true
  requests sent: 2, cancelled in flight: 1
  unhandled rejections: none
```

Both versions cancel the second request on the wire. Only the naive one leaves a rejection
behind, and Node's default for an unhandled rejection is to raise it as an uncaught exception.[^3]
The script installs an `unhandledRejection` listener to count it; `node pitfall.ts --no-handler`
runs without one and exits 1, which a test asserts.

The loop never ends. The API returns a cursor it has already given, so the same page comes back
forever. The `seen` set throws `the API returned cursor cur_0003 twice` instead.

A second `for await` over the same generator object yields nothing, because a finished generator
stays finished. Return an iterable that builds a generator per loop, as `paginated` does.

## When not to do this

Do not write the generator if your generator already emits one you accept. Fern documents a
`Page<T>` for annotated operations, and a hand-written copy beside it is a second loop to keep in
step.

Do not turn on `prefetch` by default. It spends a request on every early exit, and an API that
bills or rate-limits per request charges for pages nobody reads.

Leave sdkgen's paging feature off for an API that refuses query parameters its document does not
declare. The feature sends `page=1` on the first call, so the first page can fail. Pick OpenAPI
Generator when you want no runtime dependency and a signal that reaches `fetch` without middleware.
Kiota suits a team that also ships C#, Go, Java, or Python clients and wants one request-builder
shape in all of them.

## Related how-tos

- [Loop over every page of a REST collection](/howto/loop-over-every-page-of-a-collection)

- [Describe pagination so generators can follow it](/howto/describe-pagination-in-openapi-for-generators)

- [Paginate an API with Lua coroutines](/howto/paginate-an-api-with-lua-coroutines)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Paginate an API with Python generators](/howto/paginate-an-api-with-python-generators)

## Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0, Kiota 1.39.0 with its TypeScript runtime
packages 1.0.0-preview.113 and 1.0.0-preview.114, and TypeScript 5.9.3. Every output block is what
the command preceding it printed. The three generators ran once, in `generate.sh`, and their
compiled output is committed under `generated/`. @voxgig/sdkgen 4.45.0 wrote an identical `ts/src`
tree from the same project, so it sends `page=1` too. A second Kiota 1.39.0 run, on a copy of
`api.json` with `x-ms-pageable` added, wrote the same TypeScript. Fern was not run; its row comes
from its documentation.

[^1]: The MDN page on [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)
covers a loop exited early by `break` or by a thrown error. Such a loop calls the `return()`
method of the iterator, and awaits the promise it returns before the loop exits. A `finally`
block that awaited a slow request would hold up the caller's `break` for as long as the request
took, which is why the one here aborts and awaits nothing.

[^2]: Kiota's [overview](https://learn.microsoft.com/en-us/openapi/kiota/overview) lists
TypeScript among the languages it supports. The generator run here printed that the TypeScript
language is in preview and that source breaking changes will happen with future updates, and
`kiota info` reported its maturity level as Preview. The runtime packages agree with the second
statement, down to the version string: the HTTP library installed for this page is
1.0.0-preview.114.

[^3]: Node's [command-line reference](https://nodejs.org/api/cli.html#--unhandled-rejectionsmode)
records that version 15.0.0 changed the default mode to `throw`. Before that an unhandled
rejection printed a warning and the process carried on. The mode emits `unhandledRejection` first
and raises the rejection as an uncaught exception only when no listener is set, which is why
`pitfall.ts` can count what would otherwise have stopped it.