@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/document-io.js

@@ -1,13 +1,14 @@
 /**
  * DOCX Module - Document IO
  *
- * IO operations that depend on docx-packager and docx-reader.
- * Separated from document.ts so that builder helpers can be imported
- * without pulling in archive/xml/writer code.
+ * IO operations: package/unpackage to bytes, base64, Flat OPC,
+ * plus the public Patch and Template APIs that combine read/patch/write.
  */
-import { packageDocx } from "./docx-packager.js";
-import { readDocx } from "./docx-reader.js";
-import { bytesToBase64 } from "./internal-utils.js";
+import { bytesToBase64 } from "./core/internal-utils.js";
+import { applyPatchesToDocument } from "./patcher.js";
+import { readDocx } from "./reader/docx-reader.js";
+import { fillTemplate } from "./template/template-engine.js";
+import { packageDocx } from "./writer/docx-packager.js";
 // =============================================================================
 // Document IO (toBuffer / toBase64)
 // =============================================================================
@@ -20,6 +21,36 @@ export async function toBase64(doc, compressionLevel) {
     const bytes = await toBuffer(doc, compressionLevel);
     return bytesToBase64(bytes);
 }
+/**
+ * Compile a DOCX template for reuse with multiple data sets.
+ *
+ * Parsing the ZIP and XML is expensive. If you need to patch the same template
+ * multiple times with different data, compile it once and reuse.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @returns A compiled template handle.
+ */
+export async function compileTemplate(buffer) {
+    const doc = await readDocx(buffer);
+    return { _doc: doc };
+}
+/**
+ * Apply patches to a pre-compiled template.
+ *
+ * Much faster than `patchDocument` when applying to the same template repeatedly,
+ * since ZIP/XML parsing is skipped.
+ *
+ * @param template - A compiled template from `compileTemplate`.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function patchTemplate(template, patches, options) {
+    // Deep clone the document to avoid mutating the cached template
+    const doc = structuredClone(template._doc);
+    const patched = applyPatchesToDocument(doc, patches);
+    return packageDocx(patched, options?.compressionLevel);
+}
 /**
  * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
  *
@@ -39,201 +70,53 @@ export async function toBase64(doc, compressionLevel) {
  */
 export async function patchDocument(buffer, patches, options) {
     const doc = await readDocx(buffer);
-    // Build lookup map for quick placeholder matching
-    const patchMap = new Map();
-    for (const patch of patches) {
-        patchMap.set(patch.placeholder, patch);
-    }
-    // Process body content
-    const newBody = [];
-    for (const block of doc.body) {
-        if (block.type === "paragraph") {
-            const result = patchParagraph(block, patchMap);
-            if (result) {
-                if (Array.isArray(result)) {
-                    newBody.push(...result);
-                }
-                else {
-                    newBody.push(result);
-                }
-            }
-        }
-        else if (block.type === "table") {
-            patchTable(block, patchMap);
-            newBody.push(block);
-        }
-        else {
-            newBody.push(block);
-        }
-    }
-    // Patch headers
-    if (doc.headers) {
-        for (const [, headerDef] of doc.headers) {
-            patchHeaderFooterContent(headerDef.content, patchMap);
-        }
-    }
-    // Patch footers
-    if (doc.footers) {
-        for (const [, footerDef] of doc.footers) {
-            patchHeaderFooterContent(footerDef.content, patchMap);
-        }
-    }
-    // Add any new images from patches
-    const images = doc.images ? [...doc.images] : [];
-    for (const patch of patches) {
-        if (patch.content.type === "image") {
-            const imgContent = patch.content;
-            const existing = images.find(i => i.fileName === imgContent.image.fileName);
-            if (!existing) {
-                images.push(imgContent.image);
-            }
-        }
-    }
-    const patched = {
-        ...doc,
-        body: newBody,
-        images: images.length > 0 ? images : undefined
-    };
+    const patched = applyPatchesToDocument(doc, patches);
     return packageDocx(patched, options?.compressionLevel);
 }
 // =============================================================================
-// Internal helpers
+// Template Engine - Convenience IO
 // =============================================================================
