Course contentsShow
← JavaScript
Lesson 2349 of 2,72348. Working with Binary DataFree lesson

Handling Partial and Streaming Decoding

Using the stream option in decode() to handle multi-chunk data without corrupting multi-byte characters.

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.