Skip to content

feat(typespec-ts): streaming - #5196

Merged
Libba Lawrence (l0lawrence) merged 36 commits into
Azure:release/october-2026from
l0lawrence:l0lawrence-vigilant-system
Oct 16, 2026
Merged

Libba Lawrence (l0lawrence) merged 36 commits into
Azure:release/october-2026from
l0lawrence:l0lawrence-vigilant-system

Conversation

@l0lawrence

@l0lawrence Libba Lawrence (l0lawrence) commented Aug 10, 2026 •

Copy link
Copy Markdown
Member

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. Does not contain reconnection support - depends on createStreamSSE(). Azure Search, the library requesting this feature, does not support reconnection at this point in time.

The sse spec this is based on: https://html.spec.whatwg.org/multipage/server-sent-events.html

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.

Issues for the future:
#5660 #5659

Related pr to core for abort signal/canceling stream: Azure/azure-sdk-for-js#40238

@microsoft-github-policy-service microsoft-github-policy-service Bot added the emitter:typescript Issues for @azure-tools/typespec-ts emitter label Aug 10, 2026
@l0lawrence Libba Lawrence (l0lawrence) changed the title feat(typespec-ts): generate structured JSONL and SSE streaming by default feat(typespec-ts): streaming Aug 10, 2026
@github-actions

github-actions Bot commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

❌ There is undocummented changes. Run chronus add to add a changeset or click here.

The following packages have changes but are not documented.

  • ❌@azure-tools/typespec-autorest
  • ❌@azure-tools/typespec-azure-examples
  • ❌@azure-tools/typespec-java

The following packages have already been documented:

  • ✅ @azure-tools/typespec-ts
Show changes

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

Generate JSONL and SSE operations returning Promise<AsyncIterable<T>> of deserialized items or events instead of raw byte streams, with eager HTTP validation and terminal-event handling.

@github-actions

github-actions Bot commented Aug 10, 2026 •

Copy link
Copy Markdown
Contributor

📦 Package size report

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

Package Packed (base → head) Δ Packed Unpacked (base → head) Δ Unpacked
@azure-tools/typespec-ts 531.38 KB → 550.37 KB +18.99 KB (+3.6%) 🔴 2.67 MB → 2.75 MB +83.86 KB (+3.1%) 🔴
13 package(s) with no notable change
Package Packed (base → head) Δ Packed Unpacked (base → head) Δ Unpacked
@azure-tools/typespec-azure-examples 62.67 KB → 62.66 KB -7 B (-0.0%) 309.27 KB → 309.27 KB —
@azure-tools/azure-http-specs 143.50 KB → 143.50 KB — 1.20 MB → 1.20 MB —
@azure-tools/typespec-autorest 87.87 KB → 87.87 KB — 424.17 KB → 424.17 KB —
@azure-tools/typespec-autorest-canonical 7.42 KB → 7.42 KB — 26.00 KB → 26.00 KB —
@azure-tools/typespec-azure-core 134.23 KB → 134.23 KB — 724.20 KB → 724.20 KB —
@azure-tools/typespec-azure-portal-core 36.26 KB → 36.26 KB — 242.62 KB → 242.62 KB —
@azure-tools/typespec-azure-resource-manager 184.13 KB → 184.13 KB — 1.11 MB → 1.11 MB —
@azure-tools/typespec-azure-rulesets 5.50 KB → 5.50 KB — 33.69 KB → 33.69 KB —
@azure-tools/typespec-client-generator-core 241.87 KB → 241.87 KB — 1.29 MB → 1.29 MB —
@azure-tools/typespec-go 263.66 KB → 263.66 KB — 1.35 MB → 1.35 MB —
@azure-tools/typespec-java 20.21 MB → 20.21 MB — 22.51 MB → 22.51 MB —
@azure-tools/typespec-metadata 15.91 KB → 15.91 KB — 62.26 KB → 62.26 KB —
@azure-tools/typespec-python 42.21 KB → 42.21 KB — 164.90 KB → 164.90 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

pkg-pr-new Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

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

commit: 486979e

@azure-sdk-automation

Copy link
Copy Markdown
Contributor

You can try these changes here

🛝 Playground 🌐 Website

