How-to › Move data in and out

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.

Audience
Library maintainer
Level
intermediate
Topic
Paginate collections
Languages
TypeScript
Verified

Read first: Loop over every page of a REST collection

Your SDK’s list call returns one page and a next_cursor, so every caller writes the same while loop, and one of them stops after the first three of seven products. The version that prefetches the next page fails harder. When a caller breaks out early, the aborted request rejects with nothing listening, and Node ends the process.

What you get

You will end up with a list() that callers iterate with for await, an iterPages() for callers who want whole pages, and an early exit that cancels the request in flight. This is for you if you maintain a TypeScript SDK over a cursor-paged API.

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, 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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern auto-paginationYou generate with Fern and can annotate each list operation with x-fern-paginationRemote generation needs a login or guest session, local needs Docker or Podman, and each paged operation needs an annotationYou cannot add vendor extensions to the document
hand-written async generatorAny client, generated or not, and you want to own early exit and cancellationAbout fifty lines of code you test yourself, plus one page function per clientYour generator already emits an iterator whose shape you accept
KiotaOne request-builder shape across C#, Go, Java, Python, and TypeScript clientsNo paging helper, and no cancellation signal until you add a middleware and a request optionYou want cancellation without touching the HTTP layer
OpenAPI GeneratorYou want typescript-fetch output that runs on the platform fetch aloneNo paging helper, so each list method gets a page function written by handYou want one iterator shape generated for every list method
sdkgen paging featureThe SDK comes from sdkgen and you want its cursor handling in every targetReads the cursor for you, yields one page per call, and sends an undeclared page parameterThe 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 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.

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.

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 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.

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.

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 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 gives the substitute: a handler with execute(url, requestInit, requestOptions), added with handlers.unshift(...) before KiotaClientFactory.create.

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.

node demo.ts
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:

  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)
  })
node --test iterate.test.ts
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.

node pitfall.ts
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.

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.

Footnotes

  1. The MDN page on 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. ↩︎ Back to text

  2. Kiota’s 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. ↩︎ Back to text

  3. Node’s command-line reference 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.