Async Iterators for Streaming in the TypeScript SDK

Consume message deltas with for-await loops instead of manual event listeners.

Summary

The @anthropic-ai/sdk package streams responses from Claude as a sequence of events, and the modern way to consume them is a for await...of loop over the stream object returned by client.messages.stream(...).

Older SDK versions and many tutorials wire up streaming with .on('text', ...) style event listeners, borrowed from Node's EventEmitter pattern. That style still works, but it scatters state across callback closures and makes error handling awkward.

Async iterators fold naturally into normal async/await control flow. You write one linear loop, use try/catch for errors, and break out early exactly like you would with an array.

The stream object returned by .stream() is both an async iterable (for the granular event-by-event view) and a helper with finalMessage() (for the complete assembled response once the stream ends).

This page contrasts both styles and walks through a full example that streams a chat response and renders text deltas incrementally.

Recipe

Quick-reference recipe card, copy-paste ready.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a haiku about async iterators." }],
});
 
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}
 
const message = await stream.finalMessage();
console.log("\n\nUsage:", message.usage);

When to reach for this:

• You want to render tokens incrementally in a UI, CLI, or terminal as they arrive.
• You need the final assembled message (text, stop reason, usage) after the stream completes.
• You want type-safe handling of different content block types without manual event names.
• You're writing new streaming code and have no legacy reason to use event listeners.

Working Example

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
async function streamChatResponse(userMessage: string): Promise<void> {
  const stream = client.messages.stream({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: userMessage }],
  });
 
  let currentBlockType: string | null = null;
 
  for await (const event of stream) {
    switch (event.type) {
      case "content_block_start":
        currentBlockType = event.content_block.type;
        if (currentBlockType === "text") {
          process.stdout.write("Claude: ");
        }
        break;
 
      case "content_block_delta":
        if (event.delta.type === "text_delta") {
          // Render text deltas incrementally as they arrive.
          process.stdout.write(event.delta.text);
        } else if (event.delta.type === "thinking_delta") {
          // Extended thinking deltas arrive on their own block type.
          process.stdout.write(event.delta.thinking);
        }
        break;
 
      case "content_block_stop":
        if (currentBlockType === "text") {
          process.stdout.write("\n");
        }
        currentBlockType = null;
        break;
 
      case "message_stop":
        // The stream has ended; finalMessage() below is now cheap.
        break;
    }
  }
 
  // After the loop, the complete message is available without re-reading events.
  const finalMessage = await stream.finalMessage();
  console.log("Stop reason:", finalMessage.stop_reason);
  console.log("Input tokens:", finalMessage.usage.input_tokens);
  console.log("Output tokens:", finalMessage.usage.output_tokens);
}
 
streamChatResponse("Explain async iterators in two sentences.").catch((error) => {
  console.error("Streaming failed:", error);
});

What this demonstrates:

• A single linear for await...of loop replaces multiple named event-listener callbacks.
• Narrowing on event.type and event.delta.type gives type-safe access to text, thinking, and other delta variants without casting.
• try/catch-style error handling (here, .catch() on the outer async function) covers the whole stream, not just individual events.
• stream.finalMessage() returns the complete assembled Message object after iteration finishes, with no extra bookkeeping.
• Local variables like currentBlockType live in ordinary loop scope instead of being smuggled through closures.

Deep Dive

How It Works

• client.messages.stream(...) opens a server-sent-events connection to the Messages API and returns a MessageStream object immediately, before any events have arrived.
• MessageStream implements Symbol.asyncIterator, so for await (const event of stream) pulls events off the connection one at a time, in order, awaiting each one as it becomes available.
• Each iteration yields one event of the raw stream protocol: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, or message_stop.
• Because the loop is just async control flow, a return, break, or thrown error inside it propagates the way it would in any other for await loop, and the underlying connection is cleaned up.
• stream.finalMessage() resolves once the stream has ended, using an internal accumulator that reassembles all content blocks and deltas into a single Message object identical in shape to a non-streaming response.
• You do not have to iterate the events at all if you only care about the final result: calling await stream.finalMessage() directly (without a for await loop) still works, since the SDK drives the stream to completion internally.

