@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/stream/internal/sink-adapter.js

@@ -0,0 +1,198 @@
+/**
+ * SinkAdapter — unified writable-sink view.
+ *
+ * Producers (zip writers, docx streamers, etc.) generate `Uint8Array`
+ * chunks and want to push them through a user-supplied destination
+ * without caring whether that destination is a Web `WritableStream`,
+ * a Node `Writable`, or some duck-typed object.
+ *
+ * `SinkAdapter` collapses all three into one promise-based API:
+ *   - `write(chunk)` resolves once the chunk has been accepted by the
+ *     sink (after awaiting `drain` for Node-style sinks under
+ *     backpressure, or `writer.ready` for Web streams).
+ *   - `end()` finalises the sink and resolves on close.
+ *   - The first sink error is captured and re-thrown from the next
+ *     `write` / `end` so callers can't lose it.
+ *
+ * Producers are expected to either:
+ *   - drive `await sink.write(chunk)` directly (preferred — gives
+ *     true end-to-end backpressure), or
+ *   - chain writes onto a single shared promise so a synchronous
+ *     emit callback can still feed the adapter without blocking.
+ */
+import { onceEvent } from "./event-utils.js";
+function isWebWritable(s) {
+    return (typeof s === "object" &&
+        s !== null &&
+        typeof s.getWriter === "function");
+}
+function isNodeWritable(s) {
+    return (typeof s === "object" &&
+        s !== null &&
+        typeof s.write === "function" &&
+        typeof s.end === "function" &&
+        (typeof s.once === "function" ||
+            typeof s.on === "function"));
+}
+/** Unified sink view with awaited write + error capture. */
+export class SinkAdapter {
+    constructor(sink) {
+        this._error = null;
+        this._ended = false;
+        if (isWebWritable(sink)) {
+            this._kind = "web";
+            this._webWriter = sink.getWriter();
+            // Web writers expose .closed; surface termination errors through
+            // the same _error channel so producers see them.
+            this._webWriter.closed.catch((err) => {
+                this._captureError(err);
+            });
+        }
+        else if (isNodeWritable(sink)) {
+            this._kind = "node";
+            this._nodeSink = sink;
+            this._attachErrorListener(sink);
+        }
+        else {
+            this._kind = "duck";
+            this._duckSink = sink;
+            this._attachErrorListener(sink);
+        }
+    }
+    /**
+     * The first error reported by the sink (or `null`). Producers that
+     * cannot await `write()` (synchronous emit callbacks) should poll
+     * this between operations.
+     */
+    get error() {
+        return this._error;
+    }
+    async write(chunk) {
+        this._throwIfErrored();
+        if (this._ended) {
+            throw new Error("SinkAdapter: write after end");
+        }
+        if (chunk.length === 0) {
+            return;
+        }
+        if (this._kind === "web") {
+            const w = this._webWriter;
+            // `ready` resolves once the internal queue has drained below the
+            // high-water mark; awaiting it gives backpressure for free.
+            await w.ready;
+            await w.write(chunk);
+            return;
+        }
+        if (this._kind === "node") {
+            const sink = this._nodeSink;
+            const ok = sink.write(chunk);
+            if (!ok) {
+                await onceEvent(sink, "drain");
+                this._throwIfErrored();
+            }
+            return;
+        }
+        // duck
+        const sink = this._duckSink;
+        const result = sink.write(chunk);
+        if (result instanceof Promise) {
+            await result;
+        }
+        else if (!result) {
+            await onceEvent(sink, "drain");
+            this._throwIfErrored();
+        }
+    }
+    async end() {
+        if (this._ended) {
+            return;
+        }
+        this._ended = true;
+        this._throwIfErrored();
+        if (this._kind === "web") {
+            // close() rejects if the stream has already errored — we let that
+            // propagate so callers see the underlying failure.
+            await this._webWriter.close();
+            return;
+        }
+        if (this._kind === "node") {
+            const sink = this._nodeSink;
+            // Prefer the close event when available; some Node writables emit
+            // 'finish' first and only emit 'close' on `destroy()`. We listen
+            // for both.
+            const finished = onceEventAny(sink, ["close", "finish"]);
+            sink.end();
+            await finished;
+            this._throwIfErrored();
+            return;
+        }
+        // duck
+        const sink = this._duckSink;
+        const finished = onceEventAny(sink, ["close", "finish"]);
+        sink.end();
+        await finished;
+        this._throwIfErrored();
+    }
+    _captureError(err) {
+        if (this._error) {
+            return;
+        }
+        this._error = err instanceof Error ? err : new Error(String(err));
+    }
+    _throwIfErrored() {
+        if (this._error) {
+            throw this._error;
+        }
+    }
+    _attachErrorListener(sink) {
+        if (typeof sink.on === "function") {
+            sink.on("error", (err) => {
+                this._captureError(err);
+            });
+        }
+        else if (typeof sink.once === "function") {
+            // Best-effort: a once listener is enough to capture the first error.
+            sink.once("error", (err) => {
+                this._captureError(err);
+            });
+        }
+    }
+}
+/** Resolve on the first of `events` (or reject on `error`). */
+function onceEventAny(emitter, events) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            const off = (e, l) => {
+                if (typeof emitter.off === "function") {
+                    emitter.off(e, l);
+                }
+                else if (typeof emitter.removeListener === "function") {
+                    emitter.removeListener(e, l);
+                }
+            };
+            off("error", onError);
+            for (const e of events) {
+                off(e, onDone);
+            }
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        const onDone = () => {
+            cleanup();
+            resolve();
+        };
+        if (typeof emitter.once === "function") {
+            emitter.once("error", onError);
+            for (const e of events) {
+                emitter.once(e, onDone);
+            }
+            return;
+        }
+        emitter.on?.("error", onError);
+        for (const e of events) {
+            emitter.on?.(e, onDone);
+        }
+    });
+}

