@js-ak/excel-toolbox 1.3.2 → 1.4.1

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

@@ -62,6 +62,11 @@ class TemplateFs {
      * @type {boolean}
      */
     destroyed = false;
+    /**
+     * Flag indicating whether this template instance is currently being processed.
+     * @type {boolean}
+     */
+    #isProcessing = false;
     /**
      * Creates a Template instance.
      *
@@ -93,6 +98,70 @@ 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, } = Utils.processMergeCells(sheetXml);
+        const { sharedIndexMap, sharedStrings, sharedStringsHeader, sheetMergeCells, } = Utils.processSharedStrings(sharedStringsXml);
+        const { lastIndex, resultRows, rowShift } = Utils.processRows({
+            mergeCellMatches,
+            replacements,
+            sharedIndexMap,
+            sharedStrings,
+            sheetMergeCells,
+            sheetXml: modifiedXml,
+        });
+        return Utils.processMergeFinalize({
+            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
@@ -122,6 +191,169 @@ 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.
      *
@@ -137,61 +369,68 @@ 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`);
             }
-            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 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)));
+                }
+                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.
@@ -208,155 +447,162 @@ 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;
+                // After inserting rows, just copy the remaining lines
+                output.write(line);
             }
-            // Case 3: <sheetData>
-            if (!inserted && /<sheetData[^>]*>/.test(line)) {
-                isCollecting = true;
-                collection += line;
-                continue;
-            }
-            // 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);
+        }
+        finally {
+            this.#isProcessing = false;
         }
-        // Close the streams
-        rl.close();
-        output.end();
-        // Move the temporary file to the original location
-        await fs.rename(tempPath, fullPath);
     }
     /**
      * Saves the modified Excel template to a buffer.
@@ -366,15 +612,22 @@ 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.
@@ -385,12 +638,19 @@ 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.
@@ -403,12 +663,15 @@ 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.
@@ -419,15 +682,14 @@ 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;
         }
     }
     /**