-/** Extract concatenated plain text from a paragraph's runs. */
-function paragraphText(para) {
-    let t = "";
-    for (const child of para.children) {
-        if ("content" in child && Array.isArray(child.content)) {
-            for (const c of child.content) {
-                if ("type" in c && c.type === "text" && "text" in c) {
-                    t += c.text;
-                }
-            }
-        }
-    }
-    return t;
-}
-/** Replace text within a single paragraph. */
-function replaceInParagraph(para, search, replacement) {
-    for (const child of para.children) {
-        if (!("content" in child) || !Array.isArray(child.content)) {
-            continue;
-        }
-        for (const c of child.content) {
-            if (!("type" in c) || c.type !== "text" || !("text" in c)) {
-                continue;
-            }
-            const before = c.text;
-            if (before.includes(search)) {
-                c.text = before.replaceAll(search, replacement);
-            }
-        }
-    }
-    // Cross-run replacement fallback
-    const fullText = paragraphText(para);
-    if (fullText.includes(search)) {
-        const newText = fullText.replaceAll(search, replacement);
-        let placed = false;
-        for (const child of para.children) {
-            if (!("content" in child) || !Array.isArray(child.content)) {
-                continue;
-            }
-            for (const c of child.content) {
-                if (!("type" in c) || c.type !== "text" || !("text" in c)) {
-                    continue;
-                }
-                if (!placed) {
-                    c.text = newText;
-                    placed = true;
-                }
-                else {
-                    c.text = "";
-                }
-            }
-        }
-    }
-}
-/** Patch a paragraph — returns replacement content or null to remove. */
-function patchParagraph(para, patchMap) {
-    const text = paragraphText(para);
-    for (const [placeholder, patch] of patchMap) {
-        if (!text.includes(placeholder)) {
-            continue;
-        }
-        switch (patch.content.type) {
-            case "text": {
-                replaceInParagraph(para, placeholder, patch.content.text);
-                return para;
-            }
-            case "paragraph": {
-                return patch.content.children;
-            }
-            case "table": {
-                return patch.content.table;
-            }
-            case "image": {
-                const img = patch.content.image;
-                const rId = img.rId ?? `rId_img_${img.fileName}`;
-                const imgContent = {
-                    type: "image",
-                    rId,
-                    width: patch.content.width,
-                    height: patch.content.height,
-                    altText: img.fileName,
-                    name: img.fileName
-                };
-                const newPara = {
-                    type: "paragraph",
-                    properties: para.properties,
-                    children: [{ content: [imgContent] }]
-                };
-                return newPara;
-            }
-        }
-    }
-    return para;
-}
-/** Patch text inside table cells recursively. */
-function patchTable(table, patchMap) {
-    for (const row of table.rows) {
-        for (const cell of row.cells) {
-            const newContent = [];
-            for (const block of cell.content) {
-                if (block.type === "paragraph") {
-                    const result = patchParagraph(block, patchMap);
-                    if (result) {
-                        if (Array.isArray(result)) {
-                            newContent.push(...result);
-                        }
-                        else {
-                            newContent.push(result);
-                        }
-                    }
-                }
-                else if (block.type === "table") {
-                    patchTable(block, patchMap);
-                    newContent.push(block);
-                }
-                else {
-                    newContent.push(block);
-                }
-            }
-            cell.content = newContent;
-        }
-    }
+/**
+ * Read a DOCX buffer, fill template placeholders with data, and produce a new DOCX.
+ *
+ * This is a convenience wrapper combining readDocx + fillTemplate + packageDocx.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @param data - Data object to fill into the template placeholders.
+ * @param options - Template and compression options.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function fillTemplateFromBuffer(buffer, data, options) {
+    const doc = await readDocx(buffer);
+    const filled = fillTemplate(doc, data, options);
+    return packageDocx(filled, options?.compressionLevel);
 }
-/** Patch text in header/footer content. */
-function patchHeaderFooterContent(content, patchMap) {
-    for (const child of content.children) {
-        if (child.type === "paragraph") {
-            for (const [placeholder, patch] of patchMap) {
-                if (patch.content.type === "text") {
-                    const text = paragraphText(child);
-                    if (text.includes(placeholder)) {
-                        replaceInParagraph(child, placeholder, patch.content.text);
-                    }
-                }
-            }
-        }
+// =============================================================================
+// Flat OPC Convenience
+// =============================================================================
+/**
+ * Package a DocxDocument model into Flat OPC XML format.
+ *
+ * This packages the document to a ZIP, then re-reads the entries to wrap
+ * them as Flat OPC XML. While this involves a ZIP round-trip, it ensures
+ * the Flat OPC output is byte-identical to what `packageDocx` would produce
+ * (same XML serialization, same relationships, same content types).
+ *
+ * @param doc - The document model.
+ * @param compressionLevel - Optional compression level (0 = no compression, faster for Flat OPC).
+ * @returns The Flat OPC XML string.
+ */
+export async function toFlatOpcFromDoc(doc, compressionLevel) {
+    // Use level 0 (store-only) since we're immediately decompressing
+    const zipBytes = await packageDocx(doc, compressionLevel ?? 0);
+    const { unzip } = await import("../archive/read-archive.js");
+    const reader = unzip(zipBytes);
+    const entries = new Map();
+    for await (const entry of reader.entries()) {
+        const data = await entry.bytes();
+        const path = entry.path.replace(/^\//, "").replace(/\\/g, "/");
+        entries.set(path, data);
     }
+    const { toFlatOpc } = await import("./convert/flat-opc.js");
+    return toFlatOpc(entries);
 }

package/dist/esm/modules/word/errors.js

@@ -4,8 +4,6 @@
  * All DOCX-related errors extend DocxError.
  */
 import { BaseError } from "../../utils/errors.js";
-// Re-export common utilities from base
-export { AbortError, createAbortError, isAbortError, throwIfAborted, createLinkedAbortController, toError, suppressUnhandledRejection, errorToJSON, getErrorChain, getRootCause } from "../../utils/errors.js";
 /**
  * Base class for all DOCX-related errors.
  */
@@ -66,3 +64,57 @@ export class DocxUnsupportedFeatureError extends DocxError {
         this.name = "DocxUnsupportedFeatureError";
     }
 }
+/**
+ * Error thrown when a DOCX file is encrypted (CFB format) and no password
+ * was provided. Pass `{ password }` in the second argument of `readDocx()`
+ * to decrypt automatically, or call `decryptDocx()` from "excelts/word/crypto"
+ * directly if you need lower-level access to the decrypted ZIP bytes.
+ */
+export class DocxEncryptedError extends DocxError {
+    constructor() {
+        super("The document is encrypted (password-protected). " +
+            'Pass { password } to readDocx(), or use decryptDocx() from "excelts/word/crypto" ' +
+            "for lower-level decryption.");
+        this.name = "DocxEncryptedError";
+    }
+}
+/**
+ * Error thrown when an encrypted DOCX cannot be decrypted with the provided
+ * password (wrong password) or when the encryption metadata is malformed.
+ */
+export class DocxDecryptionError extends DocxError {
+    constructor() {
+        super(...arguments);
+        this.name = "DocxDecryptionError";
+    }
+}
+/**
+ * Error thrown when an input package exceeds a declared resource limit (e.g.
+ * total package size, single part size, number of parts). Used to defend
+ * against ZIP bombs and runaway memory usage.
+ */
+export class DocxLimitExceededError extends DocxParseError {
+    constructor(limit, maximum, actual, detail) {
+        super(`DOCX ${limit} limit exceeded: actual ${actual} > maximum ${maximum}` +
+            (detail ? ` (${detail})` : ""));
+        this.name = "DocxLimitExceededError";
+        this.limit = limit;
+        this.maximum = maximum;
+        this.actual = actual;
+    }
+}
+/**
+ * Error thrown when the active `WordSecurityPolicy.rawXmlPolicy` is `"reject"`
+ * and the writer encounters opaque/preserved rawXml that would otherwise have
+ * been emitted verbatim. Callers can either drop the offending model field
+ * before serialisation or relax the policy to `"strip"` / `"preserve"`.
+ */
+export class DocxRawXmlPolicyError extends DocxWriteError {
+    constructor(site) {
+        super(`Raw XML rejected by security policy at "${site}". ` +
+            "Either remove the rawXml/opaque field from the model or set " +
+            "WordSecurityPolicy.rawXmlPolicy to 'preserve' or 'strip'.");
+        this.name = "DocxRawXmlPolicyError";
+        this.site = site;
+    }
+}

package/dist/esm/modules/word/excel.js

@@ -0,0 +1,13 @@
+/**
+ * DOCX Module - Excel Bridge (Subpath Entry)
+ *
+ * Re-exports the Excel bridge API at `excelts/word/excel`. This file is
+ * referenced by `package.json#exports["./word/excel"]`; it forwards to the
+ * implementation under `./bridge/excel-bridge`.
+ *
+ * @example
+ * ```ts
+ * import { excelToDocx } from "excelts/word/excel";
+ * ```
+ */
+export { excelToDocx, extractTablesToExcel, renderWordChartSvg, buildWordChartExXml, wordChartToChartModel, generateChartEmbeddedXlsx } from "./bridge/excel-bridge.js";