@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/archive/compression/streaming-compress.browser.js

@@ -40,6 +40,15 @@ export function hasDeflateRaw() {
 /**
  * Base streaming codec with unified lifecycle management.
  * Backend can emit events via the returned codec reference.
+ *
+ * Backpressure: each `write()` chains a deflate task onto `writeChain`.
+ * Without throttling, a fast producer could enqueue thousands of tasks
+ * (each retaining its input chunk) before the backend catches up. To
+ * surface backpressure to the caller, we count pending writes; once the
+ * count reaches `HIGH_WATER_MARK`, `write()` returns `false`. When the
+ * count drops back below the mark, we emit `'drain'` so callers using
+ * the standard Node Writable contract (`pipe()` / `pipeline()`) can
+ * resume. This keeps memory bounded on slow backends or slow consumers.
  */
 class AsyncStreamCodec extends EventEmitter {
     constructor() {
@@ -48,6 +57,8 @@ class AsyncStreamCodec extends EventEmitter {
         this.destroyed = false;
         this.writeChain = Promise.resolve();
         this._backend = null;
+        this._pendingWrites = 0;
+        this._needsDrain = false;
     }
     setBackend(backend) {
         this._backend = backend;
@@ -67,6 +78,7 @@ class AsyncStreamCodec extends EventEmitter {
         if (!backend) {
             throw new Error("Backend not initialized");
         }
+        this._pendingWrites++;
         const promise = this.writeChain.then(() => backend.write(chunk));
         this.writeChain = promise;
         promise
@@ -79,7 +91,20 @@ class AsyncStreamCodec extends EventEmitter {
             if (!this.destroyed) {
                 handleError(this, err, callback);
             }
+        })
+            .finally(() => {
+            this._pendingWrites--;
+            if (this._needsDrain &&
+                this._pendingWrites < AsyncStreamCodec.HIGH_WATER_MARK &&
+                !this.destroyed) {
+                this._needsDrain = false;
+                this.emit("drain");
+            }
         });
+        if (this._pendingWrites >= AsyncStreamCodec.HIGH_WATER_MARK) {
+            this._needsDrain = true;
+            return false;
+        }
         return true;
     }
     end(callback) {
@@ -106,6 +131,10 @@ class AsyncStreamCodec extends EventEmitter {
         }
     }
 }
+// Allow up to this many in-flight chunks before signalling backpressure.
+// 16 chunks × typical 64 KiB ≈ 1 MiB of in-flight retention, enough to
+// saturate the deflate backend without unbounded growth.
+AsyncStreamCodec.HIGH_WATER_MARK = 16;
 function createNativeWebStreamCodec(format, isCompress) {
     const stream = isCompress
         ? new CompressionStream(format)

package/dist/browser/modules/archive/compression/streaming-compress.js

@@ -10,6 +10,15 @@ import { Transform } from "../../stream/index.browser.js";
 /**
  * Generic wrapper around zlib streams that flushes after every write.
  * This ensures true streaming behavior - data is emitted immediately, not buffered.
+ *
+ * Backpressure note: the inner `zstream` (Node's `zlib.createDeflate*` etc)
+ * is itself a Transform, so its own `_transform` honours backpressure on
+ * the writer side. The `'data'` listener pushes into our own Transform's
+ * readable side; if a consumer is slow, our `push()` returns false but
+ * the inner zlib stream keeps emitting 'data' until its OWN HWM stops it.
+ * In the worst case, the zlib internal queue + our readable queue both
+ * fill to HWM (≈64 KiB total). For excelts's actual use (one zlib stream
+ * per ZIP entry, consumer is the zip framer which keeps up), this is fine.
  */
 class TrueStreamingZlib extends Transform {
     constructor(zstream) {

package/dist/browser/modules/archive/compression/worker-pool/pool.browser.js

@@ -498,9 +498,10 @@ export class WorkerPool {
      */
     _handleWorkerError(poolWorker, event) {
         const taskId = poolWorker.currentTaskId;
+        const session = poolWorker.streamSession;
         // Terminate the failed worker
         this._terminateWorker(poolWorker);
-        // Fail the current task if any
+        // Fail the current batch task if any
         if (taskId !== null) {
             const task = this._pendingTasks.get(taskId);
             if (task) {
@@ -510,6 +511,30 @@ export class WorkerPool {
                 task.reject(new Error(event.message || "Worker error"));
             }
         }
+        // CRITICAL: a worker hosting a streaming session can die from an
+        // uncaught error in the worker script, OOM, CSP violation, page
+        // unload, etc. The session is NOT in `_pendingTasks` (those are
+        // batch-only) — without this, the session's `resolveStart` /
+        // slot waiter / drain waiter / `onError` are never called and the
+        // caller (AsyncStreamCodec.write/end) hangs forever. Wake every
+        // promise we own and report the error to the codec.
+        if (session) {
+            const error = new Error(event.message || "Worker terminated unexpectedly");
+            session.ended = true;
+            session.rejectStart?.(error);
+            session.rejectStart = null;
+            session.resolveStart = null;
+            this._resolveSlotWaiter(session);
+            this._resolveDrainWaiter(session);
+            try {
+                session.onError(error);
+            }
+            catch {
+                // The onError callback is user-supplied; if it throws we still
+                // want to keep cleaning up the pool.
+            }
+            poolWorker.streamSession = null;
+        }
         // Try to process remaining tasks
         this._processQueue();
     }

package/dist/browser/modules/archive/fs/archive-file.d.ts

@@ -234,15 +234,18 @@ export declare class ArchiveFile<F extends ArchiveFormat = "zip"> {
      * archive.addFile("large-file.bin");
      * archive.addDirectory("./data");
      *
-     * // Stream to a file
+     * // Recommended: pipeTo() handles backpressure end-to-end.
+     * await archive.pipeTo(createWriteStream("output.zip"));
+     *
+     * // Or stream manually — REMEMBER to honor backpressure on the sink:
+     * import { once } from "node:events";
      * const writeStream = createWriteStream("output.zip");
      * for await (const chunk of archive.stream()) {
-     *   writeStream.write(chunk);
+     *   if (!writeStream.write(chunk)) {
+     *     await once(writeStream, "drain");
+     *   }
      * }
      * writeStream.end();
-     *
-     * // Or use pipeTo() for simpler file output
-     * await archive.pipeTo(createWriteStream("output.zip"));
      * ```
      */
     stream(options?: ArchiveStreamOptions): AsyncIterable<Uint8Array>;

package/dist/browser/modules/archive/fs/archive-file.js

@@ -1196,15 +1196,18 @@ export class ArchiveFile {
      * archive.addFile("large-file.bin");
      * archive.addDirectory("./data");
      *
-     * // Stream to a file
+     * // Recommended: pipeTo() handles backpressure end-to-end.
+     * await archive.pipeTo(createWriteStream("output.zip"));
+     *
+     * // Or stream manually — REMEMBER to honor backpressure on the sink:
+     * import { once } from "node:events";
      * const writeStream = createWriteStream("output.zip");
      * for await (const chunk of archive.stream()) {
-     *   writeStream.write(chunk);
+     *   if (!writeStream.write(chunk)) {
+     *     await once(writeStream, "drain");
+     *   }
      * }
      * writeStream.end();
-     *
-     * // Or use pipeTo() for simpler file output
-     * await archive.pipeTo(createWriteStream("output.zip"));
      * ```
      */
     stream(options = {}) {
@@ -2582,23 +2585,82 @@ export class ArchiveFile {
                     }
                     clearConsumedChunks();
                 }
+                // Eagerly attach an error listener so a mid-stream gzip failure is
+                // captured and surfaced (instead of becoming an uncaught exception
+                // when the listener-less Transform emits 'error' during our drain
+                // await below). Stored in a closure variable so the drain await can
+                // race against it.
+                let gzipError = null;
+                const onGzipError = (err) => {
+                    if (!gzipError) {
+                        gzipError = err;
+                    }
+                };
+                gzipStream.on("error", onGzipError);
                 // Collect gzip output
                 gzipStream.on("data", (chunk) => {
                     chunks.push(chunk);
                 });
-                // Pipe tar chunks through gzip
-                for await (const tarChunk of tarIterable) {
-                    gzipStream.write(tarChunk);
-                    // Yield any available gzip output
-                    for (const chunk of drainChunks()) {
-                        yield chunk;
+                try {
+                    // Pipe tar chunks through gzip. Honor `gzipStream.write()`'s
+                    // backpressure signal so the gzip Transform's internal buffer
+                    // can't grow unbounded if tar produces faster than gzip deflates.
+                    for await (const tarChunk of tarIterable) {
+                        if (gzipError) {
+                            // gzipError is captured as an Error (the closure annotation
+                            // says `Error | null`); rethrow rather than wrap to preserve
+                            // the original stack and message.
+                            // oxlint-disable-next-line no-throw-literal
+                            throw gzipError;
+                        }
+                        if (!gzipStream.write(tarChunk)) {
+                            // Race drain vs error so a mid-stream gzip failure rejects
+                            // promptly instead of leaving us parked on a 'drain' that
+                            // will never fire.
+                            await new Promise((resolve, reject) => {
+                                const cleanup = () => {
+                                    gzipStream.off("drain", onDrain);
+                                    gzipStream.off("error", onError);
+                                };
+                                const onDrain = () => {
+                                    cleanup();
+                                    resolve();
+                                };
+                                const onError = (err) => {
+                                    cleanup();
+                                    reject(err);
+                                };
+                                gzipStream.once("drain", onDrain);
+                                gzipStream.once("error", onError);
+                            });
+                        }
+                        // Yield any available gzip output
+                        for (const chunk of drainChunks()) {
+                            yield chunk;
+                        }
                     }
+                    // Finalize gzip stream — re-use the existing onGzipError listener
+                    // for the end() callback path, but wrap it as a Promise that
+                    // rejects on either error or accepts on end.
+                    await new Promise((resolve, reject) => {
+                        if (gzipError) {
+                            reject(gzipError);
+                            return;
+                        }
+                        const onEndError = (err) => {
+                            gzipStream.off("error", onEndError);
+                            reject(err);
+                        };
+                        gzipStream.once("error", onEndError);
+                        gzipStream.end(() => {
+                            gzipStream.off("error", onEndError);
+                            resolve();
+                        });
+                    });
+                }
+                finally {
+                    gzipStream.off("error", onGzipError);
                 }
-                // Finalize gzip stream
-                await new Promise((resolve, reject) => {
-                    gzipStream.on("error", reject);
-                    gzipStream.end(() => resolve());
-                });
                 // Yield remaining chunks
                 for (const chunk of drainChunks()) {
                     yield chunk;

package/dist/browser/modules/archive/unzip/stream.browser.js

@@ -49,6 +49,11 @@ class BrowserInflateRaw extends Duplex {
         this._bytesIn = 0;
         this._bytesOut = 0;
         this._readingDone = false;
+        // Backpressure: when `push()` returns false, the reader loop parks on this
+        // resolver. `_read()` (called by Node when the consumer wants more bytes)
+        // resolves it so the loop continues. Without this, a slow consumer would
+        // cause unbounded growth of the Duplex's internal readable buffer.
+        this._readPullResolver = null;
         // Track pending write count for proper ordering
         this._pendingWrites = 0;
         this._writeFinishedPromise = null;
@@ -106,6 +111,29 @@ class BrowserInflateRaw extends Duplex {
             }
         });
     }
+    /**
+     * Park the reader loop until the consumer pulls more data. Resolved by
+     * the next `_read()` invocation from Node, which signals that the
+     * Duplex's readable buffer has room again.
+     */
+    _waitForReadablePull() {
+        if (this._readPullResolver) {
+            // Should not happen — only one push site at a time.
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            this._readPullResolver = resolve;
+        });
+    }
+    _read(_size) {
+        // Consumer wants more bytes. Wake the reader loop if it parked on
+        // backpressure.
+        const resolver = this._readPullResolver;
+        if (resolver) {
+            this._readPullResolver = null;
+            resolver();
+        }
+    }
     async _startReading() {
         if (this.reading) {
             return;
@@ -118,8 +146,14 @@ class BrowserInflateRaw extends Duplex {
                     break;
                 }
                 this._bytesOut += value.length;
-                // Directly push to the readable side of Duplex
-                this.push(value);
+                // Push to the Duplex's readable side. If the consumer is slow,
+                // `push()` returns false; pause our reader-loop until the consumer
+                // pulls. Without this, a fast WebStream decompressor could overrun
+                // the Duplex's readable buffer and accumulate megabytes of
+                // decompressed data with no consumer.
+                if (!this.push(value)) {
+                    await this._waitForReadablePull();
+                }
             }
         }
         catch (e) {
@@ -177,6 +211,13 @@ class BrowserInflateRaw extends Duplex {
             this.writer.abort(error ?? undefined).catch(() => { });
         }
         this.reader.cancel(error ?? undefined).catch(() => { });
+        // Wake the reader-loop's backpressure waiter if any so `_startReading()`
+        // can unwind cleanly instead of hanging on a never-resolved promise.
+        const resolver = this._readPullResolver;
+        if (resolver) {
+            this._readPullResolver = null;
+            resolver();
+        }
         return super.destroy(error ?? undefined);
     }
 }

package/dist/browser/modules/excel/chart/chart-ex-builder.js

@@ -779,8 +779,13 @@ function validateChartExOptions(opts) {
         validateBinning(binning);
     }
     opts.series.forEach((series, i) => {
-        if (!series.values) {
-            throw new ChartOptionsError(`chartEx.series[${i}].values is required.`);
+        // A series must reference its data either via a worksheet formula
+        // (`values`) or via cached literal values (`literalValues`). Headless
+        // chart pipelines (e.g. the Word `buildWordChartExXml` bridge) ship
+        // only `literalValues` because there is no underlying worksheet to
+        // reference.
+        if (!series.values && !series.literalValues?.length) {
+            throw new ChartOptionsError(`chartEx.series[${i}].values or literalValues is required.`);
         }
         if (series.literalValues?.some(value => !Number.isFinite(value))) {
             throw new ChartOptionsError(`chartEx.series[${i}].literalValues must contain only finite numbers.`);

package/dist/browser/modules/excel/chart/chart-ex-renderer.js

@@ -3549,11 +3549,8 @@ function consolidateDataForRender(space) {
 function renderChartData(data) {
     const parts = [];
     parts.push("  <cx:chartData>");
-    // NOTE: `cx:externalData` used to be emitted here, but it is a
-    // child of `cx:chartSpace` (not `cx:chartData`) per the Chart2014
-    // schema. The writer now emits it at the chartSpace level; the
-    // deprecated `data.externalData` slot is ignored here so a
-    // legacy round-trip cannot double-emit it.
+    // `cx:externalData` is a child of `cx:chartSpace`, not `cx:chartData`,
+    // per the Chart2014 schema — emitted by the chartSpace renderer.
     for (const entry of data.data) {
         parts.push(renderDataEntry(entry));
     }
@@ -3769,10 +3766,8 @@ function renderChart(chart) {
     if (chart.legend) {
         parts.push(renderLegend(chart.legend));
     }
-    // CT_Chart does NOT carry `spPr` in the ECMA-376 / Chart2014 schema
-    // — chart-frame styling lives on `CT_ChartSpace`. `chart.spPr` is a
-    // legacy type field kept for backward compat (see the @deprecated
-    // note on `ChartExChart.spPr`); do not emit it to avoid invalid XML.
+    // `CT_Chart` carries no `spPr` per the Chart2014 schema — chart-frame
+    // styling lives on `CT_ChartSpace`, emitted by the chartSpace renderer.
     if (chart.extLst) {
         parts.push(`    ${chart.extLst}`);
     }

package/dist/browser/modules/excel/chart/chart-ex-types.d.ts

@@ -89,18 +89,6 @@ export interface ChartExSpace {
     extLst?: string;
 }
 export interface ChartExData {
-    /**
-     * @deprecated Moved to {@link ChartExSpace.externalData} to match
-     * the Chart2014 schema (`cx:externalData` is a child of
-     * `cx:chartSpace`, not `cx:chartData`). The parser migrates legacy
-     * on-disk placements into `ChartExSpace.externalData`; this field
-     * remains on the type only to avoid breaking callers that read it
-     * directly. Write-side code no longer consults this slot.
-     */
-    externalData?: Array<{
-        id: string;
-        autoUpdate?: boolean;
-    }>;
     /** Chart data (numeric/string arrays referenced by series) */
     data: ChartExDataEntry[];
 }

package/dist/browser/modules/excel/chart/chart.d.ts

@@ -129,7 +129,7 @@ interface ChartAnchorRange {
  *   `toPNG`, `unknownElements`) work uniformly. ChartTypeGroup-level
  *   APIs (`chartTypes`, `axes`, `plotArea`, `getAxis`, `categoryAxis`,
  *   `valueAxis`, `addSeries`, `removeSeries`, `getSeries`,
- *   `updateSeries`, `addSeriesFromOptions`, `seriesCount`, `mutate`,
+ *   `updateSeries`, `addSeriesFromOptions`, `getSeriesCount`, `mutate`,
  *   `setStyle`) are classic-only — ChartEx has its own topology that
  *   doesn't map cleanly onto the classic group/series abstraction;
  *   use {@link Chart.mutateChartEx} for ChartEx mutations.
@@ -393,10 +393,6 @@ declare class Chart {
      * @param groupIndex - 0-based index of the chart type group (defaults to 0).
      */
     getSeriesCount(groupIndex?: number): number;
-    /**
-     * @deprecated Use `getSeriesCount()` instead. Returns the count of series in the first chart type group.
-     */
-    get seriesCount(): number;
     /**
      * Create a deep copy of this chart and add it to a target worksheet.
      * The new chart receives a fresh chartNumber; the original is untouched.

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

@@ -55,7 +55,7 @@ const RAW_TX_CV_RE = /<c:v(?:\s[^>]*)?>([\s\S]*?)<\/c:v>/g;
  *   `toPNG`, `unknownElements`) work uniformly. ChartTypeGroup-level
  *   APIs (`chartTypes`, `axes`, `plotArea`, `getAxis`, `categoryAxis`,
  *   `valueAxis`, `addSeries`, `removeSeries`, `getSeries`,
- *   `updateSeries`, `addSeriesFromOptions`, `seriesCount`, `mutate`,
+ *   `updateSeries`, `addSeriesFromOptions`, `getSeriesCount`, `mutate`,
  *   `setStyle`) are classic-only — ChartEx has its own topology that
  *   doesn't map cleanly onto the classic group/series abstraction;
  *   use {@link Chart.mutateChartEx} for ChartEx mutations.
@@ -878,12 +878,6 @@ class Chart {
         const ctg = this.chartTypes[groupIndex];
         return ctg?.series?.length ?? 0;
     }
-    /**
-     * @deprecated Use `getSeriesCount()` instead. Returns the count of series in the first chart type group.
-     */
-    get seriesCount() {
-        return this.getSeriesCount(0);
-    }
     // ===========================================================================
     // Chart cloning and duplication
     // ===========================================================================

package/dist/browser/modules/excel/chart/types.d.ts

@@ -1501,12 +1501,6 @@ export interface PivotFormat {
      * label styling without dropping into raw XML.
      */
     dLbl?: DataLabelEntry;
-    /**
-     * @deprecated Use {@link dLbl} for structured access. Retained so
-     * files parsed before the structured slot landed continue to
-     * round-trip. Writers prefer `dLbl` when both are present.
-     */
-    rawDLbl?: string;
     /** Extension list (raw XML for round-trip). */
     extLst?: string;
 }

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

@@ -500,7 +500,31 @@ export class WorkbookReaderBase extends EventEmitter {
     }
     async *_parseEntries(stream) {
         const zip = createParse({ forceStream: true });
-        stream.on("error", (err) => zip.emit("error", err));
+        // Bidirectional error propagation, guarded against re-entry: each side
+        // marks itself "settled" before forwarding so the partner's destroy/emit
+        // doesn't bounce the error back into an infinite loop.
+        let propagating = false;
+        stream.on("error", (err) => {
+            if (propagating) {
+                return;
+            }
+            propagating = true;
+            zip.emit("error", err);
+        });
+        zip.on("error", (err) => {
+            if (propagating) {
+                return;
+            }
+            propagating = true;
+            try {
+                if (typeof stream.destroy === "function") {
+                    stream.destroy(err);
+                }
+            }
+            catch {
+                // Best-effort cleanup; original error already on `zip`.
+            }
+        });
         stream.pipe(zip);
         for await (const entry of iterateStream(zip)) {
             let sheetNo;

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

@@ -48,6 +48,15 @@ class WorkbookReader extends WorkbookReaderBase {
                 return originalWrite(chunk, ...args);
             };
             tempStream.write = trackWrite;
+            // Forward source errors to the temp file stream so:
+            //   - the file write doesn't silently leak when zip parsing fails
+            //   - `writePromise` rejects with the original cause instead of hanging
+            // Without this, an `error` on `entry` (e.g. zip corruption / decryption
+            // failure) becomes an uncaught exception in Node ≥ 16.
+            entry.on("error", err => {
+                tempStream.destroy(err);
+                reject(err);
+            });
             entry.pipe(tempStream);
         });
         return { sheetNo, path: filePath, cleanup, writePromise };

package/dist/browser/modules/excel/stream/workbook-writer.browser.d.ts

@@ -67,6 +67,7 @@ interface OutputStreamLike {
     end(): void;
     once(eventName: string | symbol, listener: (...args: any[]) => void): this;
     removeListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    on?(eventName: string | symbol, listener: (...args: any[]) => void): this;
 }
 export interface WorksheetWriterLike {
     id: number;
@@ -130,11 +131,50 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
     promise: Promise<void[] | void>;
     protected _trueStreaming: boolean;
     protected WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>;
+    private _needsDrain;
+    private _drainResolvers;
+    private _drainListenerAttached;
+    private _sinkError;
     constructor(options: WorkbookWriterOptions, WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>);
     /**
      * Create output stream - can be overridden by Node.js to support filename
      */
     protected _createOutputStream(options: WorkbookWriterOptions): OutputStreamLike;
+    /**
+     * 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.
+     */
+    private _trackBackpressure;
+    private _ensureDrainListener;
+    /**
+     * 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.
+     */
+    private _lifecycleListenersAttached;
+    private _attachSinkLifecycleListeners;
+    private _wakeAllBackpressureWaiters;
+    /**
+     * 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.
+     */
+    private _waitForUserSinkDrain;
     get definedNames(): DefinedNames;
     /**
      * The default font for the workbook (fontId=0 / "Normal" style).