Convert JS SDK streaming APIs from callbacks to async iterables (#545)

- [x] Convert JS SDK streaming APIs from callbacks to async iterables
- [x] Add `return()` hook to async iterators to prevent unbounded
buffering on early break
- [x] Add guards in streaming callbacks to skip work after error or
cancellation
- [x] Fix test assertions to assert synchronous throws directly
- [x] Replace O(n) `chunks.shift()` with O(1) head-index dequeue with
compaction
- [x] Guard against concurrent `next()` calls with `nextInFlight` flag
- [x] Add comment explaining native stream cancellation limitation in
`return()`
- [x] Fix docs example for `completeStreamingChat(messages, tools)`
overload to pass `tools`
- [x] Regenerate TypeDoc API docs
- [x] Type-check, code review, and security scan
- [x] Add comments explaining why local variable captures are needed
(closures lose `this`)
- [x] Add comments clarifying promise-resolve wake-up pattern in
`.then()` handler
- [x] Add structural comments explaining the AsyncIterable/AsyncIterator
factory pattern
- [x] Apply same readability improvements to chatClient.ts

<!-- START COPILOT CODING AGENT TIPS -->
---

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS
or Windows machine with [Raycast](https://gh.io/cca-raycast-docs).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: baijumeswani <12852605+baijumeswani@users.noreply.github.com>

Author: Copilot

README.md

@@ -232,9 +232,9 @@ const result = await audioClient.transcribe('recording.wav');
 console.log('Transcription:', result.text);
 
 // Or stream in real-time
-await audioClient.transcribeStreaming('recording.wav', (chunk) => {
+for await (const chunk of audioClient.transcribeStreaming('recording.wav')) {
     process.stdout.write(chunk.text);
-});
+}
 
 await whisperModel.unload();
 ```

samples/js/audio-transcription-example/app.js

@@ -39,12 +39,12 @@ console.log('\nAudio transcription result:');
 console.log(transcription.text);
 console.log('✓ Audio transcription completed');
 
-// Same example but with streaming transcription using callback
+// Same example but with streaming transcription using async iteration
 console.log('\nTesting streaming audio transcription...');
-await audioClient.transcribeStreaming('./Recording.mp3', (result) => {
+for await (const result of audioClient.transcribeStreaming('./Recording.mp3')) {
     // Output the intermediate transcription results as they are received without line ending
     process.stdout.write(result.text);
-});
+}
 console.log('\n✓ Streaming transcription completed');
 
 // Unload the model

samples/js/chat-and-audio-foundry-local/src/app.js

@@ -76,22 +76,19 @@ async function main() {
 
   // Summarize the transcription
   console.log("Generating summary...\n");
-  await chatClient.completeStreamingChat(
-    [
-      {
-        role: "system",
-        content:
-          "You are a helpful assistant. Summarize the following transcribed audio and extract key themes and action items.",
-      },
-      { role: "user", content: transcription.text },
-    ],
-    (chunk) => {
-      const content = chunk.choices?.[0]?.message?.content;
-      if (content) {
-        process.stdout.write(content);
-      }
+  for await (const chunk of chatClient.completeStreamingChat([
+    {
+      role: "system",
+      content:
+        "You are a helpful assistant. Summarize the following transcribed audio and extract key themes and action items.",
+    },
+    { role: "user", content: transcription.text },
+  ])) {
+    const content = chunk.choices?.[0]?.message?.content;
+    if (content) {
+      process.stdout.write(content);
     }
-  );
+  }
   console.log("\n");
 
   // --- Clean up ---

samples/js/native-chat-completions/app.js

@@ -41,15 +41,14 @@ console.log(completion.choices[0]?.message?.content);
 
 // Example streaming completion
 console.log('\nTesting streaming completion...');
-await chatClient.completeStreamingChat(
-    [{ role: 'user', content: 'Write a short poem about programming.' }],
-    (chunk) => {
-        const content = chunk.choices?.[0]?.message?.content;
-        if (content) {
-            process.stdout.write(content);
-        }
+for await (const chunk of chatClient.completeStreamingChat(
+    [{ role: 'user', content: 'Write a short poem about programming.' }]
+)) {
+    const content = chunk.choices?.[0]?.message?.content;
+    if (content) {
+        process.stdout.write(content);
     }
-);
+}
 console.log('\n');
 
 // Unload the model

sdk/js/README.md

@@ -69,15 +69,14 @@ console.log(completion.choices[0]?.message?.content);
 
 // Example streaming completion
 console.log('\nTesting streaming completion...');
-await chatClient.completeStreamingChat(
-    [{ role: 'user', content: 'Write a short poem about programming.' }],
-    (chunk) => {
-        const content = chunk.choices?.[0]?.message?.content;
-        if (content) {
-            process.stdout.write(content);
-        }
+for await (const chunk of chatClient.completeStreamingChat(
+    [{ role: 'user', content: 'Write a short poem about programming.' }]
+)) {
+    const content = chunk.choices?.[0]?.message?.content;
+    if (content) {
+        process.stdout.write(content);
     }
-);
+}
 console.log('\n');
 
 // Unload the model
@@ -157,15 +156,14 @@ console.log(response.choices[0].message.content);
 For real-time output, use streaming:
 
 ```typescript
-await chatClient.completeStreamingChat(
-    [{ role: 'user', content: 'Write a short poem about programming.' }],
-    (chunk) => {
-        const content = chunk.choices?.[0]?.message?.content;
-        if (content) {
-            process.stdout.write(content);
-        }
+for await (const chunk of chatClient.completeStreamingChat(
+    [{ role: 'user', content: 'Write a short poem about programming.' }]
+)) {
+    const content = chunk.choices?.[0]?.message?.content;
+    if (content) {
+        process.stdout.write(content);
     }
-);
+}
 ```
 
 ### Audio Transcription
@@ -180,9 +178,9 @@ audioClient.settings.language = 'en';
 const result = await audioClient.transcribe('/path/to/audio.wav');
 
 // Streaming transcription
-await audioClient.transcribeStreaming('/path/to/audio.wav', (chunk) => {
+for await (const chunk of audioClient.transcribeStreaming('/path/to/audio.wav')) {
     console.log(chunk);
-});
+}
 ```
 
 ### Embedded Web Service