Handling Partial and Streaming Decoding
What you'll learn: How to use the stream option in decode() to safely process multi-chunk binary data without breaking multi-byte UTF-8 characters.
The Problem with Multi-Chunk Decoding
When decoding binary data that arrives in multiple chunks (like from a streaming response), you might accidentally split a multi-byte UTF-8 character across two chunks. If you call decode() on each chunk independently, the partial character bytes will produce garbled output or replacement characters (�).
Think of it like reading a sentence where a word is cut in half between two pages—you need to remember the incomplete word from the first page to complete it on the next page.
The Solution: The stream Option
TextDecoder's decode() method accepts a second argument: an options object with a stream property. When stream: true, the decoder internally buffers any incomplete multi-byte characters at the end of the current chunk and waits to complete them with bytes from the next chunk.
const decoder = new TextDecoder();
// Simulating two chunks that split a multi-byte character
const chunk1 = new Uint8Array([72, 101, 108, 108, 111, 0xE2, 0x9C]); // "Hello" + partial ✓
const chunk2 = new Uint8Array([0x93, 33]); // completes ✓ + "!"
// WITH stream option
const part1 = decoder.decode(chunk1, { stream: true }); // "Hello" (holds back incomplete bytes)
const part2 = decoder.decode(chunk2, { stream: true }); // "✓!"
console.log(part1 + part2); // "Hello✓!"
// WITHOUT stream (separate decoder for comparison)
const decoder2 = new TextDecoder();
console.log(decoder2.decode(chunk1)); // "Hello��" (broken character)
Always set stream: false (or omit it) on your final chunk to flush any remaining buffered bytes.
Key Takeaway: Use { stream: true } when calling decode() on intermediate chunks of streaming data to preserve multi-byte character integrity across chunk boundaries.