@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/excel/stream/workbook-writer.browser.js

@@ -33,11 +33,77 @@ import { stringToUint8Array } from "../../../utils/binary.js";
 import { base64ToUint8Array } from "../../../utils/utils.browser.js";
 const EMPTY_U8 = new Uint8Array(0);
 const TEXT_DECODER = new TextDecoder();
+/**
+ * Drain a resolver list, calling each. Mutates the array to empty.
+ *
+ * Used by the backpressure machinery: when a sink drains or errors, every
+ * parked `_waitForUserSinkDrain()` / pending-async waiter must be woken
+ * exactly once, and the array reset so the next backpressure cycle starts
+ * clean. Hoisted to a free function so it can be re-used across the three
+ * wake sites without per-site duplication of the splice/loop pattern.
+ */
+function callAllResolvers(resolvers) {
+    if (resolvers.length === 0) {
+        return;
+    }
+    // Snapshot then clear, so a resolver that itself triggers a fresh wait
+    // (re-pushing into the same array) doesn't get confused with the current
+    // batch.
+    const snapshot = resolvers.splice(0);
+    for (const r of snapshot) {
+        r();
+    }
+}
 // ============================================================================
 // Base Class
 // ============================================================================
 export class WorkbookWriterBase {
     constructor(options, WorksheetWriterClass) {
+        // ---------------------------------------------------------------------------
+        // Backpressure tracking for the user-supplied output sink.
+        //
+        // Set by `_trackBackpressure(ok)` whenever `this.stream.write(data)` returns
+        // false (or a Promise that resolves to false). Cleared when the sink emits
+        // `'drain'`. Awaited by `_waitForUserSinkDrain()` at async boundaries
+        // (between worksheets, before `addWorkbook`, etc) so a slow sink throttles
+        // the producer instead of letting bytes accumulate unboundedly inside the
+        // sink's internal buffer or in the zip pipeline.
+        //
+        // Important caveat: this **cannot** block a single tight synchronous
+        // `for (...) row.commit()` loop inside one worksheet — JavaScript has no
+        // sync wait, and `row.commit()` is sync void. During such a loop, every
+        // produced compressed chunk is pushed straight into the sink's internal
+        // buffer (Node `Writable` accepts writes after returning false; it just
+        // hints "drain"). For very-large single-worksheet workloads with a slow
+        // sink, the practical bound on how much can pile up is roughly the total
+        // compressed size of one worksheet — only the `wb.commit()` boundary
+        // (and any `worksheet.commit()` between sheets) gives the event loop a
+        // chance to park here on `_waitForUserSinkDrain()`.
+        //
+        // Multi-sheet workloads benefit fully because each `worksheet.commit()`
+        // hands control back to `_commitWorksheets()` which awaits drain before
+        // the next sheet starts.
+        this._needsDrain = false;
+        this._drainResolvers = [];
+        this._drainListenerAttached = false;
+        // Captured if the user sink fires 'error' before `_finalize()` attaches its
+        // own listener. Replayed by `_finalize()` so the original error is what
+        // rejects `commit()`, not a generic timeout.
+        this._sinkError = null;
+        /**
+         * Attach error/close listeners on the user sink so any parked backpressure
+         * waiters are released the moment the sink fails. Without this, a
+         * `commit()` parked on `_waitForUserSinkDrain()` would hang forever if
+         * the sink errored before emitting 'drain'. Idempotent and a no-op for
+         * sinks that don't expose `.on` (e.g. internal `StreamBuf`).
+         *
+         * Uses a non-consuming listener: if the user has their own 'error' handler
+         * it still fires (EventEmitter broadcasts to all listeners). The error is
+         * also captured into `_sinkError` so `_finalize()` can replay it — `_finalize`
+         * registers its own listener with `once()`, which would miss errors that
+         * arrived earlier in the commit pipeline.
+         */
+        this._lifecycleListenersAttached = false;
         this.WorksheetWriterClass = WorksheetWriterClass;
         this.created = options.created || new Date();
         this.modified = options.modified || this.created;
@@ -57,14 +123,26 @@ export class WorkbookWriterBase {
         this.commentRefs = [];
         this.dynamicArrayCount = 0;
         this._trueStreaming = options.trueStreaming ?? false;
-        // Create Zip instance
+        // Create Zip instance.
+        //
+        // Backpressure note: when `this.stream.write(data)` returns false (the
+        // user-supplied sink — e.g. fs.WriteStream, PassThrough, HTTP response
+        // — has reached its highWaterMark), we cannot synchronously block the
+        // zip callback (it's invoked from inside `row.commit()`'s sync chain).
+        // Instead we record a `_needsDrain` flag and a Promise that resolves
+        // when the sink emits `'drain'`. `commit()` and `_commitWorksheets()`
+        // await this promise at their natural async boundaries, so the producer
+        // stops generating new zip data until the sink has caught up. This
+        // makes `WorkbookWriter` safe against slow sinks (network responses,
+        // throttled fs, etc) without changing the public API.
         this.zip = new Zip((err, data, final) => {
             if (err) {
                 this.stream.emit("error", err);
             }
             else {
                 // `streaming-zip` already emits `Uint8Array`; avoid copying per chunk.
-                this.stream.write(data);
+                const ok = this.stream.write(data);
+                this._trackBackpressure(ok);
                 if (final) {
                     this.stream.end();
                 }
@@ -72,6 +150,11 @@ export class WorkbookWriterBase {
         });
         // Setup output stream
         this.stream = this._createOutputStream(options);
+        // Eagerly attach error/close listeners on the sink so any backpressure
+        // waiters are released the moment the sink fails — without this, a
+        // `commit()` parked on `_waitForUserSinkDrain()` would hang forever if
+        // the sink errored before emitting 'drain'.
+        this._attachSinkLifecycleListeners();
         // Theme and office rels are deferred to commit() so that worksheet files
         // are added to the ZIP first. This ensures StreamingZip sets ondata on
         // the worksheet immediately, allowing pushSync to flow data through
@@ -87,6 +170,106 @@ export class WorkbookWriterBase {
         }
         return new StreamBuf();
     }
+    /**
+     * Internal: record whether the sink accepted the last write. The
+     * `OutputStreamLike.write` type advertises `boolean | Promise<boolean>`
+     * for forward compatibility, but in practice every concrete sink we
+     * accept (Node `Writable`, browser `Writable` from `@stream`, internal
+     * `StreamBuf`, fs.WriteStream, etc) returns a sync `boolean`. We
+     * defensively handle the Promise shape but it's never exercised.
+     */
+    _trackBackpressure(ok) {
+        if (ok instanceof Promise) {
+            // Defensive path: a hypothetical sink whose `write()` returns a
+            // Promise. Await its resolution and treat false as backpressure.
+            ok.then(result => {
+                if (!result) {
+                    this._needsDrain = true;
+                }
+            }, () => {
+                // Errors surface via the sink's 'error' event; ignore here.
+            });
+            return;
+        }
+        if (ok === false) {
+            this._needsDrain = true;
+        }
+        this._ensureDrainListener();
+    }
+    _ensureDrainListener() {
+        if (this._drainListenerAttached) {
+            return;
+        }
+        if (typeof this.stream.on !== "function") {
+            // StreamBuf and similar sinks that don't follow the Writable contract
+            // never emit 'drain'; they also never return false from write(), so
+            // they reach this branch only spuriously. Skip listener attach.
+            return;
+        }
+        this._drainListenerAttached = true;
+        this.stream.on("drain", () => {
+            this._needsDrain = false;
+            callAllResolvers(this._drainResolvers);
+        });
+    }
+    _attachSinkLifecycleListeners() {
+        if (this._lifecycleListenersAttached) {
+            return;
+        }
+        if (typeof this.stream.on !== "function") {
+            return;
+        }
+        this._lifecycleListenersAttached = true;
+        // Use `.once()` for both events: we only care about the first error
+        // (subsequent errors are captured in `_sinkError` only if we haven't
+        // recorded one yet). Using `.once()` also avoids leaking the listener
+        // if the sink lives longer than the WorkbookWriter — the EventEmitter
+        // releases the closure as soon as the event fires.
+        if (typeof this.stream.once === "function") {
+            this.stream.once("error", (err) => {
+                if (!this._sinkError) {
+                    this._sinkError = err;
+                }
+                this._wakeAllBackpressureWaiters();
+            });
+            this.stream.once("close", () => {
+                this._wakeAllBackpressureWaiters();
+            });
+        }
+        else {
+            // Fallback: sink only has .on, attach normally.
+            this.stream.on("error", (err) => {
+                if (!this._sinkError) {
+                    this._sinkError = err;
+                }
+                this._wakeAllBackpressureWaiters();
+            });
+        }
+    }
+    _wakeAllBackpressureWaiters() {
+        this._needsDrain = false;
+        callAllResolvers(this._drainResolvers);
+    }
+    /**
+     * Park here until any async writes have settled and the user sink has
+     * drained below its high-water mark. Resolves immediately when no
+     * backpressure is in flight.
+     *
+     * Called at async boundaries inside `commit()` so a slow sink throttles
+     * the producer instead of letting bytes accumulate unboundedly.
+     */
+    async _waitForUserSinkDrain() {
+        // Short-circuit if the sink already errored — no point waiting for a
+        // drain that will never come. The error itself surfaces from
+        // `_finalize()` later.
+        if (this._sinkError) {
+            return;
+        }
+        if (!this._needsDrain) {
+            return;
+        }
+        return new Promise(resolve => this._drainResolvers.push(resolve));
+    }
     get definedNames() {
         return this._definedNames;
     }
@@ -135,24 +318,32 @@ export class WorkbookWriterBase {
         }
         zipFile.push(buffer, true);
     }
-    _commitWorksheets() {
-        const commitWorksheet = (worksheet) => {
-            if (!worksheet.committed) {
-                return new Promise(resolve => {
-                    worksheet.stream.once("zipped", () => resolve());
-                    worksheet.commit();
-                });
+    async _commitWorksheets() {
+        // Commit worksheets sequentially (not in parallel) so we can park on
+        // user-sink backpressure between them. Parallel commit was the old
+        // behavior; for a single-worksheet workbook the difference is nil, and
+        // for multi-sheet workbooks honoring backpressure between them keeps
+        // memory bounded against slow sinks. ZIP itself is inherently serial
+        // (StreamingZip processes one entry at a time via `activeFile`), so
+        // sequential commit imposes no real CPU cost — measured throughput is
+        // identical to parallel commit on multi-sheet workbooks.
+        for (const worksheet of this._worksheets) {
+            if (!worksheet || worksheet.committed) {
+                continue;
             }
-            return Promise.resolve();
-        };
-        const promises = this._worksheets.map(commitWorksheet);
-        return promises.length ? Promise.all(promises).then(() => { }) : Promise.resolve();
+            await new Promise(resolve => {
+                worksheet.stream.once("zipped", () => resolve());
+                worksheet.commit();
+            });
+            await this._waitForUserSinkDrain();
+        }
     }
     async commit() {
         await this.promise;
         await this._commitWorksheets();
         await this.addMedia();
         this.addDrawings();
+        await this._waitForUserSinkDrain();
         await Promise.all([
             this.addThemes(),
             this.addOfficeRels(),
@@ -165,7 +356,9 @@ export class WorkbookWriterBase {
             this.addMetadata(),
             this.addWorkbookRels()
         ]);
+        await this._waitForUserSinkDrain();
         await this.addWorkbook();
+        await this._waitForUserSinkDrain();
         await this._finalize();
     }
     get nextId() {
@@ -436,6 +629,22 @@ export class WorkbookWriterBase {
         });
     }
     _finalize() {
+        // If the user sink errored earlier in the commit pipeline (captured by
+        // `_attachSinkLifecycleListeners`), surface that error now — `commit()`
+        // would otherwise reach `_finalize` and hang waiting for `'close'` from
+        // a sink that's already destroyed.
+        if (this._sinkError) {
+            // End the zip pipeline cleanly so its internal callbacks don't keep
+            // firing into a torn-down sink. Best-effort: ignore any error from
+            // end() since the original `_sinkError` is what we care about.
+            try {
+                this.zip.end();
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+            return Promise.reject(this._sinkError);
+        }
         // Wait for "close" — emitted by all supported output streams (Node Writable,
         // browser Writable, and StreamBuf) after "finish". For file streams this
         // guarantees the fd is released, which is critical on Windows where reading
@@ -451,6 +660,12 @@ export class WorkbookWriterBase {
             };
             const onDone = () => {
                 cleanup();
+                // If an error fired between us checking `_sinkError` and reaching
+                // 'close' (rare but possible with concurrent emit), surface it.
+                if (this._sinkError) {
+                    reject(this._sinkError);
+                    return;
+                }
                 resolve(this);
             };
             this.stream.once("error", onError);

package/dist/browser/modules/excel/utils/string-buf.d.ts

@@ -1,29 +1,8 @@
 /**
- * StringBuf - Cross-Platform String Buffer
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
  *
- * A way to keep string memory operations to a minimum while building XML strings.
- * Uses TextEncoder and Uint8Array for cross-platform compatibility (Node.js + Browser).
+ * Kept as a thin alias so existing imports (`@excel/utils/string-buf`)
+ * continue to work without churn.
  */
-interface StringBufOptions {
-    size?: number;
-    encoding?: string;
-}
-/**
- * StringBuf - efficient string builder using Uint8Array
- * Works identically in Node.js and Browser environments.
- */
-declare class StringBuf {
-    private _buf;
-    private _inPos;
-    private _buffer;
-    constructor(options?: StringBufOptions);
-    get length(): number;
-    get capacity(): number;
-    get buffer(): Uint8Array;
-    toBuffer(): Uint8Array;
-    reset(position?: number): void;
-    private _grow;
-    addText(text: string): void;
-    addStringBuf(inBuf: StringBuf): void;
-}
-export { StringBuf };
+export { StringBuf } from "../../../utils/string-buf.js";
+export type { StringBufOptions } from "../../../utils/string-buf.js";

package/dist/browser/modules/excel/utils/string-buf.js

@@ -1,84 +1,7 @@
 /**
- * StringBuf - Cross-Platform String Buffer
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
  *
- * A way to keep string memory operations to a minimum while building XML strings.
- * Uses TextEncoder and Uint8Array for cross-platform compatibility (Node.js + Browser).
+ * Kept as a thin alias so existing imports (`@excel/utils/string-buf`)
+ * continue to work without churn.
  */
-const encoder = new TextEncoder();
-/**
- * StringBuf - efficient string builder using Uint8Array
- * Works identically in Node.js and Browser environments.
- */
-class StringBuf {
-    constructor(options) {
-        this._buf = new Uint8Array((options && options.size) || 16384);
-        // TextEncoder only supports UTF-8, so encoding option is ignored
-        this._inPos = 0;
-        this._buffer = undefined;
-    }
-    get length() {
-        return this._inPos;
-    }
-    get capacity() {
-        return this._buf.length;
-    }
-    get buffer() {
-        return this._buf;
-    }
-    toBuffer() {
-        // Return the current data as a single enclosing buffer
-        if (!this._buffer) {
-            this._buffer = this._buf.slice(0, this._inPos);
-        }
-        return this._buffer;
-    }
-    reset(position) {
-        position = position ?? 0;
-        this._buffer = undefined;
-        this._inPos = position;
-    }
-    _grow(min) {
-        let size = this._buf.length * 2;
-        while (size < min) {
-            size *= 2;
-        }
-        const buf = new Uint8Array(size);
-        buf.set(this._buf);
-        this._buf = buf;
-    }
-    addText(text) {
-        this._buffer = undefined;
-        // Ensure there's room for at least the string length (optimistic: 1 byte per char).
-        const optimistic = this._inPos + text.length;
-        if (optimistic > this._buf.length - 4) {
-            this._grow(optimistic);
-        }
-        // Use encodeInto to write directly into the buffer, avoiding the
-        // intermediate Uint8Array allocation that encoder.encode() creates.
-        const target = this._buf.subarray(this._inPos);
-        const result = encoder.encodeInto(text, target);
-        if (result.read < text.length) {
-            // Didn't fit — text has multi-byte UTF-8 chars that exceed the optimistic estimate.
-            // Grow to accommodate the remainder (worst case: 3 bytes per remaining char).
-            const remaining = text.length - result.read;
-            this._grow(this._inPos + result.written + remaining * 3);
-            const result2 = encoder.encodeInto(text.substring(result.read), this._buf.subarray(this._inPos + result.written));
-            this._inPos += result.written + result2.written;
-        }
-        else {
-            this._inPos += result.written;
-        }
-    }
-    addStringBuf(inBuf) {
-        if (inBuf.length) {
-            this._buffer = undefined;
-            if (this.length + inBuf.length > this.capacity) {
-                this._grow(this.length + inBuf.length);
-            }
-            // Copy bytes from input buffer
-            this._buf.set(inBuf._buf.subarray(0, inBuf.length), this._inPos);
-            this._inPos += inBuf.length;
-        }
-    }
-}
-export { StringBuf };
+export { StringBuf } from "../../../utils/string-buf.js";

package/dist/browser/modules/excel/workbook.browser.js

@@ -231,6 +231,59 @@ function isReadableStream(input) {
 // =============================================================================
 // CSV Helper Functions (Internal)
 // =============================================================================
+/**
+ * Iterate worksheet rows lazily — yields `{row, rowNumber}` for every row
+ * with values, in sheet order. Reaches into the worksheet's internal
+ * `_rows` array directly so we don't have to materialise the whole row
+ * set up front (matters for very large worksheets piped to slow sinks).
+ *
+ * Note: `_rows` is 0-based but XLSX row numbers are 1-based. Row N lives
+ * at `_rows[N - 1]`, so the yielded `rowNumber` is `i + 1`.
+ */
+function* iterateWorksheetRows(worksheet) {
+    const rows = worksheet._rows;
+    if (!rows || rows.length === 0) {
+        return;
+    }
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        if (row && row.hasValues) {
+            yield { row, rowNumber: i + 1 };
+        }
+    }
+}
+/**
+ * Build a `() => Promise<void>` that resolves on the next `'drain'` event
+ * of `emitter`, but rejects promptly if `'error'` or `'close'` fires first.
+ *
+ * Without the error/close races, a producer parked on `once('drain')`
+ * would hang forever after the downstream sink errors mid-write — the
+ * Transform is destroyed and never emits drain again.
+ */
+function createDrainRacer(emitter) {
+    return () => new Promise((resolve, reject) => {
+        const cleanup = () => {
+            emitter.off("drain", onDrain);
+            emitter.off("error", onError);
+            emitter.off("close", onClose);
+        };
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error("stream closed before drain"));
+        };
+        emitter.once("drain", onDrain);
+        emitter.once("error", onError);
+        emitter.once("close", onClose);
+    });
+}
 function buildParserOptions(options) {
     return {
         delimiter: options?.delimiter ?? ",",
@@ -596,26 +649,56 @@ class Workbook {
         const map = options?.map || createDefaultWriteMapper(options?.dateFormat, options?.dateUTC);
         const includeEmptyRows = options?.includeEmptyRows !== false;
         const formatter = new CsvFormatterStream(buildFormatterOptions(options));
-        if (worksheet) {
-            setTimeout(() => {
+        if (!worksheet) {
+            setTimeout(() => formatter.end(), 0);
+            return formatter;
+        }
+        // Drive rows asynchronously so the formatter's backpressure signal can
+        // throttle production. The drain wait races against `'error'` / `'close'`
+        // so a downstream sink failure unwinds the producer instead of hanging.
+        const awaitFormatterDrain = createDrainRacer(formatter);
+        const writeAndDrain = (values) => {
+            if (formatter.write(values)) {
+                return;
+            }
+            return awaitFormatterDrain();
+        };
+        (async () => {
+            try {
                 let lastRow = 1;
-                worksheet.eachRow((row, rowNumber) => {
+                // Iterate worksheet rows lazily — no snapshot. Each row's `values`
+                // are mapped at iteration time, so already-yielded data is GC-able
+                // as the consumer drains the formatter.
+                for (const { row, rowNumber } of iterateWorksheetRows(worksheet)) {
+                    if (formatter.destroyed) {
+                        return;
+                    }
+                    // First slot is the 1-based padding cell — skip without mutating
+                    // the row (mutating would corrupt subsequent reads / writes).
+                    const dataValues = row.values.slice(1).map(map);
                     if (includeEmptyRows) {
                         while (lastRow++ < rowNumber - 1) {
-                            formatter.write([]);
+                            const p = writeAndDrain([]);
+                            if (p) {
+                                await p;
+                            }
+                            if (formatter.destroyed) {
+                                return;
+                            }
                         }
                     }
-                    const { values } = row;
-                    values.shift();
-                    formatter.write(values.map(map));
+                    const p = writeAndDrain(dataValues);
+                    if (p) {
+                        await p;
+                    }
                     lastRow = rowNumber;
-                });
+                }
                 formatter.end();
-            }, 0);
-        }
-        else {
-            setTimeout(() => formatter.end(), 0);
-        }
+            }
+            catch (err) {
+                formatter.destroy(err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
         return formatter;
     }
     /**
@@ -814,20 +897,47 @@ class Workbook {
         const includeEmptyRows = options?.includeEmptyRows !== false;
         const formatter = new CsvFormatterStream(buildFormatterOptions(options));
         const pipelinePromise = pipeline(formatter, stream);
-        let lastRow = 1;
-        worksheet.eachRow((row, rowNumber) => {
-            if (includeEmptyRows) {
-                while (lastRow++ < rowNumber - 1) {
-                    formatter.write([]);
+        // Race drain against error / close so a mid-stream sink failure makes
+        // `writeAndDrain` reject (and the for-loop unwind) instead of hanging
+        // on a 'drain' the destroyed formatter will never emit.
+        const awaitFormatterDrain = createDrainRacer(formatter);
+        const writeAndDrain = async (values) => {
+            if (!formatter.write(values)) {
+                await awaitFormatterDrain();
+            }
+        };
+        try {
+            let lastRow = 1;
+            // Iterate worksheet rows directly without pre-collecting them. The
+            // Workbook model is already in memory, so reaching into `_rows` here
+            // adds no per-row allocation — just a Row reference per iteration,
+            // immediately reassigned. The async loop honours formatter
+            // backpressure between rows so the formatter's internal buffer can't
+            // grow unbounded against a slow sink.
+            for (const { row, rowNumber } of iterateWorksheetRows(worksheet)) {
+                // First slot is the 1-based padding cell — skip without mutating
+                // the row (mutating would corrupt subsequent reads / writes).
+                const dataValues = row.values.slice(1).map(map);
+                if (includeEmptyRows) {
+                    while (lastRow++ < rowNumber - 1) {
+                        await writeAndDrain([]);
+                    }
                 }
+                await writeAndDrain(dataValues);
+                lastRow = rowNumber;
             }
-            const { values } = row;
-            values.shift();
-            formatter.write(values.map(map));
-            lastRow = rowNumber;
-        });
-        formatter.end();
-        await pipelinePromise;
+            formatter.end();
+            await pipelinePromise;
+        }
+        catch (err) {
+            // Sink errored mid-write (or pipeline tore down for any reason).
+            // Destroy the formatter so the pipeline unwinds, swallow the
+            // pipeline rejection (the original error is what we want to surface),
+            // and rethrow.
+            formatter.destroy(err instanceof Error ? err : new Error(String(err)));
+            await pipelinePromise.catch(() => { });
+            throw err;
+        }
     }
     /**
      * Populate a worksheet from a parsed Markdown table result.