@cj-tech-master/excelts 4.2.0 → 4.2.1-canary.20260111102127.f808a37

package/dist/esm/modules/archive/zip/index.js

@@ -0,0 +1,157 @@
+import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "../defaults.js";
+import { ZipDeflateFile, StreamingZip } from "./stream.js";
+import { createZip, createZipSync } from "./zip-bytes.js";
+import { collect, pipeIterableToSink } from "../io/archive-sink.js";
+import { toAsyncIterable, toUint8Array, toUint8ArraySync } from "../io/archive-source.js";
+import { createAsyncQueue } from "../utils/async-queue.js";
+const REPRODUCIBLE_ZIP_MOD_TIME = new Date(1980, 0, 1, 0, 0, 0);
+export class ZipArchive {
+    constructor(options = {}) {
+        this._entries = [];
+        this._sealed = false;
+        const reproducible = options.reproducible ?? false;
+        this._options = {
+            level: options.level ?? DEFAULT_ZIP_LEVEL,
+            timestamps: options.timestamps ?? (reproducible ? "dos" : DEFAULT_ZIP_TIMESTAMPS),
+            comment: options.comment,
+            modTime: options.modTime ?? (reproducible ? REPRODUCIBLE_ZIP_MOD_TIME : new Date()),
+            smartStore: options.smartStore ?? true
+        };
+    }
+    add(name, source, options) {
+        if (this._sealed) {
+            throw new Error("Cannot add entries after output has started");
+        }
+        if (!name) {
+            throw new Error("Entry name is required");
+        }
+        this._entries.push({ name, source, options });
+        return this;
+    }
+    stream() {
+        this._sealed = true;
+        const queue = createAsyncQueue();
+        const zip = new StreamingZip((err, data, final) => {
+            if (err) {
+                queue.fail(err);
+                return;
+            }
+            if (data.length) {
+                queue.push(data);
+            }
+            if (final) {
+                queue.close();
+            }
+        }, { comment: this._options.comment });
+        (async () => {
+            try {
+                for (const entry of this._entries) {
+                    const level = entry.options?.level ?? this._options.level;
+                    const file = new ZipDeflateFile(entry.name, {
+                        level,
+                        modTime: entry.options?.modTime ?? this._options.modTime,
+                        timestamps: this._options.timestamps,
+                        comment: entry.options?.comment,
+                        smartStore: this._options.smartStore
+                    });
+                    zip.add(file);
+                    // Feed data
+                    if (entry.source instanceof Uint8Array ||
+                        entry.source instanceof ArrayBuffer ||
+                        typeof entry.source === "string" ||
+                        (typeof Blob !== "undefined" && entry.source instanceof Blob)) {
+                        const bytes = await toUint8Array(entry.source);
+                        await file.push(bytes, true);
+                    }
+                    else {
+                        for await (const chunk of toAsyncIterable(entry.source)) {
+                            await file.push(chunk, false);
+                        }
+                        await file.push(new Uint8Array(0), true);
+                    }
+                    await file.complete();
+                }
+                zip.end();
+            }
+            catch (e) {
+                queue.fail(e instanceof Error ? e : new Error(String(e)));
+            }
+        })();
+        return queue.iterable;
+    }
+    async bytes() {
+        this._sealed = true;
+        const allSourcesInMemory = this._entries.every(e => e.source instanceof Uint8Array ||
+            e.source instanceof ArrayBuffer ||
+            typeof e.source === "string" ||
+            (typeof Blob !== "undefined" && e.source instanceof Blob));
+        const hasBlobSource = this._entries.some(e => typeof Blob !== "undefined" && e.source instanceof Blob);
+        // Fast-path: when all sources are already in memory and there are no
+        // per-entry compression overrides, use the single-buffer ZIP builder.
+        // This avoids the overhead of chunking + collecting from the streaming writer.
+        if (allSourcesInMemory) {
+            // Prefer the sync builder when possible (Node.js hot path): it avoids
+            // async/Promise overhead and uses zlib sync fast paths.
+            if (!hasBlobSource) {
+                const entries = this._entries.map(e => ({
+                    name: e.name,
+                    data: toUint8ArraySync(e.source),
+                    level: e.options?.level,
+                    modTime: e.options?.modTime,
+                    comment: e.options?.comment
+                }));
+                return createZipSync(entries, {
+                    level: this._options.level,
+                    timestamps: this._options.timestamps,
+                    modTime: this._options.modTime,
+                    comment: this._options.comment,
+                    smartStore: this._options.smartStore
+                });
+            }
+            const entries = await Promise.all(this._entries.map(async (e) => ({
+                name: e.name,
+                data: await toUint8Array(e.source),
+                level: e.options?.level,
+                modTime: e.options?.modTime,
+                comment: e.options?.comment
+            })));
+            return createZip(entries, {
+                level: this._options.level,
+                timestamps: this._options.timestamps,
+                modTime: this._options.modTime,
+                comment: this._options.comment,
+                smartStore: this._options.smartStore
+            });
+        }
+        return collect(this.stream());
+    }
+    bytesSync() {
+        this._sealed = true;
+        const entries = this._entries.map(e => {
+            if (!(e.source instanceof Uint8Array) &&
+                !(e.source instanceof ArrayBuffer) &&
+                typeof e.source !== "string") {
+                throw new Error("bytesSync() only supports Uint8Array/ArrayBuffer/string sources");
+            }
+            return {
+                name: e.name,
+                data: toUint8ArraySync(e.source),
+                modTime: e.options?.modTime,
+                comment: e.options?.comment
+            };
+        });
+        return createZipSync(entries, {
+            level: this._options.level,
+            timestamps: this._options.timestamps,
+            modTime: this._options.modTime,
+            comment: this._options.comment,
+            smartStore: this._options.smartStore
+        });
+    }
+    async pipeTo(sink) {
+        await pipeIterableToSink(this.stream(), sink);
+    }
+}
+export function zip(options) {
+    return new ZipArchive(options);
+}

