@discere-os/zlib.wasm

WebAssembly port of zlib - High-performance data compression library with SIMD optimizations and modern TypeScript interfaces.

Features

• 🚀 SIMD-Accelerated: 2-4x faster compression with vectorized deflate operations and hash chains
• 📦 Excellent Compression: Industry-standard deflate algorithm with optimized performance
• 🔒 Type-Safe: Complete TypeScript API with zero any types
• ⚡ High Performance: 80+ MB/s SIMD compression, 300+ MB/s decompression
• 🧪 Thoroughly Tested: Comprehensive test suite with byte-by-byte validation
• 🌐 Universal: Works in browsers (Chrome, Firefox, Safari) and Node.js
• 💾 Memory Optimized: Advanced allocation patterns for efficiency
• 📏 Compact: Optimized build with minimal footprint

Quick Start

Deno-First Workflow (Recommended)

# Run demo with Deno (direct TypeScript execution)
deno task demo

# Build WASM modules
deno task build

# Run tests
deno task test

# Run benchmarks
deno task benchmark

# Build NPM package for Node.js compatibility
deno task build:npm

Node.js Compatibility

# Build NPM package for Node.js projects
deno task build:npm

# The built NPM package can then be installed in Node.js projects:
# npm install @discere-os/zlib.wasm

Usage

Basic Compression

import Zlib from '@discere-os/zlib.wasm'

const zlib = new Zlib()
await zlib.initialize()

// Compress data
const input = new TextEncoder().encode('Hello, World!')
const result = zlib.compress(input, { level: 6 })

console.log(`Compressed ${input.length} bytes to ${result.compressed.length} bytes`)
console.log(`Ratio: ${result.compressionRatio.toFixed(2)}:1`)
console.log(`Speed: ${result.compressionSpeed.toFixed(1)} KB/s`)
console.log(`CRC32: ${result.crc32.toString(16).toUpperCase()}`)

// Decompress with validation
const decompressed = zlib.decompress(result.compressed)
console.log(`Validation: ${decompressed.isValid ? 'PASSED ✅' : 'FAILED ❌'}`)

SIMD-Accelerated Compression

// Use SIMD-accelerated compression for large data (2-4x faster)
const largeData = new Uint8Array(1024 * 1024) // 1MB
const simdResult = zlib.compressSIMD(largeData, { level: 6 })

console.log(`SIMD Compression: ${simdResult.compressionSpeed.toFixed(1)} KB/s`)
console.log(`Speedup vs scalar: ${(simdResult.compressionSpeed / 50000).toFixed(1)}x`)

// Check SIMD availability and performance
if (zlib.isSIMDAvailable()) {
  const analysis = await zlib.analyzeSIMDPerformance(largeData)
  console.log(`SIMD Speedup: ${analysis.simdSpeedup.toFixed(2)}x`)
  console.log(`Recommendation: ${analysis.recommendation}`)
}

// SIMD-optimized CRC32 (10-20x faster for large buffers)
const fastCRC32 = zlib.calculateCRC32SIMD(largeData)

Advanced Configuration

// Fast compression for real-time applications
const fast = zlib.compress(data, { level: 1 })

// Maximum compression for storage
const max = zlib.compress(data, { level: 9 })

// CRC32 checksum calculation
const crc32 = zlib.calculateCRC32(data)
console.log(`Checksum: ${crc32.toString(16).toUpperCase()}`)

// Performance monitoring
const metrics = zlib.getPerformanceMetrics()
console.log(`Average speeds: ${metrics.averageCompressionSpeed.toFixed(1)} KB/s comp`)

File Processing

// Process uploaded files with auto-optimization
const fileResult = await zlib.compressFile(uploadedFile)
console.log(`${fileResult.fileName}: ${fileResult.metrics.spaceSaved.toFixed(1)}% saved`)

// Benchmark different compression levels
const benchmark = await zlib.benchmark(testData)
console.log(`Optimal level: ${benchmark.recommendation.fastestCompression}`)

Performance

Algorithm Characteristics

zlib excels at fast compression and decompression with good ratios:

• Fast Compression: Optimized for speed while maintaining good compression ratios
• Excellent Decompression: Consistently fast inflation of compressed data
• Universal Format: Standard deflate/inflate compatible with gzip, PNG, ZIP
• Memory Efficient: Streaming-capable algorithm with modest memory requirements

