How-to › Move data in and out

How to expose a streaming response through a generated SDK#

Give a streaming endpoint an iterator in TypeScript, Python, and Go that yields as lines arrive, closes the connection on cancel, and raises on a cut body.

Audience
Library maintainer
Level
advanced
Topic
Stream responses and subscriptions
Languages
TypeScript, Python and Go
Verified

Read first: Pick SSE, WebSockets, or long polling for a live endpoint, Retry a streaming response without replaying received data

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written iterators per languageEvents must reach the caller as the server writes themOne parser per language to keep in step, and three cancellation idioms to testThe response fits in memory and arrives quickly
OpenAPI Generator Raw methodsYou already ship its typescript-fetch clientlistEventsRaw() returns the unread Response, so every caller writes the parserYou want one iterator shape across every language you ship
orval NDJSON streamA TypeScript-only client and an operation documented as NDJSONA typed Response with its body unread, fetch client only, and the parser left to youYou ship more than TypeScript
sdkgen stream() methodSeveral targets, list results, and one method name for all of themWaits for the whole body, and with the streaming feature on a cut body ends with no errorEvents 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.

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

  1. 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 for application/x-ndjson, the type the sample’s server sends. ↩︎ Back to text

  2. The java generator page lists supportStreaming with the description “Support streaming endpoint (beta)” and a default of false. It is one option of the Java generator alone, because each generator in the project keeps its own options table. ↩︎ 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.