@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/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/esm/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;
+}

package/dist/esm/modules/word/advanced/drawing-shapes.js

@@ -0,0 +1,268 @@
+/**
+ * DOCX Module - Enhanced DrawingML Shape Builder
+ *
+ * Provides a comprehensive API for creating DrawingML shapes beyond the
+ * basic shape type. Includes support for:
+ * - All 187 preset geometry types
+ * - Gradient and pattern fills
+ * - Shadow, glow, reflection effects
+ * - 3D rotation and bevel
+ * - Shape connectors and groups
+ * - Custom geometry paths
+ * - Text body formatting within shapes
+ */
+import { xmlEncodeAttr } from "../../xml/encode.js";
+// =============================================================================
+// Shape Builder Functions
+// =============================================================================
+/**
+ * Create an enhanced DrawingML shape with full styling options.
+ *
+ * Basic properties (solid fill, outline color/width, text paragraphs, positioning)
+ * are mapped directly to the `DrawingShape` interface fields. Advanced properties
+ * (gradient/pattern fills, effects, line details, text body formatting) are
+ * serialized into the `rawXml` field for preservation during packaging.
+ *
+ * @param options - Complete shape creation options.
+ * @returns A DrawingShape element for the document body.
+ */
+export function createShape(options) {
+    // Convert fill to simple properties for the DrawingShape interface
+    let fillColor;
+    let noFill = false;
+    if (options.fill) {
+        if (options.fill.type === "solid") {
+            fillColor = options.fill.color;
+        }
+        else if (options.fill.type === "none") {
+            noFill = true;
+        }
+    }
+    let outlineColor;
+    let outlineWidth;
+    let noOutline = false;
+    if (options.outline) {
+        outlineColor = options.outline.color;
+        outlineWidth = options.outline.width;
+        noOutline = options.outline.noLine ?? false;
+    }
+    // Serialize advanced properties that DrawingShape can't represent directly.
+    // The writer needs them split because the OOXML schema requires fill
+    // fragments to precede a:ln while effect/3D fragments must follow it.
+    const advanced = serializeAdvancedProperties(options);
+    const rawXml = (advanced.fillXml ?? "") + (advanced.effectsXml ?? "");
+    return {
+        type: "drawingShape",
+        shapeType: options.shapeType,
+        width: options.width,
+        height: options.height,
+        fillColor,
+        noFill,
+        outlineColor,
+        outlineWidth,
+        noOutline,
+        textContent: options.textBody?.paragraphs,
+        altText: options.altText,
+        name: options.name,
+        horizontalPosition: options.horizontalPosition,
+        verticalPosition: options.verticalPosition,
+        wrap: options.wrap,
+        behindDoc: options.behindDoc,
+        rotation: options.rotation,
+        rawXml: rawXml.length > 0 ? rawXml : undefined,
+        _advancedFillXml: advanced.fillXml,
+        _advancedEffectsXml: advanced.effectsXml
+    };
+}
+/**
+ * Serialize advanced shape properties into XML fragments suitable for
+ * insertion inside `wps:spPr`. Returns them split into the two slots the
+ * OOXML schema cares about:
+ *  - `fillXml` is inserted between `a:prstGeom` and `a:ln`
+ *  - `effectsXml` is inserted after `a:ln` (effectLst → scene3d → sp3d)
+ */
+function serializeAdvancedProperties(options) {
+    const fillParts = [];
+    const effectParts = [];
+    // Gradient fill
+    if (options.fill && options.fill.type === "gradient") {
+        const gf = options.fill;
+        const stops = gf.stops
+            .map(s => `<a:gs pos="${s.position}"><a:srgbClr val="${xmlEncodeAttr(s.color)}"${s.transparency ? ` alpha="${Math.round((100 - s.transparency) * 1000)}"` : ""}/></a:gs>`)
+            .join("");
+        const angle = gf.angle !== undefined ? ` ang="${gf.angle}"` : "";
+        fillParts.push(`<a:gradFill><a:gsLst>${stops}</a:gsLst><a:lin${angle} scaled="1"/></a:gradFill>`);
+    }
+    // Pattern fill
+    if (options.fill && options.fill.type === "pattern") {
+        const pf = options.fill;
+        fillParts.push(`<a:pattFill prst="${xmlEncodeAttr(pf.preset)}"><a:fgClr><a:srgbClr val="${xmlEncodeAttr(pf.foregroundColor)}"/></a:fgClr><a:bgClr><a:srgbClr val="${xmlEncodeAttr(pf.backgroundColor)}"/></a:bgClr></a:pattFill>`);
+    }
+    // Effects: shadow / glow / reflection / softEdges must live inside
+    // <a:effectLst>. Collect all of them then emit a single wrapper.
+    const effectChildren = [];
+    if (options.effects?.shadow) {
+        const s = options.effects.shadow;
+        const attrs = [];
+        if (s.blurRadius) {
+            attrs.push(`blurRad="${s.blurRadius}"`);
+        }
+        if (s.distance) {
+            attrs.push(`dist="${s.distance}"`);
+        }
+        if (s.direction !== undefined) {
+            attrs.push(`dir="${s.direction}"`);
+        }
+        const alpha = s.transparency !== undefined
+            ? ` <a:alpha val="${Math.round((100 - s.transparency) * 1000)}"/>`
+            : "";
+        const tag = s.type === "inner" ? "a:innerShdw" : "a:outerShdw";
+        effectChildren.push(`<${tag} ${attrs.join(" ")}><a:srgbClr val="${xmlEncodeAttr(s.color)}">${alpha}</a:srgbClr></${tag}>`);
+    }
+    if (options.effects?.glow) {
+        const g = options.effects.glow;
+        const alpha = g.transparency !== undefined
+            ? `<a:alpha val="${Math.round((100 - g.transparency) * 1000)}"/>`
+            : "";
+        effectChildren.push(`<a:glow rad="${g.radius}"><a:srgbClr val="${xmlEncodeAttr(g.color)}">${alpha}</a:srgbClr></a:glow>`);
+    }
+    if (options.effects?.reflection) {
+        const r = options.effects.reflection;
+        const attrs = [];
+        if (r.blurRadius) {
+            attrs.push(`blurRad="${r.blurRadius}"`);
+        }
+        if (r.startOpacity !== undefined) {
+            attrs.push(`stA="${Math.round(r.startOpacity * 1000)}"`);
+        }
+        if (r.endOpacity !== undefined) {
+            attrs.push(`endA="${Math.round(r.endOpacity * 1000)}"`);
+        }
+        if (r.distance) {
+            attrs.push(`dist="${r.distance}"`);
+        }
+        if (r.direction !== undefined) {
+            attrs.push(`dir="${r.direction}"`);
+        }
+        if (r.fadeDirection !== undefined) {
+            attrs.push(`fadeDir="${r.fadeDirection}"`);
+        }
+        effectChildren.push(`<a:reflection ${attrs.join(" ")}/>`);
+    }
+    if (options.effects?.softEdges) {
+        effectChildren.push(`<a:softEdge rad="${options.effects.softEdges}"/>`);
+    }
+    if (effectChildren.length > 0) {
+        effectParts.push(`<a:effectLst>${effectChildren.join("")}</a:effectLst>`);
+    }
+    // 3D effect (scene3d + sp3d) — both follow effectLst.
+    if (options.effects?.effect3d) {
+        const e = options.effects.effect3d;
+        const camera = e.camera ?? "orthographicFront";
+        const rotAttrs = [];
+        if (e.rotX !== undefined) {
+            rotAttrs.push(`lat="${e.rotX}"`);
+        }
+        if (e.rotY !== undefined) {
+            rotAttrs.push(`lon="${e.rotY}"`);
+        }
+        if (e.rotZ !== undefined) {
+            rotAttrs.push(`rev="${e.rotZ}"`);
+        }
+        const rot = rotAttrs.length > 0 ? `<a:rot ${rotAttrs.join(" ")}/>` : "";
+        effectParts.push(`<a:scene3d><a:camera prst="${xmlEncodeAttr(camera)}">${rot}</a:camera><a:lightRig rig="threePt" dir="t"/></a:scene3d>`);
+        const sp3dChildren = [];
+        if (e.bevelTop) {
+            const preset = e.bevelTop.preset ? ` prst="${xmlEncodeAttr(e.bevelTop.preset)}"` : "";
+            sp3dChildren.push(`<a:bevelT w="${e.bevelTop.width}" h="${e.bevelTop.height}"${preset}/>`);
+        }
+        if (e.bevelBottom) {
+            const preset = e.bevelBottom.preset ? ` prst="${xmlEncodeAttr(e.bevelBottom.preset)}"` : "";
+            sp3dChildren.push(`<a:bevelB w="${e.bevelBottom.width}" h="${e.bevelBottom.height}"${preset}/>`);
+        }
+        if (e.extrusionColor) {
+            sp3dChildren.push(`<a:extrusionClr><a:srgbClr val="${xmlEncodeAttr(e.extrusionColor)}"/></a:extrusionClr>`);
+        }
+        const extDepth = e.extrusionDepth ? ` extrusionH="${e.extrusionDepth}"` : "";
+        effectParts.push(`<a:sp3d${extDepth}>${sp3dChildren.join("")}</a:sp3d>`);
+    }
+    return {
+        fillXml: fillParts.length > 0 ? fillParts.join("") : undefined,
+        effectsXml: effectParts.length > 0 ? effectParts.join("") : undefined
+    };
+}
+/**
+ * Create a simple rectangle shape.
+ */
+export function createRect(width, height, options) {
+    return createShape({ shapeType: "rect", width, height, ...options });
+}
+/**
+ * Create a rounded rectangle shape.
+ */
+export function createRoundRect(width, height, options) {
+    return createShape({ shapeType: "roundRect", width, height, ...options });
+}
+/**
+ * Create an ellipse/circle shape.
+ */
+export function createEllipse(width, height, options) {
+    return createShape({ shapeType: "ellipse", width, height, ...options });
+}
+/**
+ * Create a line connector.
+ */
+export function createLine(width, height, options) {
+    return createShape({
+        shapeType: "line",
+        width,
+        height,
+        fill: { type: "none" },
+        ...options
+    });
+}
+/**
+ * Create an arrow shape.
+ */
+export function createArrow(direction, width, height, options) {
+    const shapeMap = {
+        right: "rightArrow",
+        left: "leftArrow",
+        up: "upArrow",
+        down: "downArrow"
+    };
+    return createShape({ shapeType: shapeMap[direction], width, height, ...options });
+}
+/**
+ * Create a flowchart shape.
+ */
+export function createFlowchartShape(kind, width, height, options) {
+    const shapeMap = {
+        process: "flowChartProcess",
+        decision: "flowChartDecision",
+        terminator: "flowChartTerminator",
+        document: "flowChartDocument",
+        data: "flowChartInputOutput",
+        connector: "flowChartConnector",
+        preparation: "flowChartPreparation"
+    };
+    return createShape({ shapeType: shapeMap[kind], width, height, ...options });
+}
+/**
+ * Create a callout shape.
+ */
+export function createCallout(style, width, height, options) {
+    const shapeMap = {
+        rect: "wedgeRectCallout",
+        roundRect: "wedgeRoundRectCallout",
+        ellipse: "wedgeEllipseCallout",
+        cloud: "cloudCallout"
+    };
+    return createShape({ shapeType: shapeMap[style], width, height, ...options });
+}
+/**
+ * Create a star shape.
+ */
+export function createStar(points, width, height, options) {
+    return createShape({ shapeType: `star${points}`, width, height, ...options });
+}