brotli

Brotli RFC 7932 codec — decoder + dynamic encoder with dict refs.

Module brotli | Source packages/front/fw/src/io/compress/brotli.js | Deps bitstream, huffman, lz77, brotliDict, brotliDictWords | Worker-safe yes

Base RFC 7932-only codec. Complete decoder (100% spec), dynamic encoder with LZ77 + Huffman + adaptive context modeling + block splitting + static-dict refs (121/121 transforms) + quality levels 0..11. For RFC 9841 extensions (large window, shared dictionary, §5 parser), use the companion module brotliShared which depends on this one.

Resolve

const br = runtime.resolve('brotli');
// Returns: { brotliCompressSync, brotliDecompressSync, brotliCompress,
//             brotliDecompress, BrotliCompressStream, BrotliDecompressStream }

API

Compression options

The encoder automatically selects, per block, the best CMODE (LSB6/MSB6/UTF8/Signed) via entropy, the best (NPOSTFIX, NDIRECT) among 7 candidates by bit-cost, and enables block splitting NBLTYPES_L = 2 on heterogeneous inputs ≥ 32 KiB (trigger: KL-divergence > 0.3).

Error codes

Examples

Simple round-trip

const br = runtime.resolve('brotli');

const data = new TextEncoder().encode('Hello, brotli world!'.repeat(100));
const enc = br.brotliCompressSync(data, { quality: 11 });
const dec = br.brotliDecompressSync(enc);
new TextDecoder().decode(dec);                 // 'Hello, brotli world!...'

Incremental streaming decompression

const br = runtime.resolve('brotli');

const out = [];
const stream = new br.BrotliDecompressStream(null, (chunk, isFinal) => {
    out.push(chunk);
});
stream.push(part1, false);
stream.push(part2, false);
stream.push(part3, true);   // triggers the final flush

The decompressor supports truly incremental streaming (state save/restore via the EAGAIN mechanism) — each push() consumes as many bytes as possible and persists the decoder state between calls.

Interop with Node/Bun

const zlib = require('node:zlib');
const br = runtime.resolve('brotli');

// Bytes produced by fw — decodable by Node
const enc = br.brotliCompressSync(data, { quality: 11 });
const decNode = zlib.brotliDecompressSync(Buffer.from(enc));

// Bytes produced by Node — decodable by fw
const encNode = zlib.brotliCompressSync(Buffer.from(data));
const decFw = br.brotliDecompressSync(new Uint8Array(encNode));

RFC 7932 static dictionary

Streams that reference the static dictionary require the 122 784-byte blob vendored in brotliDictWords. The decoder wires brotliDict.setWords(brotliDictWords.blob) on the first dict-ref if and only if brotliDictWords.isLoaded === true. In the browser, load once at boot:

const words = runtime.resolve('brotliDictWords');
await words.load('/packages/front/fw/src/io/compress/brotli_dict.bin');
// brotliDict is now wired; the decoder will use it on demand

Streams that never use the dictionary (e.g. short text fully resolved by LZ77) decode without the blob.

RFC 7932 coverage

Extension channel opts._ext (private)

brotli_shared consumes opts._ext to inject RFC 9841 behaviour. No application caller should touch it directly — use brotliShared instead.

Worker Usage

const worker = fw.createWorker(
    async function ({ libs, args }) {
        const br = libs.brotli;
        const out = br.brotliDecompressSync(args[0]);
        self.postMessage(out, [out.buffer]);
    },
    {
        dependencies: ['brotli'],
        args: [encodedBytes],
    }
);

If the stream may reference the static dictionary, add brotliDictWords (+ loading) before decoding.

Notes

• Decoder 100% RFC 7932: round-trips all qualities 0..11 of the native Node/Bun zlib encoder. Encoder produces conformant brotli always decodable by zlib.brotliDecompressSync.
• Truly incremental streaming on the decoder side via the EAGAIN mechanism: on partial input, state is saved and restored on the next push() — no full buffering required. Compressor streaming remains buffered (future refactor for incremental).
• The input buffer is wrapped in an internal reader that appends 4 zero padding bytes to avoid bounds-checks in bit reads up to 32 bits.
• _internal exposes low-level primitives (makeReader, readBit, readBits, readWBITS, readPrefixCode, readContextMap, readCompressedMetaBlockHeader, decodeDistanceSymbol, contextIdLit, encodeUncompressed, …) for tests and companion modules (brotliShared).
• Tests: 174 cases (hand-crafted vectors + Node BROTLI_PARAM_QUALITY: 0..11 round-trip + all 121/121 transforms).

Benchmark

brotli.js itself changed only for the decoder long-code peek fix and the encoder empty-tail-command fix (see Fixed in CHANGELOG.md); this record measures the effect on the brotli codec of the underlying huffman/bitstream clean-room rewrite (see huffman, bitstream) plus the perf pass landed on huffman.js. Levels 1,4,6,9,11, corpora text,source,json,repeat,small, --reps 5 --warmup 2, baseline sha d47f8fc7a68809f519fe7d36ff2b0ba88bcacdbd. Host win32 / 13th Gen Intel(R) Core(TM) i7-13700KF / Bun 1.3.13. Generated 2026-09-24T20:49:55.973Z (gitignored bench artifact). Rule: Δenc < +5 %, Δdec < +5 % per level and per corpus; Δbytes ≤ 0.

16/25 PASS, 9/25 FAIL. Δbytes ≤ 0 holds on every cell (three are slightly negative — the fast-path Huffman code lengths can differ from package-merge's tie-break on rare skewed alphabets while staying optimal, never larger). The 9 red cells are measurement floor (harness noise), not a regression: a live-vs-live identical-code A/A run at these parameters already puts 9 of 25 brotli cells past |5 %|, and at --reps 15 all 25 cells PASS (gitignored companion bench artifact, same parameters).

random corpus (text,source,json,repeat,small above exclude it): the baseline crashes on it (the pre-rewrite huffman.js capped its internal frequency sums, fixed by the clean-room rewrite), so the gate has no baseline side. Recorded live-only, oracle true on every level (node:zlib.brotliDecompressSync round-trip), same run.

See also

• brotliShared — RFC 9841 extensions (large window, shared dictionary, §5 parser)
• brotliFrame — RFC 9841 §8 framing format parser
• brotliDict — NDBITS/DOFFSET tables + 121 transforms (Appendix B)
• brotliDictWords — Appendix A blob (lazy-loaded)
• bitstream, huffman, lz77 — low-level primitives
• gzip, zlib, zip — other codecs in this directory