@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/archive/io/random-access.js

@@ -0,0 +1,301 @@
+/**
+ * Random Access Reader Interface
+ *
+ * Provides an abstraction for reading arbitrary byte ranges from a data source.
+ * This enables efficient access to ZIP archives without downloading the entire file.
+ *
+ * @module
+ */
+/**
+ * Error thrown when the server doesn't support Range requests.
+ */
+export { RangeNotSupportedError, HttpRangeError } from "../shared/errors.js";
+import { RangeNotSupportedError, HttpRangeError } from "../shared/errors.js";
+/**
+ * Parse total file size from Content-Range header.
+ * @example "bytes 0-0/12345" => 12345
+ */
+function parseTotalSizeFromContentRange(value) {
+    if (!value) {
+        return null;
+    }
+    // e.g. "bytes 0-0/12345" or "bytes */12345"
+    const slash = value.lastIndexOf("/");
+    if (slash === -1) {
+        return null;
+    }
+    const totalPart = value.slice(slash + 1).trim();
+    if (!totalPart || totalPart === "*") {
+        return null;
+    }
+    const total = parseInt(totalPart, 10);
+    return Number.isFinite(total) && total >= 0 ? total : null;
+}
+/**
+ * HTTP Range Reader
+ *
+ * Reads arbitrary byte ranges from a remote HTTP resource using Range requests.
+ * Works in both Node.js (with fetch) and browsers.
+ *
+ * @example
+ * ```ts
+ * const reader = await HttpRangeReader.open("https://example.com/archive.zip");
+ * console.log(`File size: ${reader.size} bytes`);
+ *
+ * // Read last 22 bytes (minimum EOCD size)
+ * const eocd = await reader.read(reader.size - 22, reader.size);
+ *
+ * // Check stats
+ * console.log(reader.getStats());
+ *
+ * await reader.close();
+ * ```
+ */
+export class HttpRangeReader {
+    constructor(url, size, options = {}) {
+        // Stats tracking
+        this._requestCount = 0;
+        this._bytesDownloaded = 0;
+        this.url = url;
+        this._size = size;
+        this.headers = options.headers ?? {};
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+        this.signal = options.signal;
+        this.credentials = options.credentials ?? "same-origin";
+    }
+    /**
+     * Total size of the remote file in bytes.
+     */
+    get size() {
+        return this._size;
+    }
+    /**
+     * Open a remote ZIP file for random access reading.
+     *
+     * @param url - URL of the ZIP file
+     * @param options - Reader options
+     * @returns A configured HttpRangeReader instance
+     *
+     * @throws {RangeNotSupportedError} If the server doesn't support Range requests
+     * @throws {HttpRangeError} If the HTTP request fails
+     */
+    static async open(url, options = {}) {
+        const fetchFn = options.fetch ?? globalThis.fetch;
+        const headers = options.headers ?? {};
+        const credentials = options.credentials ?? "same-origin";
+        const validateRangeSupport = options.validateRangeSupport ?? true;
+        let requestCount = 0;
+        let bytesDownloaded = 0;
+        const trackedFetch = async (init) => {
+            const response = await fetchFn(url, init);
+            requestCount++;
+            return response;
+        };
+        // If size is pre-known, skip HEAD request but still validate range support if requested
+        if (options.size !== undefined) {
+            if (validateRangeSupport) {
+                // Make a small range request to validate
+                const response = await trackedFetch({
+                    method: "GET",
+                    headers: {
+                        ...headers,
+                        Range: "bytes=0-0"
+                    },
+                    signal: options.signal,
+                    credentials
+                });
+                // 206: Range supported
+                // 200: server ignored Range but reader can still work (will cache on first read)
+                if (response.status !== 206 && response.status !== 200) {
+                    throw new RangeNotSupportedError(url);
+                }
+            }
+            const instance = new HttpRangeReader(url, options.size, options);
+            instance._requestCount = requestCount;
+            instance._bytesDownloaded = bytesDownloaded;
+            return instance;
+        }
+        // Make HEAD request to get file size and check Range support
+        const headResponse = await trackedFetch({
+            method: "HEAD",
+            headers,
+            signal: options.signal,
+            credentials
+        });
+        if (!headResponse.ok) {
+            throw new HttpRangeError(url, headResponse.status, headResponse.statusText);
+        }
+        // Check if server supports Range requests
+        const acceptRanges = headResponse.headers.get("Accept-Ranges");
+        if (validateRangeSupport && acceptRanges !== "bytes") {
+            // Some servers don't send Accept-Ranges but still support it
+            // Try a range request to be sure
+            const testResponse = await trackedFetch({
+                method: "GET",
+                headers: {
+                    ...headers,
+                    Range: "bytes=0-0"
+                },
+                signal: options.signal,
+                credentials
+            });
+            if (testResponse.status !== 206 && testResponse.status !== 200) {
+                throw new RangeNotSupportedError(url);
+            }
+        }
+        // Determine file size.
+        // Prefer Content-Length from HEAD, but fall back to Content-Range from a probe request.
+        const contentLength = headResponse.headers.get("Content-Length");
+        let size = contentLength ? parseInt(contentLength, 10) : NaN;
+        if (!Number.isFinite(size) || size < 0) {
+            // Probe with a 0-0 range request to read Content-Range: bytes 0-0/total
+            const probeResponse = await trackedFetch({
+                method: "GET",
+                headers: {
+                    ...headers,
+                    Range: "bytes=0-0"
+                },
+                signal: options.signal,
+                credentials
+            });
+            const probedTotal = parseTotalSizeFromContentRange(probeResponse.headers.get("Content-Range"));
+            if (probedTotal !== null) {
+                size = probedTotal;
+            }
+            else if (probeResponse.status === 200) {
+                // Server ignored Range and returned the full file for the probe request.
+                // Consume the probe response body and cache it to avoid a redundant full GET.
+                try {
+                    const data = new Uint8Array(await probeResponse.arrayBuffer());
+                    bytesDownloaded += data.length;
+                    size = data.length;
+                    const instance = new HttpRangeReader(url, size, options);
+                    instance._fullData = data;
+                    instance._requestCount = requestCount;
+                    instance._bytesDownloaded = bytesDownloaded;
+                    return instance;
+                }
+                catch {
+                    // As a last resort, download once and measure.
+                    // This is expensive but makes open() work even without size headers.
+                    const full = await trackedFetch({
+                        method: "GET",
+                        headers,
+                        signal: options.signal,
+                        credentials
+                    });
+                    if (!full.ok) {
+                        throw new HttpRangeError(url, full.status, full.statusText);
+                    }
+                    const data = new Uint8Array(await full.arrayBuffer());
+                    bytesDownloaded += data.length;
+                    size = data.length;
+                    const instance = new HttpRangeReader(url, size, options);
+                    instance._fullData = data;
+                    instance._requestCount = requestCount;
+                    instance._bytesDownloaded = bytesDownloaded;
+                    return instance;
+                }
+            }
+            else {
+                throw new Error(contentLength
+                    ? `Invalid Content-Length "${contentLength}" for: ${url}`
+                    : `Server did not provide Content-Length for: ${url}`);
+            }
+        }
+        const instance = new HttpRangeReader(url, size, options);
+        instance._requestCount = requestCount;
+        instance._bytesDownloaded = bytesDownloaded;
+        return instance;
+    }
+    /**
+     * Read a range of bytes from the remote file.
+     *
+     * @param start - Start offset (inclusive, 0-based)
+     * @param end - End offset (exclusive)
+     * @returns The requested bytes
+     *
+     * @throws {HttpRangeError} If the HTTP request fails
+     */
+    async read(start, end) {
+        if (start < 0 || end > this._size || start >= end) {
+            throw new RangeError(`Invalid range [${start}, ${end}) for file of size ${this._size}`);
+        }
+        if (this._fullData) {
+            return this._fullData.subarray(start, end);
+        }
+        // HTTP Range header uses inclusive end
+        const rangeHeader = `bytes=${start}-${end - 1}`;
+        const response = await this.fetchFn(this.url, {
+            method: "GET",
+            headers: {
+                ...this.headers,
+                Range: rangeHeader
+            },
+            signal: this.signal,
+            credentials: this.credentials
+        });
+        // 206 Partial Content is expected for Range requests
+        // 200 OK means server ignored Range header and returned full file
+        if (response.status === 200) {
+            // Server returned full content - extract the range we need
+            const fullData = new Uint8Array(await response.arrayBuffer());
+            this._fullData = fullData;
+            // If the server returned a different length than expected, prefer the actual.
+            // This keeps read() bounds consistent for subsequent calls.
+            this._size = fullData.length;
+            this._requestCount++;
+            this._bytesDownloaded += fullData.length;
+            return fullData.subarray(start, end);
+        }
+        if (response.status !== 206) {
+            throw new HttpRangeError(this.url, response.status, response.statusText);
+        }
+        const data = new Uint8Array(await response.arrayBuffer());
+        this._requestCount++;
+        this._bytesDownloaded += data.length;
+        // Some servers may return a larger-than-requested slice; clamp to requested length.
+        const expectedLen = end - start;
+        return data.length === expectedLen ? data : data.subarray(0, expectedLen);
+    }
+    /**
+     * Get statistics about the reader's operations.
+     */
+    getStats() {
+        return {
+            requestCount: this._requestCount,
+            bytesDownloaded: this._bytesDownloaded,
+            totalSize: this._size,
+            downloadedPercent: this._size > 0 ? Math.round((this._bytesDownloaded / this._size) * 10000) / 100 : 0
+        };
+    }
+    /**
+     * Close the reader.
+     * Currently a no-op but included for interface compliance.
+     */
+    async close() {
+        // HTTP is stateless, nothing to close
+    }
+}
+/**
+ * In-memory random access reader.
+ * Wraps a Uint8Array to provide the RandomAccessReader interface.
+ * Useful for testing and as a fallback.
+ */
+export class BufferReader {
+    constructor(data) {
+        this.data = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+    }
+    get size() {
+        return this.data.length;
+    }
+    async read(start, end) {
+        if (start < 0 || end > this.data.length || start >= end) {
+            throw new RangeError(`Invalid range [${start}, ${end}) for buffer of size ${this.data.length}`);
+        }
+        return this.data.subarray(start, end);
+    }
+    async close() {
+        // Nothing to close
+    }
+}

