decode-brotli

small but complete JavaScript-only Brotli decompressor

features

• All RFC 7932 window sizes, compressed and uncompressed meta-blocks and metadata.
• Simple and complex Huffman codes, block switching, context modeling, distance caches and overlapping history copies.
• The complete 122 784-byte static dictionary and all 121 standard transforms, including non-ASCII entries.
• Strict single-stream decoding: truncated input, invalid codes, invalid padding and trailing bytes are rejected. Concatenated streams are not accepted.
• An encoded empty stream returns an empty array. A zero-byte input is not an encoded stream.

installation

npm install --save decode-brotli

usage

API

import decodeBrotli, {
  BrotliDecodeError,
  type BrotliInput,
  type DecodeBrotliOptions,
  type BrotliErrorCode,
} from 'decode-brotli'

const raw: Uint8Array<ArrayBuffer> = decodeBrotli(buffer)

A named decodeBrotli export is also available and is the same function as the default export.

Input

BrotliInput is ArrayBuffer | ArrayBufferView. This includes signed and unsigned typed arrays, Buffer and DataView. Multi-byte typed arrays are interpreted as their underlying bytes, not converted element values. Views with nonzero offsets and buffers from other realms are supported.

Pass exactly one complete RFC 7932 Brotli stream. A Blob, Response, string, plain array or stream is not accepted. Obtain the bytes first:

const compressed = await Bun.file('document.br').bytes()
const raw = decodeBrotli(compressed)
await Bun.write('document', raw)

In a browser, a file or blob works similarly:

const raw = decodeBrotli(await file.arrayBuffer())

Browsers usually decode HTTP Content-Encoding: br automatically. Do not decode an already decoded fetch response again. A fetched raw .br file must be served without that content encoding if the application will decode it itself.

A raw SharedArrayBuffer is not accepted, but a typed-array view over one is. The caller must prevent concurrent changes to shared bytes during decoding. Detached buffers throw TypeError.

Options

DecodeBrotliOptions has one optional property:

| Property | Default | Meaning | | --- | --- | --- | | maxOutputLength | 256_000_000 | Maximum total decompressed byte length across all non-metadata meta-blocks. |

The limit must be a nonnegative safe integer. 0 permits only empty output; Infinity, fractions and negative numbers are rejected. An exact-size output is allowed. The default is used when the property is omitted or undefined.

Result

A newly allocated Uint8Array<ArrayBuffer> containing all decompressed bytes. Its byte offset is zero and its backing buffer is exactly the output length. The output neither aliases the input nor retains the decoder’s history storage.

Text conversion is explicit:

const text = new TextDecoder('utf-8', {fatal: true}).decode(raw)

Errors

BrotliDecodeError extends Error with a stable code category:

| Code | Meaning | | --- | --- | | INVALID_DATA | Invalid Brotli structure, padding, window, prefix code, distance or dictionary reference. | | UNEXPECTED_EOF | The decoder required bytes beyond the end of the input. | | TRAILING_DATA | Bytes remain after the first complete stream. This includes concatenated streams. | | OUTPUT_LIMIT | A declared output size or decoded output exceeds maxOutputLength. |

Truncation can also manifest as an invalid code structure or an oversized declaration. The decoder reports the first detected failure rather than promising a specific category for every truncation or corruption.

byteOffset is an approximate byte position relative to the supplied view. Lookahead can place it past the end of malformed input. decoderCode, when present, is a numeric reference-decoder diagnostic; do not depend on its value for application control flow. Error messages are diagnostic text, not a stable interface.

Invalid argument types throw TypeError. An invalid output limit throws RangeError. Runtime allocation failures may also throw RangeError; a configured limit does not guarantee the runtime can allocate that much memory.

Resource and integrity considerations

Decoding is synchronous and blocks the calling thread. For large or untrusted payloads in a UI, use a worker. There is no cancellation or streaming API.

Peak memory includes the compressed input, output chunks, the final contiguous output, history and Huffman tables. Output assembly can briefly require approximately twice the decompressed size, plus a history buffer of up to 16 777 216 bytes and other working storage. The output limit is not a total-process memory limit or a CPU-time limit. Metadata processing also consumes time without contributing to output size. Bound compressed input size separately where necessary.

Brotli provides no built-in checksum. A changed bit can still describe a valid but different output. Use an external digest or authenticated transport when integrity matters.

legal

Brotli

adapted from Google’s Brotli reference implementation

Copyright © 2009, 2010, 2013-2016 by the Brotli Authors – MIT

license

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