package/dist/esm/modules/archive/{streaming-zip.js → zip/stream.js}

@@ -2,15 +2,16 @@
  * True Streaming ZIP creator - shared implementation.
  *
  * This module is intentionally platform-agnostic.
- * - In Node builds it uses `./crc32` + `./streaming-compress` (zlib-backed).
+ * - In Node builds it uses `./compression/crc32` + `./compression/streaming-compress` (zlib-backed).
  * - In browser builds the bundler aliases those imports to their browser variants.
  */
-import { crc32Update, crc32Finalize } from "./crc32.js";
-import { createDeflateStream } from "./streaming-compress.js";
-import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "./defaults.js";
-import { buildZipEntryMetadata } from "./zip-entry-metadata.js";
-import { buildCentralDirectoryHeader, buildDataDescriptor, buildEndOfCentralDirectory, buildLocalFileHeader } from "./zip-records.js";
-import { VERSION_MADE_BY, VERSION_NEEDED } from "./zip-constants.js";
+import { crc32Update, crc32Finalize } from "../compression/crc32.js";
+import { createDeflateStream } from "../compression/streaming-compress.js";
+import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "../defaults.js";
+import { buildZipEntryMetadata, resolveZipCompressionMethod } from "./zip-entry-metadata.js";
+import { decodeUtf8, encodeUtf8 } from "../utils/text.js";
+import { isProbablyIncompressible } from "../utils/compressibility.js";
+import { buildCentralDirectoryHeader, buildDataDescriptor, buildEndOfCentralDirectory, buildLocalFileHeader, VERSION_MADE_BY, VERSION_NEEDED } from "../zip-spec/zip-records.js";
 /**
  * True Streaming ZIP File - compresses chunk by chunk
  */
@@ -23,9 +24,15 @@ export class ZipDeflateFile {
         this._finalized = false;
         this._headerEmitted = false;
         this._ondata = null;
+        this._onerror = null;
         this._centralDirEntryInfo = null;
         this._pendingEnd = false;
         this._emittedDataDescriptor = false;
+        this._localHeader = null;
+        // Smart STORE: delay method selection until we sample data.
+        this._deflateWanted = null;
+        this._pendingChunks = [];
+        this._sampleLen = 0;
         // Promise resolution for completion (including data descriptor)
         this._completeResolve = null;
         this._completeReject = null;
@@ -34,46 +41,70 @@ export class ZipDeflateFile {
         // Queue for incoming data before ondata is set
         this._dataQueue = [];
         this._finalQueued = false;
+        // Serialize push() calls so callers don't need to await to preserve ordering.
+        this._pushChain = Promise.resolve();
         this.name = name;
         const modTime = options?.modTime ?? new Date();
         this._modTime = modTime;
         this.level = options?.level ?? DEFAULT_ZIP_LEVEL;
+        this._smartStore = options?.smartStore ?? true;
+        this._sampleBuffer = this._smartStore ? new Uint8Array(64 * 1024) : new Uint8Array(0);
         const metadata = buildZipEntryMetadata({
             name,
-            comment: "",
+            comment: options?.comment ?? "",
             modTime,
             timestamps: options?.timestamps ?? DEFAULT_ZIP_TIMESTAMPS,
             useDataDescriptor: true,
-            deflate: this.level > 0
+            deflate: false
         });
         this.nameBytes = metadata.nameBytes;
+        this.commentBytes = metadata.commentBytes;
         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();
-                }
-            });
+        // If smart store is disabled, decide method upfront and keep true streaming semantics.
+        if (!this._smartStore) {
+            const deflate = this.level > 0;
+            this._deflateWanted = deflate;
+            this._compressionMethod = this._buildCompressionMethod(deflate);
+            if (deflate) {
+                this._initDeflateStream();
+            }
+            return;
         }
