@js-ak/excel-toolbox 1.5.0 → 1.7.0

package/build/cjs/lib/template/template-memory.js

@@ -56,6 +56,23 @@ class TemplateMemory {
      * @type {boolean}
      */
     #isProcessing = false;
+    /**
+ * The keys for the Excel files in the template.
+ */
+    #excelKeys = {
+        contentTypes: "[Content_Types].xml",
+        sharedStrings: "xl/sharedStrings.xml",
+        styles: "xl/styles.xml",
+        workbook: "xl/workbook.xml",
+        workbookRels: "xl/_rels/workbook.xml.rels",
+    };
+    /**
+     * Creates a Template instance from a map of file paths to buffers.
+     *
+     * @param {Object<string, Buffer>} files - The files to create the template from.
+     * @throws {Error} If reading or writing files fails.
+     * @experimental This API is experimental and might change in future versions.
+     */
     constructor(files) {
         this.files = files;
     }
@@ -115,31 +132,75 @@ class TemplateMemory {
             sheetXml: modifiedXml,
         });
     }
-    #getXml(fileKey) {
+    /**
+     * Extracts the XML content from an Excel sheet file.
+     *
+     * @param {string} fileKey - The file key of the sheet to extract.
+     * @returns {string} The XML content of the sheet.
+     * @throws {Error} If the file key is not found.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #extractXmlFromSheet(fileKey) {
         if (!this.files[fileKey]) {
             throw new Error(`${fileKey} not found`);
         }
         return Xml.extractXmlFromSheet(this.files[fileKey]);
     }
     /**
-     * Get the path of the sheet with the given name inside the workbook.
-     * @param sheetName The name of the sheet to find.
-     * @returns The path of the sheet inside the workbook.
-     * @throws {Error} If the sheet is not found.
+     * Extracts row data from an Excel sheet file.
+     *
+     * @param {string} fileKey - The file key of the sheet to extract.
+     * @returns {Object} An object containing:
+     *   - rows: Array of raw XML strings for each <row> element
+     *   - lastRowNumber: Highest row number found in the sheet (1-based)
+     *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
+     *   - xml: The XML content of the sheet
+     * @throws {Error} If the file key is not found
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #extractRowsFromSheet(fileKey) {
+        if (!this.files[fileKey]) {
+            throw new Error(`${fileKey} not found`);
+        }
+        return Xml.extractRowsFromSheet(this.files[fileKey]);
+    }
+    /**
+     * Returns the Excel path of the sheet with the given name.
+     *
+     * @param sheetName - The name of the sheet to find.
+     * @returns The Excel path of the sheet.
+     * @throws {Error} If the sheet with the given name does not exist.
+     * @experimental This API is experimental and might change in future versions.
      */
