feat(typespec-ts): streaming

[Libba Lawrence (l0lawrence)]

Summary

Adds structured JSONL + SSE streaming code generation to the @azure-tools/typespec-ts modular emitter. A response whose TCGC metadata indicates a structured stream now generates a Promise<AsyncIterable<T>> of deserialized items/events instead of returning the raw binary Uint8Array body.

What is generated

• JSONL (JsonlStream<T>) -> Promise<AsyncIterable<T>> that lazily decodes JSON Lines.
• SSE (SSEStream<T>) -> Promise<AsyncIterable<...>> that dispatches each Server-Sent Event by its event: name (via @azure/core-sse), deserializes the payload, and stops at the terminal event. Full heterogeneous multi-event dispatch and @terminalEvent handling are supported (named terminals keyed on the terminal flag; unnamed data: [DONE] sentinel terminals). Generation is driven by TCGC streamMetadata / sseMetadata.

Operations connect eagerly (HTTP status/errors surface at call time) and decode the body lazily.

Implementation

• New static helpers static/static-helpers/streamingHelpers.ts (getStreamResponse, readJsonlStream, ensureStreamStatus) and sseStreamingHelpers.ts (readSseStream, SseEventDescriptor), registered in static-helpers-metadata.ts and loaded only when the package has a structured-stream operation (packageHasStructuredStreaming / packageHasSseStreaming, side-effect-free metadata checks). sseStreamingHelpers.ts is the only file importing @azure/core-sse.
• operation-helpers.ts: getStructuredStreamInfo resolves stream metadata (gated purely on response.streamMetadata / sseMetadata); branches in the operation and deserialize builders emit the AsyncIterable shape.
• @azure/core-sse added to AzureCoreDependencies and injected into the generated package's dependencies only when an SSE op is present.

[github-actions]

All changed packages have been documented.

• ✅ @azure-tools/typespec-ts

Show changes

@azure-tools/typespec-ts - feature ✏️

Generate structured JSONL and SSE streaming operations by default. A JSONL or SSE stream response now returns Promise<AsyncIterable<T>> of deserialized items/events instead of the previous raw binary Uint8Array body. An operation returning JsonlStream<T> lazily decodes JSON Lines into AsyncIterable<T>, and an operation returning SSEStream<T> returns an AsyncIterable of the event payload types, dispatching each Server-Sent Event by its event: name (using @azure/core-sse), deserializing each payload, and stopping at the terminal event. This is the default behavior — there is no opt-in option.

[github-actions]

📦 Package size report

1 package changed size, +12.43 KB (+0.1%) packed overall.

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-ts	527.17 KB → 538.77 KB	+11.59 KB (+2.2%) 🔴	2.54 MB → 2.59 MB	+54.04 KB (+2.1%) 🔴

