Registry / serialization / string_decoder

string_decoder

library1.3.0jsnpmunverified

The `string_decoder` package provides a userland implementation of the Node.js core `string_decoder` module. It is designed to correctly decode `Buffer` objects into strings, specifically handling multi-byte UTF-8 and UTF-16 characters that may span across multiple buffer chunks. This prevents issues like malformed characters when processing streamed or chunked data. Maintained by the Node.js Streams Working Group, it offers a stable and reliable solution for character decoding outside of the core Node.js environment. The current stable version is 1.3.0, released 7 years ago, indicating its maturity. Prior to version 1.0.0, its versions mirrored those of Node.js core; since 1.0.0, it adheres to Semantic Versioning. Its key differentiator is being a direct, semantically versioned mirror of the high-performance Node.js core implementation, making it suitable for environments where Node's built-in module is not directly available or a specific version parity is required, such as in browserify bundles.

serialization

github ↗package ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ESM named import is preferred in modern Node.js and bundlers. The package's `main` entry point is CommonJS, so direct ESM import relies on Node.js's CJS-ESM interop or a bundler.

import { StringDecoder } from 'string_decoder';

The `StringDecoder` class is the primary export. Destructuring `require` is common. For older Node.js or bundler setups, `require('string_decoder').StringDecoder` also works but destructuring is cleaner.

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

Demonstrates how to use `StringDecoder` to correctly handle multi-byte UTF-8 characters split across multiple `Buffer` chunks, preventing data corruption.

import { StringDecoder } from 'string_decoder'; import { Buffer } from 'buffer'; const decoder = new StringDecoder('utf8'); // Imagine receiving a multi-byte character (like '€') split across network packets. // The Euro symbol (€) is U+20AC, which is E2 82 AC in UTF-8. const chunk1 = Buffer.from([0xE2]); // First byte of '€' const chunk2 = Buffer.from([0x82]); // Second byte of '€' const chunk3 = Buffer.from([0xAC, 0x61, 0x62]); // Third byte of '€' plus 'ab' let decodedString = ''; decodedString += decoder.write(chunk1); // Should output '' (incomplete char buffered) decodedString += decoder.write(chunk2); // Should output '' (still incomplete) decodedString += decoder.write(chunk3); // Should output '€ab' (now complete and subsequent chars) decodedString += decoder.end(); // Any remaining buffered characters are flushed console.log(decodedString); // Expected output: '€ab' // Without StringDecoder, a simple buffer.toString() on chunks could lead to replacement characters. const simpleConcat = Buffer.concat([chunk1, chunk2, chunk3]).toString('utf8'); console.log(simpleConcat); // Expected output: '€ab' (for this specific example, but not reliable with *any* partial data)

Debug

Known footguns

breakingPrior to version 1.0.0, `string_decoder` versions mirrored Node.js core versions, which did not follow semantic versioning. Starting with 1.0.0, the package adopted standard semantic versioning, meaning major version bumps now indicate breaking changes in this userland package, independent of Node.js core.

gotchaThe `string_decoder` module is specifically designed to correctly handle multi-byte characters that are split across `Buffer` instances when streamed. Simply concatenating buffers and then calling `Buffer.prototype.toString()` might result in replacement characters (�) for improperly split multi-byte sequences.

deprecatedIn modern JavaScript environments, the WHATWG `TextDecoder` API (`new TextDecoder('utf-8')`) is the generally recommended and more broadly compatible alternative for decoding text from binary data, especially in browser and Web Worker contexts. `string_decoder` is considered a legacy utility module for Node.js compatibility.

gotchaWhen bundling for the browser using tools like Webpack or Rollup, ensure that `string_decoder` is correctly aliased or handled. As it's a Node.js core module mirror, bundlers might incorrectly assume it's a Node.js global or misinterpret its import path, leading to errors like 'StringDecoder' is not exported by '.../lib/string_decoder.js'.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

8 hits · last 30 days

gptbot

ahrefsbot

script

Resources

githubhttps://github.com/nodejs/string_decoder ↗

packagehttps://www.npmjs.com/package/string_decoder ↗