Decode binary payloads
Convert a Uint8Array or other binary view containing encoded text into a JavaScript string.
Node.js · Class
TextDecoder
TextDecoder implements the WHATWG Encoding Standard API for converting encoded binary data into JavaScript strings. It supports configurable encodings, streaming chunks, malformed-input handling, and byte-order-mark behavior.
- Since
- v11.0.0
How it works
TextDecoder converts encoded binary data into strings. Construct it with an encoding and optional error-handling or byte-order settings, then call decode() for complete data or stream chunks while exposing the selected encoding and decoder behavior through properties.
Syntax
new TextDecoder([encoding[, options]])
textDecoder.decode(input?, options?): stringParameters
| Name | Type | Description |
|---|---|---|
encoding | string | Encoding label or alias for the decoder; defaults to UTF-8. |
options | Object | Configuration object. fatal makes decoding failures fatal; ignoreBOM controls byte-order-mark handling. |
input | ArrayBuffer | DataView | TypedArray | Encoded data supplied to decode(). |
options | Object | Configuration for decode(); stream indicates that additional chunks are expected. |
Returns
decode() returns a string; encoding is a string property.
Key points
- TextDecoder follows the WHATWG Encoding Standard for turning encoded binary data into text.
- The constructor accepts a supported encoding name or one of its documented aliases.
- decode() transforms the supplied binary view into a JavaScript string.
- decode() accepts ArrayBuffer, DataView, and TypedArray inputs.
- The stream option indicates that more encoded chunks will follow.
- The encoding property identifies the decoder's selected character encoding.
Common mistakes
- For chunked input, stream mode buffers an incomplete trailing sequence until a later decode call.
- Fatal mode changes malformed-input handling from replacement behavior to a decoding error.
- The ignoreBOM option applies only to UTF-8 and UTF-16 encodings.
Example: Decode UTF-8 bytes
const decoder = new TextDecoder();
const bytes = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(bytes)); // HelloCreates a UTF-8 decoder and converts encoded bytes into a JavaScript string.
When to use it
Stream incremental input
Process network or file data arriving across multiple chunks without splitting multibyte characters.
Validate text encoding
Reject malformed encoded input instead of silently substituting replacement characters.
Control BOM handling
Preserve or remove a byte-order mark when decoding supported UTF encodings.
Interview questions
QWhat does TextDecoder do, and what can decode accept?
TextDecoder implements the WHATWG Encoding Standard API. Its decode method accepts an ArrayBuffer, DataView, or TypedArray and returns a string.
Follow-up: How would you decode data arriving in chunks? Use decode(chunk, { stream: true }) for intermediate chunks, then finish with a decode call that does not continue streaming.
QWhat arguments does the constructor accept?
The constructor takes an optional encoding, defaulting to UTF-8, plus options such as fatal and ignoreBOM. The encoding may be a supported encoding or an alias.
Follow-up: What should be checked when choosing a non-UTF encoding? Verify that the requested encoding is supported by the Node.js build and documentation.
QWhich decoder behavior can be configured?
The encoding property reports the encoding supported by the instance. The fatal and ignoreBOM settings control malformed-input handling and byte-order-mark treatment.
Follow-up: When is fatal preferable? Use it when silently replacing invalid sequences would hide corrupt or invalid input.
Related
TextEncoderutilArrayBufferDataViewTypedArray