rar-stream 5.1.0 → 5.1.1

package/README.md

@@ -4,33 +4,17 @@
 
 [![CI](https://github.com/doom-fish/rar-stream/actions/workflows/ci.yml/badge.svg)](https://github.com/doom-fish/rar-stream/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/rar-stream.svg)](https://www.npmjs.com/package/rar-stream)
-[![npm downloads](https://img.shields.io/npm/dm/rar-stream.svg)](https://www.npmjs.com/package/rar-stream)
 [![crates.io](https://img.shields.io/crates/v/rar-stream.svg)](https://crates.io/crates/rar-stream)
-[![crates.io downloads](https://img.shields.io/crates/d/rar-stream.svg)](https://crates.io/crates/rar-stream)
 [![docs.rs](https://docs.rs/rar-stream/badge.svg)](https://docs.rs/rar-stream)
-[![MSRV](https://img.shields.io/badge/MSRV-1.85-blue.svg)](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What's New in v5.1.0
-
-- ⚡ **Parallel RAR5 pipeline**: Beats the official C `unrar` in all 24 benchmark scenarios
-- 🌐 **WASM RAR5 support**: Full RAR5 decompression in the browser via `WasmRar5Decoder`
-- 🔌 **NAPI pipeline**: Node.js users get 40% faster decompression automatically
-- 🧪 **E2E browser tests**: Full Playwright tests for upload → decompress → verify workflow
-
-## Features
+## Installation
 
-- 🚀 **Fast**: Native Rust implementation with NAPI bindings
-- 📦 **Zero dependencies**: Core library has no external dependencies
-- 🌐 **Cross-platform**: Works on Linux, macOS, Windows
-- 🔄 **Streaming**: Stream files directly from RAR archives
-- 📚 **Multi-volume**: Supports split archives (.rar, .r00, .r01, ...)
-- 🗜️ **Full decompression**: LZSS, PPMd, and filters
-- 🔐 **Encrypted archives**: AES-256/AES-128 decryption for RAR4 & RAR5
-- 🆕 **RAR4 + RAR5**: Full support for both RAR formats
-- 🌍 **Browser support**: WASM build available
+### Node.js
 
-## Installation
+```bash
+npm install rar-stream
+```
 
 ### Rust
 
@@ -39,14 +23,10 @@
 rar-stream = { version = "5", features = ["async", "crypto"] }
 ```
 
-### Node.js
+### Browser (WASM)
 
 ```bash
-npm install rar-stream
-# or
-yarn add rar-stream
-# or
-pnpm add rar-stream
+wasm-pack build --target web --features "wasm,crypto" --no-default-features
 ```
 
 ## Quick Start
@@ -54,254 +34,54 @@ pnpm add rar-stream
 ```javascript
 import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
 
-// Open a RAR archive
 const media = new LocalFileMedia('./archive.rar');
 const pkg = new RarFilesPackage([media]);
-
-// Parse and list inner files
 const files = await pkg.parse();
 
 for (const file of files) {
   console.log(`${file.name}: ${file.length} bytes`);
-  
-  // Read entire file into memory
   const buffer = await file.readToEnd();
-  
-  // Or stream (returns Node.js Readable)
-  const stream = file.createReadStream();
-  stream.pipe(process.stdout);
-}
-```
-
-### Rust Quick Start
-
-```rust
-use rar_stream::{RarFilesPackage, ParseOptions, LocalFileMedia, FileMedia};
-use std::sync::Arc;
-
-#[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Open a RAR archive
-    let file: Arc<dyn FileMedia> = Arc::new(LocalFileMedia::new("archive.rar")?);
-    let package = RarFilesPackage::new(vec![file]);
-
-    // Parse and list files
-    let files = package.parse(ParseOptions::default()).await?;
-    for f in &files {
-        println!("{}: {} bytes", f.name, f.length);
-    }
-
-    // Read file content
-    let content = files[0].read_to_end().await?;
-    println!("Read {} bytes", content.len());
-    Ok(())
+  // or stream: file.createReadStream().pipe(process.stdout);
 }
 ```
 
 ## Examples
 
-### Extract a File to Disk
-
-```javascript
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-import fs from 'fs';
-
-const media = new LocalFileMedia('./archive.rar');
-const pkg = new RarFilesPackage([media]);
-const files = await pkg.parse();
-
-// Find a specific file
-const targetFile = files.find(f => f.name.endsWith('.txt'));
-if (targetFile) {
-  const content = await targetFile.readToEnd();
-  fs.writeFileSync('./extracted.txt', content);
-  console.log(`Extracted ${targetFile.name} (${content.length} bytes)`);
-}
-```
-
-### Stream Video from RAR (Node.js Readable Stream)
-
-```javascript
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-import fs from 'fs';
-
-const media = new LocalFileMedia('./movie.rar');
-const pkg = new RarFilesPackage([media]);
-const files = await pkg.parse();
-
-const video = files.find(f => f.name.endsWith('.mkv'));
-if (video) {
-  // Get a Node.js Readable stream for the entire file
-  const stream = video.createReadStream();
-  stream.pipe(fs.createWriteStream('./extracted-video.mkv'));
-  
-  // Or stream a specific byte range (for HTTP range requests)
-  const rangeStream = video.createReadStream({ start: 0, end: 1024 * 1024 - 1 });
-}
-```
-
-### WebTorrent Integration
-
-Use `rar-stream` with WebTorrent to stream video from RAR archives inside torrents:
-
-```javascript
-import WebTorrent from 'webtorrent';
-import { RarFilesPackage } from 'rar-stream';
-
-const client = new WebTorrent();
-
-client.add(magnetUri, (torrent) => {
-  // Find RAR files (includes .rar, .r00, .r01, etc. for multi-volume)
-  // WebTorrent files already implement the FileMedia interface!
-  const rarFiles = torrent.files
-    .filter(f => /\.(rar|r\d{2})$/i.test(f.name))
-    .sort((a, b) => a.name.localeCompare(b.name));
-
-  // No wrapper needed - pass torrent files directly
-  const pkg = new RarFilesPackage(rarFiles);
-  pkg.parse().then(innerFiles => {
-    const video = innerFiles.find(f => f.name.endsWith('.mkv'));
-    if (video) {
-      // Stream video content - this returns a Node.js Readable
-      const stream = video.createReadStream();
-      
-      // Pipe to HTTP response, media player, etc.
-      stream.pipe(process.stdout);
-    }
-  });
-});
-```
-
-### HTTP Range Request Handler (Express)
-
-```javascript
-import express from 'express';
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-
-const app = express();
-
-// Pre-parse the RAR archive
-const media = new LocalFileMedia('./videos.rar');
-const pkg = new RarFilesPackage([media]);
-const files = await pkg.parse();
-const video = files.find(f => f.name.endsWith('.mp4'));
-
-app.get('/video', (req, res) => {
-  const range = req.headers.range;
-  const fileSize = video.length;
-  
-  if (range) {
-    const [startStr, endStr] = range.replace(/bytes=/, '').split('-');
-    const start = parseInt(startStr, 10);
-    const end = endStr ? parseInt(endStr, 10) : fileSize - 1;
-    
-    res.writeHead(206, {
-      'Content-Range': `bytes ${start}-${end}/${fileSize}`,
-      'Accept-Ranges': 'bytes',
-      'Content-Length': end - start + 1,
-      'Content-Type': 'video/mp4',
-    });
-    
-    // Stream the range directly from the RAR archive
-    const stream = video.createReadStream({ start, end });
-    stream.pipe(res);
-  } else {
-    res.writeHead(200, {
-      'Content-Length': fileSize,
-      'Content-Type': 'video/mp4',
-    });
-    video.createReadStream().pipe(res);
-  }
-});
-
-app.listen(3000);
-```
-
-### Multi-Volume Archives
-
-```javascript
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-import fs from 'fs';
-import path from 'path';
-
-// Find all volumes in a directory
-const dir = './my-archive';
-const volumeFiles = fs.readdirSync(dir)
-  .filter(f => /\.(rar|r\d{2})$/i.test(f))
-  .sort()
-  .map(f => new LocalFileMedia(path.join(dir, f)));
-
-console.log(`Found ${volumeFiles.length} volumes`);
-
-const pkg = new RarFilesPackage(volumeFiles);
-const files = await pkg.parse();
-
-// Files spanning multiple volumes are handled automatically
-for (const file of files) {
-  console.log(`${file.name}: ${file.length} bytes`);
-}
-```
-
-### Check if a File is a RAR Archive
-
-```javascript
-import { isRarArchive, parseRarHeader } from 'rar-stream';
-import fs from 'fs';
-
-// Read first 300 bytes (enough for header detection)
-const buffer = Buffer.alloc(300);
-const fd = fs.openSync('./unknown-file', 'r');
-fs.readSync(fd, buffer, 0, 300, 0);
-fs.closeSync(fd);
-
-if (isRarArchive(buffer)) {
-  const info = parseRarHeader(buffer);
-  if (info) {
-    console.log(`First file: ${info.name}`);
-    console.log(`Packed size: ${info.packedSize} bytes`);
-    console.log(`Unpacked size: ${info.unpackedSize} bytes`);
-    console.log(`Compression method: 0x${info.method.toString(16)}`);
-  }
-} else {
-  console.log('Not a RAR archive');
-}
-```
-
-### Limit Number of Files Parsed
+Runnable examples in [`examples/`](./examples):
 
-```javascript
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
+| Example | Run | Description |
+|---------|-----|-------------|
+| [basic.ts](./examples/basic.ts) | `npx tsx examples/basic.ts <path>` | Parse RAR, list files, read content |
+| [http-stream.ts](./examples/http-stream.ts) | `npx tsx examples/http-stream.ts <rar>` | HTTP video server with range requests |
+| [extract.rs](./examples/extract.rs) | `cargo run --release --example extract --features async -- archive.rar out/` | Extract files to disk |
+| [browser.html](./examples/browser.html) | Open in browser (after `npm run build:wasm`) | WASM decompression demo |
+| [profile.rs](./examples/profile.rs) | `cargo run --release --example profile` | Benchmark decompression loop |
+| [benchmark_sizes.rs](./examples/benchmark_sizes.rs) | `cargo run --release --example benchmark_sizes` | Benchmark across file sizes |
 
-const media = new LocalFileMedia('./large-archive.rar');
-const pkg = new RarFilesPackage([media]);
-
-// Only parse first 10 files (useful for previewing large archives)
-const files = await pkg.parse({ maxFiles: 10 });
-console.log(`Showing first ${files.length} files`);
-```
+## API
 
-## API Reference
+### Classes
 
-### LocalFileMedia
+| Class | Description |
+|-------|-------------|
+| `LocalFileMedia(path)` | Wraps a local file for reading |
+| `RarFilesPackage(files)` | Parses single or multi-volume RAR archives |
+| `InnerFile` | A file inside the archive |
 
-Represents a local RAR file.
+### InnerFile
 
 ```typescript
-class LocalFileMedia {
-  constructor(path: string);
-  
-  readonly name: string;    // Filename (basename)
-  readonly length: number;  // File size in bytes
-  
-  // Read a byte range into a Buffer
-  // Create a Readable stream for a byte range
-  createReadStream(opts: { start: number; end: number }): Readable;
+class InnerFile {
+  readonly name: string;    // Full path inside archive
+  readonly length: number;  // Uncompressed size in bytes
+  readToEnd(): Promise<Buffer>;
+  createReadStream(opts?: { start?: number; end?: number }): Readable;
 }
 ```
 
 ### FileMedia Interface
 
-Custom data sources (WebTorrent, S3, HTTP, etc.) must implement this interface:
+Custom data sources (WebTorrent, S3, HTTP) must implement:
 
 ```typescript
 interface FileMedia {
@@ -311,134 +91,54 @@ interface FileMedia {
 }
 ```
 
-### RarFilesPackage
-
-Parses single or multi-volume RAR archives.
-
-```typescript
-class RarFilesPackage {
-  constructor(files: FileMedia[]);  // LocalFileMedia or custom FileMedia
-  
-  parse(opts?: {
-    maxFiles?: number;  // Limit number of files to parse
-  }): Promise<InnerFile[]>;
-}
-```
-
-### InnerFile
-
-Represents a file inside the RAR archive.
-
-```typescript
-import { Readable } from 'stream';
-
-class InnerFile {
-  readonly name: string;    // Full path inside archive
-  readonly length: number;  // Uncompressed size in bytes
-  
-  // Read entire file into memory
-  readToEnd(): Promise<Buffer>;
-  
-  // Create a Readable stream for the entire file or a byte range
-  createReadStream(opts?: { 
-    start?: number;   // Default: 0
-    end?: number;     // Default: length - 1
-  }): Readable;
-}
-```
-
 ### Utility Functions
 
-```typescript
-// Check if buffer starts with RAR signature
-function isRarArchive(buffer: Buffer): boolean;
-
-// Parse RAR header from buffer (needs ~300 bytes)
-function parseRarHeader(buffer: Buffer): RarFileInfo | null;
-
-// Convert a Readable stream to a Buffer
-function streamToBuffer(stream: Readable): Promise<Buffer>;
-
-// Create a FileMedia from any source with createReadStream
-function createFileMedia(source: FileMedia): FileMedia;
-
-interface RarFileInfo {
-  name: string;
-  packedSize: number;
-  unpackedSize: number;
-  method: number;
-  continuesInNext: boolean;
-}
-```
-
-## Compression Support
-
-### RAR Format Compatibility
-
-| Format | Signature | Support |
-|--------|-----------|---------|
-| RAR 1.5-4.x (RAR4) | `Rar!\x1a\x07\x00` | ✅ Full |
-| RAR 5.0+ (RAR5) | `Rar!\x1a\x07\x01\x00` | ✅ Full |
-
-### Compression Methods
-
-| Method | RAR4 | RAR5 | Description |
-|--------|------|------|-------------|
-| Store | ✅ | ✅ | No compression |
-| LZSS | ✅ | ✅ | Huffman + LZ77 sliding window |
-| PPMd | ✅ | — | Context-based (RAR4 only) |
-
-### Filter Support
-
-| Filter | RAR4 | RAR5 | Description |
-|--------|------|------|-------------|
-| E8 | ✅ | ✅ | x86 CALL preprocessing |
-| E8E9 | ✅ | ✅ | x86 CALL/JMP preprocessing |
-| Delta | ✅ | ✅ | Byte delta per channel |
-| ARM | — | ✅ | ARM branch preprocessing |
-| Itanium | ✅ | — | IA-64 preprocessing |
-| RGB | ✅ | — | Predictive color filter |
-| Audio | ✅ | — | Audio sample predictor |
-
-### Encryption Support
-
-| Feature | RAR4 | RAR5 | Notes |
-|---------|------|------|-------|
-| Encrypted files | ✅ | ✅ | `crypto` feature |
-| Encrypted headers | — | ✅ | RAR5 `-hp` archives |
-| Algorithm | AES-128-CBC | AES-256-CBC | — |
-| Key derivation | SHA-1 (262k rounds) | PBKDF2-HMAC-SHA256 | — |
-
-To enable encryption support:
-
-**Node.js/npm:** Encryption is always available.
-
-**Rust:**
-```toml
-[dependencies]
-rar-stream = { version = "5", features = ["async", "crypto"] }
-```
+| Function | Description |
+|----------|-------------|
+| `isRarArchive(buffer)` | Check if buffer starts with RAR signature |
+| `parseRarHeader(buffer)` | Parse RAR4 header from buffer (~300 bytes) |
+| `streamToBuffer(stream)` | Convert Readable to Buffer |
+| `createFileMedia(source)` | Wrap any `{ createReadStream }` as FileMedia |
+
+## Format Support
+
+| Feature | RAR4 | RAR5 |
+|---------|------|------|
+| Stored (no compression) | Yes | Yes |
+| LZSS (Huffman + LZ77) | Yes | Yes |
+| PPMd | Yes | -- |
+| E8/E8E9 filters (x86) | Yes | Yes |
+| Delta filter | Yes | Yes |
+| ARM filter | -- | Yes |
+| Itanium/RGB/Audio filters | Yes | -- |
+| Encrypted files (AES) | Yes | Yes |
+| Encrypted headers | -- | Yes |
+| Multi-volume | Yes | Yes |
+
+Encryption requires the `crypto` feature (always enabled in npm builds).
 
 ## Performance
 
-### RAR5 Decompression: Faster Than unrar
+Benchmarked against the official C `unrar` (v7.0) using `cargo bench`.
 
-rar-stream's parallel pipeline **beats the official C `unrar`** (v7.0, multi-threaded) across all tested workloads.
+Core decompression (3 KB files, single-threaded):
 
-Benchmark on AMD Ryzen 5 7640HS (6 cores):
+| Method | rar-stream | unrar | Speedup |
+|--------|-----------|-------|---------|
+| LZSS | 8 µs | 92 µs | 11x |
+| PPMd | 101 µs | 177 µs | 1.8x |
+| Stored | 54 ns | 123 µs | 2170x |
 
-| Archive | Size | rar-stream (pipeline) | unrar | Ratio |
-|---------|------|----------------------|-------|-------|
-| ISO (binary) | 200 MB | **422ms** | 453ms | **0.93×** |
-| Text | 200 MB | **144ms** | 202ms | **0.71×** |
-| Mixed | 200 MB | **342ms** | 527ms | **0.65×** |
-| Binary | 500 MB | **824ms** | 1149ms | **0.72×** |
-| Text | 500 MB | **424ms** | 604ms | **0.70×** |
-| Mixed | 1 GB | **1953ms** | 2550ms | **0.77×** |
+With the `parallel` feature (enabled by default in npm), rar-stream's pipeline beats unrar across all 24 benchmark scenarios. Best case: 1.9x faster.
 
-**Wins 24 out of 24 benchmark scenarios** across 6 data types × 4 compression settings.
-
-Best case: **1.9× faster** than unrar (ISO 200MB, `-m5 -md128m`).
+| Archive | Size | Pipeline | unrar | Ratio |
+|---------|------|----------|-------|-------|
+| Binary (ISO) | 200 MB | 289ms | 420ms | 0.69x |
+| Text | 200 MB | 119ms | 197ms | 0.61x |
+| Mixed | 200 MB | 307ms | 524ms | 0.59x |
+| Binary | 500 MB | 683ms | 1088ms | 0.63x |
+| Text | 500 MB | 357ms | 590ms | 0.61x |
+| Mixed | 1 GB | 1671ms | 2407ms | 0.69x |
 
 <details>
 <summary>Full benchmark matrix (24 scenarios)</summary>
@@ -446,74 +146,40 @@ Best case: **1.9× faster** than unrar (ISO 200MB, `-m5 -md128m`).
 ```
 Archive                  Single   Pipeline    Unrar   Pipe/Unrar
 ----------------------------------------------------------------
-bin-500_m3_32m            1278ms       884ms    1187ms     0.74x
-bin-500_m5_128m           1200ms       824ms    1149ms     0.72x
-bin-500_m5_32m            1247ms       852ms    1162ms     0.73x
-bin-500_m5_4m             1378ms       942ms    1770ms     0.53x
-iso-200_m3_32m             715ms       426ms     760ms     0.56x
-iso-200_m5_128m            720ms       423ms     811ms     0.52x
-iso-200_m5_32m             721ms       422ms     453ms     0.93x
-iso-200_m5_4m              717ms       422ms     442ms     0.95x
-mixed-1g_m3_32m           2974ms      2109ms    2775ms     0.76x
-mixed-1g_m5_128m          3177ms      2213ms    2984ms     0.74x
-mixed-1g_m5_32m           2979ms      2086ms    2731ms     0.76x
-mixed-1g_m5_4m            2761ms      1953ms    2550ms     0.77x
-mixed-200_m3_32m           499ms       385ms     547ms     0.70x
-mixed-200_m5_128m          438ms       342ms     527ms     0.65x
-mixed-200_m5_32m           495ms       384ms     539ms     0.71x
-mixed-200_m5_4m            511ms       395ms     538ms     0.73x
-text-200_m3_32m            209ms       145ms     202ms     0.72x
-text-200_m5_128m           205ms       144ms     239ms     0.60x
-text-200_m5_32m            209ms       144ms     202ms     0.71x
-text-200_m5_4m             227ms       153ms     207ms     0.74x
-text-500_m3_32m            606ms       432ms     613ms     0.70x
-text-500_m5_128m           601ms       431ms     644ms     0.67x
-text-500_m5_32m            604ms       424ms     604ms     0.70x
-text-500_m5_4m             659ms       455ms     643ms     0.71x
-```
+bin-500_m3_32m            1187ms       736ms    1122ms     0.66x
+bin-500_m5_128m           1122ms       683ms    1088ms     0.63x
+bin-500_m5_32m            1183ms       711ms    1119ms     0.64x
+bin-500_m5_4m             1311ms       765ms    1206ms     0.63x
+iso-200_m3_32m             693ms       289ms     420ms     0.69x
+iso-200_m5_128m            694ms       296ms     455ms     0.65x
+iso-200_m5_32m             697ms       290ms     418ms     0.69x
+iso-200_m5_4m              694ms       293ms     426ms     0.69x
+mixed-1g_m3_32m           2690ms      1818ms    2603ms     0.70x
+mixed-1g_m5_128m          2909ms      1916ms    2852ms     0.67x
+mixed-1g_m5_32m           2699ms      1794ms    2598ms     0.69x
+mixed-1g_m5_4m            2611ms      1671ms    2407ms     0.69x
+mixed-200_m3_32m           465ms       344ms     537ms     0.64x
+mixed-200_m5_128m          413ms       307ms     524ms     0.59x
+mixed-200_m5_32m           463ms       338ms     527ms     0.64x
+mixed-200_m5_4m            487ms       350ms     531ms     0.66x
+text-200_m3_32m            199ms       120ms     200ms     0.60x
+text-200_m5_128m           196ms       119ms     230ms     0.52x
+text-200_m5_32m            197ms       120ms     197ms     0.61x
+text-200_m5_4m             218ms       127ms     199ms     0.64x
+text-500_m3_32m            583ms       362ms     591ms     0.61x
+text-500_m5_128m           572ms       365ms     628ms     0.58x
+text-500_m5_32m            567ms       357ms     590ms     0.61x
+text-500_m5_4m             623ms       382ms     620ms     0.62x
+```
+
+Ratio < 1.0 = rar-stream is faster.
 
 </details>
 
-### Node.js (NAPI) Performance
-
-| Configuration | Time (200MB) | vs unrar |
-|---------------|-------------|----------|
-| v5.0.0 (single-threaded) | 1127ms | 2.73× slower |
-| **v5.1.0 (pipeline)** | **673ms** | **1.53× slower** |
-
-The remaining NAPI gap vs native is I/O + buffer copy overhead, not decompression.
-
-### Optimization Features
-
-- **Parallel pipeline**: Decode + apply in parallel using rayon worker threads
-- **Split-buffer decode**: Separates literals from commands for cache-friendly apply
-- **LTO (Link-Time Optimization)**: Enabled by default in release builds
-- **SIMD**: Automatic vectorization for E8/E9 filter scanning and memcpy
-- **Zero-copy streaming**: Direct buffer access without intermediate copies
-
 ## Migrating from v3.x
 
-rar-stream v4 is a complete Rust rewrite with the same API. It's a drop-in replacement:
-
-```javascript
-// Works the same in v3.x and v4.x
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-
-const media = new LocalFileMedia('./archive.rar');
-const pkg = new RarFilesPackage([media]);
-const files = await pkg.parse();
-```
-
-### Breaking Changes
-
-- Node.js 18+ required (was 14+)
-- Native Rust implementation (faster, lower memory)
+Drop-in replacement. Same API, native Rust implementation. Requires Node.js 18+.
 
 ## License
 
 MIT
-
-## Credits
-
-- Based on [unrar](https://www.rarlab.com/) reference implementation
-- PPMd algorithm by Dmitry Shkarin

package/lib/browser.d.ts

@@ -2,20 +2,35 @@
  * rar-stream browser entry point with Web Streams API support
  */
 
-// Re-export WASM bindings
+// WASM init
+/**
+ * Initialize the WASM module. Safe to call multiple times.
+ * Automatically called by all async helper functions.
+ */
+export declare function init(wasmUrl?: string | URL | Request | Response | BufferSource | WebAssembly.Module): Promise<void>;
+export declare function initSync(module: { module: BufferSource | WebAssembly.Module } | BufferSource | WebAssembly.Module): void;
+
+// Auto-init async helpers (call init() automatically)
+export declare function isRarArchive(data: Uint8Array): Promise<boolean>;
+export declare function getRarVersion(data: Uint8Array): Promise<number>;
+export declare function parseRarHeader(data: Uint8Array): Promise<any>;
+export declare function parseRarHeaders(data: Uint8Array): Promise<any[]>;
+export declare function parseRar5Header(data: Uint8Array): Promise<any>;
+export declare function parseRar5Headers(data: Uint8Array): Promise<any[]>;
+
+// Classes (require init() before construction)
+export { WasmRarDecoder, WasmRar5Decoder, WasmRar5Crypto } from '../pkg/rar_stream.d.ts';
+export { WasmRarDecoder as RarDecoder, WasmRar5Decoder as Rar5Decoder } from '../pkg/rar_stream.d.ts';
+
+// Direct snake_case access (require init() before use)
 export {
-  default as init,
-  initSync,
-  isRarArchive,
-  getRarVersion,
-  parseRarHeader,
-  RarDecoder,
-  WasmRar5Crypto,
   is_rar_archive,
   get_rar_version,
   parse_rar_header,
-  WasmRarDecoder,
-} from '../browser.js';
+  parse_rar_headers,
+  parse_rar5_header,
+  parse_rar5_headers,
+} from '../pkg/rar_stream.d.ts';
 
 /** Options for creating a ReadableStream */
 export interface ReadableStreamOptions {

package/lib/browser.mjs

@@ -4,26 +4,91 @@
  * Provides ReadableStream support for streaming file content in browsers.
  */
 
-// Re-export all WASM bindings
-export {
-  default as init,
-  initSync,
-  is_rar_archive as isRarArchive,
-  get_rar_version as getRarVersion,
-  parse_rar_header as parseRarHeader,
-  WasmRarDecoder as RarDecoder,
-} from '../pkg/rar_stream.js';
-
-// Also export snake_case versions for compatibility
-export {
+import wasmInit, {
+  initSync as _initSync,
   is_rar_archive,
   get_rar_version,
   parse_rar_header,
+  parse_rar_headers,
+  parse_rar5_header,
+  parse_rar5_headers,
   WasmRarDecoder,
+  WasmRar5Decoder,
+  WasmRar5Crypto,
 } from '../pkg/rar_stream.js';
 
-// Re-export crypto if available
-export { WasmRar5Crypto } from '../pkg/rar_stream.js';
+let _initialized = false;
+let _initPromise = null;
+
+/**
+ * Initialize the WASM module. Safe to call multiple times — subsequent calls are no-ops.
+ * Automatically called by all exported functions, but can be called explicitly for eager loading.
+ * @param {string | URL | Request | Response | BufferSource | WebAssembly.Module} [wasmUrl] - Optional WASM source
+ */
+export async function init(wasmUrl) {
+  if (_initialized) return;
+  if (_initPromise) return _initPromise;
+  _initPromise = wasmInit(wasmUrl).then(() => { _initialized = true; });
+  return _initPromise;
+}
+
+export { _initSync as initSync };
+
+// Auto-init wrappers for all functions
+async function ensureInit() {
+  if (!_initialized) await init();
+}
+
+/** Check if a buffer contains a RAR signature. */
+export async function isRarArchive(data) {
+  await ensureInit();
+  return is_rar_archive(data);
+}
+
+/** Get the RAR format version (15 for RAR4, 50 for RAR5, 0 if not RAR). */
+export async function getRarVersion(data) {
+  await ensureInit();
+  return get_rar_version(data);
+}
+
+/** Parse the first RAR4 file header from a buffer. */
+export async function parseRarHeader(data) {
+  await ensureInit();
+  return parse_rar_header(data);
+}
+
+/** Parse all RAR4 file headers from a buffer. */
+export async function parseRarHeaders(data) {
+  await ensureInit();
+  return parse_rar_headers(data);
+}
+
+/** Parse the first RAR5 file header from a buffer. */
+export async function parseRar5Header(data) {
+  await ensureInit();
+  return parse_rar5_header(data);
+}
+
+/** Parse all RAR5 file headers from a buffer. */
+export async function parseRar5Headers(data) {
+  await ensureInit();
+  return parse_rar5_headers(data);
+}
+
+// Re-export classes (require manual init() before use)
+export { WasmRarDecoder, WasmRar5Decoder, WasmRar5Crypto };
+// Aliases
+export { WasmRarDecoder as RarDecoder, WasmRar5Decoder as Rar5Decoder };
+
+// Re-export snake_case direct access (require manual init() before use)
+export {
+  is_rar_archive,
+  get_rar_version,
+  parse_rar_header,
+  parse_rar_headers,
+  parse_rar5_header,
+  parse_rar5_headers,
+};
 
 /**
  * Create a Web ReadableStream from an async data source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rar-stream",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "RAR streaming library - Rust implementation with NAPI and WASM bindings",
   "main": "lib/index.mjs",
   "browser": "lib/browser.mjs",
@@ -105,12 +105,12 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rar-stream-win32-x64-msvc": "5.1.0",
-    "rar-stream-darwin-x64": "5.1.0",
-    "rar-stream-linux-x64-gnu": "5.1.0",
-    "rar-stream-linux-x64-musl": "5.1.0",
-    "rar-stream-linux-arm64-gnu": "5.1.0",
-    "rar-stream-darwin-arm64": "5.1.0",
-    "rar-stream-linux-arm64-musl": "5.1.0"
+    "rar-stream-win32-x64-msvc": "5.1.1",
+    "rar-stream-darwin-x64": "5.1.1",
+    "rar-stream-linux-x64-gnu": "5.1.1",
+    "rar-stream-linux-x64-musl": "5.1.1",
+    "rar-stream-linux-arm64-gnu": "5.1.1",
+    "rar-stream-darwin-arm64": "5.1.1",
+    "rar-stream-linux-arm64-musl": "5.1.1"
   }
 }