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

package/dist/browser/modules/archive/unzip/zip-parser.js

@@ -3,250 +3,55 @@
  * Works in both Node.js and browser environments
  * No dependency on Node.js stream module
  */
-import { decompress, decompressSync } from "../compression/compress.browser.js";
-import { BinaryReader } from "../utils/binary.js";
-import { resolveZipLastModifiedDateFromUnixSeconds } from "../utils/timestamps.js";
-import { parseZipExtraFields } from "../utils/zip-extra-fields.js";
-import { CENTRAL_DIR_HEADER_SIG, COMPRESSION_DEFLATE, COMPRESSION_STORE, LOCAL_FILE_HEADER_SIG, UINT16_MAX, UINT32_MAX, ZIP64_END_OF_CENTRAL_DIR_SIG } from "../zip-spec/zip-records.js";
-/**
- * Find the End of Central Directory record
- * Searches backwards from the end of the file
- */
-function findEndOfCentralDir(data) {
-    // EOCD is at least 22 bytes, search backwards
-    // Comment can be up to 65535 bytes
-    const minOffset = Math.max(0, data.length - 65557);
-    // Signature bytes (little-endian): 0x06054b50 -> 50 4b 05 06
-    const b0 = 0x50;
-    const b1 = 0x4b;
-    const b2 = 0x05;
-    const b3 = 0x06;
-    for (let i = data.length - 22; i >= minOffset; i--) {
-        if (data[i] === b0 && data[i + 1] === b1 && data[i + 2] === b2 && data[i + 3] === b3) {
-            return i;
-        }
-    }
-    return -1;
-}
-/**
- * Find ZIP64 End of Central Directory Locator
- */
-function findZip64EOCDLocator(data, eocdOffset) {
-    // ZIP64 EOCD Locator is 20 bytes and appears right before EOCD
-    const locatorOffset = eocdOffset - 20;
-    if (locatorOffset < 0) {
-        return -1;
-    }
-    // Signature bytes (little-endian): 0x07064b50 -> 50 4b 06 07
-    if (data[locatorOffset] === 0x50 &&
-        data[locatorOffset + 1] === 0x4b &&
-        data[locatorOffset + 2] === 0x06 &&
-        data[locatorOffset + 3] === 0x07) {
-        return locatorOffset;
+import { EMPTY_UINT8ARRAY } from "../shared/bytes.js";
+import { parseZipArchiveFromBuffer } from "../zip-spec/zip-parser-core.js";
+import { processEntryData, processEntryDataSync, readEntryCompressedData } from "./zip-extract-core.js";
+const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+function assertEntryExtractableInMemory(entry) {
+    // This parser extracts into memory. If ZIP64 values exceed JS safe integers,
+    // callers need a random-access + streaming extraction path (not implemented here).
+    if (entry.uncompressedSize64 !== undefined &&
+        entry.uncompressedSize64 > MAX_SAFE_INTEGER_BIGINT) {
+        throw new Error(`File "${entry.path}" is too large to extract into memory (ZIP64 size > 2^53-1)`);
+    }
+    if (entry.compressedSize64 !== undefined && entry.compressedSize64 > MAX_SAFE_INTEGER_BIGINT) {
+        throw new Error(`File "${entry.path}" is too large to extract into memory (ZIP64 size > 2^53-1)`);
+    }
+    if (entry.localHeaderOffset64 !== undefined &&
+        entry.localHeaderOffset64 > MAX_SAFE_INTEGER_BIGINT) {
+        throw new Error(`File "${entry.path}" has a ZIP64 offset > 2^53-1 and cannot be extracted by the in-memory parser`);
     }
-    return -1;
 }
 /**
- * Parse ZIP file entries from Central Directory
+ * Parse ZIP archive including entries and archive comment.
  */
-function parseZipEntries(data, options = {}) {
-    const { decodeStrings = true } = options;
-    let entries = [];
-    // Find End of Central Directory
-    const eocdOffset = findEndOfCentralDir(data);
-    if (eocdOffset === -1) {
-        throw new Error("Invalid ZIP file: End of Central Directory not found");
-    }
-    const reader = new BinaryReader(data, eocdOffset);
-    // Read EOCD
-    // Offset  Size  Description
-    // 0       4     EOCD signature (0x06054b50)
-    // 4       2     Number of this disk
-    // 6       2     Disk where central directory starts
-    // 8       2     Number of central directory records on this disk
-    // 10      2     Total number of central directory records
-    // 12      4     Size of central directory (bytes)
-    // 16      4     Offset of start of central directory
-    // 20      2     Comment length
-    reader.skip(4); // signature
-    reader.skip(2); // disk number
-    reader.skip(2); // disk where central dir starts
-    reader.skip(2); // entries on this disk
-    let totalEntries = reader.readUint16(); // total entries
-    reader.skip(4); // central directory size (unused)
-    let centralDirOffset = reader.readUint32();
-    // Check for ZIP64
-    const zip64LocatorOffset = findZip64EOCDLocator(data, eocdOffset);
-    if (zip64LocatorOffset !== -1) {
-        const locatorReader = new BinaryReader(data, zip64LocatorOffset);
-        locatorReader.skip(4); // signature
-        locatorReader.skip(4); // disk number with ZIP64 EOCD
-        const zip64EOCDOffset = Number(locatorReader.readBigUint64());
-        // Read ZIP64 EOCD
-        const zip64Reader = new BinaryReader(data, zip64EOCDOffset);
-        const zip64Sig = zip64Reader.readUint32();
-        if (zip64Sig === ZIP64_END_OF_CENTRAL_DIR_SIG) {
-            zip64Reader.skip(8); // size of ZIP64 EOCD
-            zip64Reader.skip(2); // version made by
-            zip64Reader.skip(2); // version needed
-            zip64Reader.skip(4); // disk number
-            zip64Reader.skip(4); // disk with central dir
-            const zip64TotalEntries = Number(zip64Reader.readBigUint64());
-            zip64Reader.skip(8); // central directory size (unused)
-            const zip64CentralDirOffset = Number(zip64Reader.readBigUint64());
-            // Use ZIP64 values if standard values are maxed out
-            if (totalEntries === UINT16_MAX) {
-                totalEntries = zip64TotalEntries;
-            }
-            if (centralDirOffset === UINT32_MAX) {
-                centralDirOffset = zip64CentralDirOffset;
-            }
-        }
-    }
-    // Preallocate to avoid repeated array growth on large archives.
-    if (totalEntries > 0) {
-        entries = new Array(totalEntries);
-    }
-    // Read Central Directory entries
-    const centralReader = new BinaryReader(data, centralDirOffset);
-    for (let i = 0; i < totalEntries; i++) {
-        const sig = centralReader.readUint32();
-        if (sig !== CENTRAL_DIR_HEADER_SIG) {
-            throw new Error(`Invalid Central Directory header signature at entry ${i}`);
-        }
-        // Central Directory File Header format:
-        // Offset  Size  Description
-        // 0       4     Central directory file header signature (0x02014b50)
-        // 4       2     Version made by
-        // 6       2     Version needed to extract
-        // 8       2     General purpose bit flag
-        // 10      2     Compression method
-        // 12      2     File last modification time
-        // 14      2     File last modification date
-        // 16      4     CRC-32
-        // 20      4     Compressed size
-        // 24      4     Uncompressed size
-        // 28      2     File name length
-        // 30      2     Extra field length
-        // 32      2     File comment length
-        // 34      2     Disk number where file starts
-        // 36      2     Internal file attributes
-        // 38      4     External file attributes
-        // 42      4     Relative offset of local file header
-        // 46      n     File name
-        // 46+n    m     Extra field
-        // 46+n+m  k     File comment
-        centralReader.skip(2); // version made by
-        centralReader.skip(2); // version needed
-        const flags = centralReader.readUint16();
-        const compressionMethod = centralReader.readUint16();
-        const lastModTime = centralReader.readUint16();
-        const lastModDate = centralReader.readUint16();
-        const crc32 = centralReader.readUint32();
-        let compressedSize = centralReader.readUint32();
-        let uncompressedSize = centralReader.readUint32();
-        const fileNameLength = centralReader.readUint16();
-        const extraFieldLength = centralReader.readUint16();
-        const commentLength = centralReader.readUint16();
-        centralReader.skip(2); // disk number start
-        centralReader.skip(2); // internal attributes
-        const externalAttributes = centralReader.readUint32();
-        let localHeaderOffset = centralReader.readUint32();
-        // Check for UTF-8 flag (bit 11)
-        const isUtf8 = (flags & 0x800) !== 0;
-        const useUtf8 = decodeStrings && isUtf8;
-        const fileName = fileNameLength > 0 ? centralReader.readString(fileNameLength, useUtf8) : "";
-        let extraFields = {};
-        if (extraFieldLength > 0) {
-            const extraField = centralReader.readBytes(extraFieldLength);
-            const vars = {
-                compressedSize,
-                uncompressedSize,
-                offsetToLocalFileHeader: localHeaderOffset
-            };
-            extraFields = parseZipExtraFields(extraField, vars);
-            compressedSize = vars.compressedSize;
-            uncompressedSize = vars.uncompressedSize;
-            localHeaderOffset = vars.offsetToLocalFileHeader ?? localHeaderOffset;
-        }
-        const comment = commentLength > 0 ? centralReader.readString(commentLength, useUtf8) : "";
-        const isDirectory = fileName.endsWith("/") || (externalAttributes & 0x10) !== 0;
-        const isEncrypted = (flags & 0x01) !== 0;
-        const unixSecondsMtime = extraFields.mtimeUnixSeconds;
-        const lastModified = resolveZipLastModifiedDateFromUnixSeconds(lastModDate, lastModTime, unixSecondsMtime);
-        entries[i] = {
-            path: fileName,
-            isDirectory,
-            compressedSize,
-            uncompressedSize,
-            compressionMethod,
-            crc32,
-            lastModified,
-            localHeaderOffset,
-            comment,
-            externalAttributes,
-            isEncrypted
-        };
-    }
-    return entries;
+function parseZipArchive(data, options = {}) {
+    return parseZipArchiveFromBuffer(data, {
+        decodeStrings: options.decodeStrings,
+        encoding: options.encoding
+    });
 }
 /**
- * Extract file data for a specific entry
+ * Extract file data for a specific entry (async)
  */
-async function extractEntryData(data, entry) {
-    if (entry.isDirectory) {
-        return new Uint8Array(0);
-    }
-    if (entry.isEncrypted) {
-        throw new Error(`File "${entry.path}" is encrypted and cannot be extracted`);
+async function extractEntryData(data, entry, options = {}) {
+    if (entry.type === "directory") {
+        return EMPTY_UINT8ARRAY;
     }
+    assertEntryExtractableInMemory(entry);
     const compressedData = readEntryCompressedData(data, entry);
-    if (entry.compressionMethod === COMPRESSION_STORE) {
-        return compressedData;
-    }
-    if (entry.compressionMethod === COMPRESSION_DEFLATE) {
-        return decompress(compressedData);
-    }
-    throw new Error(`Unsupported compression method: ${entry.compressionMethod}`);
+    return processEntryData(entry, compressedData, options.password);
 }
 /**
- * Extract file data synchronously
+ * Extract file data synchronously (only supports ZipCrypto, not AES)
  */
-function extractEntryDataSync(data, entry) {
-    if (entry.isDirectory) {
-        return new Uint8Array(0);
-    }
-    if (entry.isEncrypted) {
-        throw new Error(`File "${entry.path}" is encrypted and cannot be extracted`);
+function extractEntryDataSync(data, entry, options = {}) {
+    if (entry.type === "directory") {
+        return EMPTY_UINT8ARRAY;
     }
+    assertEntryExtractableInMemory(entry);
     const compressedData = readEntryCompressedData(data, entry);
-    if (entry.compressionMethod === COMPRESSION_STORE) {
-        return compressedData;
-    }
-    if (entry.compressionMethod === COMPRESSION_DEFLATE) {
-        return decompressSync(compressedData);
-    }
-    throw new Error(`Unsupported compression method: ${entry.compressionMethod}`);
-}
-function readEntryCompressedData(data, entry) {
-    const reader = new BinaryReader(data, entry.localHeaderOffset);
-    const sig = reader.readUint32();
-    if (sig !== LOCAL_FILE_HEADER_SIG) {
-        throw new Error(`Invalid local file header signature for "${entry.path}"`);
-    }
-    reader.skip(2); // version needed
-    reader.skip(2); // flags
-    reader.skip(2); // compression method
-    reader.skip(2); // last mod time
-    reader.skip(2); // last mod date
-    reader.skip(4); // crc32
-    reader.skip(4); // compressed size
-    reader.skip(4); // uncompressed size
-    const fileNameLength = reader.readUint16();
-    const extraFieldLength = reader.readUint16();
-    reader.skip(fileNameLength);
-    reader.skip(extraFieldLength);
-    return reader.readBytes(entry.compressedSize);
+    return processEntryDataSync(entry, compressedData, options.password);
 }
 /**
  * High-level ZIP parser class
@@ -254,8 +59,17 @@ function readEntryCompressedData(data, entry) {
 export class ZipParser {
     constructor(data, options = {}) {
         this.data = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-        this.entries = parseZipEntries(this.data, options);
+        const result = parseZipArchive(this.data, options);
+        this.entries = result.entries;
+        this.archiveComment = result.comment;
         this.entryMap = new Map(this.entries.map(e => [e.path, e]));
+        this.password = options.password;
+    }
+    /**
+     * Set the password for encrypted entries.
+     */
+    setPassword(password) {
+        this.password = password;
     }
     /**
      * Get all entries in the ZIP file
@@ -269,12 +83,85 @@ export class ZipParser {
     getEntry(path) {
         return this.entryMap.get(path);
     }
+    /**
+     * Get a zero-copy view of the raw (compressed) entry payload.
+     *
+     * Notes:
+     * - This returns the bytes as stored in the ZIP (compressed and possibly encrypted).
+     * - The returned Uint8Array is a view into the original ZIP buffer.
+     * - This does NOT include the local file header, extra field, or data descriptor.
+     */
+    getRawCompressedData(path) {
+        const entry = this.entryMap.get(path);
+        if (!entry) {
+            return null;
+        }
+        // This helper returns a subarray view into the original `data`.
+        return readEntryCompressedData(this.data, entry);
+    }
+    /**
+     * Get raw (compressed) payload together with its parsed entry info.
+     */
+    getRawEntry(path) {
+        const entry = this.entryMap.get(path);
+        if (!entry) {
+            return null;
+        }
+        return { info: entry, compressedData: readEntryCompressedData(this.data, entry) };
+    }
     /**
      * Check if entry exists
      */
     hasEntry(path) {
         return this.entryMap.has(path);
     }
+    /**
+     * Get the number of child entries in a directory.
+     *
+     * Returns the count of entries whose paths start with the directory prefix,
+     * excluding the directory entry itself. For non-directory entries, returns 0.
+     *
+     * @param path - Directory path (with or without trailing slash)
+     * @returns Number of child entries
+     */
+    childCount(path) {
+        const direct = this.entryMap.get(path);
+        if (direct && direct.type !== "directory") {
+            return 0;
+        }
+        const slashPath = path.endsWith("/") ? path : path + "/";
+        const dirEntry = direct?.type === "directory" ? direct : this.entryMap.get(slashPath);
+        // If there is no explicit directory entry, still support implicit directories
+        // as long as there are entries under the prefix.
+        const prefix = (dirEntry?.path ?? slashPath).endsWith("/")
+            ? (dirEntry?.path ?? slashPath)
+            : (dirEntry?.path ?? slashPath) + "/";
+        let count = 0;
+        for (const e of this.entries) {
+            if (e.path.startsWith(prefix) && e.path !== prefix) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get the archive comment.
+     */
+    getZipComment() {
+        return this.archiveComment;
+    }
+    /**
+     * Check if the archive contains encrypted entries
+     */
+    hasEncryptedEntries() {
+        return this.entries.some(e => e.isEncrypted);
+    }
+    /**
+     * Get all encrypted entries
+     */
+    getEncryptedEntries() {
+        return this.entries.filter(e => e.isEncrypted);
+    }
     /**
      * List all file paths
      */
@@ -283,33 +170,41 @@ export class ZipParser {
     }
     /**
      * Extract a single file (async)
+     * @param path - File path within the archive
+     * @param password - Optional password for this entry (overrides constructor password)
      */
-    async extract(path) {
+    async extract(path, password) {
         const entry = this.entryMap.get(path);
         if (!entry) {
             return null;
         }
-        return extractEntryData(this.data, entry);
+        return extractEntryData(this.data, entry, { password: password ?? this.password });
     }
     /**
      * Extract a single file (sync)
      *
-     * This is supported in both Node.js and browser builds.
+     * Note: AES-encrypted files cannot be extracted synchronously.
+     * Use the async extract() method for AES-encrypted files.
+     *
+     * @param path - File path within the archive
+     * @param password - Optional password for this entry (overrides constructor password)
      */
-    extractSync(path) {
+    extractSync(path, password) {
         const entry = this.entryMap.get(path);
         if (!entry) {
             return null;
         }
-        return extractEntryDataSync(this.data, entry);
+        return extractEntryDataSync(this.data, entry, { password: password ?? this.password });
     }
     /**
      * Extract all files (async)
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    async extractAll() {
+    async extractAll(password) {
         const result = new Map();
+        const pw = password ?? this.password;
         for (const entry of this.entries) {
-            const data = await extractEntryData(this.data, entry);
+            const data = await extractEntryData(this.data, entry, { password: pw });
             result.set(entry.path, data);
         }
         return result;
@@ -317,23 +212,32 @@ export class ZipParser {
     /**
      * Extract all files (sync)
      * Returns object with file paths as keys and Uint8Array content as values
+     *
+     * Note: AES-encrypted files cannot be extracted synchronously.
+     * Use the async extractAll() method if the archive contains AES-encrypted files.
+     *
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    extractAllSync() {
+    extractAllSync(password) {
         const result = {};
+        const pw = password ?? this.password;
         for (const entry of this.entries) {
-            result[entry.path] = extractEntryDataSync(this.data, entry);
+            result[entry.path] = extractEntryDataSync(this.data, entry, { password: pw });
         }
         return result;
     }
     /**
      * Iterate over entries with async callback
+     * @param callback - Callback for each entry
+     * @param password - Optional password for encrypted entries (overrides constructor password)
      */
-    async forEach(callback) {
+    async forEach(callback, password) {
+        const pw = password ?? this.password;
         for (const entry of this.entries) {
             let dataPromise = null;
             const getData = () => {
                 if (!dataPromise) {
-                    dataPromise = extractEntryData(this.data, entry);
+                    dataPromise = extractEntryData(this.data, entry, { password: pw });
                 }
                 return dataPromise;
             };

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

@@ -0,0 +1,103 @@
+import { type ZipEntryInfo } from "./zip-parser.js";
+import { type ParseOptions, type ZipEntry as ParseZipEntry } from "./stream.js";
+import { type ArchiveSink } from "../io/archive-sink.js";
+import { type ArchiveSource } from "../io/archive-source.js";
+import type { UnzipOperation, UnzipProgress, UnzipStreamOptions } from "./progress.js";
+import type { ArchiveFormat } from "../formats/types.js";
+import type { ZipStringEncoding } from "../shared/text.js";
+type PipeToOptions = {
+    preventClose?: boolean;
+    preventAbort?: boolean;
+    preventCancel?: boolean;
+    signal?: AbortSignal;
+};
+export interface UnzipOptions {
+    /**
+     * Archive format: "zip" (default) or "tar".
+     * Note: format dispatch is handled by `unzip()`.
+     */
+    format?: ArchiveFormat;
+    decodeStrings?: boolean;
+    /** Optional string encoding for legacy (non-UTF8) names/comments. */
+    encoding?: ZipStringEncoding;
+    parse?: ParseOptions;
+    /** Password for encrypted entries (ZIP only). */
+    password?: string | Uint8Array;
+    /** Default abort signal used by streaming operations. */
+    signal?: AbortSignal;
+    /** Default progress callback used by streaming operations. */
+    onProgress?: (p: UnzipProgress) => void;
+    /** Default throttle for progress callbacks. */
+    progressIntervalMs?: number;
+}
+export type { UnzipOperation, UnzipProgress, UnzipStreamOptions } from "./progress.js";
+import { type ZipEntryType } from "../zip-spec/zip-entry-info.js";
+export declare class UnzipEntry {
+    readonly path: string;
+    /** Entry type: file, directory, or symlink */
+    readonly type: ZipEntryType;
+    /**
+     * For symlinks, returns the target path after calling bytes().
+     * Before extraction, this is undefined.
+     */
+    linkTarget?: string;
+    /**
+     * Unix file mode/permissions (0 if unavailable).
+     */
+    readonly mode: number;
+    /** Whether this entry is encrypted (ZipCrypto or AES). */
+    readonly isEncrypted: boolean;
+    private readonly _data?;
+    private readonly _info?;
+    private readonly _password?;
+    private readonly _parseEntry?;
+    private readonly _onBytesOut?;
+    private readonly _signal?;
+    constructor(args: {
+        kind: "buffer";
+        data: Uint8Array;
+        info: ZipEntryInfo;
+        password?: string | Uint8Array;
+    } | {
+        kind: "stream";
+        entry: ParseZipEntry;
+    }, hooks?: {
+        onBytesOut?: (path: string, type: ZipEntryType, bytes: number) => void;
+        signal?: AbortSignal;
+    });
+    /**
+     * Process extracted bytes: populate linkTarget for symlinks and notify progress.
+     */
+    private _processExtractedBytes;
+    bytes(): Promise<Uint8Array>;
+    stream(): AsyncIterable<Uint8Array>;
+    pipeTo(sink: WritableStream<Uint8Array>, options?: PipeToOptions): Promise<void>;
+    pipeTo(sink: ArchiveSink): Promise<void>;
+    readableStream(): ReadableStream<Uint8Array>;
+    text(encoding?: string): Promise<string>;
+    discard(): void;
+}
+export declare class ZipReader {
+    private readonly _source;
+    private readonly _options;
+    private _bufferParser;
+    private _bufferData;
+    constructor(source: ArchiveSource, options?: UnzipOptions);
+    private get _encoding();
+    entries(options?: UnzipStreamOptions): AsyncIterable<UnzipEntry>;
+    entriesStream(options?: UnzipStreamOptions): ReadableStream<UnzipEntry>;
+    operation(options?: UnzipStreamOptions): UnzipOperation;
+    private _ensureBufferParser;
+    get(path: string): Promise<UnzipEntry | null>;
+    bytes(path: string): Promise<Uint8Array | null>;
+    close(): Promise<void>;
+}
+/** Unzip options with format: "tar" */
+export interface UnzipOptionsTar extends UnzipOptions {
+    format: "tar";
+}
+/** Unzip options with format: "zip" (or default) */
+export interface UnzipOptionsZip extends UnzipOptions {
+    format?: "zip";
+}
+export declare function createZipReader(source: ArchiveSource, options?: UnzipOptionsZip): ZipReader;