@cj-tech-master/excelts 3.0.1 → 3.1.0-canary.20260102041828.82ed571

package/dist/esm/modules/archive/streaming-zip.js

@@ -0,0 +1,407 @@
+/**
+ * True Streaming ZIP creator - shared implementation.
+ *
+ * This module is intentionally platform-agnostic.
+ * - In Node builds it uses `./crc32` + `./streaming-compress` (zlib-backed).
+ * - In browser builds the bundler aliases those imports to their browser variants.
+ */
+import { crc32Update, crc32Finalize } from "@archive/crc32";
+import { createDeflateStream } from "@archive/streaming-compress";
+import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "@archive/defaults";
+import { buildZipEntryMetadata } from "@archive/zip-entry-metadata";
+import { buildCentralDirectoryHeader, buildDataDescriptor, buildEndOfCentralDirectory, buildLocalFileHeader } from "@archive/zip-records";
+import { VERSION_MADE_BY, VERSION_NEEDED } from "@archive/zip-constants";
+/**
+ * True Streaming ZIP File - compresses chunk by chunk
+ */
+export class ZipDeflateFile {
+    constructor(name, options) {
+        this._deflate = null;
+        this._crc = 0xffffffff;
+        this._uncompressedSize = 0;
+        this._compressedSize = 0;
+        this._finalized = false;
+        this._headerEmitted = false;
+        this._ondata = null;
+        this._centralDirEntryInfo = null;
+        this._pendingEnd = false;
+        this._emittedDataDescriptor = false;
+        // Promise resolution for completion (including data descriptor)
+        this._completeResolve = null;
+        this._completeReject = null;
+        this._completePromise = null;
+        this._completeError = null;
+        // Queue for incoming data before ondata is set
+        this._dataQueue = [];
+        this._finalQueued = false;
+        this.name = name;
+        const modTime = options?.modTime ?? new Date();
+        this._modTime = modTime;
+        this.level = options?.level ?? DEFAULT_ZIP_LEVEL;
+        const metadata = buildZipEntryMetadata({
+            name,
+            comment: "",
+            modTime,
+            timestamps: options?.timestamps ?? DEFAULT_ZIP_TIMESTAMPS,
+            useDataDescriptor: true,
+            deflate: this.level > 0
+        });
+        this.nameBytes = metadata.nameBytes;
+        this.dosTime = metadata.dosTime;
+        this.dosDate = metadata.dosDate;
+        this.extraField = metadata.extraField;
+        this._flags = metadata.flags;
+        this._compressionMethod = metadata.compressionMethod;
+        // Create deflate stream for compression
+        if (this.level > 0) {
+            this._deflate = createDeflateStream({ level: this.level });
+            this._deflate.on("error", (err) => {
+                this._rejectComplete(err);
+            });
+            // Handle compressed output - this is true streaming!
+            this._deflate.on("data", (chunk) => {
+                this._compressedSize += chunk.length;
+                this._enqueueData(chunk, false);
+            });
+            // Handle end - emit data descriptor
+            // IMPORTANT: Only use 'end' event, NOT 'finish'!
+            // Node.js zlib emits events in order: finish -> data -> end
+            this._deflate.on("end", () => {
+                if (this._pendingEnd && !this._emittedDataDescriptor) {
+                    this._emittedDataDescriptor = true;
+                    this._emitDataDescriptor();
+                }
+            });
+        }
+        this._localHeader = this._buildLocalHeader();
+    }
+    _buildLocalHeader() {
+        // CRC + sizes are written via data descriptor for true streaming.
+        return buildLocalFileHeader({
+            fileName: this.nameBytes,
+            extraField: this.extraField,
+            flags: this._flags,
+            compressionMethod: this._compressionMethod,
+            dosTime: this.dosTime,
+            dosDate: this.dosDate,
+            crc32: 0,
+            compressedSize: 0,
+            uncompressedSize: 0,
+            versionNeeded: VERSION_NEEDED
+        });
+    }
+    _enqueueData(data, final) {
+        if (this._ondata) {
+            this._ondata(data, final);
+        }
+        else {
+            this._dataQueue.push(data);
+            if (final) {
+                this._finalQueued = true;
+            }
+        }
+    }
+    _flushQueue() {
+        if (!this._ondata) {
+            return;
+        }
+        const len = this._dataQueue.length;
+        const finalIndex = this._finalQueued ? len - 1 : -1;
+        for (let i = 0; i < len; i++) {
+            this._ondata(this._dataQueue[i], i === finalIndex);
+        }
+        this._dataQueue = [];
+        this._finalQueued = false;
+    }
+    get ondata() {
+        return this._ondata ?? undefined;
+    }
+    set ondata(cb) {
+        this._ondata = cb;
+        // Flush any queued data
+        this._flushQueue();
+    }
+    _resolveComplete() {
+        if (this._completeResolve) {
+            this._completeResolve();
+        }
+    }
+    _rejectComplete(err) {
+        this._completeError = err;
+        if (this._completeReject) {
+            this._completeReject(err);
+        }
+    }
+    _ensureCompletePromise() {
+        if (this._completeError) {
+            return Promise.reject(this._completeError);
+        }
+        if (this._emittedDataDescriptor) {
+            return Promise.resolve();
+        }
+        if (!this._completePromise) {
+            this._completePromise = new Promise((resolve, reject) => {
+                this._completeResolve = resolve;
+                this._completeReject = reject;
+            });
+        }
+        return this._completePromise;
+    }
+    _tapCallback(promise, callback) {
+        if (!callback) {
+            return;
+        }
+        promise.then(() => callback()).catch(err => callback(err));
+    }
+    _emitHeaderIfNeeded() {
+        if (this._headerEmitted) {
+            return;
+        }
+        this._emitHeader();
+        this._headerEmitted = true;
+    }
+    _writeData(data) {
+        if (data.length === 0) {
+            return Promise.resolve();
+        }
+        // Update CRC32 on uncompressed data
+        this._crc = crc32Update(this._crc, data);
+        this._uncompressedSize += data.length;
+        if (this._deflate) {
+            // Write to deflate stream - returns Promise for async streaming
+            return new Promise((resolve, reject) => {
+                this._deflate.write(data, (err) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
+        // STORE mode - pass through
+        this._compressedSize += data.length;
+        this._enqueueData(data, false);
+        return Promise.resolve();
+    }
+    _endDeflateAndWait() {
+        return new Promise((resolve, reject) => {
+            const deflate = this._deflate;
+            const onError = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const onEnd = () => {
+                cleanup();
+                resolve();
+            };
+            const cleanup = () => {
+                deflate.off("error", onError);
+                deflate.off("end", onEnd);
+            };
+            deflate.once("error", onError);
+            deflate.once("end", onEnd);
+            deflate.end();
+        });
+    }
+    _finalizeAfterWrite(writePromise) {
+        this._finalized = true;
+        this._pendingEnd = true;
+        const completePromise = this._ensureCompletePromise();
+        if (this._deflate) {
+            return writePromise.then(() => this._endDeflateAndWait()).then(() => completePromise);
+        }
+        // STORE mode - emit data descriptor directly
+        this._emittedDataDescriptor = true;
+        this._emitDataDescriptor();
+        return completePromise;
+    }
+    /**
+     * Push data - immediately compresses and outputs
+     * Returns a Promise that resolves when the write is complete.
+     * If final=true, it resolves after the data descriptor is emitted.
+     */
+    push(data, final = false, callback) {
+        if (this._finalized) {
+            const promise = Promise.reject(new Error("Cannot push to finalized ZipDeflateFile"));
+            this._tapCallback(promise, callback);
+            return promise;
+        }
+        this._emitHeaderIfNeeded();
+        const writePromise = this._writeData(data);
+        const promise = final ? this._finalizeAfterWrite(writePromise) : writePromise;
+        this._tapCallback(promise, callback);
+        return promise;
+    }
+    /**
+     * Emit local file header with Data Descriptor flag
+     */
+    _emitHeader() {
+        this._enqueueData(this._localHeader, false);
+    }
+    /**
+     * Emit Data Descriptor with CRC and sizes
+     */
+    _emitDataDescriptor() {
+        const crcValue = crc32Finalize(this._crc);
+        const descriptor = buildDataDescriptor(crcValue, this._compressedSize, this._uncompressedSize);
+        // Store entry info for central directory
+        this._centralDirEntryInfo = {
+            name: this.nameBytes,
+            extraField: this.extraField,
+            flags: this._flags,
+            crc: crcValue,
+            compressedSize: this._compressedSize,
+            uncompressedSize: this._uncompressedSize,
+            compressionMethod: this._compressionMethod,
+            dosTime: this.dosTime,
+            dosDate: this.dosDate,
+            offset: -1
+        };
+        this._enqueueData(descriptor, true);
+        this._resolveComplete();
+    }
+    /**
+     * Returns a promise that resolves when the file is completely written
+     * (including data descriptor)
+     */
+    complete() {
+        return this._ensureCompletePromise();
+    }
+    /**
+     * Get entry metadata in the same shape as unzip parser outputs.
+     * This is best-effort: writer-only fields like encryption are always false.
+     */
+    getEntryInfo() {
+        if (!this._centralDirEntryInfo) {
+            return null;
+        }
+        const path = this.name;
+        const isDirectory = path.endsWith("/") || path.endsWith("\\");
+        return {
+            path,
+            isDirectory,
+            compressedSize: this._centralDirEntryInfo.compressedSize,
+            uncompressedSize: this._centralDirEntryInfo.uncompressedSize,
+            compressionMethod: this._centralDirEntryInfo.compressionMethod,
+            crc32: this._centralDirEntryInfo.crc,
+            lastModified: this._modTime,
+            localHeaderOffset: this._centralDirEntryInfo.offset,
+            comment: "",
+            externalAttributes: 0,
+            isEncrypted: false
+        };
+    }
+    /** Writer-only metadata for building the Central Directory. */
+    getCentralDirectoryEntryInfo() {
+        return this._centralDirEntryInfo;
+    }
+    isComplete() {
+        return this._emittedDataDescriptor && this._centralDirEntryInfo !== null;
+    }
+}
+/**
+ * Streaming ZIP Creator - processes files sequentially
+ */
+export class StreamingZip {
+    constructor(callback) {
+        this.entries = [];
+        this.currentOffset = 0;
+        this.ended = false;
+        this.endPending = false;
+        // Queue for sequential file processing
+        this.fileQueue = [];
+        this.fileQueueIndex = 0;
+        this.activeFile = null;
+        this.callback = callback;
+    }
+    add(file) {
+        if (this.ended) {
+            throw new Error("Cannot add files after calling end()");
+        }
+        this.fileQueue.push(file);
+        // If no active file, process this one
+        if (!this.activeFile) {
+            this._processNextFile();
+        }
+    }
+    _processNextFile() {
+        if (this.fileQueueIndex >= this.fileQueue.length) {
+            this.activeFile = null;
+            // Reset queue storage
+            this.fileQueue = [];
+            this.fileQueueIndex = 0;
+            // Check if we can finalize
+            if (this.endPending) {
+                this._finalize();
+            }
+            return;
+        }
+        const file = this.fileQueue[this.fileQueueIndex++];
+        this.activeFile = file;
+        const startOffset = this.currentOffset;
+        file.ondata = (data, final) => {
+            this.currentOffset += data.length;
+            this.callback(null, data, false);
+            if (final) {
+                const entryInfo = file.getCentralDirectoryEntryInfo();
+                if (entryInfo) {
+                    entryInfo.offset = startOffset;
+                    this.entries.push(entryInfo);
+                }
+                // Process next file
+                this._processNextFile();
+            }
+        };
+    }
+    _finalize() {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        const centralDirOffset = this.currentOffset;
+        let centralDirSize = 0;
+        const empty = new Uint8Array(0);
+        for (const entry of this.entries) {
+            const header = buildCentralDirectoryHeader({
+                fileName: entry.name,
+                extraField: entry.extraField,
+                comment: empty,
+                flags: entry.flags,
+                compressionMethod: entry.compressionMethod,
+                dosTime: entry.dosTime,
+                dosDate: entry.dosDate,
+                crc32: entry.crc,
+                compressedSize: entry.compressedSize,
+                uncompressedSize: entry.uncompressedSize,
+                localHeaderOffset: entry.offset,
+                versionMadeBy: VERSION_MADE_BY,
+                versionNeeded: VERSION_NEEDED
+            });
+            centralDirSize += header.length;
+            this.callback(null, header, false);
+        }
+        const eocd = buildEndOfCentralDirectory({
+            entryCount: this.entries.length,
+            centralDirSize,
+            centralDirOffset,
+            comment: empty
+        });
+        this.callback(null, eocd, true);
+    }
+    end() {
+        if (this.endPending || this.ended) {
+            return;
+        }
+        this.endPending = true;
+        // If no active file (all complete), finalize now
+        if (!this.activeFile) {
+            this._finalize();
+        }
+        // Otherwise, _processNextFile will call _finalize when done
+    }
+}
+// =============================================================================
+// Export aliases for fflate compatibility
+export { StreamingZip as Zip, ZipDeflateFile as ZipDeflate };

package/dist/esm/modules/archive/utils/binary.js

@@ -0,0 +1,69 @@
+/**
+ * Tiny binary reader for Uint8Array-backed DataView.
+ * Shared by ZIP parsers.
+ */
+import { decodeLatin1, decodeUtf8 } from "@archive/utils/text";
+export function writeUint32LE(value) {
+    const out = new Uint8Array(4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, value >>> 0, true);
+    return out;
+}
+export function readUint32LE(data, offset) {
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return view.getUint32(offset, true);
+}
+export class BinaryReader {
+    constructor(data, offset = 0) {
+        this.data = data;
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        this.offset = offset;
+    }
+    get position() {
+        return this.offset;
+    }
+    set position(value) {
+        this.offset = value;
+    }
+    get remaining() {
+        return this.data.length - this.offset;
+    }
+    readUint8() {
+        const value = this.view.getUint8(this.offset);
+        this.offset += 1;
+        return value;
+    }
+    readUint16() {
+        const value = this.view.getUint16(this.offset, true);
+        this.offset += 2;
+        return value;
+    }
+    readUint32() {
+        const value = this.view.getUint32(this.offset, true);
+        this.offset += 4;
+        return value;
+    }
+    readBigUint64() {
+        const value = this.view.getBigUint64(this.offset, true);
+        this.offset += 8;
+        return value;
+    }
+    readBytes(length) {
+        const bytes = this.data.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return bytes;
+    }
+    readString(length, utf8 = true) {
+        const bytes = this.readBytes(length);
+        return utf8 ? decodeUtf8(bytes) : decodeLatin1(bytes);
+    }
+    skip(length) {
+        this.offset += length;
+    }
+    slice(start, end) {
+        return this.data.subarray(start, end);
+    }
+    peekUint32(offset) {
+        return this.view.getUint32(offset, true);
+    }
+}

package/dist/esm/modules/archive/utils/bytes.js

@@ -0,0 +1,101 @@
+export function sumUint8ArrayLengths(arrays) {
+    let totalLength = 0;
+    for (let i = 0; i < arrays.length; i++) {
+        totalLength += arrays[i].length;
+    }
+    return totalLength;
+}
+export function concatUint8Arrays(arrays) {
+    const len = arrays.length;
+    if (len === 0) {
+        return new Uint8Array(0);
+    }
+    if (len === 1) {
+        return arrays[0];
+    }
+    const totalLength = sumUint8ArrayLengths(arrays);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (let i = 0; i < len; i++) {
+        const arr = arrays[i];
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+/**
+ * Find the first index of `pattern` within `buffer`.
+ * Returns -1 when not found.
+ */
+export function indexOfUint8ArrayPattern(buffer, pattern, startIndex = 0) {
+    const bufLen = buffer.length;
+    const patLen = pattern.length;
+    if (patLen === 0) {
+        return 0;
+    }
+    if (patLen > bufLen) {
+        return -1;
+    }
+    let start = startIndex | 0;
+    if (start < 0) {
+        start = 0;
+    }
+    if (start > bufLen - patLen) {
+        return -1;
+    }
+    // Fast paths for small patterns (very common in ZIP parsing: 2/3/4-byte signatures).
+    if (patLen === 1) {
+        const p0 = pattern[0];
+        for (let i = start; i < bufLen; i++) {
+            if (buffer[i] === p0) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    if (patLen === 2) {
+        const p0 = pattern[0];
+        const p1 = pattern[1];
+        for (let i = start; i <= bufLen - 2; i++) {
+            if (buffer[i] === p0 && buffer[i + 1] === p1) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    if (patLen === 3) {
+        const p0 = pattern[0];
+        const p1 = pattern[1];
+        const p2 = pattern[2];
+        for (let i = start; i <= bufLen - 3; i++) {
+            if (buffer[i] === p0 && buffer[i + 1] === p1 && buffer[i + 2] === p2) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    if (patLen === 4) {
+        const p0 = pattern[0];
+        const p1 = pattern[1];
+        const p2 = pattern[2];
+        const p3 = pattern[3];
+        for (let i = start; i <= bufLen - 4; i++) {
+            if (buffer[i] === p0 &&
+                buffer[i + 1] === p1 &&
+                buffer[i + 2] === p2 &&
+                buffer[i + 3] === p3) {
+                return i;
+            }
+        }
+        return -1;
+    }
+    outer: for (let i = start; i <= bufLen - patLen; i++) {
+        for (let j = 0; j < patLen; j++) {
+            if (buffer[i + j] !== pattern[j]) {
+                continue outer;
+            }
+        }
+        return i;
+    }
+    return -1;
+}

package/dist/esm/modules/archive/utils/parse-buffer.js

@@ -0,0 +1,55 @@
+/**
+ * Read unsigned little-endian integer from Uint8Array
+ */
+function readUIntLE(buffer, offset, size) {
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    switch (size) {
+        case 1:
+            return view.getUint8(offset);
+        case 2:
+            return view.getUint16(offset, true);
+        case 4:
+            return view.getUint32(offset, true);
+        case 8: {
+            // Read as BigUint64 and convert to Number
+            const low = view.getUint32(offset, true);
+            const high = view.getUint32(offset + 4, true);
+            return high * 0x100000000 + low;
+        }
+        default:
+            throw new Error("Unsupported UInt LE size!");
+    }
+}
+/**
+ * Parses sequential unsigned little endian numbers from the head of the passed buffer according to
+ * the specified format passed. If the buffer is not large enough to satisfy the full format,
+ * null values will be assigned to the remaining keys.
+ * @param buffer The buffer to sequentially extract numbers from.
+ * @param format Expected format to follow when extracting values from the buffer. A list of list entries
+ * with the following structure:
+ * [
+ *   [
+ *     <key>,  // Name of the key to assign the extracted number to.
+ *     <size>  // The size in bytes of the number to extract. possible values are 1, 2, 4, 8.
+ *   ],
+ *   ...
+ * ]
+ * @returns An object with keys set to their associated extracted values.
+ */
+export function parse(buffer, format) {
+    const result = {};
+    let offset = 0;
+    for (const [key, size] of format) {
+        if (buffer.length >= offset + size) {
+            result[key] = readUIntLE(buffer, offset, size);
+        }
+        else {
+            result[key] = null;
+        }
+        offset += size;
+    }
+    return result;
+}
+export function parseTyped(buffer, format) {
+    return parse(buffer, format);
+}

package/dist/esm/modules/archive/utils/text.js

@@ -0,0 +1,33 @@
+/**
+ * Shared text encoding/decoding utilities.
+ *
+ * Caches encoder/decoder instances for performance.
+ */
+export const utf8Encoder = new TextEncoder();
+export const utf8Decoder = new TextDecoder("utf-8");
+/**
+ * Encode a string as UTF-8.
+ */
+export function encodeUtf8(value) {
+    return utf8Encoder.encode(value);
+}
+/**
+ * Decode bytes as UTF-8.
+ */
+export function decodeUtf8(bytes) {
+    return utf8Decoder.decode(bytes);
+}
+/**
+ * Decode bytes as Latin-1/byte-to-char.
+ * Used as a fallback when UTF-8 flag is not set.
+ */
+export function decodeLatin1(bytes) {
+    // Avoid spreading huge arrays; build incrementally.
+    let out = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        out += String.fromCharCode(...chunk);
+    }
+    return out;
+}