decode-zstd

small, dependency-free JavaScript Zstandard decompressor

minimal example

import decodeZstd from 'decode-zstd'

const raw = decodeZstd(buffer)

features

• Standard Zstandard frames, optional and unknown content sizes, every frame-header size encoding and all 16 skippable magic values.
• Raw, run-length encoded and compressed blocks, including multi-block history.
• Raw/RLE literals, Huffman literals with raw or FSE-compressed weights, one/four streams and treeless table reuse.
• Predefined, RLE, compressed and repeated FSE sequence tables, all standard literal/match length codes and offset codes 0–31.
• Repeat offsets, overlapping matches and frame-local state reset.
• XXH64 content checksums with seed zero, using the required low 32 bits.
• Block, window, sequence, entropy and exact-consumption validation, plus published decompressor errata regressions.

Streaming and custom dictionaries are intentionally out of scope. Nonzero dictionary IDs are rejected explicitly. Legacy Zstandard versions and the nonstandard magicless API format are not supported.

installation

npm install --save decode-zstd

usage

API

decodeZstd is available as both a default and named export.

import decodeZstd, {ZstdError} from 'decode-zstd'
import type {DecodeZstdOptions, ZstdErrorCode} from 'decode-zstd'

const raw = decodeZstd(compressed, {
  maxOutputSize: 64 * 1024 * 1024,
})

• Input: Uint8Array or ArrayBuffer. Node/Bun Buffer works because it is a Uint8Array. Byte-offset views are respected. Other typed arrays and DataView are intentionally not accepted.
• Output: a new exact-length Uint8Array containing the concatenated decoded bytes. It neither shares memory with nor modifies the input.
• maxOutputSize: a nonnegative safe integer limiting total decoded bytes across all frames. The default is 2 ** 30 (1 073 741 824 bytes). Zero permits only empty output.
• Framing: input must contain at least one complete standard or skippable frame. Concatenated frames are decoded in order and skippable frames produce no output.
• Integrity: content checksums are verified whenever present.

The call is synchronous and retains the full result. maxOutputSize is an output budget, not a peak-memory limit. Buffer growth and final trimming may temporarily hold additional copies alongside compressed input and block scratch space. Choose a suitably small budget for untrusted input and use a Worker when decoding should not block a UI thread.

Errors

Malformed or unsupported compressed data throws ZstdError, whose code is one of:

| Code | Meaning | | --- | --- | | INVALID_DATA | Invalid framing, truncated data, invalid entropy tables/bitstreams, bad match history or a size mismatch. | | UNSUPPORTED_DICTIONARY | A nonzero dictionary ID was requested. | | OUTPUT_LIMIT | The output budget, safe-integer size range or a catchable allocation limit was exceeded. | | CHECKSUM_MISMATCH | The stored frame checksum disagrees with decoded content. |

Messages are diagnostic, not a stable parsing interface. Entropy failures preserve their underlying error as cause. Incorrect API argument types throw TypeError; invalid maxOutputSize values throw RangeError.

legal

Zstandard

adapted from Meta’s Zstandard reference implementation

Copyright © Meta Platforms, Inc. and affiliates – BSD

license

MIT License Copyright © 2026, Jaid <[email protected]> (https://github.com/jaid)