12 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-client-generator-core	227.76 KB → 228.79 KB	+1.03 KB (+0.5%)	1.23 MB → 1.23 MB	+1.85 KB (+0.1%)
@azure-tools/typespec-go	258.55 KB → 258.42 KB	-138 B (-0.1%)	1.32 MB → 1.32 MB	-671 B (-0.0%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	-76 B (-0.0%)	15.03 MB → 15.03 MB	+65 B (+0.0%)
@azure-tools/typespec-python	42.20 KB → 42.22 KB	+20 B (+0.0%)	164.85 KB → 164.91 KB	+65 B (+0.0%)
@azure-tools/typespec-azure-portal-core	42.40 KB → 42.41 KB	+1 B (+0.0%)	192.91 KB → 192.91 KB	—
@azure-tools/azure-http-specs	146.63 KB → 146.63 KB	—	1.16 MB → 1.16 MB	—
@azure-tools/typespec-autorest	80.93 KB → 80.93 KB	—	395.06 KB → 395.06 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-core	129.43 KB → 129.43 KB	—	702.77 KB → 702.77 KB	—
@azure-tools/typespec-azure-resource-manager	171.92 KB → 171.92 KB	—	1.04 MB → 1.04 MB	—
@azure-tools/typespec-azure-rulesets	5.16 KB → 5.16 KB	—	32.09 KB → 32.09 KB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—

_{Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included.
🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-ts@5196

commit: c96ee67

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website

[Libba Lawrence (l0lawrence)]

is there anything else that should be added?

[Maor Leger (maorleger)]

This is coming along quite nicely!! Thanks so much for all the effort in getting this together.

I still have lots to review, but the overall direction seems ok. I noted a few findings that we should fix though

[Maor Leger (maorleger)]

I'm not sure, but would it be better to use the contentTypes in SdkStreamMetadata to determine whether this is an sse or jsonl stream?

• application/jsonl
• text/event-stream

I just worry that something like a custom stream template might be incorrectly interpreted as jsonl but we should verify, I might just be thinking about it wrong and it may be a non-issue

[Maor Leger (maorleger)]

Can you have a terminal event with data / model? If so, would this lose type information?

To help me understand a bit, I asked and decided to shamelessly paste its output here verbatim 😄

 terminal event *with a model payload* still gets a deserializer. The helper yields it before the
generator returns (`sseStreamingHelpers.ts:78-85`). Executed against the PR's own helper bodies:

| Case | Observed | Problem |
| --- | --- | --- |
| Terminal event, model payload | `[{desc:"a"}, {desc:"FINAL"}]` | Yielded, but its type is absent from the declared union — unsound |
| Terminal event, primitive payload | `[{desc:"a"}]` | Silently dropped — inconsistent with the model case |
| Unrelated `event: delta` carrying `data: [DONE]` | `[]` | Sentinel matched on data only; the wrong event ends the stream |

The third case happens because the terminal check runs before descriptor matching. It ignores the
event name.

**Impact**: a typed terminal event often carries the final logical result. Runtime delivers it, but
the type system cannot see it. Consumers need a cast to narrow to it.

**Fix**: `@terminalEvent` says only that the client must disconnect. It does not dictate whether the
triggering event is yielded. Pick one policy: yield typed terminal events, or consume all terminal
events internally. Then make the runtime value, declared item union, and primitive/model paths
match. Name-sensitive sentinel matching is secondary hardening, not part of the blocker.

> **Cross-language note**: matching the terminal by data value mirrors Python's `terminal_event`
> with `event.data == self._terminal_event`. That half is a deliberate shared choice. Raise
> name-matching with both languages.

[Libba Lawrence (l0lawrence)]

So from my understanding the case we are supporting now is something like the following:

data: hello this is blah

data: [DONE]

where @terminalEvent in typespec is defined as "[DONE]"

[Maor Leger (maorleger)]

I see, ok so as long as we're guaranteeing that the terminal event is just a sentinel value and doesnt carry data this should be fine. Thanks for confirming! 👍

[Libba Lawrence (l0lawrence)]

I went looking at the search typespec instead of just the spector tests and my understanding is actually wrong they have a terminal event as a model not a literal in their typespec that this would need to support:

@terminalEvent
response.completed: KnowledgeBaseResponseCompletedEvent

so I believe we want to yield it to look like:

{event: response.completed; data: KnowledgeBaseResponseCompletedEvent} ?

[Maor Leger (maorleger)]

Oh nice find!! Thanks for digging into it. And yea, what you're proposing makes sense at first glance but I trust your judgement

[Maor Leger (maorleger)]

I think we probably want to keep the event name for better type information?

Something like:

export type NamedReceiveEvent =
  | { event: "responseCreated"; data: ResponseCreated }
  | { event: "responseDelta"; data: ResponseDelta };

Will allow the user to narrow down the event based on the kind like in this playground

In general it's probably better to keep the envelope shape if one is defined. I noticed TCGC has that information. I think JSONL needs to stay payload only though

[Libba Lawrence (l0lawrence)]

you can have named and unamed events here based on the spector test like Info vs responseCreated: Info - so if there is an unamed event it will just be the payload as well

[Maor Leger (maorleger)]

I see, but for the case of an envelope see here, just scrolling down a bit how do we represent it in other languages? Do we drop the envelope there as well and just return the payload?

[Libba Lawrence (l0lawrence)]

It looks like we dont have spector tests for envelope scenarios yet (@data), so at least in python I did not have support for them yet

[Maor Leger (maorleger)]

hmm ok so if there's a JSON parse error, the customer loses all information about the event like event name, status, etc.

This is minor, since it involves an edge case (invalid JSON payload) but still, would it make sense to throw a more useful error here?

try {
      const payload = event.data
        ? isJsonContentType(descriptor.contentType)
          ? JSON.parse(event.data)
catch (e) {
    throw new Error(`Unable to deserialize event ${event.event} as JSON", { cause: e });
}
   ...

Or something along those lines?