@js-ak/excel-toolbox 1.6.0 → 1.8.0

package/build/esm/lib/merge-sheets-to-base-file-process.js

@@ -16,13 +16,13 @@ import * as Xml from "./xml/index.js";
  *
  * The function returns a dictionary of file paths to their corresponding XML content.
  */
-export function mergeSheetsToBaseFileProcess(data) {
+export async function mergeSheetsToBaseFileProcess(data) {
     const { additions, baseFiles, baseSheetIndex, gap, sheetNamesToRemove, sheetsToRemove, } = data;
     const basePath = `xl/worksheets/sheet${baseSheetIndex}.xml`;
     if (!baseFiles[basePath]) {
         throw new Error(`Base file does not contain ${basePath}`);
     }
-    const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, xml, } = Xml.extractRowsFromSheet(baseFiles[basePath]);
+    const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, xml, } = await Xml.extractRowsFromSheet(baseFiles[basePath]);
     const allRows = [...baseRows];
     const allMergeCells = [...baseMergeCells];
     let currentRowOffset = lastRowNumber + gap;
@@ -32,7 +32,7 @@ export function mergeSheetsToBaseFileProcess(data) {
             if (!files[sheetPath]) {
                 throw new Error(`File does not contain ${sheetPath}`);
             }
-            const { mergeCells, rows } = Xml.extractRowsFromSheet(files[sheetPath]);
+            const { mergeCells, rows } = await Xml.extractRowsFromSheet(files[sheetPath]);
             const shiftedRows = Xml.shiftRowIndices(rows, currentRowOffset);
             const shiftedMergeCells = mergeCells.map(cell => {
                 const [start, end] = cell.ref.split(":");

package/build/esm/lib/merge-sheets-to-base-file-sync.js

@@ -1,6 +1,6 @@
 import * as Utils from "./utils/index.js";
 import * as Zip from "./zip/index.js";
-import { mergeSheetsToBaseFileProcess } from "./merge-sheets-to-base-file-process.js";
+import { mergeSheetsToBaseFileProcessSync } from "./merge-sheets-to-base-file-process-sync.js";
 /**
  * Merge rows from other Excel files into a base Excel file.
  * The output is a new Excel file with the merged content.
@@ -29,7 +29,7 @@ export function mergeSheetsToBaseFileSync(data) {
             sheetIndexes,
         });
     }
-    mergeSheetsToBaseFileProcess({
+    mergeSheetsToBaseFileProcessSync({
         additions: additionsUpdated,
         baseFiles,
         baseSheetIndex,

package/build/esm/lib/merge-sheets-to-base-file.js

@@ -29,7 +29,7 @@ export async function mergeSheetsToBaseFile(data) {
             sheetIndexes,
         });
     }
-    mergeSheetsToBaseFileProcess({
+    await mergeSheetsToBaseFileProcess({
         additions: additionsUpdated,
         baseFiles,
         baseSheetIndex,

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

@@ -53,6 +53,7 @@ export class TemplateFs {
         this.fileKeys = fileKeys;
         this.destination = destination;
     }
+    /** Private methods */
     /**
      * Removes the temporary directory created by this Template instance.
      * @private
@@ -126,13 +127,13 @@ export class TemplateFs {
      */
     async #getSheetPathByName(sheetName) {
         // Read XML workbook to find sheet name and path
-        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile(this.#excelKeys.workbook));
+        const workbookXml = await Xml.extractXmlFromSheet(await this.#readFile(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 = Xml.extractXmlFromSheet(await this.#readFile(this.#excelKeys.workbookRels));
+        const relsXml = await Xml.extractXmlFromSheet(await this.#readFile(this.#excelKeys.workbookRels));
         const relMatch = relsXml.match(Utils.relationshipMatch(rId));
         if (!relMatch || !relMatch[1]) {
             throw new Error(`Relationship "${rId}" not found`);
@@ -185,16 +186,30 @@ export class TemplateFs {
         const fullPath = path.join(this.destination, ...key.split("/"));
         await fs.writeFile(fullPath, Buffer.isBuffer(content) ? content : Buffer.from(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 = this.#excelKeys.sharedStrings;
         const sheetPath = await this.#getSheetPathByName(sheetName);
         let sharedStringsContent = "";
         let sheetContent = "";
         if (this.fileKeys.has(sharedStringsPath)) {
-            sharedStringsContent = Xml.extractXmlFromSheet(await this.#readFile(sharedStringsPath));
+            sharedStringsContent = await Xml.extractXmlFromSheet(await this.#readFile(sharedStringsPath));
         }
         if (this.fileKeys.has(sheetPath)) {
-            sheetContent = Xml.extractXmlFromSheet(await this.#readFile(sheetPath));
+            sheetContent = await 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) {
@@ -212,6 +227,54 @@ export class TemplateFs {
             await this.#set(sheetPath, sheetContent);
         }
     }
+    /**
+     * 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.
+     */
+    async #removeSheets(data) {
+        const { sheetIndexes = [], sheetNames = [] } = data;
+        // first get index of sheets to remove
+        const sheetIndexesToRemove = new Set(sheetIndexes);
+        for (const sheetName of sheetNames) {
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetIndexMatch = sheetPath.match(/sheet(\d+)\.xml$/);
+            if (!sheetIndexMatch || !sheetIndexMatch[1]) {
+                throw new Error(`Sheet "${sheetName}" not found`);
+            }
+            const sheetIndex = parseInt(sheetIndexMatch[1], 10);
+            sheetIndexesToRemove.add(sheetIndex);
+        }
+        // Remove sheets by index
+        for (const sheetIndex of sheetIndexesToRemove.values()) {
+            const sheetPath = `xl/worksheets/sheet${sheetIndex}.xml`;
+            if (!this.fileKeys.has(sheetPath)) {
+                continue;
+            }
+            // remove sheet file
+            await fs.unlink(path.join(this.destination, ...sheetPath.split("/")));
+            this.fileKeys.delete(sheetPath);
+            // remove sheet from workbook
+            if (this.fileKeys.has(this.#excelKeys.workbook)) {
+                this.#set(this.#excelKeys.workbook, Buffer.from(Utils.Common.removeSheetFromWorkbook(this.#readFile(this.#excelKeys.workbook).toString(), sheetIndex)));
+            }
+            // remove sheet from workbook relations
+            if (this.fileKeys.has(this.#excelKeys.workbookRels)) {
+                this.#set(this.#excelKeys.workbookRels, Buffer.from(Utils.Common.removeSheetFromRels(this.#readFile(this.#excelKeys.workbookRels).toString(), sheetIndex)));
+            }
+            // remove sheet from content types
+            if (this.fileKeys.has(this.#excelKeys.contentTypes)) {
+                this.#set(this.#excelKeys.contentTypes, Buffer.from(Utils.Common.removeSheetFromContentTypes(this.#readFile(this.#excelKeys.contentTypes).toString(), sheetIndex)));
+            }
+        }
+    }
     /**
      * Validates the template by checking all required files exist.
      *
@@ -231,6 +294,7 @@ export class TemplateFs {
             }
         }
     }
+    /** Public methods */
     /**
      * Copies a sheet from the template to a new name.
      *
@@ -251,7 +315,7 @@ export class TemplateFs {
             }
             // Read workbook.xml and find the source sheet
             const workbookXmlPath = this.#excelKeys.workbook;
-            const workbookXml = Xml.extractXmlFromSheet(await this.#readFile(workbookXmlPath));
+            const workbookXml = await Xml.extractXmlFromSheet(await this.#readFile(workbookXmlPath));
             // Find the source sheet
             const sheetMatch = workbookXml.match(Utils.sheetMatch(sourceName));
             if (!sheetMatch || !sheetMatch[1]) {
@@ -265,7 +329,7 @@ export class TemplateFs {
             // Find the source sheet path by rId
             const rId = sheetMatch[1];
             const relsXmlPath = this.#excelKeys.workbookRels;
-            const relsXml = Xml.extractXmlFromSheet(await this.#readFile(relsXmlPath));
+            const relsXml = await Xml.extractXmlFromSheet(await this.#readFile(relsXmlPath));
             const relMatch = relsXml.match(Utils.relationshipMatch(rId));
             if (!relMatch || !relMatch[1]) {
                 throw new Error(`Relationship "${rId}" not found`);
@@ -300,7 +364,7 @@ export class TemplateFs {
             // Read [Content_Types].xml
             // Update [Content_Types].xml
             const contentTypesPath = this.#excelKeys.contentTypes;
-            const contentTypesXml = Xml.extractXmlFromSheet(await this.#readFile(contentTypesPath));
+            const contentTypesXml = await 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);
@@ -321,12 +385,12 @@ export class TemplateFs {
      * @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) {
+    async substitute(sheetName, replacements) {
         this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
-            return this.#substitute(sheetName, replacements);
+            await this.#substitute(sheetName, replacements);
         }
         finally {
             this.#isProcessing = false;
@@ -359,7 +423,7 @@ export class TemplateFs {
             // Find the sheet
             const sheetPath = await this.#getSheetPathByName(sheetName);
             const sheetXmlRaw = await this.#readFile(sheetPath);
-            const sheetXml = Xml.extractXmlFromSheet(sheetXmlRaw);
+            const sheetXml = await Xml.extractXmlFromSheet(sheetXmlRaw);
             let nextRow = 0;
             if (!startRowNumber) {
                 // Find the last row
@@ -488,7 +552,7 @@ export class TemplateFs {
                             }
                         }
                         const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
-                        if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                        if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
                             dimension.maxColumn = newDimension.maxColumn;
                         }
                         if (newDimension.maxRow > dimension.maxRow) {
@@ -535,7 +599,7 @@ export class TemplateFs {
                     }
                     // new <row>
                     const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
-                    if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                    if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
                         dimension.maxColumn = newDimension.maxColumn;
                     }
                     if (newDimension.maxRow > dimension.maxRow) {
@@ -568,7 +632,7 @@ export class TemplateFs {
                     output.write("<sheetData>");
                     // Prepare the rows
                     const { dimension: newDimension } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
-                    if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                    if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
                         dimension.maxColumn = newDimension.maxColumn;
                     }
                     if (newDimension.maxRow > dimension.maxRow) {
@@ -635,6 +699,25 @@ export class TemplateFs {
             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}
+     */
+    async removeSheets(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            await this.#removeSheets(data);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
     /**
      * Saves the modified Excel template to a buffer.
      *
@@ -723,6 +806,7 @@ export class TemplateFs {
             this.#isProcessing = false;
         }
     }
+    /** Static methods */
     /**
      * Creates a Template instance from an Excel file source.
      * Removes any existing files in the destination directory.
@@ -760,8 +844,3 @@ export class TemplateFs {
         return new TemplateFs(new Set(Object.keys(files)), destinationWithUuid);
     }
 }
-const compareColumns = (a, b) => {
-    if (a === b)
-        return 0;
-    return a.length === b.length ? (a < b ? -1 : 1) : (a.length < b.length ? -1 : 1);
-};

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

@@ -40,6 +40,7 @@ export class TemplateMemory {
     constructor(files) {
         this.files = files;
     }
+    /** Private methods */
     /**
      * Ensures that this Template instance has not been destroyed.
      * @private
@@ -104,7 +105,7 @@ export class TemplateMemory {
      * @throws {Error} If the file key is not found.
      * @experimental This API is experimental and might change in future versions.
      */
-    #extractXmlFromSheet(fileKey) {
+    async #extractXmlFromSheet(fileKey) {
         if (!this.files[fileKey]) {
             throw new Error(`${fileKey} not found`);
         }
@@ -122,7 +123,7 @@ export class TemplateMemory {
      * @throws {Error} If the file key is not found
      * @experimental This API is experimental and might change in future versions.
      */
-    #extractRowsFromSheet(fileKey) {
+    async #extractRowsFromSheet(fileKey) {
         if (!this.files[fileKey]) {
             throw new Error(`${fileKey} not found`);
         }
@@ -136,15 +137,15 @@ export class TemplateMemory {
      * @throws {Error} If the sheet with the given name does not exist.
      * @experimental This API is experimental and might change in future versions.
      */
-    #getSheetPathByName(sheetName) {
+    async #getSheetPathByName(sheetName) {
         // Find the sheet
-        const workbookXml = this.#extractXmlFromSheet(this.#excelKeys.workbook);
+        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.#extractXmlFromSheet(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`);
@@ -197,11 +198,11 @@ export class TemplateMemory {
         let sharedStringsContent = "";
         let sheetContent = "";
         if (this.files[sharedStringsPath]) {
-            sharedStringsContent = this.#extractXmlFromSheet(sharedStringsPath);
+            sharedStringsContent = await this.#extractXmlFromSheet(sharedStringsPath);
         }
-        const sheetPath = this.#getSheetPathByName(sheetName);
+        const sheetPath = await this.#getSheetPathByName(sheetName);
         if (this.files[sheetPath]) {
-            sheetContent = this.#extractXmlFromSheet(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) {
@@ -236,11 +237,11 @@ export class TemplateMemory {
      * @throws {Error} If no sheets are found to merge.
      * @experimental This API is experimental and might change in future versions.
      */
-    #mergeSheets(data) {
+    async #mergeSheets(data) {
         const { additions, baseSheetIndex = 1, baseSheetName, gap = 0, } = data;
         let fileKey = "";
         if (baseSheetName) {
-            fileKey = this.#getSheetPathByName(baseSheetName);
+            fileKey = await this.#getSheetPathByName(baseSheetName);
         }
         if (baseSheetIndex && !fileKey) {
             if (baseSheetIndex < 1) {
@@ -251,16 +252,16 @@ export class TemplateMemory {
         if (!fileKey) {
             throw new Error("Base sheet not found");
         }
-        const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, xml, } = this.#extractRowsFromSheet(fileKey);
+        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(...(additions.sheetIndexes).map(e => this.#getSheetPathById(e)));
+            sheetPaths.push(...(await Promise.all(additions.sheetIndexes.map(e => this.#getSheetPathById(e)))));
         }
         if (additions.sheetNames) {
-            sheetPaths.push(...(additions.sheetNames).map(e => this.#getSheetPathByName(e)));
+            sheetPaths.push(...(await Promise.all(additions.sheetNames.map(e => this.#getSheetPathByName(e)))));
         }
         if (sheetPaths.length === 0) {
             throw new Error("No sheets found to merge");
@@ -269,7 +270,7 @@ export class TemplateMemory {
             if (!this.files[sheetPath]) {
                 throw new Error(`Sheet "${sheetPath}" not found`);
             }
-            const { mergeCells, rows } = Xml.extractRowsFromSheet(this.files[sheetPath]);
+            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(":");
@@ -299,28 +300,45 @@ export class TemplateMemory {
      * @throws {Error} If the sheet does not exist.
      * @experimental This API is experimental and might change in future versions.
      */
-    #removeSheets(data) {
+    async #removeSheets(data) {
         const { sheetIndexes = [], sheetNames = [] } = data;
-        for (const sheetIndex of sheetIndexes) {
+        // first get index of sheets to remove
+        const sheetIndexesToRemove = new Set(sheetIndexes);
+        for (const sheetName of sheetNames) {
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetIndexMatch = sheetPath.match(/sheet(\d+)\.xml$/);
+            if (!sheetIndexMatch || !sheetIndexMatch[1]) {
+                throw new Error(`Sheet "${sheetName}" not found`);
+            }
+            const sheetIndex = parseInt(sheetIndexMatch[1], 10);
+            sheetIndexesToRemove.add(sheetIndex);
+        }
+        // Remove sheets by index
+        for (const sheetIndex of sheetIndexesToRemove.values()) {
             const sheetPath = `xl/worksheets/sheet${sheetIndex}.xml`;
             if (!this.files[sheetPath]) {
                 continue;
             }
+            // remove sheet file
             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));
+            // remove sheet from workbook
+            const workbook = this.files[this.#excelKeys.workbook];
+            if (workbook) {
+                this.files[this.#excelKeys.workbook] = Buffer.from(Utils.Common.removeSheetFromWorkbook(workbook.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));
+            // remove sheet from workbook relations
+            const workbookRels = this.files[this.#excelKeys.workbookRels];
+            if (workbookRels) {
+                this.files[this.#excelKeys.workbookRels] = Buffer.from(Utils.Common.removeSheetFromRels(workbookRels.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));
+            // remove sheet from content types
+            const contentTypes = this.files[this.#excelKeys.contentTypes];
+            if (contentTypes) {
+                this.files[this.#excelKeys.contentTypes] = Buffer.from(Utils.Common.removeSheetFromContentTypes(contentTypes.toString(), sheetIndex));
             }
         }
-        for (const sheetName of sheetNames) {
-            Utils.Common.removeSheetByName(this.files, sheetName);
-        }
     }
+    /** Public methods */
     /**
      * Copies a sheet from the template to a new name.
      *
@@ -341,7 +359,7 @@ export class TemplateMemory {
             }
             // Read workbook.xml and find the source sheet
             const workbookXmlPath = this.#excelKeys.workbook;
-            const workbookXml = this.#extractXmlFromSheet(this.#excelKeys.workbook);
+            const workbookXml = await this.#extractXmlFromSheet(this.#excelKeys.workbook);
             // Find the source sheet
             const sheetMatch = workbookXml.match(Utils.sheetMatch(sourceName));
             if (!sheetMatch || !sheetMatch[1]) {
@@ -355,7 +373,7 @@ export class TemplateMemory {
             // Find the source sheet path by rId
             const rId = sheetMatch[1];
             const relsXmlPath = this.#excelKeys.workbookRels;
-            const relsXml = this.#extractXmlFromSheet(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`);
@@ -397,7 +415,7 @@ export class TemplateMemory {
             // Read [Content_Types].xml
             // Update [Content_Types].xml
             const contentTypesPath = "[Content_Types].xml";
-            const contentTypesXml = this.#extractXmlFromSheet(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));
@@ -418,12 +436,12 @@ export class TemplateMemory {
      * @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) {
+    async substitute(sheetName, replacements) {
         this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
-            return this.#substitute(sheetName, replacements);
+            await this.#substitute(sheetName, replacements);
         }
         finally {
             this.#isProcessing = false;
@@ -454,8 +472,8 @@ export class TemplateMemory {
             Utils.checkStartRow(startRowNumber);
             Utils.checkRows(preparedRows);
             // Find the sheet
-            const sheetPath = this.#getSheetPathByName(sheetName);
-            const sheetXml = this.#extractXmlFromSheet(sheetPath);
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetXml = await this.#extractXmlFromSheet(sheetPath);
             let nextRow = 0;
             if (!startRowNumber) {
                 // Find the last row
@@ -489,7 +507,7 @@ export class TemplateMemory {
             else {
                 updatedXml = sheetXml.replace(/<worksheet[^>]*>/, (match) => `${match}<sheetData>${rowsXml}</sheetData>`);
             }
-            await this.#set(sheetPath, Buffer.from(updatedXml));
+            await this.#set(sheetPath, Buffer.from(Utils.updateDimension(updatedXml)));
         }
         finally {
             this.#isProcessing = false;
@@ -518,10 +536,30 @@ export class TemplateMemory {
             if (!sheetName)
                 throw new Error("Sheet name is required");
             // Read XML workbook to find sheet name and path
-            const sheetPath = this.#getSheetPathByName(sheetName);
-            const sheetXml = this.#extractXmlFromSheet(sheetPath);
+            const sheetPath = await this.#getSheetPathByName(sheetName);
+            const sheetXml = await this.#extractXmlFromSheet(sheetPath);
             const output = new MemoryWriteStream();
             let inserted = false;
+            const initialDimension = sheetXml.match(/<dimension\s+ref="[^"]*"/)?.[0] || "";
+            const dimension = {
+                maxColumn: "A",
+                maxRow: 1,
+                minColumn: "A",
+                minRow: 1,
+            };
+            if (initialDimension) {
+                const dimensionMatch = initialDimension.match(/<dimension\s+ref="([^"]*)"/);
+                if (dimensionMatch) {
+                    const dimensionRef = dimensionMatch[1];
+                    if (dimensionRef) {
+                        const [min, max] = dimensionRef.split(":");
+                        dimension.minColumn = min.slice(0, 1);
+                        dimension.minRow = parseInt(min.slice(1));
+                        dimension.maxColumn = max.slice(0, 1);
+                        dimension.maxRow = parseInt(max.slice(1));
+                    }
+                }
+            }
             // --- Case 1: <sheetData>...</sheetData> on one line ---
             const singleLineMatch = sheetXml.match(/(<sheetData[^>]*>)(.*)(<\/sheetData>)/);
             if (!inserted && singleLineMatch) {
@@ -542,7 +580,13 @@ export class TemplateMemory {
                         output.write(innerRows);
                     }
                 }
-                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                    dimension.maxColumn = newDimension.maxColumn;
+                }
+                if (newDimension.maxRow > dimension.maxRow) {
+                    dimension.maxRow = newDimension.maxRow;
+                }
                 if (innerRows) {
                     const filtered = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
                     if (filtered)
@@ -559,7 +603,13 @@ export class TemplateMemory {
                 const matchIndex = match.index;
                 output.write(sheetXml.slice(0, matchIndex));
                 output.write("<sheetData>");
-                await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                const { dimension: newDimension } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                    dimension.maxColumn = newDimension.maxColumn;
+                }
+                if (newDimension.maxRow > dimension.maxRow) {
+                    dimension.maxRow = newDimension.maxRow;
+                }
                 output.write("</sheetData>");
                 output.write(sheetXml.slice(matchIndex + match[0].length));
                 inserted = true;
@@ -590,7 +640,13 @@ export class TemplateMemory {
                         output.write(innerRows);
                     }
                 }
-                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, Utils.getMaxRowNumber(innerRows));
+                const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, Utils.getMaxRowNumber(innerRows));
+                if (Utils.compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                    dimension.maxColumn = newDimension.maxColumn;
+                }
+                if (newDimension.maxRow > dimension.maxRow) {
+                    dimension.maxRow = newDimension.maxRow;
+                }
                 if (innerRows) {
                     const filtered = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
                     if (filtered)
@@ -602,8 +658,18 @@ export class TemplateMemory {
             }
             if (!inserted)
                 throw new Error("Failed to locate <sheetData> for insertion");
+            let result = output.toBuffer();
+            // update dimension
+            {
+                const target = initialDimension;
+                const refRange = `${dimension.minColumn}${dimension.minRow}:${dimension.maxColumn}${dimension.maxRow}`;
+                const replacement = `<dimension ref="${refRange}"`;
+                if (target) {
+                    result = Buffer.from(result.toString().replace(target, replacement));
+                }
+            }
             // Save the buffer to the sheet
-            this.files[sheetPath] = output.toBuffer();
+            this.files[sheetPath] = result;
         }
         finally {
             this.#isProcessing = false;
@@ -666,12 +732,12 @@ export class TemplateMemory {
      * @param {number} [data.gap=0] - The number of empty rows to insert between each added section.
      * @returns {void}
      */
-    mergeSheets(data) {
+    async mergeSheets(data) {
         this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
-            this.#mergeSheets(data);
+            await this.#mergeSheets(data);
         }
         finally {
             this.#isProcessing = false;
@@ -685,17 +751,18 @@ export class TemplateMemory {
      * @param {string[]} [data.sheetNames] - The names of the sheets to remove.
      * @returns {void}
      */
-    removeSheets(data) {
+    async removeSheets(data) {
         this.#ensureNotProcessing();
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
-            this.#removeSheets(data);
+            await this.#removeSheets(data);
         }
         finally {
             this.#isProcessing = false;
         }
     }
+    /** Static methods */
     /**
      * Creates a Template instance from an Excel file source.
      *

package/build/esm/lib/template/utils/compare-columns.js

@@ -0,0 +1,13 @@
+/**
+ * Compares two column strings and returns a number indicating their relative order.
+ *
+ * @param a - The first column string to compare.
+ * @param b - The second column string to compare.
+ * @returns 0 if the columns are equal, -1 if the first column is less than the second, or 1 if the first column is greater than the second.
+ */
+export function compareColumns(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a.length === b.length ? (a < b ? -1 : 1) : (a.length < b.length ? -1 : 1);
+}

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

@@ -4,6 +4,7 @@ export * from "./check-row.js";
 export * from "./check-rows.js";
 export * from "./check-start-row.js";
 export * from "./column-index-to-letter.js";
+export * from "./compare-columns.js";
 export * from "./escape-xml.js";
 export * from "./extract-xml-declaration.js";
 export * from "./get-by-path.js";