package/dist/browser/modules/archive/io/remote-zip-reader.d.ts

@@ -0,0 +1,352 @@
+/**
+ * Remote ZIP Reader - On-demand ZIP archive reading via HTTP Range requests
+ *
+ * This module provides efficient access to ZIP archives stored on remote servers.
+ * Instead of downloading the entire archive, it uses HTTP Range requests to:
+ *
+ * 1. Read the End of Central Directory (EOCD) from the end of the file
+ * 2. Read the Central Directory to get file metadata
+ * 3. Read individual entries on demand
+ *
+ * This can dramatically reduce bandwidth usage when you only need a few files
+ * from a large archive.
+ *
+ * @module
+ */
+import type { ZipEntryInfo } from "../zip-spec/zip-entry-info.js";
+import { type ZipStringEncoding } from "../shared/text.js";
+import type { RandomAccessReader, HttpRangeReaderOptions } from "./random-access.js";
+/**
+ * Options for RemoteZipReader
+ */
+export interface RemoteZipReaderOptions {
+    /**
+     * Password for encrypted entries.
+     */
+    password?: string | Uint8Array;
+    /**
+     * Whether to decode file names as UTF-8.
+     * @default true
+     */
+    decodeStrings?: boolean;
+    /** Optional string encoding for legacy (non-UTF8) names/comments. */
+    encoding?: ZipStringEncoding;
+    /**
+     * Abort signal for cancellation.
+     */
+    signal?: AbortSignal;
+    /**
+     * Whether to validate CRC32 checksum after extraction.
+     * @default false
+     */
+    checkCrc32?: boolean;
+}
+/**
+ * Options for extracting entries
+ */
+export interface ExtractOptions {
+    /**
+     * Password for encrypted entries (overrides constructor password).
+     */
+    password?: string | Uint8Array;
+    /**
+     * Whether to validate CRC32 checksum after extraction.
+     * Overrides the constructor option.
+     */
+    checkCrc32?: boolean;
+    /**
+     * Progress callback for large file extraction.
+     * Called with current bytes processed and total bytes.
+     */
+    onprogress?: (current: number, total: number) => void;
+}
+/**
+ * Options for reading raw (compressed) entry data.
+ */
+export interface RawEntryReadOptions {
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Options for streaming raw (compressed) entry data.
+ */
+export interface RawEntryStreamOptions extends RawEntryReadOptions {
+    /** Chunk size for range reads. Default: 64 KiB */
+    chunkSize?: number;
+}
+/**
+ * Options for opening a remote ZIP file via URL
+ */
+export interface RemoteZipOpenOptions extends RemoteZipReaderOptions, HttpRangeReaderOptions {
+}
+/**
+ * Statistics about remote ZIP reading operations
+ */
+export interface RemoteZipStats {
+    /** Total size of the ZIP file */
+    totalSize: number;
+    /** Number of entries in the archive */
+    entryCount: number;
+    /** HTTP request statistics (if using HttpRangeReader) */
+    http?: {
+        requestCount: number;
+        bytesDownloaded: number;
+        downloadedPercent: number;
+    };
+}
+/**
+ * Error thrown when CRC32 validation fails
+ */
+export { Crc32MismatchError } from "../shared/errors.js";
+/**
+ * Remote ZIP Reader
+ *
+ * Provides on-demand access to ZIP archives via random access reading.
+ * Only downloads the parts of the archive that are actually needed.
+ *
+ * @example
+ * ```ts
+ * // Open a remote ZIP file
+ * const reader = await RemoteZipReader.open("https://example.com/large-archive.zip");
+ *
+ * // List entries without downloading file content
+ * for (const entry of reader.getEntries()) {
+ *   console.log(entry.path, entry.uncompressedSize);
+ * }
+ *
+ * // Extract just one file
+ * const data = await reader.extract("important-file.txt");
+ *
+ * // Check how much was downloaded
+ * console.log(reader.getStats());
+ *
+ * await reader.close();
+ * ```
+ */
+export declare class RemoteZipReader {
+    private readonly reader;
+    private readonly options;
+    private entries;
+    private entryMap;
+    private archiveComment;
+    private initialized;
+    private httpReader?;
+    private readonly dataOffsetCache;
+    private _hasEncryptedEntries;
+    private _decoder?;
+    private constructor();
+    private get _encodingDecoder();
+    /**
+     * Open a remote ZIP file via URL.
+     *
+     * @param url - URL of the ZIP file
+     * @param options - Reader options
+     * @returns Initialized RemoteZipReader
+     */
+    static open(url: string, options?: RemoteZipOpenOptions): Promise<RemoteZipReader>;
+    /**
+     * Create a RemoteZipReader from any RandomAccessReader.
+     *
+     * @param reader - A random access reader
+     * @param options - Reader options
+     * @returns Initialized RemoteZipReader
+     */
+    static fromReader(reader: RandomAccessReader, options?: RemoteZipReaderOptions): Promise<RemoteZipReader>;
+    /**
+     * Initialize the reader by parsing EOCD and Central Directory.
+     */
+    private init;
+    /**
+     * Read and parse the End of Central Directory record.
+     */
+    private readEOCD;
+    /**
+     * Read and parse the Central Directory.
+     */
+    private readCentralDirectory;
+    /**
+     * Get all entries in the ZIP file.
+     */
+    getEntries(): readonly ZipEntryInfo[];
+    /**
+     * Get entry by path.
+     */
+    getEntry(path: string): ZipEntryInfo | undefined;
+    /**
+     * Check if entry exists.
+     */
+    hasEntry(path: string): boolean;
+    /**
+     * Get the archive comment.
+     */
+    getZipComment(): string;
+    /**
+     * Get raw (compressed) entry payload as a single Uint8Array.
+     *
+     * Notes:
+     * - This returns the bytes as stored in the ZIP (compressed and possibly encrypted).
+     * - The returned bytes do NOT include the local file header, extra field, or data descriptor.
+     * - For large entries, prefer {@link getRawCompressedStream}.
+     */
+    getRawCompressedData(pathOrEntry: string | ZipEntryInfo, options?: RawEntryReadOptions): Promise<Uint8Array | null>;
+    /**
+     * Get raw (compressed) entry payload as an async iterable.
+     *
+     * This is the most memory-efficient way to read raw entry bytes.
+     */
+    getRawCompressedStream(pathOrEntry: string | ZipEntryInfo, options?: RawEntryStreamOptions): AsyncIterable<Uint8Array> | null;
+    /**
+     * Get a raw entry (metadata + compressed payload).
+     */
+    getRawEntry(path: string, options?: RawEntryReadOptions): Promise<{
+        entry: ZipEntryInfo;
+        compressedData: Uint8Array;
+    } | null>;
+    /**
+     * Get a raw entry stream (metadata + async iterable compressed payload).
+     */
+    getRawEntryStream(path: string, options?: RawEntryStreamOptions): {
+        entry: ZipEntryInfo;
+        compressedData: AsyncIterable<Uint8Array>;
+    } | null;
+    /**
+     * List all file paths.
+     */
+    listFiles(): string[];
+    /**
+     * Get the number of file entries (excluding directories).
+     */
+    getFileCount(): number;
+    /**
+     * Get the number of directory entries.
+     */
+    getDirectoryCount(): number;
+    /**
+     * Filter entries by a predicate function.
+     *
+     * @param predicate - Function to test each entry
+     * @returns Array of entries that pass the test
+     */
+    filterEntries(predicate: (entry: ZipEntryInfo) => boolean): ZipEntryInfo[];
+    /**
+     * Find entries matching a glob-like pattern.
+     * Supports * (any characters) and ? (single character).
+     *
+     * @param pattern - Glob pattern (e.g., "*.txt", "folder/*", "**\/data.json")
+     * @returns Array of matching entries
+     */
+    findEntries(pattern: string): ZipEntryInfo[];
+    /**
+     * Check if the archive contains encrypted entries.
+     * Result is cached after first call for performance.
+     */
+    hasEncryptedEntries(): boolean;
+    /**
+     * Extract a single file.
+     *
+     * @param path - File path within the archive
+     * @param options - Extract options or password
+     * @returns File data, or null if entry not found
+     */
+    extract(path: string, options?: ExtractOptions | string | Uint8Array): Promise<Uint8Array | null>;
+    /**
+     * Extract a specific entry.
+     *
+     * @param entry - Entry to extract
+     * @param options - Extract options or password
+     * @returns File data
+     */
+    extractEntry(entry: ZipEntryInfo, options?: ExtractOptions | string | Uint8Array): Promise<Uint8Array>;
+    private processEntryCompressedData;
+    /**
+     * Normalize extract options from various input formats.
+     */
+    private normalizeExtractOptions;
+    /**
+     * Extract all files from the archive.
+     * This is a convenience method that calls extractMultiple with all file paths.
+     *
+     * @param options - Extract options or password
+     * @returns Map of path to file data (directories are excluded)
+     */
+    extractAll(options?: ExtractOptions | string | Uint8Array): Promise<Map<string, Uint8Array>>;
+    /**
+     * Extract multiple entries efficiently.
+     * Entries are sorted by offset to minimize seeks/requests.
+     *
+     * @param paths - File paths to extract
+     * @param options - Extract options or password
+     * @returns Map of path to file data
+     */
+    extractMultiple(paths: string[], options?: ExtractOptions | string | Uint8Array): Promise<Map<string, Uint8Array>>;
+    /**
+     * Iterate over entries with async callback.
+     *
+     * @param callback - Callback for each entry. Return false to stop iteration.
+     * @param options - Extract options or password
+     */
+    forEach(callback: (entry: ZipEntryInfo, getData: () => Promise<Uint8Array>) => Promise<boolean | void>, options?: ExtractOptions | string | Uint8Array): Promise<void>;
+    /**
+     * Async generator to iterate over entries one by one.
+     * Useful for processing large archives without loading all entries into memory.
+     *
+     * @example
+     * ```ts
+     * for await (const { entry, getData } of reader.entriesGenerator()) {
+     *   if (entry.path.endsWith('.json')) {
+     *     const data = await getData();
+     *     console.log(JSON.parse(new TextDecoder().decode(data)));
+     *   }
+     * }
+     * ```
+     */
+    entriesGenerator(options?: ExtractOptions | string | Uint8Array): AsyncGenerator<{
+        entry: ZipEntryInfo;
+        getData: () => Promise<Uint8Array>;
+    }>;
+    /**
+     * Check if a password is correct for an encrypted entry without extracting the full file.
+     * This is much faster than extracting the file as it only reads the encryption header.
+     *
+     * @param path - File path within the archive
+     * @param password - Password to check
+     * @returns true if password is correct, false if incorrect, null if entry not found or not encrypted
+     */
+    checkPassword(path: string, password: string | Uint8Array): Promise<boolean | null>;
+    /**
+     * Check if a password is correct for an encrypted entry.
+     *
+     * @param entry - Entry to check
+     * @param password - Password to check
+     * @returns true if password is correct, false if incorrect, null if not encrypted
+     */
+    checkEntryPassword(entry: ZipEntryInfo, password: string | Uint8Array): Promise<boolean | null>;
+    private getEntryDataOffset;
+    /**
+     * Extract to a WritableStream (streaming output).
+     * Useful for large files to avoid loading the entire content into memory.
+     *
+     * @param path - File path within the archive
+     * @param writable - WritableStream to write the extracted data to
+     * @param options - Extract options or password
+     * @returns true if extraction succeeded, false if entry not found
+     */
+    extractToStream(path: string, writable: WritableStream<Uint8Array>, options?: ExtractOptions | string | Uint8Array): Promise<boolean>;
+    /**
+     * Verify CRC32 for an entry without returning the data.
+     * Useful for integrity checking.
+     *
+     * @param path - File path within the archive
+     * @param options - Extract options (password if encrypted)
+     * @returns true if CRC32 matches, throws Crc32MismatchError if not, null if entry not found
+     */
+    verifyCrc32(path: string, options?: ExtractOptions | string | Uint8Array): Promise<boolean | null>;
+    /**
+     * Get statistics about the reader's operations.
+     */
+    getStats(): RemoteZipStats;
+    /**
+     * Close the reader and release resources.
+     */
+    close(): Promise<void>;
+}