package/dist/browser/modules/stream/pull-stream.d.ts

@@ -17,15 +17,32 @@ export declare class PullStream extends EventEmitter {
     protected finished: boolean;
     protected _match?: number;
     private _destroyed;
-    constructor(_options?: PullStreamOptions);
+    private _highWaterMark;
+    private _needsDrain;
+    constructor(options?: PullStreamOptions);
     /** Reset the internal buffer to empty. */
     private _resetBuffer;
     protected get buffer(): Uint8Array;
     protected set buffer(buf: Uint8Array);
     /**
-     * Write data to the stream
+     * Write data to the stream.
+     *
+     * Returns `false` when the buffer's readable size exceeds `highWaterMark`
+     * (backpressure signal). Producers should pause and resume on the next
+     * `'drain'` event.
      */
     write(chunk: Uint8Array): boolean;
+    /**
+     * Set `_needsDrain` based on current buffer size, return whether the
+     * producer should keep writing (true) or pause (false).
+     */
+    private _evaluateBackpressure;
+    /**
+     * Internal: subclasses or pull paths must call this after consuming bytes
+     * (advancing `_bufferReadIndex`) to potentially emit `'drain'`. Idempotent
+     * and free when no backpressure is in effect.
+     */
+    protected _maybeEmitDrain(): void;
     /**
      * Signal end of input
      */

package/dist/browser/modules/stream/pull-stream.js

@@ -11,7 +11,7 @@ const EMPTY_U8 = new Uint8Array(0);
  * Browser-compatible Pull Stream - Read data from buffer on demand with pattern matching
  */
 export class PullStream extends EventEmitter {
-    constructor(_options = {}) {
+    constructor(options = {}) {
         super();
         // Single growable buffer with read/write cursors.
         // IMPORTANT: never mutate bytes that have already been returned via subarray
@@ -22,6 +22,18 @@ export class PullStream extends EventEmitter {
         this._bufferWriteIndex = 0;
         this.finished = false;
         this._destroyed = false;
+        // Backpressure: when buffer length exceeds highWaterMark, `write()` returns
+        // false so producers know to slow down. `'drain'` fires once the buffer
+        // drops below half the HWM (low-water mark). Defaults to Infinity for
+        // backward compatibility — callers that opt in by passing `highWaterMark`
+        // get bounded memory, callers that don't keep the legacy unbounded behaviour.
+        this._highWaterMark = Infinity;
+        this._needsDrain = false;
+        if (options.highWaterMark !== undefined &&
+            options.highWaterMark > 0 &&
+            Number.isFinite(options.highWaterMark)) {
+            this._highWaterMark = options.highWaterMark;
+        }
     }
     /** Reset the internal buffer to empty. */
     _resetBuffer() {
@@ -47,7 +59,11 @@ export class PullStream extends EventEmitter {
         this._bufferWriteIndex = buf.length;
     }
     /**
-     * Write data to the stream
+     * Write data to the stream.
+     *
+     * Returns `false` when the buffer's readable size exceeds `highWaterMark`
+     * (backpressure signal). Producers should pause and resume on the next
+     * `'drain'` event.
      */
     write(chunk) {
         if (this._destroyed) {
@@ -57,7 +73,7 @@ export class PullStream extends EventEmitter {
         const chunkLen = chunk.length;
         if (chunkLen === 0) {
             this.emit("chunk");
-            return true;
+            return !this._needsDrain;
         }
         // Fast path: first write can reuse caller buffer without copy.
         if (this._buffer.length === 0) {
@@ -65,14 +81,14 @@ export class PullStream extends EventEmitter {
             this._bufferReadIndex = 0;
             this._bufferWriteIndex = chunkLen;
             this.emit("chunk");
-            return true;
+            return this._evaluateBackpressure();
         }
         const required = this._bufferWriteIndex + chunkLen;
         if (required <= this._buffer.length) {
             this._buffer.set(chunk, this._bufferWriteIndex);
             this._bufferWriteIndex += chunkLen;
             this.emit("chunk");
-            return true;
+            return this._evaluateBackpressure();
         }
         // Need a new buffer. We keep previously returned views stable by allocating.
         const remaining = this._bufferWriteIndex - this._bufferReadIndex;
@@ -87,8 +103,36 @@ export class PullStream extends EventEmitter {
         this._bufferReadIndex = 0;
         this._bufferWriteIndex = nextLength;
         this.emit("chunk");
+        return this._evaluateBackpressure();
+    }
+    /**
+     * Set `_needsDrain` based on current buffer size, return whether the
+     * producer should keep writing (true) or pause (false).
+     */
+    _evaluateBackpressure() {
+        const readable = this._bufferWriteIndex - this._bufferReadIndex;
+        if (readable >= this._highWaterMark) {
+            this._needsDrain = true;
+            return false;
+        }
         return true;
     }
+    /**
+     * Internal: subclasses or pull paths must call this after consuming bytes
+     * (advancing `_bufferReadIndex`) to potentially emit `'drain'`. Idempotent
+     * and free when no backpressure is in effect.
+     */
+    _maybeEmitDrain() {
+        if (!this._needsDrain) {
+            return;
+        }
+        const readable = this._bufferWriteIndex - this._bufferReadIndex;
+        // Low-water mark = half of HWM (classic Node Writable behaviour).
+        if (readable * 2 < this._highWaterMark) {
+            this._needsDrain = false;
+            this.emit("drain");
+        }
+    }
     /**
      * Signal end of input
      */
@@ -156,6 +200,7 @@ export class PullStream extends EventEmitter {
                     if (this._bufferReadIndex === this._bufferWriteIndex) {
                         this._resetBuffer();
                     }
+                    this._maybeEmitDrain();
                     resolve(result);
                     return;
                 }
@@ -202,6 +247,7 @@ export class PullStream extends EventEmitter {
                     if (this._bufferReadIndex === this._bufferWriteIndex) {
                         this._resetBuffer();
                     }
+                    this._maybeEmitDrain();
                     resolve(result);
                     return;
                 }

package/dist/browser/modules/stream/types.d.ts

@@ -157,7 +157,19 @@ export interface IDuplex<TRead = any, TWrite = any> extends IReadable<TRead>, IW
 /**
  * Options for pull stream (reserved for future use)
  */
-export type PullStreamOptions = object;
+export type PullStreamOptions = {
+    /**
+     * Buffer high-water mark in bytes. When the readable buffer exceeds this
+     * size, `write()` returns `false` to signal backpressure to the producer.
+     * Once the buffer drops back to the low-water mark (half the HWM), a
+     * `'drain'` event is emitted. Defaults to `Infinity` (no backpressure).
+     *
+     * Set this when the stream is fed by a fast producer with a slow `pull()`
+     * consumer to keep memory bounded — the legacy default of `Infinity`
+     * preserves existing behaviour for callers that drain promptly.
+     */
+    highWaterMark?: number;
+};
 /**
  * Pull stream interface - allows pulling data on demand
  */

package/dist/browser/modules/word/advanced/diff.d.ts

@@ -0,0 +1,61 @@
+/**
+ * DOCX Module - Document Comparison (Diff)
+ *
+ * Compares two DocxDocument models and returns a list of differences.
+ * This is a text-level comparison — it compares paragraphs by their text content
+ * and reports additions, deletions, and modifications.
+ *
+ * @example
+ * ```ts
+ * import { diffDocuments } from "excelts/word";
+ *
+ * const changes = diffDocuments(oldDoc, newDoc);
+ * console.log(changes.filter(c => c.type === "modified"));
+ * ```
+ */
+import type { DocxDocument } from "../types.js";
+/** Type of change detected between two documents. */
+export type DiffChangeType = "added" | "deleted" | "modified" | "unchanged";
+/** A single diff entry representing a change between two documents. */
+export interface DiffEntry {
+    /** Type of change. */
+    readonly type: DiffChangeType;
+    /** Paragraph index in the old document (undefined for "added"). */
+    readonly oldIndex?: number;
+    /** Paragraph index in the new document (undefined for "deleted"). */
+    readonly newIndex?: number;
+    /** Text content from old document. */
+    readonly oldText?: string;
+    /** Text content from new document. */
+    readonly newText?: string;
+}
+/** Summary statistics for a diff result. */
+export interface DiffSummary {
+    /** Total number of paragraphs compared. */
+    readonly totalParagraphs: number;
+    /** Number of unchanged paragraphs. */
+    readonly unchanged: number;
+    /** Number of added paragraphs. */
+    readonly added: number;
+    /** Number of deleted paragraphs. */
+    readonly deleted: number;
+    /** Number of modified paragraphs. */
+    readonly modified: number;
+}
+/** Result of a document comparison. */
+export interface DiffResult {
+    /** Individual change entries. */
+    readonly entries: readonly DiffEntry[];
+    /** Summary statistics. */
+    readonly summary: DiffSummary;
+}
+/**
+ * Compare two DocxDocuments and return a diff of their text content.
+ *
+ * Uses the Myers diff algorithm (LCS-based) for optimal minimal edit sequence.
+ *
+ * @param oldDoc - The original document.
+ * @param newDoc - The modified document.
+ * @returns DiffResult with entries and summary.
+ */
+export declare function diffDocuments(oldDoc: DocxDocument, newDoc: DocxDocument): DiffResult;

package/dist/browser/modules/word/advanced/diff.js

@@ -0,0 +1,167 @@
+/**
+ * DOCX Module - Document Comparison (Diff)
+ *
+ * Compares two DocxDocument models and returns a list of differences.
+ * This is a text-level comparison — it compares paragraphs by their text content
+ * and reports additions, deletions, and modifications.
+ *
+ * @example
+ * ```ts
+ * import { diffDocuments } from "excelts/word";
+ *
+ * const changes = diffDocuments(oldDoc, newDoc);
+ * console.log(changes.filter(c => c.type === "modified"));
+ * ```
+ */
+import { extractParagraphText } from "../core/text-utils.js";
+import { walkBlocks } from "../core/walker.js";
+/**
+ * Compare two DocxDocuments and return a diff of their text content.
+ *
+ * Uses the Myers diff algorithm (LCS-based) for optimal minimal edit sequence.
+ *
+ * @param oldDoc - The original document.
+ * @param newDoc - The modified document.
+ * @returns DiffResult with entries and summary.
+ */
+export function diffDocuments(oldDoc, newDoc) {
+    const oldTexts = extractParagraphTexts(oldDoc.body);
+    const newTexts = extractParagraphTexts(newDoc.body);
+    const entries = computeDiff(oldTexts, newTexts);
+    let added = 0;
+    let deleted = 0;
+    let modified = 0;
+    let unchanged = 0;
+    for (const e of entries) {
+        switch (e.type) {
+            case "added":
+                added++;
+                break;
+            case "deleted":
+                deleted++;
+                break;
+            case "modified":
+                modified++;
+                break;
+            case "unchanged":
+                unchanged++;
+                break;
+        }
+    }
+    return {
+        entries,
+        summary: {
+            totalParagraphs: Math.max(oldTexts.length, newTexts.length),
+            unchanged,
+            added,
+            deleted,
+            modified
+        }
+    };
+}
+/** Extract all paragraph texts from body content (flattens tables). */
+function extractParagraphTexts(body) {
+    const texts = [];
+    walkBlocks(body, {
+        enterParagraph(para) {
+            texts.push(extractParagraphText(para));
+            return "skip";
+        }
+    });
+    return texts;
+}
+/**
+ * Compute diff using LCS (Longest Common Subsequence) approach.
+ * Produces an optimal edit sequence.
+ *
+ * Memory note: the LCS DP table is `(m+1) * (n+1)` cells, each a 32-bit
+ * integer. We allocate it as a single `Uint32Array` so two 5000-paragraph
+ * documents take ~100 MB instead of ~200 MB. We also reject pairs whose
+ * product would exceed `MAX_LCS_CELLS` to avoid OOM-killing the host —
+ * callers wanting to diff arbitrarily-large documents should pre-segment
+ * by section.
+ */
+const MAX_LCS_CELLS = 32000000; // ~128 MB at 4 bytes/cell
+function computeDiff(oldTexts, newTexts) {
+    const m = oldTexts.length;
+    const n = newTexts.length;
+    if ((m + 1) * (n + 1) > MAX_LCS_CELLS) {
+        throw new Error(`diffDocuments: LCS table for ${m}x${n} paragraphs exceeds ` +
+            `MAX_LCS_CELLS (${MAX_LCS_CELLS}). Diff was aborted to avoid ` +
+            `excessive memory use; consider diffing sections individually.`);
+    }
+    // Single contiguous Uint32Array indexed as `i * (n+1) + j`. This keeps
+    // memory at one allocation and lets the runtime use SIMD-friendly
+    // contiguous reads in the hot loop below.
+    const stride = n + 1;
+    const dp = new Uint32Array((m + 1) * stride);
+    for (let i = 1; i <= m; i++) {
+        const rowBase = i * stride;
+        const prevRowBase = (i - 1) * stride;
+        for (let j = 1; j <= n; j++) {
+            if (oldTexts[i - 1] === newTexts[j - 1]) {
+                dp[rowBase + j] = dp[prevRowBase + (j - 1)] + 1;
+            }
+            else {
+                const a = dp[prevRowBase + j];
+                const b = dp[rowBase + (j - 1)];
+                dp[rowBase + j] = a >= b ? a : b;
+            }
+        }
+    }
+    // Backtrack to produce diff entries
+    const entries = [];
+    let i = m;
+    let j = n;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && oldTexts[i - 1] === newTexts[j - 1]) {
+            entries.push({
+                type: "unchanged",
+                oldIndex: i - 1,
+                newIndex: j - 1,
+                oldText: oldTexts[i - 1],
+                newText: newTexts[j - 1]
+            });
+            i--;
+            j--;
+        }
+        else if (i > 0 && (j === 0 || dp[(i - 1) * stride + j] >= dp[i * stride + (j - 1)])) {
+            entries.push({
+                type: "deleted",
+                oldIndex: i - 1,
+                oldText: oldTexts[i - 1]
+            });
+            i--;
+        }
+        else {
+            entries.push({
+                type: "added",
+                newIndex: j - 1,
+                newText: newTexts[j - 1]
+            });
+            j--;
+        }
+    }
+    // Reverse since we built it backwards
+    entries.reverse();
+    // Post-process: pair adjacent delete+add as "modified" when they're at the same position
+    const result = [];
+    for (let k = 0; k < entries.length; k++) {
+        const curr = entries[k];
+        const next = k + 1 < entries.length ? entries[k + 1] : undefined;
+        if (curr.type === "deleted" && next?.type === "added") {
+            result.push({
+                type: "modified",
+                oldIndex: curr.oldIndex,
+                newIndex: next.newIndex,
+                oldText: curr.oldText,
+                newText: next.newText
+            });
+            k++; // skip next
+        }
+        else {
+            result.push(curr);
+        }
+    }
+    return result;
+}