-    async #getSheetPath(sheetName) {
-        // Read XML workbook to find sheet name and path
-        const workbookXml = this.#getXml("xl/workbook.xml");
-        const sheetMatch = workbookXml.match(new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`));
-        if (!sheetMatch)
+    async #getSheetPathByName(sheetName) {
+        // Find the sheet
+        const workbookXml = await this.#extractXmlFromSheet(this.#excelKeys.workbook);
+        const sheetMatch = workbookXml.match(Utils.sheetMatch(sheetName));
+        if (!sheetMatch || !sheetMatch[1]) {
             throw new Error(`Sheet "${sheetName}" not found`);
+        }
         const rId = sheetMatch[1];
-        const relsXml = this.#getXml("xl/_rels/workbook.xml.rels");
-        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
-        if (!relMatch)
+        const relsXml = await this.#extractXmlFromSheet(this.#excelKeys.workbookRels);
+        const relMatch = relsXml.match(Utils.relationshipMatch(rId));
+        if (!relMatch || !relMatch[1]) {
             throw new Error(`Relationship "${rId}" not found`);
+        }
         return "xl/" + relMatch[1].replace(/^\/?xl\//, "");
     }
+    /**
+     * Returns the Excel path of the sheet with the given ID.
+     *
+     * @param {number} id - The 1-based index of the sheet to find.
+     * @returns {string} The Excel path of the sheet.
+     * @throws {Error} If the sheet index is less than 1.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #getSheetPathById(id) {
+        if (id < 1) {
+            throw new Error("Sheet index must be greater than 0");
+        }
+        return `xl/worksheets/sheet${id}.xml`;
+    }
     /**
      * Replaces the contents of a file in the template.
      *
@@ -153,16 +214,30 @@ class TemplateMemory {
     async #set(key, content) {
         this.files[key] = content;
     }
+    /**
+     * Replaces placeholders in the given sheet with values from the replacements map.
+     *
+     * The function searches for placeholders in the format `${key}` within the sheet
+     * content, where `key` corresponds to a path in the replacements object.
+     * If a value is found for the key, it replaces the placeholder with the value.
+     * If no value is found, the original placeholder remains unchanged.
+     *
+     * @param sheetName - The name of the sheet to be replaced.
+     * @param replacements - An object where keys represent placeholder paths and values are the replacements.
+     * @returns A promise that resolves when the substitution is complete.
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
     async #substitute(sheetName, replacements) {
-        const sharedStringsPath = "xl/sharedStrings.xml";
-        const sheetPath = await this.#getSheetPath(sheetName);
+        const sharedStringsPath = this.#excelKeys.sharedStrings;
         let sharedStringsContent = "";
         let sheetContent = "";
         if (this.files[sharedStringsPath]) {
-            sharedStringsContent = this.#getXml(sharedStringsPath);
+            sharedStringsContent = await this.#extractXmlFromSheet(sharedStringsPath);
         }
+        const sheetPath = await this.#getSheetPathByName(sheetName);
         if (this.files[sheetPath]) {
-            sheetContent = this.#getXml(sheetPath);
+            sheetContent = await this.#extractXmlFromSheet(sheetPath);
             const TABLE_REGEX = /\$\{table:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)\}/g;
             const hasTablePlaceholders = TABLE_REGEX.test(sharedStringsContent) || TABLE_REGEX.test(sheetContent);
             if (hasTablePlaceholders) {
@@ -180,6 +255,108 @@ class TemplateMemory {
             await this.#set(sheetPath, Buffer.from(sheetContent));
         }
     }
+    /**
+     * Merges rows from other sheets into a base sheet.
+     *
+     * @param {Object} data
+     * @param {Object} data.additions
+     * @param {number[]} [data.additions.sheetIndexes] - The 1-based indexes of the sheets to extract rows from.
+     * @param {string[]} [data.additions.sheetNames] - The names of the sheets to extract rows from.
+     * @param {number} [data.baseSheetIndex=1] - The 1-based index of the sheet in the workbook to add rows to.
+     * @param {string} [data.baseSheetName] - The name of the sheet in the workbook to add rows to.
+     * @param {number} [data.gap=0] - The number of empty rows to insert between each added section.
+     * @throws {Error} If the base sheet index is less than 1.
+     * @throws {Error} If the base sheet name is not found.
+     * @throws {Error} If the sheet index is less than 1.
+     * @throws {Error} If the sheet name is not found.
+     * @throws {Error} If no sheets are found to merge.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #mergeSheets(data) {
+        const { additions, baseSheetIndex = 1, baseSheetName, gap = 0, } = data;
+        let fileKey = "";
+        if (baseSheetName) {
+            fileKey = await this.#getSheetPathByName(baseSheetName);
+        }
+        if (baseSheetIndex && !fileKey) {
+            if (baseSheetIndex < 1) {
+                throw new Error("Base sheet index must be greater than 0");
+            }
+            fileKey = `xl/worksheets/sheet${baseSheetIndex}.xml`;
+        }
+        if (!fileKey) {
+            throw new Error("Base sheet not found");
+        }
+        const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, xml, } = await this.#extractRowsFromSheet(fileKey);
+        const allRows = [...baseRows];
+        const allMergeCells = [...baseMergeCells];
+        let currentRowOffset = lastRowNumber + gap;
+        const sheetPaths = [];
+        if (additions.sheetIndexes) {
+            sheetPaths.push(...(await Promise.all(additions.sheetIndexes.map(e => this.#getSheetPathById(e)))));
+        }
+        if (additions.sheetNames) {
+            sheetPaths.push(...(await Promise.all(additions.sheetNames.map(e => this.#getSheetPathByName(e)))));
+        }
+        if (sheetPaths.length === 0) {
+            throw new Error("No sheets found to merge");
+        }
+        for (const sheetPath of sheetPaths) {
+            if (!this.files[sheetPath]) {
+                throw new Error(`Sheet "${sheetPath}" not found`);
+            }
+            const { mergeCells, rows } = await Xml.extractRowsFromSheet(this.files[sheetPath]);
+            const shiftedRows = Xml.shiftRowIndices(rows, currentRowOffset);
+            const shiftedMergeCells = mergeCells.map(cell => {
+                const [start, end] = cell.ref.split(":");
+                if (!start || !end) {
+                    return cell;
+                }
+                const shiftedStart = Utils.Common.shiftCellRef(start, currentRowOffset);
+                const shiftedEnd = Utils.Common.shiftCellRef(end, currentRowOffset);
+                return { ...cell, ref: `${shiftedStart}:${shiftedEnd}` };
+            });
+            allRows.push(...shiftedRows);
+            allMergeCells.push(...shiftedMergeCells);
+            currentRowOffset += Utils.Common.getMaxRowNumber(rows) + gap;
+        }
+        const mergedXml = Xml.buildMergedSheet(xml, allRows, allMergeCells);
+        this.#set(fileKey, mergedXml);
+    }
+    /**
+     * Removes sheets from the workbook.
+     *
+     * @param {Object} data - The data for sheet removal.
+     * @param {number[]} [data.sheetIndexes] - The 1-based indexes of the sheets to remove.
+     * @param {string[]} [data.sheetNames] - The names of the sheets to remove.
+     * @returns {void}
+     *
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #removeSheets(data) {
+        const { sheetIndexes = [], sheetNames = [] } = data;
+        for (const sheetIndex of sheetIndexes) {
+            const sheetPath = `xl/worksheets/sheet${sheetIndex}.xml`;
+            if (!this.files[sheetPath]) {
+                continue;
+            }
+            delete this.files[sheetPath];
+            if (this.files["xl/workbook.xml"]) {
+                this.files["xl/workbook.xml"] = Buffer.from(Utils.Common.removeSheetFromWorkbook(this.files["xl/workbook.xml"].toString(), sheetIndex));
+            }
+            if (this.files["xl/_rels/workbook.xml.rels"]) {
+                this.files["xl/_rels/workbook.xml.rels"] = Buffer.from(Utils.Common.removeSheetFromRels(this.files["xl/_rels/workbook.xml.rels"].toString(), sheetIndex));
+            }
+            if (this.files["[Content_Types].xml"]) {
+                this.files["[Content_Types].xml"] = Buffer.from(Utils.Common.removeSheetFromContentTypes(this.files["[Content_Types].xml"].toString(), sheetIndex));
+            }
+        }
+        for (const sheetName of sheetNames) {
+            Utils.Common.removeSheetByName(this.files, sheetName);
+        }
+    }
     /**
      * Copies a sheet from the template to a new name.
      *
@@ -195,30 +372,31 @@ class TemplateMemory {
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
+            if (sourceName === newName) {
+                throw new Error("Source and new sheet names cannot be the same");
+            }
             // Read workbook.xml and find the source sheet
-            const workbookXmlPath = "xl/workbook.xml";
-            const workbookXml = this.#getXml(workbookXmlPath);
+            const workbookXmlPath = this.#excelKeys.workbook;
+            const workbookXml = await this.#extractXmlFromSheet(this.#excelKeys.workbook);
             // Find the source sheet
-            const sheetRegex = new RegExp(`<sheet[^>]+name="${sourceName}"[^>]+r:id="([^"]+)"[^>]*/>`);
-            const sheetMatch = workbookXml.match(sheetRegex);
-            if (!sheetMatch)
+            const sheetMatch = workbookXml.match(Utils.sheetMatch(sourceName));
+            if (!sheetMatch || !sheetMatch[1]) {
                 throw new Error(`Sheet "${sourceName}" not found`);
-            const sourceRId = sheetMatch[1];
+            }
             // Check if a sheet with the new name already exists
             if (new RegExp(`<sheet[^>]+name="${newName}"`).test(workbookXml)) {
                 throw new Error(`Sheet "${newName}" already exists`);
             }
             // Read workbook.rels
             // Find the source sheet path by rId