@maorleger Maor Leger (maorleger) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@microsoft-github-policy-service microsoft-github-policy-service Bot added the stale Mark a PR that hasn't been recently updated and will be closed. label Sep 4, 2026
@microsoft-github-policy-service

Copy link
Copy Markdown

Hi @Libba Lawrence (@l0lawrence). Your PR has had no update for 14 days and it is marked as a stale PR. If it is not updated within 14 days, the PR will automatically be closed. If you want to refresh the PR, please remove the stale label.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved critical and moderate streaming-generation and runtime issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds structured JSONL and SSE streaming generation for the TypeScript emitter, producing lazy AsyncIterable responses with deserialization and terminal-event handling.

Changes:

  • Adds Node, browser, and React Native streaming helpers.
  • Integrates stream metadata and conditional @azure/core-sse dependencies.
  • Adds scenarios, tests, generated baselines, configuration, and changelog updates.
File summaries
File Summary
pnpm-workspace.yaml Adds the SSE dependency catalog entry.
pnpm-lock.yaml Locks streaming-related dependencies.
packages/typespec-ts/test/util/test-util.ts Adds streaming test-library support.
packages/typespec-ts/test/modular-unit/scenarios/operations/streaming.md Adds JSONL and SSE generation scenarios.
packages/typespec-ts/test/azure-modular-integration/streaming-sse.test.ts Adds SSE integration coverage.
packages/typespec-ts/test/azure-modular-integration/generated/streaming/sse/tspconfig.yaml Configures the generated SSE fixture.
packages/typespec-ts/test/azure-modular-integration/generated/streaming/sse/src/index.d.ts Adds the generated SSE API baseline.
packages/typespec-ts/test/azure-modular-integration/generated/streaming/sse/.gitignore Tracks generated fixture artifacts.
packages/typespec-ts/test-next/unit/static-helpers/sse-streaming-helpers.test.ts Tests SSE helper behavior.
packages/typespec-ts/static/static-helpers/streamingHelpers.ts Implements Node JSONL streaming; includes a moderate decoder-flush issue and a nit for missing JSONL coverage.
packages/typespec-ts/static/static-helpers/streamingHelpers-react-native.mts Re-exports browser streaming helpers for React Native.
packages/typespec-ts/static/static-helpers/streamingHelpers-browser.mts Implements browser streaming; has moderate cancellation and decoder-flush issues.
packages/typespec-ts/static/static-helpers/sseStreamingHelpers.ts Implements SSE parsing, dispatch, and termination.
packages/typespec-ts/static/static-helpers/sseStreamingHelpers-react-native.mts Provides React Native SSE exports.
packages/typespec-ts/static/static-helpers/sseStreamingHelpers-browser.mts Provides browser SSE exports.
packages/typespec-ts/src/modular/static-helpers-metadata.ts Registers streaming helper metadata.
packages/typespec-ts/src/modular/helpers/operation-helpers.ts Generates streaming operations and deserializers; has two critical and two moderate unresolved issues involving envelopes, content types, response options, and modeled errors.
packages/typespec-ts/src/modular/external-dependencies.ts Registers the SSE runtime dependency.
packages/typespec-ts/src/index.ts Loads helpers and injects dependencies conditionally.
packages/typespec-ts/spector.config.yaml Enables the SSE Spector scenario.
packages/typespec-ts/package.json Declares streaming-related dependencies.
.chronus/changes/structured-jsonl-sse-streaming-2026-7-30-0-0-0.md Documents the streaming feature.
Review details

Files not reviewed (1)

  • pnpm-lock.yaml: Generated file

Suppressed comments (3)

packages/typespec-ts/src/modular/helpers/operation-helpers.ts:925

  • This early return bypasses the existing enableStorageCompat and includeHeadersInResponse handling below. Structured-stream operations therefore never install the storage-compat onResponse interceptor, never return the configured response/header metadata, and silently ignore those emitter options, unlike the existing streaming response path. Support these options for structured streams or reject/document the incompatible combination instead of silently changing the contract.
  const structuredStreamInfo = getStructuredStreamInfo(context, operation);
  if (structuredStreamInfo) {

packages/typespec-ts/static/static-helpers/streamingHelpers-browser.mts:78

  • The browser implementation has the same unflushed TextDecoder state: a UTF-8 code point split at end-of-stream is not emitted before the trailing JSONL fragment is parsed. Flush the decoder before reading buffer after the loop.
    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });

