rar-stream 4.0.3 → 5.1.0

package/README.md

@@ -1,22 +1,46 @@
 # rar-stream
 
-> Fast RAR archive streaming for Node.js and browsers. Zero dependencies, pure Rust.
+> Fast RAR archive streaming for Rust, Node.js, and browsers. Zero dependencies core.
 
+[![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
 
 - 🚀 **Fast**: Native Rust implementation with NAPI bindings
-- 📦 **Zero dependencies**: No external runtime dependencies
+- 📦 **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 VM filters
+- 🗜️ **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
 
 ## Installation
 
+### Rust
+
+```toml
+[dependencies]
+rar-stream = { version = "5", features = ["async", "crypto"] }
+```
+
+### Node.js
+
 ```bash
 npm install rar-stream
 # or
@@ -43,8 +67,34 @@ for (const file of files) {
   // Read entire file into memory
   const buffer = await file.readToEnd();
   
-  // Or read a specific byte range (for streaming)
-  const chunk = await file.createReadStream({ start: 0, end: 1023 });
+  // 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(())
 }
 ```
 
@@ -69,10 +119,11 @@ if (targetFile) {
 }
 ```
 
-### Stream Video from RAR (Partial Reads)
+### 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]);
@@ -80,20 +131,92 @@ const files = await pkg.parse();
 
 const video = files.find(f => f.name.endsWith('.mkv'));
 if (video) {
-  // Read first 1MB for header analysis
-  const header = await video.createReadStream({ start: 0, end: 1024 * 1024 - 1 });
-  console.log(`Video: ${video.name}, Total size: ${video.length} bytes`);
+  // Get a Node.js Readable stream for the entire file
+  const stream = video.createReadStream();
+  stream.pipe(fs.createWriteStream('./extracted-video.mkv'));
   
-  // Stream in chunks
-  const chunkSize = 1024 * 1024; // 1MB chunks
-  for (let offset = 0; offset < video.length; offset += chunkSize) {
-    const end = Math.min(offset + chunkSize - 1, video.length - 1);
-    const chunk = await video.createReadStream({ start: offset, end });
-    // Process chunk...
-  }
+  // 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
@@ -170,7 +293,21 @@ class LocalFileMedia {
   readonly name: string;    // Filename (basename)
   readonly length: number;  // File size in bytes
   
-  createReadStream(opts: { start: number; end: number }): Promise<Buffer>;
+  // Read a byte range into a Buffer
+  // Create a Readable stream for a byte range
+  createReadStream(opts: { start: number; end: number }): Readable;
+}
+```
+
+### FileMedia Interface
+
+Custom data sources (WebTorrent, S3, HTTP, etc.) must implement this interface:
+
+```typescript
+interface FileMedia {
+  readonly name: string;
+  readonly length: number;
+  createReadStream(opts: { start: number; end: number }): Readable;
 }
 ```
 
@@ -180,7 +317,7 @@ Parses single or multi-volume RAR archives.
 
 ```typescript
 class RarFilesPackage {
-  constructor(files: LocalFileMedia[]);
+  constructor(files: FileMedia[]);  // LocalFileMedia or custom FileMedia
   
   parse(opts?: {
     maxFiles?: number;  // Limit number of files to parse
@@ -193,12 +330,20 @@ class RarFilesPackage {
 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>;
-  createReadStream(opts: { start: number; end: number }): 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;
 }
 ```
 
@@ -211,6 +356,12 @@ 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;
@@ -222,22 +373,123 @@ interface RarFileInfo {
 
 ## Compression Support
 
-| Method | Support | Description |
-|--------|---------|-------------|
-| Store (0x30) | ✅ | No compression |
-| LZSS (0x31-0x35) | ✅ | Huffman + LZ77 |
-| PPMd | ✅ | Context-based |
-| VM Filters | ✅ | E8, Delta, Audio, RGB |
+### 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"] }
+```
 
 ## Performance
 
-Benchmarks on M1 MacBook Pro (v4.x vs v3.x):
+### RAR5 Decompression: Faster Than unrar
+
+rar-stream's parallel pipeline **beats the official C `unrar`** (v7.0, multi-threaded) across all tested workloads.
+
+Benchmark on AMD Ryzen 5 7640HS (6 cores):
+
+| 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×** |
+
+**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`).
+
+<details>
+<summary>Full benchmark matrix (24 scenarios)</summary>
+
+```
+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
+```
+
+</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
 
-| Operation | rar-stream v4 (Rust) | rar-stream v3 (JS) |
-|-----------|---------------------|-------------------|
-| Parse 1GB archive | ~50ms | ~200ms |
-| Decompress 100MB | ~800ms | ~3000ms |
-| Memory usage | ~50MB | ~200MB |
+- **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
 

package/lib/browser.d.ts

@@ -0,0 +1,63 @@
+/**
+ * rar-stream browser entry point with Web Streams API support
+ */
+
+// Re-export WASM bindings
+export {
+  default as init,
+  initSync,
+  isRarArchive,
+  getRarVersion,
+  parseRarHeader,
+  RarDecoder,
+  WasmRar5Crypto,
+  is_rar_archive,
+  get_rar_version,
+  parse_rar_header,
+  WasmRarDecoder,
+} from '../browser.js';
+
+/** Options for creating a ReadableStream */
+export interface ReadableStreamOptions {
+  /** Total size of the data */
+  totalSize: number;
+  /** Start offset (default: 0) */
+  start?: number;
+  /** End offset inclusive (default: totalSize - 1) */
+  end?: number;
+  /** Size of each chunk to read (default: 65536) */
+  chunkSize?: number;
+  /** Function to read a chunk of data */
+  readChunk: (start: number, end: number) => Promise<Uint8Array>;
+}
+
+/** Options for creating a range response */
+export interface RangeResponseOptions {
+  /** Total file size */
+  totalSize: number;
+  /** HTTP Range header value */
+  rangeHeader?: string;
+  /** MIME type (default: 'application/octet-stream') */
+  contentType?: string;
+  /** Function to read a chunk of data */
+  readChunk: (start: number, end: number) => Promise<Uint8Array>;
+}
+
+/** Result from createRangeResponse */
+export interface RangeResponseResult {
+  stream: ReadableStream<Uint8Array>;
+  headers: Headers;
+  status: number;
+}
+
+/**
+ * Create a Web ReadableStream from an async data source.
+ * Useful for Service Workers and streaming responses.
+ */
+export declare function createReadableStream(options: ReadableStreamOptions): ReadableStream<Uint8Array>;
+
+/**
+ * Helper to create a streaming response for HTTP range requests.
+ * Parses the Range header and returns appropriate stream, headers, and status.
+ */
+export declare function createRangeResponse(options: RangeResponseOptions): RangeResponseResult;

package/lib/browser.mjs

@@ -0,0 +1,132 @@
+/**
+ * rar-stream browser entry point with Web Streams API support
+ * 
+ * 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 {
+  is_rar_archive,
+  get_rar_version,
+  parse_rar_header,
+  WasmRarDecoder,
+} from '../pkg/rar_stream.js';
+
+// Re-export crypto if available
+export { WasmRar5Crypto } from '../pkg/rar_stream.js';
+
+/**
+ * Create a Web ReadableStream from an async data source.
+ * 
+ * This utility helps create streaming responses for browsers,
+ * useful for Service Workers and fetch handlers.
+ * 
+ * @param {Object} options
+ * @param {number} options.totalSize - Total size of the data
+ * @param {number} [options.start=0] - Start offset
+ * @param {number} [options.end] - End offset (inclusive), defaults to totalSize-1
+ * @param {number} [options.chunkSize=65536] - Size of each chunk to read
+ * @param {function(start: number, end: number): Promise<Uint8Array>} options.readChunk - Function to read a chunk
+ * @returns {ReadableStream<Uint8Array>}
+ * 
+ * @example
+ * // In a Service Worker fetch handler
+ * const stream = createReadableStream({
+ *   totalSize: file.length,
+ *   start: rangeStart,
+ *   end: rangeEnd,
+ *   readChunk: async (start, end) => {
+ *     const decoder = new WasmRarDecoder(file.unpackedSize);
+ *     // ... fetch and decompress data
+ *     return decompressedData.slice(start, end + 1);
+ *   }
+ * });
+ * return new Response(stream, { headers: { 'Content-Type': 'video/mp4' } });
+ */
+export function createReadableStream(options) {
+  const { totalSize, start = 0, end = totalSize - 1, chunkSize = 64 * 1024, readChunk } = options;
+  let offset = start;
+
+  return new ReadableStream({
+    async pull(controller) {
+      if (offset > end) {
+        controller.close();
+        return;
+      }
+      
+      const chunkEnd = Math.min(offset + chunkSize - 1, end);
+      try {
+        const chunk = await readChunk(offset, chunkEnd);
+        controller.enqueue(chunk);
+        offset = chunkEnd + 1;
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+  });
+}
+
+/**
+ * Helper to create a streaming response for range requests.
+ * 
+ * @param {Object} options
+ * @param {number} options.totalSize - Total file size
+ * @param {string} [options.rangeHeader] - HTTP Range header value
+ * @param {string} [options.contentType='application/octet-stream'] - MIME type
+ * @param {function(start: number, end: number): Promise<Uint8Array>} options.readChunk
+ * @returns {{ stream: ReadableStream, headers: Headers, status: number }}
+ * 
+ * @example
+ * // In a Service Worker
+ * const { stream, headers, status } = createRangeResponse({
+ *   totalSize: innerFile.length,
+ *   rangeHeader: request.headers.get('Range'),
+ *   contentType: 'video/mp4',
+ *   readChunk: async (start, end) => decompress(start, end),
+ * });
+ * return new Response(stream, { status, headers });
+ */
+export function createRangeResponse(options) {
+  const { totalSize, rangeHeader, contentType = 'application/octet-stream', readChunk } = options;
+  
+  let start = 0;
+  let end = totalSize - 1;
+  let status = 200;
+  
+  const headers = new Headers({
+    'Content-Type': contentType,
+    'Accept-Ranges': 'bytes',
+  });
+  
+  // Parse Range header if present
+  if (rangeHeader) {
+    const match = rangeHeader.match(/bytes=(\d*)-(\d*)/);
+    if (match) {
+      start = match[1] ? parseInt(match[1], 10) : 0;
+      end = match[2] ? parseInt(match[2], 10) : totalSize - 1;
+      status = 206;
+      headers.set('Content-Range', `bytes ${start}-${end}/${totalSize}`);
+    }
+  }
+  
+  headers.set('Content-Length', String(end - start + 1));
+  
+  const stream = createReadableStream({
+    totalSize,
+    start,
+    end,
+    readChunk,
+  });
+  
+  return { stream, headers, status };
+}

package/lib/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * rar-stream - Node.js wrapper with Readable stream support
+ */
+
+import { Readable } from 'stream';
+
+/** Read interval options. */
+export interface ReadIntervalJs {
+  start: number;
+  end: number;
+}
+
+/** Stream options for createReadStream. */
+export interface StreamOptions {
+  start?: number;
+  end?: number;
+}
+
+/** Parse options for filtering results. */
+export interface ParseOptionsJs {
+  maxFiles?: number;
+}
+
+/** Parsed file info from RAR header. */
+export interface RarFileInfo {
+  name: string;
+  packedSize: number;
+  unpackedSize: number;
+  method: number;
+  continuesInNext: boolean;
+}
+
+/**
+ * FileMedia interface for custom file sources.
+ * Implement this to use WebTorrent, HTTP, S3, etc.
+ */
+export interface FileMedia {
+  readonly name: string;
+  readonly length: number;
+  createReadStream(opts: ReadIntervalJs): Readable;
+}
+
+/**
+ * Helper to read a Readable stream into a Buffer.
+ */
+export declare function streamToBuffer(stream: Readable): Promise<Buffer>;
+
+/**
+ * Create a FileMedia wrapper from any object with createReadStream.
+ * Use this to wrap WebTorrent files, HTTP responses, S3 objects, etc.
+ */
+export declare function createFileMedia(source: FileMedia): FileMedia;
+
+/**
+ * Parse RAR file header from a buffer.
+ * This can be used to detect RAR archives and get inner file info
+ * without downloading the entire archive.
+ *
+ * The buffer should contain at least the first ~300 bytes of a .rar file.
+ */
+export declare function parseRarHeader(buffer: Buffer): RarFileInfo | null;
+
+/** Check if a buffer starts with a RAR signature. */
+export declare function isRarArchive(buffer: Buffer): boolean;
+
+/**
+ * LocalFileMedia - reads from local filesystem.
+ * Implements the FileMedia interface.
+ */
+export declare class LocalFileMedia implements FileMedia {
+  constructor(path: string);
+  
+  readonly name: string;
+  readonly length: number;
+  
+  /**
+   * Create a Readable stream for a byte range.
+   * @param opts Byte range (inclusive)
+   */
+  createReadStream(opts: ReadIntervalJs): Readable;
+}
+
+/**
+ * InnerFile - a file inside the RAR archive.
+ * Provides stream-based access to file content.
+ */
+export declare class InnerFile {
+  readonly name: string;
+  readonly length: number;
+  
+  /**
+   * Create a Readable stream for the entire file or a byte range.
+   * 
+   * @example
+   * // Stream entire file
+   * const stream = file.createReadStream();
+   * stream.pipe(fs.createWriteStream('output.bin'));
+   * 
+   * @example
+   * // Stream with range (for HTTP range requests, WebTorrent, etc.)
+   * const stream = file.createReadStream({ start: 0, end: 1024 * 1024 - 1 });
+   */
+  createReadStream(opts?: StreamOptions): Readable;
+  
+  /** Read entire file into memory. */
+  readToEnd(): Promise<Buffer>;
+}
+
+/**
+ * RarFilesPackage - parses multi-volume RAR archives.
+ * 
+ * Supports both LocalFileMedia and custom FileMedia implementations.
+ */
+export declare class RarFilesPackage {
+  constructor(files: FileMedia[]);
+  
+  /** Parse the archive and return inner files. */
+  parse(opts?: ParseOptionsJs | undefined | null): Promise<InnerFile[]>;
+}

package/lib/index.mjs

@@ -0,0 +1,376 @@
+/**
+ * rar-stream - Node.js wrapper with Readable stream support
+ * 
+ * This module wraps the native NAPI bindings to provide Node.js Readable streams
+ * for streaming file content from RAR archives.
+ * 
+ * Supports both native LocalFileMedia and custom FileMedia implementations
+ * (like WebTorrent files).
+ */
+
+import { Readable } from 'stream';
+import { createRequire } from 'module';
+
+// Import native bindings (CommonJS, auto-generated by NAPI-RS)
+const require = createRequire(import.meta.url);
+const native = require('../index.js');
+const {
+  LocalFileMedia: NativeLocalFileMedia,
+  InnerFile: NativeInnerFile,
+  RarFilesPackage: NativeRarFilesPackage,
+  parseRarHeader,
+  isRarArchive,
+} = native;
+
+// Re-export utility functions
+export { parseRarHeader, isRarArchive };
+
+// RAR signatures
+const RAR4_SIGNATURE = Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x00]);
+const RAR5_SIGNATURE = Buffer.from([0x52, 0x61, 0x72, 0x21, 0x1A, 0x07, 0x01, 0x00]);
+
+/**
+ * Helper to read a Readable stream into a Buffer.
+ * @param {Readable} stream
+ * @returns {Promise<Buffer>}
+ */
+export function streamToBuffer(stream) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    stream.on('data', chunk => chunks.push(chunk));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+  });
+}
+
+/**
+ * Check if a file is a native LocalFileMedia
+ */
+function isNativeMedia(file) {
+  return file._native instanceof NativeLocalFileMedia || 
+         file instanceof NativeLocalFileMedia ||
+         (file._nativeMedia && file._nativeMedia instanceof NativeLocalFileMedia);
+}
+
+/**
+ * Create a FileMedia wrapper from any object with createReadStream.
+ * 
+ * This is optional - any object with name, length, and createReadStream
+ * can be passed directly to RarFilesPackage (like WebTorrent files).
+ * 
+ * Use this helper when your source has different property names or
+ * needs adaptation to the FileMedia interface.
+ * 
+ * @param {Object} source - Object implementing FileMedia interface
+ * @returns {FileMedia}
+ * 
+ * @example
+ * // Adapt an S3 object to FileMedia
+ * const media = createFileMedia({
+ *   name: s3Object.Key,
+ *   length: s3Object.ContentLength,
+ *   createReadStream: ({ start, end }) => s3.getObject({
+ *     Bucket: bucket,
+ *     Key: s3Object.Key,
+ *     Range: `bytes=${start}-${end}`,
+ *   }).createReadStream(),
+ * });
+ */
+export function createFileMedia(source) {
+  return {
+    get name() { return source.name; },
+    get length() { return source.length; },
+    createReadStream(opts) {
+      return source.createReadStream(opts);
+    },
+  };
+}
+
+/**
+ * LocalFileMedia - reads from local filesystem.
+ * Implements the FileMedia interface.
+ */
+export class LocalFileMedia {
+  constructor(path) {
+    this._native = new NativeLocalFileMedia(path);
+  }
+
+  get name() {
+    return this._native.name;
+  }
+
+  get length() {
+    return this._native.length;
+  }
+
+  /**
+   * Create a Readable stream for a byte range.
+   * @param {{ start: number, end: number }} opts - Byte range (inclusive)
+   * @returns {Readable}
+   */
+  createReadStream(opts) {
+    const { start, end } = opts;
+    const media = this._native;
+    let offset = start;
+
+    return new Readable({
+      highWaterMark: 64 * 1024,
+      async read(size) {
+        if (offset > end) {
+          this.push(null);
+          return;
+        }
+        const chunkEnd = Math.min(offset + size - 1, end);
+        try {
+          // Native returns Promise<Buffer>, we stream it
+          const chunk = await media.createReadStream({ start: offset, end: chunkEnd });
+          offset = chunkEnd + 1;
+          this.push(chunk);
+        } catch (err) {
+          this.destroy(err);
+        }
+      },
+    });
+  }
+
+  /** @internal */
+  get _nativeMedia() {
+    return this._native;
+  }
+}
+
+/**
+ * InnerFile - a file inside the RAR archive.
+ * Wraps the native implementation with stream support.
+ */
+export class InnerFile {
+  constructor(nativeInnerFile) {
+    this._native = nativeInnerFile;
+  }
+
+  get name() {
+    return this._native.name;
+  }
+
+  get length() {
+    return this._native.length;
+  }
+
+  /**
+   * Create a Readable stream for a byte range or entire file.
+   * @param {{ start?: number, end?: number }} [opts] - Byte range (inclusive)
+   * @returns {Readable}
+   * 
+   * @example
+   * // Stream entire file
+   * const stream = file.createReadStream();
+   * stream.pipe(fs.createWriteStream('output.bin'));
+   * 
+   * @example
+   * // Stream a specific range (for HTTP range requests)
+   * const stream = file.createReadStream({ start: 0, end: 1024 * 1024 - 1 });
+   * stream.pipe(res);
+   */
+  createReadStream(opts = {}) {
+    const start = opts.start ?? 0;
+    const end = opts.end ?? this.length - 1;
+    const innerFile = this._native;
+    let offset = start;
+
+    return new Readable({
+      highWaterMark: 64 * 1024,
+      async read(size) {
+        if (offset > end) {
+          this.push(null);
+          return;
+        }
+        const chunkEnd = Math.min(offset + size - 1, end);
+        try {
+          // Native returns Promise<Buffer>
+          const chunk = await innerFile.createReadStream({ start: offset, end: chunkEnd });
+          offset = chunkEnd + 1;
+          this.push(chunk);
+        } catch (err) {
+          this.destroy(err);
+        }
+      },
+    });
+  }
+
+  /**
+   * Read entire file into memory.
+   * @returns {Promise<Buffer>}
+   */
+  async readToEnd() {
+    return this._native.readToEnd();
+  }
+}
+
+/**
+ * JsInnerFile - a file inside the RAR archive (JS-based implementation).
+ * Used when parsing with custom FileMedia implementations.
+ */
+class JsInnerFile {
+  constructor(opts) {
+    this._name = opts.name;
+    this._length = opts.unpackedSize;
+    this._packedSize = opts.packedSize;
+    this._method = opts.method;
+    this._dataOffset = opts.dataOffset;
+    this._media = opts.media;
+    this._isStored = opts.method === 0x30;
+  }
+
+  get name() {
+    return this._name;
+  }
+
+  get length() {
+    return this._length;
+  }
+
+  /**
+   * Create a Readable stream for a byte range or entire file.
+   * Note: Range reads only work for stored files (method 0x30).
+   * Compressed files require full decompression.
+   * 
+   * @param {{ start?: number, end?: number }} [opts]
+   * @returns {Readable}
+   */
+  createReadStream(opts = {}) {
+    const start = opts.start ?? 0;
+    const end = opts.end ?? this.length - 1;
+    const file = this;
+
+    if (!this._isStored) {
+      // For compressed files, throw an error for range reads
+      if (start !== 0 || end !== this.length - 1) {
+        throw new Error('Range reads not supported for compressed files. Use readToEnd() instead.');
+      }
+      // TODO: streaming decompression
+      throw new Error('Streaming compressed files not yet supported for custom FileMedia.');
+    }
+
+    // For stored files, stream directly from the source
+    const dataOffset = this._dataOffset;
+    const media = this._media;
+    let offset = start;
+
+    return new Readable({
+      highWaterMark: 64 * 1024,
+      async read(size) {
+        if (offset > end) {
+          this.push(null);
+          return;
+        }
+        const chunkEnd = Math.min(offset + size - 1, end);
+        try {
+          // Get stream from underlying media and collect it
+          const dataStart = dataOffset + offset;
+          const dataEnd = dataOffset + chunkEnd;
+          const sourceStream = media.createReadStream({ start: dataStart, end: dataEnd });
+          const chunk = await streamToBuffer(sourceStream);
+          offset = chunkEnd + 1;
+          this.push(chunk);
+        } catch (err) {
+          this.destroy(err);
+        }
+      },
+    });
+  }
+
+  /**
+   * Read entire file into memory.
+   * @returns {Promise<Buffer>}
+   */
+  async readToEnd() {
+    const stream = this.createReadStream();
+    return streamToBuffer(stream);
+  }
+}
+
+/**
+ * RarFilesPackage - parses multi-volume RAR archives.
+ * 
+ * Supports both native LocalFileMedia and custom FileMedia implementations
+ * (like WebTorrent files). Custom implementations must have:
+ * - name: string
+ * - length: number
+ * - createReadStream({ start, end }): Readable
+ */
+export class RarFilesPackage {
+  constructor(files) {
+    this._files = files;
+    this._useNative = files.every(f => isNativeMedia(f));
+    
+    if (this._useNative) {
+      const nativeFiles = files.map(f => f._nativeMedia ?? f._native ?? f);
+      this._native = new NativeRarFilesPackage(nativeFiles);
+    }
+  }
+
+  /**
+   * Parse the archive and return inner files.
+   * @param {{ maxFiles?: number }} [opts]
+   * @returns {Promise<InnerFile[]>}
+   */
+  async parse(opts) {
+    if (this._useNative) {
+      const nativeFiles = await this._native.parse(opts);
+      return nativeFiles.map(f => new InnerFile(f));
+    }
+    
+    // JS-based parsing for custom FileMedia
+    return this._parseJs(opts);
+  }
+  
+  /**
+   * JS-based parsing for custom FileMedia implementations.
+   * @private
+   */
+  async _parseJs(opts) {
+    const maxFiles = opts?.maxFiles;
+    const results = [];
+    
+    for (const media of this._files) {
+      // Read header data (first 512 bytes should be enough for header)
+      const headerSize = Math.min(512, media.length);
+      const headerStream = media.createReadStream({ start: 0, end: headerSize - 1 });
+      const headerData = await streamToBuffer(headerStream);
+      
+      // Check signature
+      if (!isRarArchive(headerData)) {
+        continue;
+      }
+      
+      // Determine RAR version
+      const isRar5 = headerData.slice(0, 8).equals(RAR5_SIGNATURE);
+      
+      // Parse header to get file info
+      const header = parseRarHeader(headerData);
+      if (!header) {
+        continue;
+      }
+      
+      // Calculate data offset (approximate - after headers)
+      // For RAR4: marker(7) + archive(13) + file header (variable)
+      // For RAR5: signature(8) + headers (variable length)
+      const dataOffset = media.length - header.packedSize;
+      
+      results.push(new JsInnerFile({
+        name: header.name,
+        packedSize: header.packedSize,
+        unpackedSize: header.unpackedSize,
+        method: header.method,
+        dataOffset,
+        media,
+      }));
+      
+      if (maxFiles && results.length >= maxFiles) {
+        break;
+      }
+    }
+    
+    return results;
+  }
+}

