LogoفارسیFA

The StringDecoder Module in Node.js

The node:string_decoder module provides a safe and reliable way to decode Buffer objects into strings, especially when dealing with multibyte UTF‑8 or UTF‑16 characters. Unlike buffer.toString(), which may produce corrupted output when characters are split across chunks, StringDecoder preserves incomplete multibyte sequences and completes them only when enough bytes are available.

UTF‑8 / UTF‑16 multibyteBuffer decodingIncomplete characters handlingstringDecoder.write()stringDecoder.end()

~2 min read • Updated Dec 30, 2025

1. Introduction


The node:string_decoder module is designed to convert Buffer data into strings without breaking multibyte characters. It is especially useful when processing streamed or chunked data where character boundaries may not align with chunk boundaries.


2. Accessing the Module


const { StringDecoder } = require('node:string_decoder');

3. Basic Usage


Here is a simple example decoding UTF‑8 multibyte characters:


const decoder = new StringDecoder('utf8');

console.log(decoder.write(Buffer.from([0xC2, 0xA2]))); // ¢
console.log(decoder.write(Buffer.from([0xE2, 0x82, 0xAC]))); // €

4. Handling Incomplete Multibyte Characters


If a character arrives in multiple chunks, StringDecoder buffers the incomplete bytes until the full character is available:


decoder.write(Buffer.from([0xE2]));
decoder.write(Buffer.from([0x82]));
console.log(decoder.end(Buffer.from([0xAC]))); // €

5. The StringDecoder Class


5.1 Constructor


  • new StringDecoder(encoding): Creates a new instance.
  • Default encoding: 'utf8'.

5.2 write(buffer)


  • Accepts Buffer, TypedArray, DataView, or string.
  • Returns a decoded string.
  • Stores incomplete multibyte sequences internally for the next call.

5.3 end([buffer])


  • Flushes any remaining buffered bytes.
  • Replaces incomplete characters with the appropriate substitution character.
  • Can optionally process one final chunk before ending.
  • The decoder can be reused after calling end().

6. Why Use StringDecoder?


  • Prevents corrupted output when decoding multibyte characters.
  • Ideal for streaming data where chunks may split characters.
  • Supports UTF‑8 and UTF‑16 safely.
  • Predictable behavior with incomplete sequences.

7. Common Use Cases


  • Decoding data from TCP sockets.
  • Processing chunked HTTP requests/responses.
  • Reading text files via streams.
  • Handling partial data in real‑time applications.

Conclusion


The StringDecoder module is an essential tool for safely decoding streamed or chunked text data in Node.js. By intelligently buffering incomplete multibyte sequences, it ensures clean, accurate string output and prevents the corruption that can occur with naive decoding methods.


Written & researched by Dr. Shahin Siami

Next Article