Performance Benchmarks

Metric	Scalar	SIMD	Speedup	Description
Compression Speed	50+ MB/s	80-200 MB/s	2-4x	Vectorized deflate with hash chain optimization
Decompression Speed	200+ MB/s	300-800 MB/s	1.5-4x	SIMD-accelerated inflate operations
CRC32 Calculation	100+ MB/s	1000+ MB/s	10-20x	Vectorized polynomial arithmetic
Bundle Size	~100 KB	~120 KB	+20%	Additional SIMD code with graceful fallback
Load Time	~30ms	~35ms	+15%	Slightly larger WASM with feature detection
Compression Ratio	3-50:1	3-50:1	Same	Maintains deflate algorithm fidelity

Browser Support

• Chrome 91+ - Full SIMD support, optimal performance
• Firefox 89+ - Full SIMD support, excellent performance
• Safari 16.4+ - SIMD support, good performance
• Node.js 16.4+ - Server-side compression and processing
• Edge 91+ - Chromium-based, full support

API Reference

class Zlib

Core Methods

• initialize(options?) - Initialize WASM module with configuration
• compress(input, options?) - Compress data with compression level
• decompress(compressed) - Decompress data with validation
• calculateCRC32(data) - Calculate CRC32 checksum
• getCompressBound(length) - Calculate maximum compressed size
• getVersion() - Get zlib library version

Performance Methods

• benchmark(data) - Comprehensive performance testing
• getPerformanceMetrics() - Detailed performance statistics
• getSystemCapabilities() - Browser/system capability detection
• resetMetrics() - Reset performance counters

TypeScript Interfaces

interface CompressionOptions {
  level?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9  // 0=none, 1=fast, 6=default, 9=max
  strategy?: 'default' | 'filtered' | 'huffman' | 'rle' | 'fixed'
}

interface CompressionResult {
  compressed: Uint8Array      // Compressed data
  compressionRatio: number    // Compression ratio
  compressionTime: number     // Time in milliseconds
  compressionSpeed: number    // Speed in KB/s
  spaceSaved: number         // Percentage saved
  crc32: number              // CRC32 checksum
}

Development

Building from Source

# Build optimized WASM module
deno task build

# Run comprehensive tests
deno task test

Testing

# Run complete test suite
deno task test

# Run benchmarks
deno task benchmark

Performance Analysis

# Run performance demonstration
deno task demo

# Comprehensive benchmarking
deno task benchmark

Architecture

WASM-Native Design

This implementation maintains the proven zlib algorithm while adding modern enhancements:

• Algorithm Fidelity: 100% compatible with standard zlib/deflate format
• SIMD Optimization: WebAssembly SIMD for parallel processing in critical paths
• Memory Efficiency: Optimized allocation patterns and streaming support
• Type Safety: TypeScript interfaces with comprehensive validation
• Single-threaded: Reliable, deterministic behavior faithful to original design

Use Cases

• Web Applications: Client-side compression for data transfer optimization
• Progressive Web Apps: Offline data compression and caching
• File Processing: Browser-based compress/decompress with standard gzip compatibility
• Real-time Applications: Fast compression for live data streams and WebRTC
• Creative Tools: Handle ZIP, PNG, and other deflate-based formats in browsers
• Game Development: Asset compression for WebAssembly games

License and Attribution

Licensed under the same zlib license as the original library.

Original Copyright

Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler

WASM Fork Attribution

Copyright (C) 2025 Superstruct Ltd, New Zealand
Licensed under the zlib license

---

High-performance WASM-native zlib implementation with comprehensive TypeScript support

💖 Support This Work

This WebAssembly port is part of a larger effort to bring professional desktop applications to browsers with native performance.

👨‍💻 About the Maintainer: Isaac Johnston (@superstructor) - Building foundational browser-native computing infrastructure through systematic C/C++ to WebAssembly porting.

📊 Impact: 70+ open source WASM libraries enabling professional applications like Blender, GIMP, and scientific computing tools to run natively in browsers.

🚀 Your Support Enables:

• Continued maintenance and updates
• Performance optimizations
• New library ports and integrations
• Documentation and tutorials
• Cross-browser compatibility testing

💖 Sponsor this work to help build the future of browser-native computing.