Event Types at a Glance

Async Iterators vs. Manual Event Listeners

// Older style: manual event-listener wiring.
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});
 
stream.on("text", (textDelta) => {
  process.stdout.write(textDelta);
});
 
stream.on("error", (error) => {
  console.error("Stream error:", error);
});
 
stream.on("end", () => {
  console.log("\nDone.");
});
 
// Modern style: one async iterator loop, shown in the Recipe and Working Example above.

The listener style still ships in the SDK for backward compatibility, but it has three practical downsides next to for await...of:

• Scattered control flow. Success, error, and completion each live in a separate callback, so there is no single place to reason about "what happens during this stream."
• Awkward cleanup. Breaking out of a stream early (say, after the user cancels a request) means manually calling stream.abort() and unregistering listeners, instead of just break-ing a loop.
• Weaker typing at the call site. Event names like "text" are strings you have to get right, versus event.type values that TypeScript narrows for you inside the loop.

TypeScript Notes

import type { MessageStreamEvent } from "@anthropic-ai/sdk/resources/messages";
 
function handleEvent(event: MessageStreamEvent): void {
  // event.type narrows the union, so event.delta and event.content_block
  // are only accessible with the fields that variant actually has.
  if (event.type === "content_block_delta") {
    if (event.delta.type === "text_delta") {
      console.log(event.delta.text); // string, no cast needed
    } else if (event.delta.type === "input_json_delta") {
      console.log(event.delta.partial_json); // string, tool input fragment
    }
  }
}

The SDK ships its own type definitions, so every event and content block is a discriminated union keyed on type. Narrowing with if/switch on event.type (and event.delta.type one level down) gives you exhaustive, compiler-checked handling instead of loosely-typed callback payloads.

Parameters & Return Values

Gotchas

• Iterating the stream twice. A MessageStream can only be consumed once; calling for await on it a second time yields nothing. Fix: capture what you need (text, usage, tool calls) during the single pass, or call stream.finalMessage() if you only need the end result.
• Forgetting to narrow event.delta.type. Treating every content_block_delta as a text delta breaks when a thinking_delta or input_json_delta arrives, since those variants use different field names. Fix: always check event.delta.type before reading event.delta.text.
• Mixing .on() listeners with a for await loop on the same stream. Both consume the same underlying events, so combining them leads to missed or duplicated data. Fix: pick one style per stream; use the async iterator unless you have a specific reason to keep listeners.
• Not handling stream errors. An unhandled rejection from a broken connection or an API error mid-stream will crash a Node process if nothing awaits or catches it. Fix: wrap the loop (or the calling async function) in try/catch, or attach a .catch() to the outer promise.
• Calling finalMessage() before the loop finishes. If you call stream.finalMessage() concurrently while still iterating in another part of the code, you can end up racing the same stream. Fix: call finalMessage() after the for await loop completes, or skip the loop entirely and only call finalMessage() if you don't need per-token updates.
• Assuming content_block_start always means text. Tool-use blocks and thinking blocks also fire content_block_start, with a different content_block.type. Fix: check content_block.type before assuming the block is text.

Alternatives

FAQs

const stream = client.messages.stream({ /* ... */ });
 
const timeout = setTimeout(() => stream.abort(), 5000);
 
for await (const event of stream) {
  // ... handle events
}
 
clearTimeout(timeout);

const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hi" }],
});
 
for await (const text of stream.textStream ?? []) {
  process.stdout.write(text);
}

Related

• TypeScript/JavaScript SDK Basics - client setup and request basics this page builds on.
• The Anthropic TypeScript SDK Mental Model - how requests, responses, and streams fit together conceptually.
• TypeScript SDK Type Reference for Content Blocks - full type reference for TextBlock, ToolUseBlock, and ThinkingBlock.
• Building a Streaming Chat Endpoint with Next.js and the TypeScript SDK - applies this streaming pattern inside a Next.js route handler.
• Retry, Timeout, and AbortController Patterns in the TypeScript SDK - canceling and retrying streams safely.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official @anthropic-ai/sdk TypeScript SDK (latest release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.