package/package.json

@@ -1,21 +1,27 @@
 {
   "name": "rar-stream",
-  "version": "4.0.3",
+  "version": "5.1.0",
   "description": "RAR streaming library - Rust implementation with NAPI and WASM bindings",
-  "main": "index.js",
-  "browser": "browser.js",
-  "types": "index.d.ts",
+  "main": "lib/index.mjs",
+  "browser": "lib/browser.mjs",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "node": {
-        "types": "./index.d.ts",
-        "default": "./index.js"
+        "types": "./lib/index.d.ts",
+        "import": "./lib/index.mjs",
+        "require": "./index.js"
       },
       "browser": {
-        "types": "./browser.d.ts",
-        "default": "./browser.js"
+        "types": "./lib/browser.d.ts",
+        "import": "./lib/browser.mjs"
       },
-      "default": "./index.js"
+      "import": "./lib/index.mjs",
+      "require": "./index.js"
+    },
+    "./native": {
+      "types": "./index.d.ts",
+      "require": "./index.js"
     }
   },
   "author": "doom-fish",
@@ -55,15 +61,20 @@
   "scripts": {
     "build": "napi build --platform --release --features napi",
     "build:debug": "napi build --platform --features napi",
-    "build:wasm": "wasm-pack build --target web --features wasm --no-default-features",
+    "build:wasm": "wasm-pack build --target web --features wasm,crypto --no-default-features",
     "lint": "eslint .",
-    "lint:rust": "cargo clippy --features napi -- -D warnings && cargo clippy --features wasm --no-default-features -- -D warnings",
+    "lint:rust": "cargo clippy --features napi -- -D warnings && cargo clippy --features wasm,crypto --no-default-features -- -D warnings",
     "lint:fix": "eslint . --fix",
     "format": "cargo fmt && prettier --write '**/*.{ts,js,json,md}'",
     "format:check": "cargo fmt --check && prettier --check '**/*.{ts,js,json,md}'",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:browser": "npx playwright test",
+    "bench": "cargo bench",
+    "bench:save": "cargo bench -- --save-baseline main",
+    "bench:compare": "cargo bench -- --baseline main",
+    "profile": "cargo build --release && perf record -g ./target/release/examples/profile_decompress && perf report",
+    "flamegraph": "cargo flamegraph --bench decompress -- --bench",
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
   },
   "devDependencies": {
@@ -75,9 +86,14 @@
     "prettier": "^3.2.0",
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "webtorrent": "^2.8.5"
   },
   "files": [
+    "lib/index.mjs",
+    "lib/index.d.ts",
+    "lib/browser.mjs",
+    "lib/browser.d.ts",
     "index.js",
     "index.d.ts",
     "browser.js",
@@ -89,12 +105,12 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rar-stream-win32-x64-msvc": "4.0.3",
-    "rar-stream-darwin-x64": "4.0.3",
-    "rar-stream-linux-x64-gnu": "4.0.3",
-    "rar-stream-linux-x64-musl": "4.0.3",
-    "rar-stream-linux-arm64-gnu": "4.0.3",
-    "rar-stream-darwin-arm64": "4.0.3",
-    "rar-stream-linux-arm64-musl": "4.0.3"
+    "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"
   }
 }