@js-ak/excel-toolbox 1.3.1 → 1.4.0

package/build/esm/lib/template/template-fs.js

@@ -26,6 +26,11 @@ export class TemplateFs {
      * @type {boolean}
      */
     destroyed = false;
+    /**
+     * Flag indicating whether this template instance is currently being processed.
+     * @type {boolean}
+     */
+    #isProcessing = false;
     /**
      * Creates a Template instance.
      *
@@ -57,6 +62,70 @@ export class TemplateFs {
             throw new Error("This Template instance has already been saved and destroyed.");
         }
     }
+    /**
+     * Ensures that this Template instance is not currently being processed.
+     * @throws {Error} If the template instance is currently being processed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #ensureNotProcessing() {
+        if (this.#isProcessing) {
+            throw new Error("This Template instance is currently being processed.");
+        }
+    }
+    /**
+     * Expand table rows in the given sheet and shared strings XML.
+     *
+     * @param {string} sheetXml - The XML content of the sheet.
+     * @param {string} sharedStringsXml - The XML content of the shared strings.
+     * @param {Record<string, unknown>} replacements - An object containing replacement values.
+     *
+     * @returns {Object} An object with two properties:
+     *   - sheet: The expanded sheet XML.
+     *   - shared: The expanded shared strings XML.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #expandTableRows(sheetXml, sharedStringsXml, replacements) {
+        const { initialMergeCells, mergeCellMatches, modifiedXml, } = processMergeCells(sheetXml);
+        const { sharedIndexMap, sharedStrings, sharedStringsHeader, sheetMergeCells, } = processSharedStrings(sharedStringsXml);
+        const { lastIndex, resultRows, rowShift } = processRows({
+            mergeCellMatches,
+            replacements,
+            sharedIndexMap,
+            sharedStrings,
+            sheetMergeCells,
+            sheetXml: modifiedXml,
+        });
+        return processBuild({
+            initialMergeCells,
+            lastIndex,
+            mergeCellMatches,
+            resultRows,
+            rowShift,
+            sharedStrings,
+            sharedStringsHeader,
+            sheetMergeCells,
+            sheetXml: modifiedXml,
+        });
+    }
+    /**
+     * 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.
+     */
+    async #getSheetPath(sheetName) {
+        // Read XML workbook to find sheet name and path
+        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("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 = Xml.extractXmlFromSheet(await this.#readFile("xl/_rels/workbook.xml.rels"));
+        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
+        if (!relMatch)
+            throw new Error(`Relationship "${rId}" not found`);
+        return "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+    }
     /**
      * Reads all files from the destination directory.
      * @private
@@ -86,6 +155,169 @@ export class TemplateFs {
         const fullPath = path.join(this.destination, ...pathKey.split("/"));
         return await fs.readFile(fullPath);
     }
+    /**
+     * Replaces the contents of a file in the template.
+     *
+     * @param {string} key - The Excel path of the file to replace.
+     * @param {Buffer|string} content - The new content.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the file does not exist in the template.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #set(key, content) {
+        if (!this.fileKeys.has(key)) {
+            throw new Error(`File "${key}" is not part of the original template.`);
+        }
+        const fullPath = path.join(this.destination, ...key.split("/"));
+        await fs.writeFile(fullPath, Buffer.isBuffer(content) ? content : Buffer.from(content));
+    }
+    async #substitute(sheetName, replacements) {
+        const sharedStringsPath = "xl/sharedStrings.xml";
+        const sheetPath = await this.#getSheetPath(sheetName);
+        let sharedStringsContent = "";
+        let sheetContent = "";
+        if (this.fileKeys.has(sharedStringsPath)) {
+            sharedStringsContent = Xml.extractXmlFromSheet(await this.#readFile(sharedStringsPath));
+        }
+        if (this.fileKeys.has(sheetPath)) {
+            sheetContent = Xml.extractXmlFromSheet(await this.#readFile(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) {
+                const result = this.#expandTableRows(sheetContent, sharedStringsContent, replacements);
+                sheetContent = result.sheet;
+                sharedStringsContent = result.shared;
+            }
+        }
+        if (this.fileKeys.has(sharedStringsPath)) {
+            sharedStringsContent = Utils.applyReplacements(sharedStringsContent, replacements);
+            await this.#set(sharedStringsPath, sharedStringsContent);
+        }
+        if (this.fileKeys.has(sheetPath)) {
+            sheetContent = Utils.applyReplacements(sheetContent, replacements);
+            await this.#set(sheetPath, sheetContent);
+        }
+    }
+    /**
+     * Validates the template by checking all required files exist.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If any required files are missing.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #validate() {
+        for (const key of this.fileKeys) {
+            const fullPath = path.join(this.destination, ...key.split("/"));
+            try {
+                await fs.access(fullPath);
+            }
+            catch {
+                throw new Error(`Missing file in template directory: ${key}`);
+            }
+        }
+    }
+    /**
+     * Copies a sheet from the template to a new name.
+     *
+     * @param {string} sourceName - The name of the sheet to copy.
+     * @param {string} newName - The new name for the sheet.
+     * @returns {Promise<void>}
+     * @throws {Error} If the sheet with the source name does not exist.
+     * @throws {Error} If a sheet with the new name already exists.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async copySheet(sourceName, newName) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            // Read workbook.xml and find the source sheet
+            const workbookXmlPath = "xl/workbook.xml";
+            const workbookXml = Xml.extractXmlFromSheet(await this.#readFile(workbookXmlPath));
+            // Find the source sheet
+            const sheetRegex = new RegExp(`<sheet[^>]+name="${sourceName}"[^>]+r:id="([^"]+)"[^>]*/>`);
+            const sheetMatch = workbookXml.match(sheetRegex);
+            if (!sheetMatch)
+                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 = Xml.extractXmlFromSheet(await this.#readFile(relsXmlPath));
+            const relRegex = new RegExp(`<Relationship[^>]+Id="${sourceRId}"[^>]+Target="([^"]+)"[^>]*/>`);
+            const relMatch = relsXml.match(relRegex);
+            if (!relMatch)
+                throw new Error(`Relationship "${sourceRId}" 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 = [...this.fileKeys]
+                .map((key) => key.match(/^xl\/worksheets\/sheet(\d+)\.xml$/))
+                .filter(Boolean)
+                .map((match) => parseInt(match[1], 10));
+            const nextSheetIndex = sheetNumbers.length > 0 ? Math.max(...sheetNumbers) + 1 : 1;
+            const newSheetFilename = `sheet${nextSheetIndex}.xml`;
+            const newSheetPath = `xl/worksheets/${newSheetFilename}`;
+            const newTarget = `worksheets/${newSheetFilename}`;
+            // Generate a unique rId
+            const usedRIds = [...relsXml.matchAll(/Id="(rId\d+)"/g)].map(m => m[1]);
+            let nextRIdNum = 1;
+            while (usedRIds.includes(`rId${nextRIdNum}`))
+                nextRIdNum++;
+            const newRId = `rId${nextRIdNum}`;
+            // Copy the source sheet file
+            const sheetContent = await this.#readFile(sourceSheetPath);
+            await fs.writeFile(path.join(this.destination, ...newSheetPath.split("/")), sheetContent);
+            this.fileKeys.add(newSheetPath);
+            // Update workbook.xml
+            const updatedWorkbookXml = workbookXml.replace("</sheets>", `<sheet name="${newName}" sheetId="${nextSheetIndex}" r:id="${newRId}"/></sheets>`);
+            await this.#set(workbookXmlPath, updatedWorkbookXml);
+            // Update workbook.xml.rels
+            const updatedRelsXml = relsXml.replace("</Relationships>", `<Relationship Id="${newRId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="${newTarget}"/></Relationships>`);
+            await this.#set(relsXmlPath, updatedRelsXml);
+            // Read [Content_Types].xml
+            // Update [Content_Types].xml
+            const contentTypesPath = "[Content_Types].xml";
+            const contentTypesXml = Xml.extractXmlFromSheet(await this.#readFile(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, updatedContentTypesXml);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * 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.
+     */
+    substitute(sheetName, replacements) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            return this.#substitute(sheetName, replacements);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
     /**
      * Inserts rows into a specific sheet in the template.
      *
@@ -101,61 +333,68 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async insertRows(data) {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        const { rows, sheetName, startRowNumber } = data;
-        const preparedRows = rows.map(row => Utils.toExcelColumnObject(row));
-        // Validation
-        Utils.checkStartRow(startRowNumber);
-        Utils.checkRows(preparedRows);
-        // Find the sheet
-        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("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 = Xml.extractXmlFromSheet(await this.#readFile("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 sheetXmlRaw = await this.#readFile(sheetPath);
-        const sheetXml = Xml.extractXmlFromSheet(sheetXmlRaw);
-        let nextRow = 0;
-        if (!startRowNumber) {
-            // Find the last row
-            let lastRowNumber = 0;
-            const rowMatches = [...sheetXml.matchAll(/<row[^>]+r="(\d+)"[^>]*>/g)];
-            if (rowMatches.length > 0) {
-                lastRowNumber = Math.max(...rowMatches.map((m) => parseInt(m[1], 10)));
+        this.#isProcessing = true;
+        try {
+            const { rows, sheetName, startRowNumber } = data;
+            const preparedRows = rows.map(row => Utils.toExcelColumnObject(row));
+            // Validation
+            Utils.checkStartRow(startRowNumber);
+            Utils.checkRows(preparedRows);
+            // Find the sheet
+            const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("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 = Xml.extractXmlFromSheet(await this.#readFile("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`);
             }
-            nextRow = lastRowNumber + 1;
-        }
-        else {
-            nextRow = startRowNumber;
-        }
-        // Generate XML for all rows
-        const rowsXml = preparedRows.map((cells, i) => {
-            const rowNumber = nextRow + i;
-            const cellTags = Object.entries(cells).map(([col, value]) => {
-                const colUpper = col.toUpperCase();
-                const ref = `${colUpper}${rowNumber}`;
-                return `<c r="${ref}" t="inlineStr"><is><t>${Utils.escapeXml(value)}</t></is></c>`;
+            const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+            const sheetXmlRaw = await this.#readFile(sheetPath);
+            const sheetXml = Xml.extractXmlFromSheet(sheetXmlRaw);
+            let nextRow = 0;
+            if (!startRowNumber) {
+                // Find the last row
+                let lastRowNumber = 0;
+                const rowMatches = [...sheetXml.matchAll(/<row[^>]+r="(\d+)"[^>]*>/g)];
+                if (rowMatches.length > 0) {
+                    lastRowNumber = Math.max(...rowMatches.map((m) => parseInt(m[1], 10)));
+                }
+                nextRow = lastRowNumber + 1;
+            }
+            else {
+                nextRow = startRowNumber;
+            }
+            // Generate XML for all rows
+            const rowsXml = preparedRows.map((cells, i) => {
+                const rowNumber = nextRow + i;
+                const cellTags = Object.entries(cells).map(([col, value]) => {
+                    const colUpper = col.toUpperCase();
+                    const ref = `${colUpper}${rowNumber}`;
+                    return `<c r="${ref}" t="inlineStr"><is><t>${Utils.escapeXml(value)}</t></is></c>`;
+                }).join("");
+                return `<row r="${rowNumber}">${cellTags}</row>`;
             }).join("");
-            return `<row r="${rowNumber}">${cellTags}</row>`;
-        }).join("");
-        let updatedXml;
-        if (/<sheetData\s*\/>/.test(sheetXml)) {
-            updatedXml = sheetXml.replace(/<sheetData\s*\/>/, `<sheetData>${rowsXml}</sheetData>`);
-        }
-        else if (/<sheetData>([\s\S]*?)<\/sheetData>/.test(sheetXml)) {
-            updatedXml = sheetXml.replace(/<\/sheetData>/, `${rowsXml}</sheetData>`);
+            let updatedXml;
+            if (/<sheetData\s*\/>/.test(sheetXml)) {
+                updatedXml = sheetXml.replace(/<sheetData\s*\/>/, `<sheetData>${rowsXml}</sheetData>`);
+            }
+            else if (/<sheetData>([\s\S]*?)<\/sheetData>/.test(sheetXml)) {
+                updatedXml = sheetXml.replace(/<\/sheetData>/, `${rowsXml}</sheetData>`);
+            }
+            else {
+                updatedXml = sheetXml.replace(/<worksheet[^>]*>/, (match) => `${match}<sheetData>${rowsXml}</sheetData>`);
+            }
+            await this.#set(sheetPath, updatedXml);
         }
-        else {
-            updatedXml = sheetXml.replace(/<worksheet[^>]*>/, (match) => `${match}<sheetData>${rowsXml}</sheetData>`);
+        finally {
+            this.#isProcessing = false;
         }
-        await this.set(sheetPath, updatedXml);
     }
     /**
      * Inserts rows into a specific sheet in the template using an async stream.
@@ -172,155 +411,162 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async insertRowsStream(data) {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        const { rows, sheetName, startRowNumber } = data;
-        if (!sheetName)
-            throw new Error("Sheet name is required");
-        // Read XML workbook to find sheet name and path
-        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("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 = Xml.extractXmlFromSheet(await this.#readFile("xl/_rels/workbook.xml.rels"));
-        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
-        if (!relMatch)
-            throw new Error(`Relationship "${rId}" not found`);
-        // Path to the desired sheet (sheet1.xml)
-        const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
-        // The temporary file for writing
-        const fullPath = path.join(this.destination, ...sheetPath.split("/"));
-        const tempPath = fullPath + ".tmp";
-        // Streams for reading and writing
-        const input = fsSync.createReadStream(fullPath, { encoding: "utf-8" });
-        const output = fsSync.createWriteStream(tempPath, { encoding: "utf-8" });
-        // Inserted rows flag
-        let inserted = false;
-        const rl = readline.createInterface({
-            // Process all line breaks
-            crlfDelay: Infinity,
-            input,
-        });
-        let isCollecting = false;
-        let collection = "";
-        for await (const line of rl) {
-            // Collect lines between <sheetData> and </sheetData>
-            if (!inserted && isCollecting) {
-                collection += line;
-                if (line.includes("</sheetData>")) {
+        this.#isProcessing = true;
+        try {
+            const { rows, sheetName, startRowNumber } = data;
+            if (!sheetName)
+                throw new Error("Sheet name is required");
+            // Read XML workbook to find sheet name and path
+            const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("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 = Xml.extractXmlFromSheet(await this.#readFile("xl/_rels/workbook.xml.rels"));
+            const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
+            if (!relMatch)
+                throw new Error(`Relationship "${rId}" not found`);
+            // Path to the desired sheet (sheet1.xml)
+            const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+            // The temporary file for writing
+            const fullPath = path.join(this.destination, ...sheetPath.split("/"));
+            const tempPath = fullPath + ".tmp";
+            // Streams for reading and writing
+            const input = fsSync.createReadStream(fullPath, { encoding: "utf-8" });
+            const output = fsSync.createWriteStream(tempPath, { encoding: "utf-8" });
+            // Inserted rows flag
+            let inserted = false;
+            const rl = readline.createInterface({
+                // Process all line breaks
+                crlfDelay: Infinity,
+                input,
+            });
+            let isCollecting = false;
+            let collection = "";
+            for await (const line of rl) {
+                // Collect lines between <sheetData> and </sheetData>
+                if (!inserted && isCollecting) {
+                    collection += line;
+                    if (line.includes("</sheetData>")) {
+                        const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
+                        isCollecting = false;
+                        inserted = true;
+                        const openTag = collection.match(/<sheetData[^>]*>/)?.[0] ?? "<sheetData>";
+                        const closeTag = "</sheetData>";
+                        const openIdx = collection.indexOf(openTag);
+                        const closeIdx = collection.lastIndexOf(closeTag);
+                        const beforeRows = collection.slice(0, openIdx + openTag.length);
+                        const innerRows = collection.slice(openIdx + openTag.length, closeIdx).trim();
+                        const afterRows = collection.slice(closeIdx);
+                        output.write(beforeRows);
+                        const innerRowsMap = Utils.parseRows(innerRows);
+                        if (innerRows) {
+                            if (startRowNumber) {
+                                const filteredRows = Utils.getRowsBelow(innerRowsMap, startRowNumber);
+                                if (filteredRows)
+                                    output.write(filteredRows);
+                            }
+                            else {
+                                output.write(innerRows);
+                            }
+                        }
+                        const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                        if (innerRows) {
+                            const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
+                            if (filteredRows)
+                                output.write(filteredRows);
+                        }
+                        output.write(afterRows);
+                    }
+                    continue;
+                }
+                // Case 1: <sheetData> and </sheetData> on one line
+                const singleLineMatch = line.match(/(<sheetData[^>]*>)(.*)(<\/sheetData>)/);
+                if (!inserted && singleLineMatch) {
                     const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
-                    isCollecting = false;
-                    inserted = true;
-                    const openTag = collection.match(/<sheetData[^>]*>/)?.[0] ?? "<sheetData>";
+                    const fullMatch = singleLineMatch[0];
+                    const before = line.slice(0, singleLineMatch.index);
+                    const after = line.slice(singleLineMatch.index + fullMatch.length);
+                    const openTag = "<sheetData>";
                     const closeTag = "</sheetData>";
-                    const openIdx = collection.indexOf(openTag);
-                    const closeIdx = collection.lastIndexOf(closeTag);
-                    const beforeRows = collection.slice(0, openIdx + openTag.length);
-                    const innerRows = collection.slice(openIdx + openTag.length, closeIdx).trim();
-                    const afterRows = collection.slice(closeIdx);
+                    const openIdx = fullMatch.indexOf(openTag);
+                    const closeIdx = fullMatch.indexOf(closeTag);
+                    const beforeRows = fullMatch.slice(0, openIdx + openTag.length);
+                    const innerRows = fullMatch.slice(openIdx + openTag.length, closeIdx).trim();
+                    const afterRows = fullMatch.slice(closeIdx);
+                    if (before) {
+                        output.write(before);
+                    }
                     output.write(beforeRows);
                     const innerRowsMap = Utils.parseRows(innerRows);
                     if (innerRows) {
                         if (startRowNumber) {
                             const filteredRows = Utils.getRowsBelow(innerRowsMap, startRowNumber);
-                            if (filteredRows)
+                            if (filteredRows) {
                                 output.write(filteredRows);
+                            }
                         }
                         else {
                             output.write(innerRows);
                         }
                     }
+                    // new <row>
                     const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
                     if (innerRows) {
                         const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
-                        if (filteredRows)
-                            output.write(filteredRows);
-                    }
-                    output.write(afterRows);
-                }
-                continue;
-            }
-            // Case 1: <sheetData> and </sheetData> on one line
-            const singleLineMatch = line.match(/(<sheetData[^>]*>)(.*)(<\/sheetData>)/);
-            if (!inserted && singleLineMatch) {
-                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
-                const fullMatch = singleLineMatch[0];
-                const before = line.slice(0, singleLineMatch.index);
-                const after = line.slice(singleLineMatch.index + fullMatch.length);
-                const openTag = "<sheetData>";
-                const closeTag = "</sheetData>";
-                const openIdx = fullMatch.indexOf(openTag);
-                const closeIdx = fullMatch.indexOf(closeTag);
-                const beforeRows = fullMatch.slice(0, openIdx + openTag.length);
-                const innerRows = fullMatch.slice(openIdx + openTag.length, closeIdx).trim();
-                const afterRows = fullMatch.slice(closeIdx);
-                if (before) {
-                    output.write(before);
-                }
-                output.write(beforeRows);
-                const innerRowsMap = Utils.parseRows(innerRows);
-                if (innerRows) {
-                    if (startRowNumber) {
-                        const filteredRows = Utils.getRowsBelow(innerRowsMap, startRowNumber);
                         if (filteredRows) {
                             output.write(filteredRows);
                         }
                     }
-                    else {
-                        output.write(innerRows);
+                    output.write(afterRows);
+                    if (after) {
+                        output.write(after);
                     }
+                    inserted = true;
+                    continue;
                 }
-                // new <row>
-                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
-                if (innerRows) {
-                    const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
-                    if (filteredRows) {
-                        output.write(filteredRows);
+                // Case 2: <sheetData/>
+                if (!inserted && /<sheetData\s*\/>/.test(line)) {
+                    const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
+                    const fullMatch = line.match(/<sheetData\s*\/>/)?.[0] || "";
+                    const matchIndex = line.indexOf(fullMatch);
+                    const before = line.slice(0, matchIndex);
+                    const after = line.slice(matchIndex + fullMatch.length);
+                    if (before) {
+                        output.write(before);
                     }
+                    // Insert opening tag
+                    output.write("<sheetData>");
+                    // Prepare the rows
+                    await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    // Insert closing tag
+                    output.write("</sheetData>");
+                    if (after) {
+                        output.write(after);
+                    }
+                    inserted = true;
+                    continue;
                 }
-                output.write(afterRows);
-                if (after) {
-                    output.write(after);
-                }
-                inserted = true;
-                continue;
-            }
-            // Case 2: <sheetData/>
-            if (!inserted && /<sheetData\s*\/>/.test(line)) {
-                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
-                const fullMatch = line.match(/<sheetData\s*\/>/)?.[0] || "";
-                const matchIndex = line.indexOf(fullMatch);
-                const before = line.slice(0, matchIndex);
-                const after = line.slice(matchIndex + fullMatch.length);
-                if (before) {
-                    output.write(before);
-                }
-                // Insert opening tag
-                output.write("<sheetData>");
-                // Prepare the rows
-                await Utils.writeRowsToStream(output, rows, maxRowNumber);
-                // Insert closing tag
-                output.write("</sheetData>");
-                if (after) {
-                    output.write(after);
+                // Case 3: <sheetData>
+                if (!inserted && /<sheetData[^>]*>/.test(line)) {
+                    isCollecting = true;
+                    collection += line;
+                    continue;
                 }
-                inserted = true;
-                continue;
-            }
-            // Case 3: <sheetData>
-            if (!inserted && /<sheetData[^>]*>/.test(line)) {
-                isCollecting = true;
-                collection += line;
-                continue;
+                // After inserting rows, just copy the remaining lines
+                output.write(line);
             }
-            // After inserting rows, just copy the remaining lines
-            output.write(line);
-        }
-        // Close the streams
-        rl.close();
-        output.end();
-        // Move the temporary file to the original location
-        await fs.rename(tempPath, fullPath);
+            // Close the streams
+            rl.close();
+            output.end();
+            // Move the temporary file to the original location
+            await fs.rename(tempPath, fullPath);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
     }
     /**
      * Saves the modified Excel template to a buffer.
@@ -330,15 +576,22 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async save() {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        // Guarantee integrity
-        await this.validate();
-        // Read the current files from the directory(in case they were changed manually)
-        const updatedFiles = await this.#readAllFromDestination();
-        const zipBuffer = await Zip.create(updatedFiles);
-        await this.#cleanup();
-        this.destroyed = true;
-        return zipBuffer;
+        this.#isProcessing = true;
+        try {
+            // Guarantee integrity
+            await this.#validate();
+            // Read the current files from the directory(in case they were changed manually)
+            const updatedFiles = await this.#readAllFromDestination();
+            const zipBuffer = await Zip.create(updatedFiles);
+            await this.#cleanup();
+            this.destroyed = true;
+            return zipBuffer;
+        }
+        finally {
+            this.#isProcessing = false;
+        }
     }
     /**
      * Writes the modified Excel template to a writable stream.
@@ -349,12 +602,19 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async saveStream(output) {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        // Guarantee integrity
-        await this.validate();
-        await Zip.createWithStream(Array.from(this.fileKeys), this.destination, output);
-        await this.#cleanup();
-        this.destroyed = true;
+        this.#isProcessing = true;
+        try {
+            // Guarantee integrity
+            await this.#validate();
+            await Zip.createWithStream(Array.from(this.fileKeys), this.destination, output);
+            await this.#cleanup();
+            this.destroyed = true;
+        }
+        finally {
+            this.#isProcessing = false;
+        }
     }
     /**
      * Replaces the contents of a file in the template.
@@ -367,12 +627,15 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async set(key, content) {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        if (!this.fileKeys.has(key)) {
-            throw new Error(`File "${key}" is not part of the original template.`);
+        this.#isProcessing = true;
+        try {
+            await this.#set(key, content);
+        }
+        finally {
+            this.#isProcessing = false;
         }
-        const fullPath = path.join(this.destination, ...key.split("/"));
-        await fs.writeFile(fullPath, Buffer.isBuffer(content) ? content : Buffer.from(content));
     }
     /**
      * Validates the template by checking all required files exist.
@@ -383,15 +646,14 @@ export class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     async validate() {
+        this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
-        for (const key of this.fileKeys) {
-            const fullPath = path.join(this.destination, ...key.split("/"));
-            try {
-                await fs.access(fullPath);
-            }
-            catch {
-                throw new Error(`Missing file in template directory: ${key}`);
-            }
+        this.#isProcessing = true;
+        try {
+            await this.#validate();
+        }
+        finally {
+            this.#isProcessing = false;
         }
     }
     /**
@@ -426,3 +688,222 @@ export class TemplateFs {
         return new TemplateFs(new Set(Object.keys(files)), destination);
     }
 }
+function processMergeCells(sheetXml) {
+    // Regular expression for finding <mergeCells> block
+    const mergeCellsBlockRegex = /<mergeCells[^>]*>[\s\S]*?<\/mergeCells>/;
+    // Find the first <mergeCells> block (if there are multiple, in xlsx usually there is only one)
+    const mergeCellsBlockMatch = sheetXml.match(mergeCellsBlockRegex);
+    const initialMergeCells = [];
+    const mergeCellMatches = [];
+    if (mergeCellsBlockMatch) {
+        const mergeCellsBlock = mergeCellsBlockMatch[0];
+        initialMergeCells.push(mergeCellsBlock);
+        // Extract <mergeCell ref="A1:B2"/> from this block
+        const mergeCellRegex = /<mergeCell ref="([A-Z]+\d+):([A-Z]+\d+)"\/>/g;
+        for (const match of mergeCellsBlock.matchAll(mergeCellRegex)) {
+            mergeCellMatches.push({ from: match[1], to: match[2] });
+        }
+    }
+    // Remove the <mergeCells> block from the XML
+    const modifiedXml = sheetXml.replace(mergeCellsBlockRegex, "");
+    return {
+        initialMergeCells,
+        mergeCellMatches,
+        modifiedXml,
+    };
+}
+;
+function processSharedStrings(sharedStringsXml) {
+    // Final list of merged cells with all changes
+    const sheetMergeCells = [];
+    // Array for storing shared strings
+    const sharedStrings = [];
+    const sharedStringsHeader = Utils.extractXmlDeclaration(sharedStringsXml);
+    // Map for fast lookup of shared string index by content
+    const sharedIndexMap = new Map();
+    // Regular expression for finding <si> elements (shared string items)
+    const siRegex = /<si>([\s\S]*?)<\/si>/g;
+    // Parse sharedStringsXml and fill sharedStrings and sharedIndexMap
+    for (const match of sharedStringsXml.matchAll(siRegex)) {
+        const content = match[1];
+        if (!content)
+            throw new Error("Shared index not found");
+        const fullSi = `<si>${content}</si>`;
+        sharedIndexMap.set(content, sharedStrings.length);
+        sharedStrings.push(fullSi);
+    }
+    return {
+        sharedIndexMap,
+        sharedStrings,
+        sharedStringsHeader,
+        sheetMergeCells,
+    };
+}
+;
+function processRows(data) {
+    const { mergeCellMatches, replacements, sharedIndexMap, sharedStrings, sheetMergeCells, sheetXml, } = data;
+    const TABLE_REGEX = /\$\{table:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)\}/g;
+    // Array for storing resulting XML rows
+    const resultRows = [];
+    // Previous position of processed part of XML
+    let lastIndex = 0;
+    // Shift for row numbers
+    let rowShift = 0;
+    // Regular expression for finding <row> elements
+    const rowRegex = /<row[^>]*?>[\s\S]*?<\/row>/g;
+    // Process each <row> element
+    for (const match of sheetXml.matchAll(rowRegex)) {
+        // Full XML row
+        const fullRow = match[0];
+        // Start position of the row in XML
+        const matchStart = match.index;
+        // End position of the row in XML
+        const matchEnd = matchStart + fullRow.length;
+        // Add the intermediate XML chunk (if any) between the previous and the current row
+        if (lastIndex !== matchStart) {
+            resultRows.push(sheetXml.slice(lastIndex, matchStart));
+        }
+        lastIndex = matchEnd;
+        // Get row number from r attribute
+        const originalRowNumber = parseInt(fullRow.match(/<row[^>]* r="(\d+)"/)?.[1] ?? "1", 10);
+        // Update row number based on rowShift
+        const shiftedRowNumber = originalRowNumber + rowShift;
+        // Find shared string indexes in cells of the current row
+        const sharedValueIndexes = [];
+        // Regular expression for finding a cell
+        const cellRegex = /<c[^>]*?r="([A-Z]+\d+)"[^>]*?>([\s\S]*?)<\/c>/g;
+        for (const cell of fullRow.matchAll(cellRegex)) {
+            const cellTag = cell[0];
+            // Check if the cell is a shared string
+            const isShared = /t="s"/.test(cellTag);
+            const valueMatch = cellTag.match(/<v>(\d+)<\/v>/);
+            if (isShared && valueMatch) {
+                sharedValueIndexes.push(parseInt(valueMatch[1], 10));
+            }
+        }
+        // Get the text content of shared strings by their indexes
+        const sharedTexts = sharedValueIndexes.map(i => sharedStrings[i]?.replace(/<\/?si>/g, "") ?? "");
+        // Find table placeholders in shared strings
+        const tablePlaceholders = sharedTexts.flatMap(e => [...e.matchAll(TABLE_REGEX)]);
+        // If there are no table placeholders, just shift the row
+        if (tablePlaceholders.length === 0) {
+            const updatedRow = fullRow
+                .replace(/(<row[^>]* r=")(\d+)(")/, `$1${shiftedRowNumber}$3`)
+                .replace(/<c r="([A-Z]+)(\d+)"/g, (_, col) => `<c r="${col}${shiftedRowNumber}"`);
+            resultRows.push(updatedRow);
+            // Update mergeCells for regular row with rowShift
+            const calculatedRowNumber = originalRowNumber + rowShift;
+            for (const { from, to } of mergeCellMatches) {
+                const [, fromCol, fromRow] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, toCol] = to.match(/^([A-Z]+)(\d+)$/);
+                if (Number(fromRow) === calculatedRowNumber) {
+                    const newFrom = `${fromCol}${shiftedRowNumber}`;
+                    const newTo = `${toCol}${shiftedRowNumber}`;
+                    sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+                }
+            }
+            continue;
+        }
+        // Get the table name from the first placeholder
+        const firstMatch = tablePlaceholders[0];
+        const tableName = firstMatch?.[1];
+        if (!tableName)
+            throw new Error("Table name not found");
+        // Get data for replacement from replacements
+        const array = replacements[tableName];
+        if (!array)
+            continue;
+        if (!Array.isArray(array))
+            throw new Error("Table data is not an array");
+        const tableRowStart = shiftedRowNumber;
+        // Find mergeCells to duplicate (mergeCells that start with the current row)
+        const mergeCellsToDuplicate = mergeCellMatches.filter(({ from }) => {
+            const match = from.match(/^([A-Z]+)(\d+)$/);
+            if (!match)
+                return false;
+            // Row number of the merge cell start position is in the second group
+            const rowNumber = match[2];
+            return Number(rowNumber) === tableRowStart;
+        });
+        // Change the current row to multiple rows from the data array
+        for (let i = 0; i < array.length; i++) {
+            const rowData = array[i];
+            let newRow = fullRow;
+            // Replace placeholders in shared strings with real data
+            sharedValueIndexes.forEach((originalIdx, idx) => {
+                const originalText = sharedTexts[idx];
+                if (!originalText)
+                    throw new Error("Shared value not found");
+                // Replace placeholders ${tableName.field} with real data from array data
+                const replacedText = originalText.replace(TABLE_REGEX, (_, tbl, field) => tbl === tableName ? String(rowData?.[field] ?? "") : "");
+                // Add new text to shared strings if it doesn't exist
+                let newIndex;
+                if (sharedIndexMap.has(replacedText)) {
+                    newIndex = sharedIndexMap.get(replacedText);
+                }
+                else {
+                    newIndex = sharedStrings.length;
+                    sharedIndexMap.set(replacedText, newIndex);
+                    sharedStrings.push(`<si>${replacedText}</si>`);
+                }
+                // Replace the shared string index in the cell
+                newRow = newRow.replace(`<v>${originalIdx}</v>`, `<v>${newIndex}</v>`);
+            });
+            // Update row number and cell references
+            const newRowNum = shiftedRowNumber + i;
+            newRow = newRow
+                .replace(/<row[^>]* r="\d+"/, rowTag => rowTag.replace(/r="\d+"/, `r="${newRowNum}"`))
+                .replace(/<c r="([A-Z]+)\d+"/g, (_, col) => `<c r="${col}${newRowNum}"`);
+            resultRows.push(newRow);
+            // Add duplicate mergeCells for new rows
+            for (const { from, to } of mergeCellsToDuplicate) {
+                const [, colFrom, rowFrom] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, colTo, rowTo] = to.match(/^([A-Z]+)(\d+)$/);
+                const newFrom = `${colFrom}${Number(rowFrom) + i}`;
+                const newTo = `${colTo}${Number(rowTo) + i}`;
+                sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+            }
+        }
+        // It increases the row shift by the number of added rows minus one replaced
+        rowShift += array.length - 1;
+        const delta = array.length - 1;
+        const calculatedRowNumber = originalRowNumber + rowShift - array.length + 1;
+        if (delta > 0) {
+            for (const merge of mergeCellMatches) {
+                const fromRow = parseInt(merge.from.match(/\d+$/)[0], 10);
+                if (fromRow > calculatedRowNumber) {
+                    merge.from = merge.from.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                    merge.to = merge.to.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                }
+            }
+        }
+    }
+    return { lastIndex, resultRows, rowShift };
+}
+;
+function processBuild(data) {
+    const { initialMergeCells, lastIndex, mergeCellMatches, resultRows, rowShift, sharedStrings, sharedStringsHeader, sheetMergeCells, sheetXml, } = data;
+    for (const { from, to } of mergeCellMatches) {
+        const [, fromCol, fromRow] = from.match(/^([A-Z]+)(\d+)$/);
+        const [, toCol, toRow] = to.match(/^([A-Z]+)(\d+)$/);
+        const fromRowNum = Number(fromRow);
+        // These rows have already been processed, don't add duplicates
+        if (fromRowNum <= lastIndex)
+            continue;
+        const newFrom = `${fromCol}${fromRowNum + rowShift}`;
+        const newTo = `${toCol}${Number(toRow) + rowShift}`;
+        sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+    }
+    resultRows.push(sheetXml.slice(lastIndex));
+    // Form XML for mergeCells if there are any
+    const mergeXml = sheetMergeCells.length
+        ? `<mergeCells count="${sheetMergeCells.length}">${sheetMergeCells.join("")}</mergeCells>`
+        : initialMergeCells;
+    // Insert mergeCells before the closing sheetData tag
+    const sheetWithMerge = resultRows.join("").replace(/<\/sheetData>/, `</sheetData>${mergeXml}`);
+    // Return modified sheet XML and shared strings
+    return {
+        shared: `${sharedStringsHeader}\n<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="${sharedStrings.length}" uniqueCount="${sharedStrings.length}">${sharedStrings.join("")}</sst>`,
+        sheet: Utils.updateDimension(sheetWithMerge),
+    };
+}