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

Source: https://voxgig.com/howto/expose-a-streaming-response-through-a-generated-sdk

- Audience: library-maintainer
- Level: advanced
- Languages: typescript, python, go
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://github.com/ndjson/ndjson-spec), 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](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader/cancel) | 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](https://openapi-generator.tech/docs/generators/typescript-fetch/) | 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](https://orval.dev/docs/guides/stream-ndjson/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | 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.

```bash title="generate.sh"
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:

```python title="generated/py/event_entity.py"
    def stream(self, action, args=None, callopts=None):
```

```go title="generated/go/event_entity.go"
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
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.

```bash
node demo.mjs
```

```text output
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:

```python title="generated/py/streaming_feature.py"
    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:

```js title="ndjson.mjs"
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()`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamDefaultReader/cancel)
closes the connection. The Python twin is a generator over
[`http.client`](https://docs.python.org/3/library/http.client.html) that closes the connection in
its own `finally`. The Go twin sends on a channel and stops when its
[`context`](https://pkg.go.dev/context) is cancelled. Each checks the same three things against its
own stand-in:

```bash
python3 py/check.py
```

```text output
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']
```

```bash
go -C go run .
```

```text output
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:

```ts title="other/openapi-generator-DefaultApi.ts"
    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](https://orval.dev/docs/guides/stream-ndjson/) 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:

```ts title="other/orval-feed.ts"
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`](https://orval.dev/docs/guides/set-base-url/) 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:

```bash
node other.mjs
```

```text output
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.

```bash
node --test stream.test.mjs
```

```text output
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:

```bash
node pitfall.mjs
```

```text output
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:

```js title="sdk.mjs"
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

- [Pick SSE, WebSockets, or long polling for a live endpoint](/howto/choose-sse-websockets-or-long-polling)

- [Retry a streaming response without replaying received data](/howto/retry-a-streaming-response-without-replaying-data)

- [Consume Server-Sent Events with fetch and custom headers](/howto/consume-sse-with-fetch-and-custom-headers)

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

- [Audit SDK retry and timeout defaults before adoption](/howto/audit-sdk-retry-and-timeout-defaults)

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

[^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](https://www.rfc-editor.org/rfc/rfc7464.html) 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.

[^2]: The [java generator page](https://openapi-generator.tech/docs/generators/java/) 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.