ZXC WebAssembly

High-performance lossless compression for the browser and Node.js via WebAssembly.

Features

• Buffer API: Compress and decompress Uint8Array buffers
• Reusable Contexts: Amortise allocation overhead across multiple operations
• All Levels: Compression levels 1–7
• Checksum Support: Optional on compression, verified on decompression whenever the archive carries them
• Tiny Footprint: ~60 KB .wasm file (scalar build, no SIMD)

Quick Start

Install

npm install zxc-wasm

The package ships the Emscripten build (zxc.js + zxc.wasm) next to the ES module wrapper, so no toolchain is required to consume it. To build it yourself instead, see Building from Source and import ./zxc_wasm.js by path.

Browser (ES Module)

import createZXC from 'zxc-wasm';

const zxc = await createZXC();

// Compress
const input = new TextEncoder().encode('Hello, World!');
const compressed = zxc.compress(input, { level: 3 });

// Decompress
const output = zxc.decompress(compressed);
console.log(new TextDecoder().decode(output)); // "Hello, World!"

Node.js

import createZXC from 'zxc-wasm';
import { readFileSync } from 'fs';

const zxc = await createZXC();
const data = new Uint8Array(readFileSync('input.bin'));

const compressed = zxc.compress(data, { level: 5, checksum: true });
const decompressed = zxc.decompress(compressed);

API Reference

createZXC(moduleOverrides?) -> Promise<ZXC>

Initialise the WASM module. Returns a frozen API object.

zxc.compress(data, opts?) -> Uint8Array

| Option | Type | Default | Description | |--------|------|---------|-------------| | level | number | 3 | Compression level (1–7) | | checksum | boolean | false | Write integrity checksums |

zxc.decompress(data, opts?) -> Uint8Array

| Option | Type | Default | Description | |--------|------|---------|-------------| | checksum | boolean | true | Verify the checksums the archive carries | | maxOutputSize | number | none | Refuse an archive declaring more decompressed bytes |

Without maxOutputSize, the size comes from the archive's footer and is allocated as is, so a forged footer can grow the WASM heap up to 2 GiB, for good, before the decode fails. Set it on untrusted input.

zxc.compressBound(inputSize) -> number

Maximum compressed output size for a given input size.

zxc.getDecompressedSize(data) -> number

Read the original size from a compressed buffer without decompressing.

zxc.getFrameInfo(data) -> object

Read 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.

zxc.createCompressContext(opts?) -> CompressContext

Create a reusable compression context (avoids per-call allocation). opts takes the same level, checksum, seekable, dict and dictHuf as compress, and applies them to every compress() call.

const ctx = zxc.createCompressContext({ level: 3, dict });
const c1 = ctx.compress(data1);
const c2 = ctx.compress(data2);
ctx.free(); // Release WASM memory

zxc.createDecompressContext(opts?) -> DecompressContext

Create a reusable decompression context. opts takes the same checksum, dict, dictHuf and maxOutputSize as decompress.

const ctx = zxc.createDecompressContext({ dict });
const d1 = ctx.decompress(compressed1);
const d2 = ctx.decompress(compressed2);
ctx.free();

Properties

| Property | Type | Description | |----------|------|-------------| | version | string | Library version | | codename | string | Release code name (informational) | | minLevel | number | Minimum compression level (1) | | maxLevel | number | Maximum compression level (5) | | defaultLevel | number | Default compression level (3) |

Building from Source

Requires Emscripten SDK.

# Configure
emcmake cmake -B build-wasm -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build-wasm

# Test
BUILD_DIR=build-wasm node bindings/wasm/test.mjs

The build produces build-wasm/zxc.js and build-wasm/zxc.wasm.

License

BSD 3-Clause. See LICENSE.