Your build-events endpoint writes one JSON object per line for minutes at a time. The generated
listEvents hands every caller a raw response body, so each team writes its own line parser. One
of them breaks out of the loop early and leaves the connection open. Another treats a dropped
connection as the end of the feed.
What you get
You will know what sdkgen’s stream() waits for in TypeScript, Python, and Go, and have an NDJSON
iterator, tested for cancellation and truncation, for events that cannot wait. This is for you if
you maintain an SDK whose callers read long responses.
Short answer
Every entity in an sdkgen SDK has a stream('list') method in TypeScript, Python, and Go. It
yields only after the whole body is parsed, and its streaming feature makes a cut body end the
stream with no error. For events the caller needs as they are written, read NDJSON from the SDK’s
prepare() in a hand-written iterator. It closes the connection on break and raises on a cut body.
You will need
Node 22 or later, Python 3.10 or later, Go 1.22 or later, and an endpoint that streams NDJSON.
The sample’s api.json offers GET /events as a JSON array and as
NDJSON, one event per line.1 Choosing a framing at all
is the subject of picking SSE, WebSockets, or long polling, linked below.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-written iterators per language | Events must reach the caller as the server writes them | One parser per language to keep in step, and three cancellation idioms to test | The response fits in memory and arrives quickly |
| OpenAPI Generator Raw methods | You already ship its typescript-fetch client | listEventsRaw() returns the unread Response, so every caller writes the parser | You want one iterator shape across every language you ship |
| orval NDJSON stream | A TypeScript-only client and an operation documented as NDJSON | A typed Response with its body unread, fetch client only, and the parser left to you | You ship more than TypeScript |
| sdkgen stream() method | Several targets, list results, and one method name for all of them | Waits for the whole body, and with the streaming feature on a cut body ends with no error | Events must arrive while the response is still open |
Voxgig maintains sdkgen. It is one of four options here, not the recommendation.
The generated method buys every language the same name, at the price of waiting for the last
byte. The raw body costs each caller a parser, and in exchange it survives
a server that changes its framing, because the parser is yours to change. OpenAPI Generator and
orval both stop at the raw Response.
Generate stream() in every target
Scaffold with the streaming feature and the three targets, then add retry, which the last
section needs.
npx --yes @voxgig/create-sdkgen@0.31.9 feed --def api.json -t ts -t py -t go -f streaming
(cd feed-sdk/.sdk && npx voxgig-sdkgen feature add retry && npm run generate)
Every entity has a stream(action, args, callopts) method. In TypeScript it is an async
generator, in Python a generator, and in Go a function returning a channel:
def stream(self, action, args=None, callopts=None):
func (e *EventEntity) Stream(action string, args map[string]any, callopts map[string]any) <-chan core.StreamItem {
The method is there with the feature off, and then yields from the list the operation returned,
as the features reference
says. A client turns the feature on with feature: { streaming: { active: true } }. It then
supplies the items for the operations its ops option names, list by default, and adds
chunkSize for batches. A signal in callopts ends the iteration, and in TypeScript it also
cancels the request in flight.
Read what stream() waits for
demo.mjs reads the same five events twice from a stand-in server that writes one every 40 ms.
Each row says how many events the server had written when the caller received that one.
node demo.mjs
sdkgen Event().stream('list'), JSON array
e1 queued server had written 5 of 5
e2 started server had written 5 of 5
e3 compiled server had written 5 of 5
e4 tested server had written 5 of 5
e5 finished server had written 5 of 5
hand-written ndjsonEvents over sdk.prepare(), NDJSON
e1 queued server had written 1 of 5
e2 started server had written 2 of 5
e3 compiled server had written 3 of 5
e4 tested server had written 4 of 5
e5 finished server had written 5 of 5
accept headers the server saw: application/json | application/x-ndjson
The sdkgen iterator yields entities one at a time from a list that has already been parsed. The Python feature shows it plainly:
def _iterate(self, result):
chunk_delay = self.options.get("chunkDelay") or 0
chunk_size = self.options.get("chunkSize") or 0
# Read lazily so downstream result processing is reflected.
items = result.resdata if isinstance(result.resdata, list) else []
The Go feature does the same into a channel buffered to the item count. The features reference says the feature spares a caller “materialising the whole array” but the array it reads, in all three targets, is the one the operation has already built. That design makes a retry safe, because no item reaches the caller before the request has succeeded.
Read the body as it arrives with prepare()
prepare() builds the request the SDK would send, with its URL and credentials, and sends
nothing. The iterator takes it from there, and ndjsonBody parses any fetch body, which the next
two sections reuse:
export async function* ndjsonEvents(sdk, { signal, after } = {}) {
const req = await sdk.prepare({
path: '/events',
method: 'GET',
headers: { accept: 'application/x-ndjson' },
})
const url = new URL(req.url)
if (after != null) url.searchParams.set('after', after)
const res = await fetch(url, { method: req.method, headers: req.headers, signal })
if (!res.ok) throw new Error(`GET /events answered ${res.status}`)
yield* ndjsonBody(res.body, { signal })
}
// Parses any fetch Response body as NDJSON, so it also serves the Response
// that another generator's client hands back unread.
export async function* ndjsonBody(body, { signal } = {}) {
const reader = body.pipeThrough(new TextDecoderStream()).getReader()
let buffered = ''
try {
while (true) {
let chunk
try {
chunk = await reader.read()
} catch (err) {
if (signal?.aborted) return
throw new TruncatedStream('the connection closed before the stream ended', err)
}
if (chunk.done) break
buffered += chunk.value
let nl
while ((nl = buffered.indexOf('\n')) >= 0) {
const line = buffered.slice(0, nl).trim()
buffered = buffered.slice(nl + 1)
if (line !== '') yield JSON.parse(line)
}
}
if (buffered.trim() !== '') {
throw new TruncatedStream(`the stream ended mid-line: ${JSON.stringify(buffered.slice(0, 20))}`)
}
} finally {
// Runs on break, return, throw and abort alike.
await reader.cancel().catch(() => {})
}
}
The finally is the cancellation story. A break in the caller’s loop runs it, and
cancel()
closes the connection. The Python twin is a generator over
http.client that closes the connection in
its own finally. The Go twin sends on a channel and stops when its
context is cancelled. Each checks the same three things against its
own stand-in:
python3 py/check.py
ok yields each event as it is written [1, 2, 3, 4, 5]
ok break closes the connection
ok a dropped connection raises after ['e1', 'e2']
go -C go run .
ok yields each event as it is written [1 2 3 4 5]
ok cancelling the context closes the connection
ok a dropped connection sends ErrTruncated after [e1 e2]
Read the raw response from OpenAPI Generator
OpenAPI Generator’s typescript-fetch page lists no streaming option, and its java generator
offers supportStreaming, marked beta.2 What typescript-fetch wrote for this document is a
Raw twin of each method:
async listEventsRaw(requestParameters: ListEventsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Array<Event>>> {
const requestOptions = await this.listEventsRequestOpts(requestParameters);
const response = await this.request(requestOptions, initOverrides);
return new runtime.JSONApiResponse(response, (jsonValue) => jsonValue.map(EventFromJSON));
}
JSONApiResponse keeps the Response as raw and reads it only when value() is called, so
raw.body can go to ndjsonBody. Set the Accept header through initOverrides, and pass a
function that spreads init.headers. An object in its place replaces every header the client
built, the credential from Configuration included.
This generator is the better fit when you already ship its clients in many languages and want one extra parser, not a second generator.
Read the stream field from orval
orval’s NDJSON guide says it supports NDJSON with
the fetch client only and leaves parsing to you. For this document it returned the Response
unread for both media types:
export const listEvents = async (params?: ListEventsParams, options?: RequestInit): Promise<listEventsResponse> => {
const stream = await fetch(getListEventsUrl(params),
{
...options,
method: 'GET'
}
);
return { status: stream.status, stream, headers: stream.headers } as listEventsResponse
}
The type for the JSON answer promises a data field that this function never sets. No Accept
header is set, so pass it in options. Without a
baseUrl the URL is a bare /events, so
orval.config.cjs takes it from FEED_BASE. other.mjs runs both clients, compiled, against the
stand-in:
node other.mjs
OpenAPI Generator listEventsRaw(), events as written
initOverrides function 1 2 3 4 5 credential kept
initOverrides object 1 2 3 4 5 credential dropped
orval listEvents(), events as written
options.headers 1 2 3 4 5 credential kept
orval is the better choice for a TypeScript-only client that already uses its query hooks.
Check it worked
Thirteen tests cancel mid-stream and assert that the stand-in saw the socket close. They also cut the body after two events, run the other two generators’ clients, and compare a naive retry with a resume.
node --test stream.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
The cancel tests assert on the server’s count of closed sockets, and also that it stopped writing before the fifth event.
When it goes wrong
With the streaming feature on, a dropped connection ends the sdkgen stream as if the feed were
empty. The body failed to parse, so the feature has no list to iterate. list() on the same
response raises, and so does stream() with the feature off:
node pitfall.mjs
connection dropped after 2 of 5 events
sdkgen Event().list() raises response_body_read
sdkgen stream('list'), feature off 0 events, then raises response_body_read
sdkgen stream('list'), feature on ends after 0 events, no error
feature on, with raiseOnBrokenBody 0 events, then raises response_body_read
hand-written ndjsonEvents 2 events, then raises TruncatedStream
retrying after the drop
naive retry e1 e2 e1 e2 e3 e4 e5 (after= -, -)
resume from last id e1 e2 e3 e4 e5 (after= -, e2)
sdkgen stream('list') with retry, first answer 503: e1 e2 e3 e4 e5 over 2 requests
Leave the feature off, or keep it for chunkSize and add a hook to the client’s extend list
that re-raises the stored error:
export const raiseOnBrokenBody = {
PreResult(ctx) {
const result = ctx.result
const inner = result?.stream
if (typeof inner !== 'function') return
result.stream = async function* () {
if (result.err) throw result.err
yield* inner()
}
},
}
The second failure is a retry wrapped around an iterator that has already yielded. The naive
wrapper replays e1 and e2. Exclude streaming calls from it, or resume with the last event id,
as resumingEvents does with the API’s after parameter. sdkgen’s own retry is safe here only
because its stream yields nothing until the body is whole.
When not to do this
Do not hand-write three iterators for a response that fits in memory and arrives in a second.
sdkgen’s stream('list') gives you one method name per target, and its buffering costs nothing at
that size.
Do not reach for sdkgen’s stream() when events must arrive while the response is open. Build
logs and model tokens are two such feeds. It waits for the last byte. With the streaming feature
on and no hook, a dropped connection also reads as an empty feed.
Do not wrap a retry around a stream that has no event ids. Without a point to resume from, a retry replays what the caller has already processed.
Pick OpenAPI Generator when you already ship its clients and want one parser beside them, and orval when the client is TypeScript only.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, Python 3.13.18, Go 1.24.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0 through its npm wrapper
2.42.2, orval 8.48.0, and TypeScript 5.9.3. Every output block is what the command preceding it
printed. The generators ran once, through generate.sh, and their output is committed. The
OpenAPI Generator and orval clients run compiled in other.mjs and the tests. The generated
Python and Go SDKs were not run on the page; it quotes their source.
Footnotes
-
The NDJSON specification is a README with a version number, 1.0.0, and a last update of 2014-10-19. Its introduction says there is no standard for transporting JSON texts in a stream protocol, apart from WebSockets. RFC 7464 supplied one in February 2015, as
application/json-seq, with a record separator before each text and a line feed after it as a canary for truncation. The NDJSON README asks forapplication/x-ndjson, the type the sample’s server sends. ↩︎ Back to text -
The java generator page lists
supportStreamingwith the description “Support streaming endpoint (beta)” and a default offalse. It is one option of the Java generator alone, because each generator in the project keeps its own options table. ↩︎ Back to text