rar-stream 5.7.0 → 5.7.2

package/lib/browser.mjs

@@ -1,214 +0,0 @@
-/**
- * rar-stream browser entry point with Web Streams API support
- * 
- * Provides ReadableStream support for streaming file content in browsers.
- */
-
-import wasmInit, {
-  initSync as _initSync,
-  is_rar_archive,
-  get_rar_version,
-  parse_rar_header,
-  parse_rar_headers,
-  parse_rar5_header,
-  parse_rar5_headers,
-  extract_file,
-  WasmRarArchive,
-  WasmRarDecoder,
-  WasmRar5Decoder,
-  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 with aligned names (require manual init() before use)
-export {
-  WasmRarArchive as RarFilesPackage,
-  WasmRarDecoder as RarDecoder,
-  WasmRar5Decoder as Rar5Decoder,
-  WasmRar5Crypto as Rar5Crypto,
-};
-
-/**
- * Extract the first file from a RAR archive buffer.
- * Auto-detects RAR4/RAR5, parses headers, and decompresses in one call.
- * @param {Uint8Array} data - The entire RAR archive
- * @returns {Promise<{name: string, data: Uint8Array, size: number}>}
- */
-export async function extractFile(data) {
-  await ensureInit();
-  return extract_file(data);
-}
-
-// 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,
-  extract_file,
-};
-
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,376 +0,0 @@
-/**
- * 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.');
-      }
-      // Streaming decompression not supported for custom FileMedia
-      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;
-  }
-}