-        this._localHeader = this._buildLocalHeader();
+        // Level 0: always STORE.
+        if (this.level === 0) {
+            this._deflateWanted = false;
+            this._compressionMethod = this._buildCompressionMethod(false);
+        }
+    }
+    _buildCompressionMethod(deflate) {
+        return resolveZipCompressionMethod(deflate);
+    }
+    _initDeflateStream() {
+        if (this._deflate) {
+            return;
+        }
+        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();
+            }
+        });
     }
     _buildLocalHeader() {
         // CRC + sizes are written via data descriptor for true streaming.
@@ -90,6 +121,63 @@ export class ZipDeflateFile {
             versionNeeded: VERSION_NEEDED
         });
     }
+    _accumulateSample(data) {
+        if (this._deflateWanted !== null) {
+            return;
+        }
+        if (this._sampleLen >= this._sampleBuffer.length) {
+            return;
+        }
+        const take = Math.min(this._sampleBuffer.length - this._sampleLen, data.length);
+        if (take <= 0) {
+            return;
+        }
+        this._sampleBuffer.set(data.subarray(0, take), this._sampleLen);
+        this._sampleLen += take;
+    }
+    _shouldDecide(final) {
+        if (this._deflateWanted !== null) {
+            return false;
+        }
+        return final || this._sampleLen >= 16 * 1024;
+    }
+    _decideCompressionIfNeeded(final) {
+        if (this._deflateWanted !== null) {
+            return;
+        }
+        // Match non-streaming builder semantics: empty files never need DEFLATE.
+        if (final && this._sampleLen === 0) {
+            this._deflateWanted = false;
+            this._compressionMethod = this._buildCompressionMethod(false);
+            this._localHeader = null;
+            return;
+        }
+        // Default to DEFLATE unless heuristic says STORE.
+        const sample = this._sampleBuffer.subarray(0, this._sampleLen);
+        const store = isProbablyIncompressible(sample);
+        this._deflateWanted = !store;
+        this._compressionMethod = this._buildCompressionMethod(this._deflateWanted);
+        this._localHeader = null;
+        if (this._deflateWanted) {
+            this._initDeflateStream();
+        }
+    }
+    _emitHeaderIfNeeded() {
+        if (this._headerEmitted) {
+            return;
+        }
+        this._emitHeader();
+        this._headerEmitted = true;
+    }
+    async _flushPendingChunks() {
+        if (this._pendingChunks.length === 0) {
+            return;
+        }
+        for (const chunk of this._pendingChunks) {
+            await this._writeData(chunk);
+        }
+        this._pendingChunks = [];
+    }
     _enqueueData(data, final) {
         if (this._ondata) {
             this._ondata(data, final);
@@ -121,13 +209,29 @@ export class ZipDeflateFile {
         // Flush any queued data
         this._flushQueue();
     }
+    get onerror() {
+        return this._onerror ?? undefined;
+    }
+    set onerror(cb) {
+        this._onerror = cb;
+        // If an error already occurred, surface it immediately.
+        if (this._completeError) {
+            cb(this._completeError);
+        }
+    }
     _resolveComplete() {
         if (this._completeResolve) {
             this._completeResolve();
         }
     }
     _rejectComplete(err) {
+        if (this._completeError) {
+            return;
+        }
         this._completeError = err;
+        if (this._onerror) {
+            this._onerror(err);
+        }
         if (this._completeReject) {
             this._completeReject(err);
         }
@@ -153,13 +257,6 @@ export class ZipDeflateFile {
         }
         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();
@@ -217,27 +314,60 @@ export class ZipDeflateFile {
         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) {
+    _pushUnchained(data, final, callback) {
         if (this._finalized) {
             const promise = Promise.reject(new Error("Cannot push to finalized ZipDeflateFile"));
             this._tapCallback(promise, callback);
             return promise;
         }
+        if (this._deflateWanted === null) {
+            this._accumulateSample(data);
+            if (!this._shouldDecide(final)) {
+                if (data.length > 0) {
+                    this._pendingChunks.push(data);
+                }
+                const promise = Promise.resolve();
+                this._tapCallback(promise, callback);
+                return promise;
+            }
+            this._decideCompressionIfNeeded(final);
+            this._emitHeaderIfNeeded();
+            const hadPendingChunks = this._pendingChunks.length > 0;
+            const flushPromise = this._flushPendingChunks();
+            let writePromise = flushPromise;
+            if (data.length > 0) {
+                writePromise = hadPendingChunks
+                    ? flushPromise.then(() => this._writeData(data))
+                    : this._writeData(data);
+            }
+            const promise = final ? this._finalizeAfterWrite(writePromise) : writePromise;
+            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;
     }
+    /**
+     * 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) {
+        const promise = (this._pushChain = this._pushChain.then(() => this._pushUnchained(data, final, callback)));
+        // Prevent unhandled rejection when callers intentionally ignore the Promise.
+        promise.catch(() => { });
+        return promise;
+    }
     /**
      * Emit local file header with Data Descriptor flag
      */
     _emitHeader() {
+        if (!this._localHeader) {
+            this._localHeader = this._buildLocalHeader();
+        }
         this._enqueueData(this._localHeader, false);
     }
     /**
@@ -250,6 +380,7 @@ export class ZipDeflateFile {
         this._centralDirEntryInfo = {
             name: this.nameBytes,
             extraField: this.extraField,
+            comment: this.commentBytes,
             flags: this._flags,
             crc: crcValue,
             compressedSize: this._compressedSize,
@@ -288,7 +419,7 @@ export class ZipDeflateFile {
             crc32: this._centralDirEntryInfo.crc,
             lastModified: this._modTime,
             localHeaderOffset: this._centralDirEntryInfo.offset,
-            comment: "",
+            comment: decodeUtf8(this._centralDirEntryInfo.comment),
             externalAttributes: 0,
             isEncrypted: false
         };
@@ -305,7 +436,7 @@ export class ZipDeflateFile {
  * Streaming ZIP Creator - processes files sequentially
  */
 export class StreamingZip {
-    constructor(callback) {
+    constructor(callback, options) {
         this.entries = [];
         this.currentOffset = 0;
         this.ended = false;
@@ -315,10 +446,12 @@ export class StreamingZip {
         this.fileQueueIndex = 0;
         this.activeFile = null;
         this.callback = callback;
+        // Avoid per-instance TextEncoder allocations.
+        this.zipComment = options?.comment ? encodeUtf8(options.comment) : new Uint8Array(0);
     }
     add(file) {
         if (this.ended) {
-            throw new Error("Cannot add files after calling end()");
+            throw new Error("Cannot add files after calling end() ");
         }
         this.fileQueue.push(file);
         // If no active file, process this one
@@ -341,7 +474,18 @@ export class StreamingZip {
         const file = this.fileQueue[this.fileQueueIndex++];
         this.activeFile = file;
         const startOffset = this.currentOffset;
+        const empty = new Uint8Array(0);
+        file.onerror = (err) => {
+            if (this.ended) {
+                return;
+            }
+            this.ended = true;
+            this.callback(err, empty, true);
+        };
         file.ondata = (data, final) => {
+            if (this.ended) {
+                return;
+            }
             this.currentOffset += data.length;
             this.callback(null, data, false);
             if (final) {
@@ -367,7 +511,7 @@ export class StreamingZip {
             const header = buildCentralDirectoryHeader({
                 fileName: entry.name,
                 extraField: entry.extraField,
-                comment: empty,
+                comment: entry.comment ?? empty,
                 flags: entry.flags,
                 compressionMethod: entry.compressionMethod,
                 dosTime: entry.dosTime,
@@ -386,7 +530,7 @@ export class StreamingZip {
             entryCount: this.entries.length,
             centralDirSize,
             centralDirOffset,
-            comment: empty
+            comment: this.zipComment
         });
         this.callback(null, eocd, true);
     }