rar-stream 5.7.0 → 5.7.2

package/README.md

@@ -1,283 +0,0 @@
-<div align="center">
-  <h1>rar-stream</h1>
-</div>
-
-<div align="center"><p>
-    <a href="https://crates.io/crates/rar-stream"><img alt="Crates.io" src="https://img.shields.io/crates/v/rar-stream?style=for-the-badge&logo=rust&color=C9CBFF&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://crates.io/crates/rar-stream"><img alt="Crates.io Downloads" src="https://img.shields.io/crates/d/rar-stream?style=for-the-badge&logo=rust&color=A6E3A1&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://docs.rs/rar-stream"><img alt="docs.rs" src="https://img.shields.io/docsrs/rar-stream?style=for-the-badge&logo=docs.rs&color=8bd5ca&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://www.npmjs.com/package/rar-stream"><img alt="npm" src="https://img.shields.io/npm/v/rar-stream?style=for-the-badge&logo=npm&color=F5A97F&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://www.npmjs.com/package/rar-stream"><img alt="npm Downloads" src="https://img.shields.io/npm/dm/rar-stream?style=for-the-badge&logo=npm&color=F5E0DC&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://github.com/doom-fish/rar-stream#license"><img alt="License" src="https://img.shields.io/crates/l/rar-stream?style=for-the-badge&logo=apache&color=ee999f&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://github.com/doom-fish/rar-stream/actions"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/doom-fish/rar-stream/ci.yml?branch=main&style=for-the-badge&logo=github&color=c69ff5&logoColor=D9E0EE&labelColor=302D41" /></a>
-    <a href="https://codecov.io/gh/doom-fish/rar-stream"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/doom-fish/rar-stream?style=for-the-badge&logo=codecov&color=F0C6C6&logoColor=D9E0EE&labelColor=302D41" /></a>
-</p></div>
-
-> Fast RAR archive streaming for Rust, Node.js, and browsers. Zero dependencies core.
-
-## 📑 Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Examples](#examples)
-- [API](#api)
-- [Feature Flags](#feature-flags)
-- [Format Support](#format-support)
-- [Performance](#performance)
-- [Migrating from v3.x](#migrating-from-v3x)
-- [Architecture](ARCHITECTURE.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security](SECURITY.md)
-- [Changelog](CHANGELOG.md)
-- [License](#license)
-
-## Installation
-
-### Node.js
-
-```bash
-npm install rar-stream
-```
-
-Native binaries are automatically downloaded from [GitHub Releases](https://github.com/doom-fish/rar-stream/releases) during install. Supported platforms: Linux (x64, arm64), macOS (x64, arm64), Windows (x64).
-
-### Rust
-
-```toml
-[dependencies]
-rar-stream = { version = "5", features = ["async", "crypto"] }
-```
-
-### Browser (WASM)
-
-```bash
-wasm-pack build --target web --features "wasm,crypto" --no-default-features
-```
-
-## Quick Start
-
-```javascript
-import { LocalFileMedia, RarFilesPackage } from 'rar-stream';
-
-const media = new LocalFileMedia('./archive.rar');
-const pkg = new RarFilesPackage([media]);
-const files = await pkg.parse();
-
-for (const file of files) {
-  console.log(`${file.name}: ${file.length} bytes`);
-  const buffer = await file.readToEnd();
-  // or stream: file.createReadStream().pipe(process.stdout);
-}
-```
-
-## Examples
-
-Runnable examples in [`examples/`](./examples):
-
-| 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 |
-
-## API
-
-### Classes
-
-| 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 |
-
-### InnerFile
-
-```typescript
-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) must implement:
-
-```typescript
-interface FileMedia {
-  readonly name: string;
-  readonly length: number;
-  createReadStream(opts: { start: number; end: number }): Readable;
-}
-```
-
-### Utility Functions
-
-| 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 |
-
-### Rust API
-
-#### In-Memory (no features required)
-
-```rust
-use rar_stream::{MemoryArchive, is_rar_archive, detect_version};
-
-// Check format
-let data = std::fs::read("archive.rar")?;
-assert!(is_rar_archive(&data));
-
-// Parse and extract
-let archive = MemoryArchive::new(&data)?;
-let info = archive.archive_info();
-println!("Format: {:?}, solid: {}", info.version, info.is_solid);
-
-for entry in archive.entries() {
-    println!("{}: {} bytes", entry.name, entry.unpacked_size);
-}
-let content = archive.extract(0)?;
-let readme = archive.extract_by_name("README.md")?;
-```
-
-#### Async (requires `async` feature)
-
-```rust
-use rar_stream::{RarFilesPackage, ParseOptions, LocalFileMedia, FileMedia};
-use std::sync::Arc;
-
-let file: Arc<dyn FileMedia> = Arc::new(LocalFileMedia::new("archive.rar")?);
-let package = RarFilesPackage::new(vec![file]);
-let files = package.parse(ParseOptions::default()).await?;
-let content = files[0].read_to_end().await?;
-```
-
-## Feature Flags
-
-### Rust (Cargo)
-
-| Feature | Default | Description |
-|---------|---------|-------------|
-| `async` | No | Async archive reading via tokio (`RarFilesPackage`, `InnerFile`) |
-| `crypto` | No | AES encryption (RAR4: AES-128, RAR5: AES-256) |
-| `parallel` | No | Multi-threaded RAR5 decompression (rayon) |
-| `napi` | No | Node.js bindings (implies `async` + `parallel`) |
-| `wasm` | No | Browser WASM bindings |
-
-### Platform Support
-
-| Capability | Rust | Node.js (NAPI) | Browser (WASM) |
-|-----------|------|----------------|----------------|
-| Parse RAR4/RAR5 | ✅ | ✅ | ✅ |
-| Decompress | ✅ | ✅ | ✅ |
-| Encryption | ✅ (`crypto`) | ✅ (always on) | ✅ (`crypto`) |
-| Async I/O | ✅ (`async`) | ✅ | — |
-| Parallel decompress | ✅ (`parallel`) | ✅ (always on) | — |
-| Multi-volume | ✅ | ✅ | ✅ |
-| Streaming reads | ✅ | ✅ | — |
-
-## Format Support
-
-| Feature | RAR4 | RAR5 |
-|---------|------|------|
-| Stored (no compression) | Yes | Yes |
-| LZSS (Huffman + LZ77) | Yes | Yes |
-| PPMd | Yes | -- |
-| Solid archives | Yes | Yes |
-| SFX (self-extracting) | Yes | 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
-
-Benchmarked against the official C `unrar` (v7.0) using `cargo bench`.
-
-Core decompression (3 KB files, single-threaded):
-
-| Method | rar-stream | unrar | Speedup |
-|--------|-----------|-------|---------|
-| LZSS | 8 µs | 92 µs | 11x |
-| PPMd | 107 µs | 177 µs | 1.7x |
-| Stored | 54 ns | 123 µs | 2170x |
-
-Single-threaded decompression vs unrar across data types (200 MB, method 5, 128 MB dict):
-
-| Data type | rar-stream | unrar | Ratio |
-|-----------|-----------|-------|-------|
-| Text | 631 MiB/s | 535 MiB/s | **1.18x faster** |
-| Binary | 424 MiB/s | 439 MiB/s | 0.97x |
-| ISO (x86) | 297 MiB/s | 440 MiB/s | 0.67x |
-
-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.
-
-| 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>
-
-```
-Archive                  Single   Pipeline    Unrar   Pipe/Unrar
-----------------------------------------------------------------
-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>
-
-## Migrating from v3.x
-
-Drop-in replacement. Same API, native Rust implementation. Requires Node.js 18+.
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, conventions, and the PR process.
-
-## License
-
-MIT

package/browser.d.ts

@@ -1,126 +0,0 @@
-/**
- * rar-stream browser type definitions
- */
-
-export { InitInput, InitOutput, SyncInitInput } from './pkg/rar_stream.d.ts';
-
-/** Initialize WASM module (must be called before using other functions) */
-export { default as init } from './pkg/rar_stream.js';
-
-/** Initialize WASM module synchronously */
-export { initSync } from './pkg/rar_stream.js';
-
-/** Check if data is a RAR archive */
-export function isRarArchive(data: Uint8Array): boolean;
-
-/** Get RAR version (15 for RAR4, 50 for RAR5, 0 if not RAR) */
-export function getRarVersion(data: Uint8Array): number;
-
-/** Extract the first file from a RAR archive buffer */
-export function extractFile(archive: Uint8Array): {
-  name: string;
-  data: Uint8Array;
-  length: number;
-};
-
-/** Parse RAR4 header information (returns first file's header) */
-export function parseRarHeader(data: Uint8Array): {
-  name: string;
-  packedSize: number;
-  unpackedSize: number;
-  method: number;
-  isCompressed: boolean;
-  dataOffset: number;
-};
-
-/** Parse RAR5 header information (returns first file's header) */
-export function parseRar5Header(data: Uint8Array): {
-  name: string;
-  packedSize: number;
-  unpackedSize: number;
-  method: number;
-  dictSizeLog: number;
-  isCompressed: boolean;
-  isDirectory: boolean;
-  dataOffset: number;
-};
-
-/** Parse all RAR4 file headers from a buffer */
-export function parseRarHeaders(data: Uint8Array): Array<{
-  name: string;
-  packedSize: number;
-  unpackedSize: number;
-  method: number;
-  isCompressed: boolean;
-  dataOffset: number;
-}>;
-
-/** Parse all RAR5 file headers from a buffer */
-export function parseRar5Headers(data: Uint8Array): Array<{
-  name: string;
-  packedSize: number;
-  unpackedSize: number;
-  method: number;
-  dictSizeLog: number;
-  isCompressed: boolean;
-  isDirectory: boolean;
-  dataOffset: number;
-}>;
-
-/** High-level RAR archive reader */
-export class RarFilesPackage {
-  constructor(data: Uint8Array);
-  free(): void;
-  [Symbol.dispose](): void;
-  readonly length: number;
-  parse(): Array<{
-    name: string;
-    length: number;
-    packedSize: number;
-    isDirectory: boolean;
-  }>;
-  extract(index: number): { name: string; data: Uint8Array; length: number };
-  extractAll(): Array<{ name: string; data: Uint8Array; length: number }>;
-}
-
-/** RAR4 decompressor */
-export class RarDecoder {
-  constructor(unpacked_size: bigint);
-  free(): void;
-  [Symbol.dispose](): void;
-  bytes_written(): bigint;
-  decompress(data: Uint8Array): Uint8Array;
-  is_complete(): boolean;
-  reset(): void;
-}
-
-/** RAR5 decompressor */
-export class Rar5Decoder {
-  constructor(unpacked_size: bigint, dict_size_log: number, method: number, is_solid: boolean);
-  free(): void;
-  [Symbol.dispose](): void;
-  decompress(data: Uint8Array): Uint8Array;
-  reset(): void;
-}
-
-/** RAR5 AES-256 crypto helper */
-export class Rar5Crypto {
-  constructor(password: string, salt: Uint8Array, lg2_count: number);
-  free(): void;
-  [Symbol.dispose](): void;
-  decrypt(iv: Uint8Array, data: Uint8Array): Uint8Array;
-  verify_password(check_value: Uint8Array): boolean;
-}
-
-// Snake_case aliases for compatibility
-export { isRarArchive as is_rar_archive };
-export { getRarVersion as get_rar_version };
-export { extractFile as extract_file };
-export { parseRarHeader as parse_rar_header };
-export { parseRar5Header as parse_rar5_header };
-export { parseRarHeaders as parse_rar_headers };
-export { parseRar5Headers as parse_rar5_headers };
-export { RarDecoder as WasmRarDecoder };
-export { Rar5Decoder as WasmRar5Decoder };
-export { Rar5Crypto as WasmRar5Crypto };
-export { RarFilesPackage as WasmRarArchive };

package/browser.js

@@ -1,22 +0,0 @@
-/**
- * rar-stream browser entry point
- * Re-exports WASM bindings with unified API
- */
-
-// 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';

package/index.d.ts

@@ -1,60 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/* auto-generated by NAPI-RS */
-
-/** Read interval options. */
-export interface ReadIntervalJs {
-  start: number
-  end: number
-}
-/** Parse options for filtering results. */
-export interface ParseOptionsJs {
-  maxFiles?: number
-  /**
-   * Prefetch buffer size for header parsing in bytes (default: 32768).
-   * Increase for archives with many files over slow connections.
-   */
-  headerPrefetchSize?: number
-}
-/** Parsed file info from RAR header. */
-export interface RarFileInfo {
-  name: string
-  packedSize: number
-  unpackedSize: number
-  method: number
-  continuesInNext: boolean
-}
-/**
- * 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 (RAR4 or RAR5). */
-export declare function isRarArchive(buffer: Buffer): boolean
-/** LocalFileMedia - reads from local filesystem. */
-export declare class LocalFileMedia {
-  constructor(path: string)
-  get name(): string
-  get length(): number
-  createReadStream(opts: ReadIntervalJs): Promise<Buffer>
-}
-/**
- * InnerFile - a file inside the RAR archive.
- * Note: We use the name "NapiInnerFile" in Rust to avoid conflict with RustInnerFile,
- * but it's exported to JS as "InnerFile".
- */
-export declare class InnerFile {
-  get name(): string
-  get length(): number
-  createReadStream(opts: ReadIntervalJs): Promise<Buffer>
-  readToEnd(): Promise<Buffer>
-}
-/** RarFilesPackage - parses multi-volume RAR archives. */
-export declare class RarFilesPackage {
-  constructor(files: Array<LocalFileMedia>)
-  parse(opts?: ParseOptionsJs | undefined | null): Promise<Array<InnerFile>>
-}

package/lib/browser.d.ts

@@ -1,114 +0,0 @@
-/**
- * rar-stream browser entry point with Web Streams API support
- */
-
-// 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[]>;
-
-/**
- * Extract the first file from a RAR archive buffer.
- * Auto-detects RAR4/RAR5, parses headers, and decompresses in one call.
- */
-export declare function extractFile(data: Uint8Array): Promise<{name: string, data: Uint8Array, length: number}>;
-
-// Classes (require init() before construction)
-export declare class RarFilesPackage {
-  constructor(data: Uint8Array);
-  readonly length: number;
-  parse(): Array<{name: string, length: number, packedSize: number, isDirectory: boolean}>;
-  extract(index: number): {name: string, data: Uint8Array, length: number};
-  extractAll(): Array<{name: string, data: Uint8Array, length: number}>;
-  free(): void;
-}
-
-export declare class RarDecoder {
-  constructor(unpackedSize: bigint);
-  decompress(data: Uint8Array): Uint8Array;
-  bytes_written(): bigint;
-  is_complete(): boolean;
-  reset(): void;
-  free(): void;
-}
-
-export declare class Rar5Decoder {
-  constructor(unpackedSize: bigint, dictSizeLog: number, method: number, isSolid: boolean);
-  decompress(data: Uint8Array): Uint8Array;
-  reset(): void;
-  free(): void;
-}
-
-export declare class Rar5Crypto {
-  constructor(password: string, salt: Uint8Array, lg2Count: number);
-  decrypt(iv: Uint8Array, data: Uint8Array): Uint8Array;
-  verify_password(checkValue: Uint8Array): boolean;
-  free(): void;
-}
-
-// Direct snake_case access (require init() before use)
-export {
-  is_rar_archive,
-  get_rar_version,
-  parse_rar_header,
-  parse_rar_headers,
-  parse_rar5_header,
-  parse_rar5_headers,
-  extract_file,
-} from '../pkg/rar_stream.d.ts';
-
-/** 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;