ZXC Node.js Bindings

High-performance Node.js bindings for the ZXC asymmetric compressor, optimized for fast decompression.
Designed for Write Once, Read Many workloads like ML datasets, game assets, and caches.

Features

• Blazing fast decompression - ZXC is specifically optimized for read-heavy workloads.
• Native N-API addon - compiled C code via cmake-js for maximum performance.
• Buffer support - works directly with Node.js Buffer objects.
• TypeScript declarations - full type definitions included.

Installation (from source)

git clone https://github.com/hellobertrand/zxc.git
cd zxc/bindings/nodejs
npm install

Prerequisites

• Node.js ^20.17.0 or >= 22.9.0
• CMake >= 3.21
• A C17/C++17 compiler (GCC, Clang, or MSVC)

Usage

const zxc = require("zxc-compress");

// Compress
const data = Buffer.from("Hello, World!".repeat(1_000));
const compressed = zxc.compress(data, { level: zxc.LEVEL_DEFAULT });

// Decompress (auto-detects size)
const decompressed = zxc.decompress(compressed);

console.log(`Original: ${data.length} bytes`);
console.log(`Compressed: ${compressed.length} bytes`);
console.log(`Ratio: ${((compressed.length / data.length) * 100).toFixed(1)}%`);

API

compress(data, options?)

Compress a Buffer.

| Parameter | Type | Default | Description | | ------------------ | --------- | --------------- | -------------------------------------------- | | data | Buffer | - | Input data | | options.level | number | LEVEL_DEFAULT | Compression level (1–7); out of range throws | | options.checksum | boolean | false | Write checksums | | options.seekable | boolean | false | Append a seek table (see Seekable) | | options.dict | Buffer | - | Pre-trained dictionary (or a Dictionary) |

Returns: Buffer - compressed data.

decompress(data, options?)

Decompress a ZXC compressed Buffer.

| Parameter | Type | Default | Description | | ----------------------- | --------- | ------- | ------------------------------------------ | | data | Buffer | - | Compressed data | | options.size | number | auto | Expected decompressed size | | options.checksum | boolean | true | Verify the checksums the archive carries | | options.dict | Buffer | - | Dictionary the archive was compressed with | | options.maxOutputSize | number | none | Refuse a larger size before allocating |

Returns: Buffer - decompressed data.

The size comes from the archive's footer, unverified until the decode ends. A forged one that cannot be allocated throws a RangeError; one that can is reserved for the time of the call. maxOutputSize (on Dctx too) refuses it first: set it on untrusted input.

new Cctx(options?) / new Dctx(options?)

Reusable contexts: the working buffers are carved once instead of once per call, which pays off when compressing many payloads with the same settings. The options are set on the native context at construction and apply to every call; an invalid value throws from the constructor with the zxc error code (for example ERROR_BAD_LEVEL for a level outside 1–7, which every entry point refuses rather than clamps).

| Parameter | Type | Default | Description | | ------------------ | --------- | --------------- | -------------------------------- | | options.level | number | LEVEL_DEFAULT | Compression level (Cctx only) | | options.checksum | boolean | see below | Write or verify checksums | | options.dict | Buffer | - | Dictionary used by every call | | options.dictHuf | Buffer | - | Shared literal table (128 bytes) |

const cctx = new zxc.Cctx({ level: zxc.LEVEL_DEFAULT, dict });
const dctx = new zxc.Dctx({ dict });
const archives = payloads.map((p) => cctx.compress(p));
const restored = archives.map((a) => dctx.decompress(a));
cctx.close();
dctx.close();

Cctx writes no checksums unless asked. Dctx, like decompress, DStream, DecompressStream and Seekable, verifies them whenever the archive carries them; checksum: false (setChecksum(false) on Seekable) opts out.

A context is not thread-safe, and close() is idempotent.

compressBound(inputSize)

Returns the maximum compressed size for a given input size.

getDecompressedSize(data)

Returns the original size from a ZXC compressed buffer (reads footer only).

getFrameInfo(data)

Reads the frame's header and footer without decoding: decompressedSize, compressedSize, digest (a BigInt, 0n without checksums), blockSize, dictId, formatVersion, hasChecksum, hasSeekTable. Throws on an invalid frame.

Constants

| Constant | Value | Description | | ---------------- | ----- | ---------------------- | | LEVEL_FASTEST | 1 | Fastest compression | | LEVEL_FAST | 2 | Fast compression | | LEVEL_DEFAULT | 3 | Recommended balance | | LEVEL_BALANCED | 4 | Good ratio, good speed | | LEVEL_COMPACT | 5 | Highest density |

Testing

npm test

License

BSD-3-Clause