-            const relsXmlPath = "xl/_rels/workbook.xml.rels";
-            const relsXml = this.#getXml(relsXmlPath);
-            const relRegex = new RegExp(`<Relationship[^>]+Id="${sourceRId}"[^>]+Target="([^"]+)"[^>]*/>`);
-            const relMatch = relsXml.match(relRegex);
-            if (!relMatch)
-                throw new Error(`Relationship "${sourceRId}" not found`);
+            const rId = sheetMatch[1];
+            const relsXmlPath = this.#excelKeys.workbookRels;
+            const relsXml = await this.#extractXmlFromSheet(this.#excelKeys.workbookRels);
+            const relMatch = relsXml.match(Utils.relationshipMatch(rId));
+            if (!relMatch || !relMatch[1]) {
+                throw new Error(`Relationship "${rId}" not found`);
+            }
             const sourceTarget = relMatch[1]; // sheetN.xml
-            if (!sourceTarget)
-                throw new Error(`Relationship "${sourceRId}" not found`);
             const sourceSheetPath = "xl/" + sourceTarget.replace(/^\/?.*xl\//, "");
             // Get the index of the new sheet
             const sheetNumbers = Array.from(Object.keys(this.files))
@@ -255,7 +433,7 @@ class TemplateMemory {
             // Read [Content_Types].xml
             // Update [Content_Types].xml
             const contentTypesPath = "[Content_Types].xml";
-            const contentTypesXml = this.#getXml(contentTypesPath);
+            const contentTypesXml = await this.#extractXmlFromSheet(contentTypesPath);
             const overrideTag = `<Override PartName="/xl/worksheets/${newSheetFilename}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`;
             const updatedContentTypesXml = contentTypesXml.replace("</Types>", overrideTag + "</Types>");
             await this.#set(contentTypesPath, Buffer.from(updatedContentTypesXml));
@@ -312,19 +490,8 @@ class TemplateMemory {
             Utils.checkStartRow(startRowNumber);
             Utils.checkRows(preparedRows);
             // Find the sheet
-            const workbookXml = this.#getXml("xl/workbook.xml");
-            const sheetMatch = workbookXml.match(new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`));
-            if (!sheetMatch || !sheetMatch[1]) {
-                throw new Error(`Sheet "${sheetName}" not found`);
-            }
-            const rId = sheetMatch[1];
-            const relsXml = this.#getXml("xl/_rels/workbook.xml.rels");
-            const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
-            if (!relMatch || !relMatch[1]) {
-                throw new Error(`Relationship "${rId}" not found`);
-            }
-            const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
-            const sheetXml = this.#getXml(sheetPath);
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetXml = await this.#extractXmlFromSheet(sheetPath);
             let nextRow = 0;
             if (!startRowNumber) {
                 // Find the last row
@@ -364,6 +531,20 @@ class TemplateMemory {
             this.#isProcessing = false;
         }
     }
+    /**
+     * Inserts rows into a specific sheet in the template using an async stream.
+     *
+     * @param {Object} data - The data for row insertion.
+     * @param {string} data.sheetName - The name of the sheet to insert rows into.
+     * @param {number} [data.startRowNumber] - The row number to start inserting from.
+     * @param {AsyncIterable<unknown[]>} data.rows - Async iterable of rows to insert.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @throws {Error} If the row number is out of range.
+     * @throws {Error} If a column is out of range.
+     * @experimental This API is experimental and might change in future versions.
+     */
     async insertRowsStream(data) {
         this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
@@ -372,17 +553,9 @@ class TemplateMemory {
             const { rows, sheetName, startRowNumber } = data;
             if (!sheetName)
                 throw new Error("Sheet name is required");
-            const workbookXml = this.#getXml("xl/workbook.xml");
-            const sheetMatch = workbookXml.match(new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`));
-            if (!sheetMatch)
-                throw new Error(`Sheet "${sheetName}" not found`);
-            const rId = sheetMatch[1];
-            const relsXml = this.#getXml("xl/_rels/workbook.xml.rels");
-            const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
-            if (!relMatch || !relMatch[1])
-                throw new Error(`Relationship "${rId}" not found`);
-            const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
-            const sheetXml = this.#getXml(sheetPath);
+            // Read XML workbook to find sheet name and path
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetXml = await this.#extractXmlFromSheet(sheetPath);
             const output = new memory_write_stream_js_1.MemoryWriteStream();
             let inserted = false;
             // --- Case 1: <sheetData>...</sheetData> on one line ---
@@ -465,7 +638,7 @@ class TemplateMemory {
             }
             if (!inserted)
                 throw new Error("Failed to locate <sheetData> for insertion");
-            // ← теперь мы не собираем строку, а собираем Buffer
+            // Save the buffer to the sheet
             this.files[sheetPath] = output.toBuffer();
         }
         finally {
@@ -486,10 +659,10 @@ class TemplateMemory {
         try {
             const zipBuffer = await Zip.create(this.files);
             this.destroyed = true;
-            // Очистка всех буферов
+            // Clear all buffers
             for (const key in this.files) {
                 if (this.files.hasOwnProperty(key)) {
-                    this.files[key] = Buffer.alloc(0); // Заменяем на пустой буфер
+                    this.files[key] = Buffer.alloc(0); // Clear the buffer
                 }
             }
             return zipBuffer;
@@ -519,6 +692,55 @@ class TemplateMemory {
             this.#isProcessing = false;
         }
     }
+    /**
+     * Merges sheets into a base sheet.
+     *
+     * @param {Object} data
+     * @param {{ sheetIndexes?: number[]; sheetNames?: string[] }} data.additions - The sheets to merge.
+     * @param {number} [data.baseSheetIndex=1] - The 1-based index of the sheet to merge into.
+     * @param {string} [data.baseSheetName] - The name of the sheet to merge into.
+     * @param {number} [data.gap=0] - The number of empty rows to insert between each added section.
+     * @returns {void}
+     */
+    mergeSheets(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            this.#mergeSheets(data);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Removes sheets from the workbook.
+     *
+     * @param {Object} data
+     * @param {number[]} [data.sheetIndexes] - The 1-based indexes of the sheets to remove.
+     * @param {string[]} [data.sheetNames] - The names of the sheets to remove.
+     * @returns {void}
+     */
+    removeSheets(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            this.#removeSheets(data);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Creates a Template instance from an Excel file source.
+     *
+     * @param {Object} data - The data to create the template from.
+     * @param {string | Buffer} data.source - The path or buffer of the Excel file.
+     * @returns {Promise<TemplateMemory>} A new Template instance.
+     * @throws {Error} If reading the file fails.
+     * @experimental This API is experimental and might change in future versions.
+     */
     static async from(data) {
         const { source } = data;
         const buffer = typeof source === "string"

package/build/cjs/lib/template/utils/index.js

@@ -10,10 +10,34 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     if (k2 === undefined) k2 = k;
     o[k2] = m[k];
 }));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Common = void 0;
+exports.Common = __importStar(require("../../utils/index.js"));
 __exportStar(require("./apply-replacements.js"), exports);
 __exportStar(require("./check-row.js"), exports);
 __exportStar(require("./check-rows.js"), exports);
@@ -30,6 +54,7 @@ __exportStar(require("./process-merge-cells.js"), exports);
 __exportStar(require("./process-merge-finalize.js"), exports);
 __exportStar(require("./process-rows.js"), exports);
 __exportStar(require("./process-shared-strings.js"), exports);
+__exportStar(require("./regexp.js"), exports);
 __exportStar(require("./to-excel-column-object.js"), exports);
 __exportStar(require("./update-dimension.js"), exports);
 __exportStar(require("./validate-worksheet-xml.js"), exports);

package/build/cjs/lib/template/utils/prepare-row-to-cells.js

@@ -8,6 +8,10 @@ function prepareRowToCells(row, rowNumber) {
         const colLetter = (0, column_index_to_letter_js_1.columnIndexToLetter)(colIndex);
         const cellRef = `${colLetter}${rowNumber}`;
         const cellValue = (0, escape_xml_js_1.escapeXml)(String(value ?? ""));
-        return `<c r="${cellRef}" t="inlineStr"><is><t>${cellValue}</t></is></c>`;
+        return {
+            cellRef,
+            cellValue,
+            cellXml: `<c r="${cellRef}" t="inlineStr"><is><t>${cellValue}</t></is></c>`,
+        };
     });
 }

package/build/cjs/lib/template/utils/regexp.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationshipMatch = relationshipMatch;
+exports.sheetMatch = sheetMatch;
+/**
+ * Creates a regular expression to match a relationship element with a specific ID.
+ *
+ * @param {string} id - The relationship ID to match (e.g. "rId1")
+ * @returns {RegExp} A regular expression that matches a Relationship XML element with the given ID and captures the Target attribute value
+ * @example
+ * const regex = relationshipMatch("rId1");
+ * const xml = '<Relationship Id="rId1" Target="worksheets/sheet1.xml"/>';
+ * const match = xml.match(regex);
+ * // match[1] === "worksheets/sheet1.xml"
+ */
+function relationshipMatch(id) {
+    return new RegExp(`<Relationship[^>]+Id="${id}"[^>]+Target="([^"]+)"[^>]*/>`);
+}
+/**
+ * Creates a regular expression to match a sheet element with a specific name.
+ *
+ * @param {string} sheetName - The name of the sheet to match
+ * @returns {RegExp} A regular expression that matches a sheet XML element with the given name and captures the r:id attribute value
+ * @example
+ * const regex = sheetMatch("Sheet1");
+ * const xml = '<sheet name="Sheet1" sheetId="1" r:id="rId1"/>';
+ * const match = xml.match(regex);
+ * // match[1] === "rId1"
+ */
+function sheetMatch(sheetName) {
+    return new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`);
+}

package/build/cjs/lib/template/utils/update-dimension.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateDimension = updateDimension;
+/**
+ * Updates the dimension element in an Excel worksheet XML string based on the actual cell references.
+ *
+ * This function scans the XML for all cell references and calculates the minimum and maximum
+ * column/row values to determine the actual used range in the worksheet. It then updates
+ * the dimension element to reflect this range.
+ *
+ * @param {string} xml - The worksheet XML string to process
+ * @returns {string} The XML string with updated dimension element
+ * @example
+ * // XML with cells from A1 to C3
+ * const xml = '....<dimension ref="A1:B2"/>.....<c r="C3">...</c>...';
+ * const updated = updateDimension(xml);
+ * // Returns XML with dimension updated to ref="A1:C3"
+ */
 function updateDimension(xml) {
     const cellRefs = [...xml.matchAll(/<c r="([A-Z]+)(\d+)"/g)];
     if (cellRefs.length === 0)