@web-engine-dev/binary-compression

LZ4 compression compiled to WebAssembly for fast binary data compression and decompression. Used for save files, network packets, and asset bundles where speed matters more than compression ratio.

Layer 8 · Content

Features

• LZ4 Algorithm: Extremely fast compression/decompression (designed for real-time use)
• WASM Implementation: Near-native speed via WebAssembly
• Streaming API: Compress/decompress in chunks for large data
• Block and Frame Formats: LZ4 block (minimal overhead) and LZ4 frame (with checksums)
• Zero-Copy Decompression: Decompresses directly into provided output buffer
• Content Size: Optional content-size header for pre-allocated output buffers
• Dictionary Compression: Shared dictionary for small messages (network packets)

Installation

npm install @web-engine-dev/binary-compression
# or
pnpm add @web-engine-dev/binary-compression

Quick Start

import { compress, decompress, initLZ4 } from '@web-engine-dev/binary-compression';

// Initialize WASM module (once, at startup)
await initLZ4();

// Compress binary data
const input = new Uint8Array(saveFileBuffer);
const compressed = compress(input);

console.log(`${input.length} → ${compressed.length} bytes`);
// Typical: 100KB → 25-40KB for game save data

// Decompress
const decompressed = decompress(compressed);

Performance Characteristics

Operation	Speed	Ratio
Compress	~500 MB/s (WASM)	2–3× for structured data
Decompress	~2 GB/s (WASM)	—

LZ4 prioritizes speed over compression ratio. For maximum compression, consider using gzip/brotli at the HTTP layer instead.

Use Cases

• Save Files: Fast compression for frequent auto-saves
• Network Packets: Dictionary-assisted compression for small messages
• Asset Bundles: Bundle compression for grouped resources
• Undo History: Compress command snapshots for memory efficiency

Dependencies

None at runtime — the LZ4 WASM module is bundled.