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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Fern 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 | 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 | 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 | 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 | 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
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.
Related how-tos
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
-
The MDN page on
for await...ofcovers a loop exited early bybreakor by a thrown error. Such a loop calls thereturn()method of the iterator, and awaits the promise it returns before the loop exits. Afinallyblock that awaited a slow request would hold up the caller’sbreakfor as long as the request took, which is why the one here aborts and awaits nothing. ↩︎ Back to text -
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 inforeported 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 -
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 emitsunhandledRejectionfirst and raises the rejection as an uncaught exception only when no listener is set, which is whypitfall.tscan count what would otherwise have stopped it. ↩︎ Back to text