packages/typespec-ts/static/static-helpers/streamingHelpers.ts:52

  • TextDecoder.decode(..., { stream: true }) can retain a partial UTF-8 sequence at the end of the body. Because the decoder is never flushed after the loop, a multibyte character split across the final chunk is silently dropped/replaced before the last JSON line is parsed. Flush the decoder before processing buffer after iteration.
    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
  • Files reviewed: 18/22 changed files
  • Comments generated: 5
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@microsoft-github-policy-service

Copy link
Copy Markdown

Hi @Libba Lawrence (@l0lawrence). This PR will be closed since it has had no update for 28 days. If this change is still relevant, please reopen the PR.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 4 High severity · 7 Medium severity · 2 Low severity

Open (13)
Files not reviewed (1)
  • pnpm-lock.yaml: Generated file

@microsoft-github-policy-service microsoft-github-policy-service Bot added the lib:tcgc Issues for @azure-tools/typespec-client-generator-core library label Oct 5, 2026
Remove obsolete protocol skip detection and compatibility casts. Assert explicit @DaTa payloads and full-model SSE events independently through EOF using generated operation types.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Use ordinary JSON.stringify quoting instead of custom script-embedding escapes. Remove the dedicated utility and exotic-metadata tests while preserving SSE Spector coverage.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Include terminal constants in generated return types and yield them before stopping. Preserve named event envelopes with the default message name for unnamed terminals, keep unnamed streams payload-only, and update runtime, snapshots and Spector coverage.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
…tream on terminal event

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bbec15a-04ed-41e4-9fae-e27932b80317
Handle unnamed constant payloads and declared bodyless SSE responses, preserve exact public method names, and avoid the contentType local collision. Keep dedicated nullable SSE payload support deferred and shorten the changelog.
Drop three transport-prefetch assertions that depend on core-sse and Node scheduling. Preserve the existing terminal cleanup and typed cutoff coverage.
@JialinHuang803 Jialin Huang (JialinHuang803) removed stale Mark a PR that hasn't been recently updated and will be closed. emitter:java Issues for @azure-tools/typespec-java emitter labels Oct 16, 2026

@maorleger Maor Leger (maorleger) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for pushing this along!!

@l0lawrence
Libba Lawrence (l0lawrence) merged commit d30e2a6 into Azure:release/october-2026 Oct 16, 2026
44 checks passed
Jialin Huang (JialinHuang803) added a commit that referenced this pull request Oct 19, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

## Summary

Prepare the October release-branch publication of
`@azure-tools/typespec-ts@0.58.0` for the streaming functionality merged
in #5196.

- Bump only `@azure-tools/typespec-ts` from `0.57.1` to `0.58.0`.
- Generate the changelog entry for JSONL and SSE streaming and consume
its Chronus change description.
- Leave all other package versions, `core`, and `pnpm-lock.yaml`
unchanged.

Generated with:
```sh
pnpm chronus version --ignore-policies --only "@azure-tools/typespec-ts"
```

## Validation

- `pnpm format` passed.
- `git diff --check` passed; verified exactly the three expected release
files changed and no TypeScript package changes remain pending in
Chronus.
- `pnpm lint` was attempted but blocked by the missing `vite/client`
type definition in `packages/typespec-azure-playground-website`. Full
dependency installation could not complete because the registry download
for `@fluentui/react-icons@2.0.339` stalled; fetching it from npm also
failed with a TLS handshake error. The cached root release tools and
formatter prerequisites were restored successfully.

## Release

Target: **`release/october-2026`**, not `main`. The `0.58.0` minor
version is intentional because #5196 is a feature.

After CI and approval, **squash merge** this PR to trigger publication.
Verify npm publication, then open the automatically generated
`backmerge/release/october-2026-YYYY-MM-DD` branch as a PR into `main`
and **rebase merge** it.

Copilot-Session: bdcbe5ce-69fd-4bac-8980-7c2d1a73dc34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:autorest Issues for @azure-tools/typespec-autorest emitter emitter:typescript Issues for @azure-tools/typespec-ts emitter lib:tcgc Issues for @azure-tools/typespec-client-generator-core library meta:website TypeSpec.io updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants