wasm-hash-module

🚀 WASM Hash Module

A high-performance WebAssembly module providing multiple fast hash functions optimized for web applications. Built with Rust and compiled to WebAssembly for maximum speed and compatibility.

✨ Features

🔧 Hash Functions

• XXH3 (64-bit & 128-bit) - Industry-standard, extremely fast
• WyHash - Ultra-fast hash function, excellent for hash tables
• MuseAir - Modern, high-quality hash function

📤 Output Formats

• Hexadecimal - Traditional hex encoding
• Base58 - Bitcoin-style encoding (no confusing characters)
• Base64 - Standard base64 encoding

🎯 Advanced Features

• Streaming API - Hash large files incrementally
• Batch Processing - Hash multiple inputs efficiently
• Custom Seeds - Cryptographic-quality seeding
• Performance Benchmarking - Built-in timing functions
• Memory Optimized - Minimal WASM binary size (~100KB)
• Zero Dependencies - Self-contained module

🏁 Quick Start

Prerequisites

# Install Rust and wasm-pack
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Build Instructions

# Clone and build
git clone <your-repo>
cd wasm-hash-module

# Standard build (recommended)
wasm-pack build --target web --release

# With debug features
wasm-pack build --target web --release -- --features "console_error_panic_hook"

# Size-optimized build
wasm-pack build --target web --release
wasm-opt pkg/wasm_hash_module_bg.wasm -O4 -o pkg/wasm_hash_module_bg.wasm

Installation in Your Project

# Copy the generated pkg/ directory to your project
cp -r pkg/ your-project/wasm-hash-module/

# Or publish to npm and install
npm install wasm-hash-module

🔥 Usage Examples

Basic Usage

import init, { 
  xxh3_hash, 
  wyhash, 
  museair_hash, 
  string_to_bytes,
  OutputFormat 
} from './pkg/wasm_hash_module.js';

// Initialize the module
await init();

// Hash a string
const data = string_to_bytes("Hello, World!");

// Get hashes in different formats
console.log("XXH3 (Hex):", xxh3_hash(data, OutputFormat.Hex));
console.log("XXH3 (Base58):", xxh3_hash(data, OutputFormat.Base58));
console.log("XXH3 (Base64):", xxh3_hash(data, OutputFormat.Base64));

console.log("WyHash:", wyhash(data, OutputFormat.Hex));
console.log("MuseAir:", museair_hash(data, OutputFormat.Hex));

Streaming Large Files

import { XXH3Hasher } from './pkg/wasm_hash_module.js';

// Stream processing for large files
const hasher = new XXH3Hasher();
hasher.update(chunk1);
hasher.update(chunk2);
hasher.update(chunk3);
const finalHash = hasher.finalize(OutputFormat.Hex);

File Hashing

async function hashFile(file) {
  const reader = new FileReader();
  return new Promise((resolve) => {
    reader.onload = (e) => {
      const bytes = new Uint8Array(e.target.result);
      const hash = xxh3_hash(bytes, OutputFormat.Hex);
      resolve(hash);
    };
    reader.readAsArrayBuffer(file);
  });
}

// Usage
const fileHash = await hashFile(document.getElementById('file').files[0]);

Performance Comparison

import { benchmark_hash_function, compare_all_hashes } from './pkg/wasm_hash_module.js';

const testData = string_to_bytes("A".repeat(1000)); // 1KB test data

// Benchmark each algorithm
console.log("XXH3:", benchmark_hash_function(testData, "xxh3", 10000), "ms");
console.log("WyHash:", benchmark_hash_function(testData, "wyhash", 10000), "ms");
console.log("MuseAir:", benchmark_hash_function(testData, "museair", 10000), "ms");

// Compare all algorithms on same data
const comparison = compare_all_hashes(testData, OutputFormat.Hex);
console.log("All hashes:", comparison.xxh3, comparison.wyhash, comparison.museair);

📚 API Reference

Hash Functions

xxh3_hash(data: Uint8Array, format: OutputFormat) → string

Compute XXH3 64-bit hash.

xxh3_128_hash(data: Uint8Array, format: OutputFormat) → string

Compute XXH3 128-bit hash (more collision-resistant).

xxh3_hash_with_seed(data: Uint8Array, seed: bigint, format: OutputFormat) → string

Compute XXH3 hash with custom seed.

wyhash(data: Uint8Array, format: OutputFormat) → string

Compute WyHash (ultra-fast, good distribution).

wyhash_with_seed(data: Uint8Array, seed: bigint, format: OutputFormat) → string

Compute WyHash with custom seed.

museair_hash(data: Uint8Array, format: OutputFormat) → string

Compute MuseAir hash (modern, high-quality).

museair_hash_with_seed(data: Uint8Array, seed: bigint, format: OutputFormat) → string

Compute MuseAir hash with custom seed.

Streaming API

XXH3Hasher

const hasher = new XXH3Hasher();           // Default constructor
const hasher = new XXH3Hasher(seed);       // With seed
hasher.update(data);                       // Add data
const hash = hasher.finalize(format);      // Get result
hasher.reset();                           // Reset for reuse

Utility Functions

string_to_bytes(input: string) → Uint8Array

Convert string to bytes for hashing.

hex_to_bytes(hex: string) → Uint8Array

Convert hex string to bytes.

compare_all_hashes(data: Uint8Array, format: OutputFormat) → HashComparison

Get all three hash results in one call.

benchmark_hash_function(data: Uint8Array, algorithm: string, iterations: number) → number

Benchmark performance (returns milliseconds).

Output Formats

OutputFormat.Hex     // "a1b2c3d4..."
OutputFormat.Base58  // "2NEpo7TZR..."  
OutputFormat.Base64  // "YWJjZGVm..."

🛠 Build Targets

# Web (ES modules)
wasm-pack build --target web

# Node.js
wasm-pack build --target nodejs  

# Bundler (Webpack, Rollup, etc.)
wasm-pack build --target bundler

🔧 Configuration

Cargo.toml Features

[features]
default = []
console_error_panic_hook = ["dep:console_error_panic_hook"]  # Debug builds

Build Profiles

The module is optimized for:

• Size: LTO enabled, opt-level = "s"
• Speed: Single codegen unit, panic = abort
• Compatibility: No SIMD dependencies

🌐 Browser Support

• Chrome/Edge: Full support (recommended)
• Firefox: Full support
• Safari: Full support (iOS 11.3+)
• Node.js: v12+ with --experimental-wasm-modules

🔍 Use Cases

Web Applications

• File integrity checking
• Duplicate detection
• Cache keys generation
• Data deduplication

Cryptographic Applications

• Key derivation (with seeds)
• Message authentication
• Fingerprinting

Performance-Critical

• Hash tables (WyHash recommended)
• Bloom filters
• Consistent hashing

📈 Benchmarks

Run included benchmarks:

// Test with your data
const myData = string_to_bytes("Your test data here");
console.log("Performance:", benchmark_hash_function(myData, "xxh3", 1000));

🤝 Contributing

• Fork the repository
• Create a feature branch
• Add tests for new functionality
• Ensure all tests pass: cargo test
• Build and test WASM: wasm-pack build --target web
• Submit a pull request

Development Setup

# Install dev dependencies
cargo install wasm-pack
npm install -g serve  # For testing

# Run tests
cargo test
wasm-pack test --headless --firefox

📋 TODO

• Add BLAKE3 support
• Implement CRC32 variants
• Add streaming Base58/Base64 encoding
• Web Worker support
• TypeScript definitions improvements

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• xxHash - Extremely fast hash algorithm
• wyhash - The FASTEST PRNG
• MuseAir - Modern hash function
• wasm-bindgen - Rust-WASM bridge

Built with ❤️ using Rust + WebAssembly