@js-ak/excel-toolbox 1.4.1 → 1.6.0

package/README.md

@@ -2,100 +2,79 @@
 
 ![ci-cd](https://github.com/JS-AK/excel-toolbox/actions/workflows/ci-cd-master.yml/badge.svg)
 
-A lightweight toolkit for merging sheets from multiple `.xlsx` Excel files without dependencies.
+📘 **Docs:** [js-ak.github.io/excel-toolbox](https://js-ak.github.io/excel-toolbox/)
 
-## Installation
+A lightweight toolkit for working with `.xlsx` Excel files — modify templates, merge sheets, and handle massive datasets without dependencies.
 
-You can install the package via npm:
+## Installation
 
 ```bash
 npm install @js-ak/excel-toolbox
 ```
 
-## Getting Started
-
-To merge rows from multiple Excel files into one:
+## Features
 
-```ts
-import fs from "node:fs";
-import { mergeSheetsToBaseFileSync } from "@js-ak/excel-toolbox";
+- ✨ Work with templates using `TemplateFs` (filesystem) or `TemplateMemory` (in-memory)
+- 📥 Insert and stream rows into Excel files
+- 🧩 Merge sheets from multiple `.xlsx` files
+- 🧼 Remove sheets by name or index
+- 💎 Preserve styles, merges, and shared strings
 
-const baseFile = fs.readFileSync("base.xlsx");
-const otherFile = fs.readFileSync("data.xlsx");
+## Template API
 
-const resultBuffer = mergeSheetsToBaseFileSync({
-  baseFile,
-  additions: [
-    { file: otherFile, sheetIndexes: [1] }
-  ],
-  gap: 2,
-});
+### `TemplateFs` and `TemplateMemory`
 
-fs.writeFileSync("output.xlsx", resultBuffer);
-```
+Both classes provide the same API for modifying Excel templates.
 
-## Features
+#### Common Features
 
-- 🧩 **Merge sheets** from multiple Excel files
-- 🧼 **Clean sheet removal** — by name or index
-- 📎 **Keeps styles and merged cells**
-- 🍃 **Lightweight ZIP and XML handling**
+- `substitute()` — replace placeholders like `${name}` or `${table:name}`
+- `insertRows()` / `insertRowsStream()` — insert rows statically or via stream
+- `copySheet()` — duplicate existing sheets
+- `validate()` and `save()` / `saveStream()` — output the result
 
-## API
+```ts
+import { TemplateFs } from "@js-ak/excel-toolbox";
 
-### `mergeSheetsToBaseFileSync(options): Buffer`
+const template = await TemplateFs.from({
+  destination: "/tmp/template",
+  source: fs.readFileSync("template.xlsx"),
+});
 
-#### Parameters
+await template.substitute("Sheet1", { name: "Alice" });
+await template.insertRows({ sheetName: "Sheet1", rows: [["Data"]] });
+const buffer = await template.save();
+fs.writeFileSync("output.xlsx", buffer);
+```
 
-| Name                  | Type                                                               | Description                                    |
-|-----------------------|--------------------------------------------------------------------|------------------------------------------------|
-| `baseFile`            | `Buffer`                                                           | The base Excel file.                           |
-| `additions`           | `{ file: Buffer; sheetIndexes: number[]; isBaseFile?: boolean }[]` | Files and sheet indices to merge.              |
-| `baseSheetIndex`      | `number` (default: `1`)                                            | The sheet index in the base file to append to. |
-| `gap`                 | `number` (default: `0`)                                            | Empty rows inserted between merged blocks.     |
-| `sheetNamesToRemove`  | `string[]` (default: `[]`)                                         | Sheets to remove by name.                      |
-| `sheetsToRemove`      | `number[]` (default: `[]`)                                         | Sheets to remove by index (1-based).           |
+## Sheet Merging API
 
-#### Returns
+### `mergeSheetsToBaseFileSync(options): Buffer`
 
-`Buffer` — the merged Excel file.
+Synchronously merges sheets into a base file.
 
 ### `mergeSheetsToBaseFile(options): Promise<Buffer>`
 
-Asynchronous version of `mergeSheetsToBaseFileSync`.
-
-#### Parameters
-
-Same as [`mergeSheetsToBaseFileSync`](#mergesheetstobasefilesyncoptions).
-
-#### Returns
-
-`Promise<Buffer>` — resolves with the merged Excel file.
+Async version of the above.
 
 #### Example
 
 ```ts
-import fs from "node:fs/promises";
-import { mergeSheetsToBaseFile } from "@js-ak/excel-toolbox";
+import fs from "node:fs";
+import { mergeSheetsToBaseFileSync } from "@js-ak/excel-toolbox";
 
-const baseFile = await fs.readFile("base.xlsx");
-const otherFile = await fs.readFile("data.xlsx");
+const baseFile = fs.readFileSync("base.xlsx");
+const dataFile = fs.readFileSync("data.xlsx");
 
-const output = await mergeSheetsToBaseFile({
+const result = mergeSheetsToBaseFileSync({
   baseFile,
-  additions: [
-    { file: otherFile, sheetIndexes: [1] }
-  ],
-  gap: 1,
+  additions: [{ file: dataFile, sheetIndexes: [1] }],
+  gap: 2,
 });
 
-await fs.writeFile("output.xlsx", output);
+fs.writeFileSync("output.xlsx", result);
 ```
 
-## Contributing
-
-Contributions are welcome! Feel free to open an issue or submit a pull request if you have ideas or encounter bugs.
-
 ## License
 
-MIT — see [LICENSE](./LICENSE) for details.
+MIT — see [LICENSE](./LICENSE)

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

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./template-fs.js"), exports);
+__exportStar(require("./template-memory.js"), exports);

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryWriteStream = void 0;
+class MemoryWriteStream {
+    chunks = [];
+    write(chunk) {
+        this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf-8"));
+        return true;
+    }
+    end() {
+        // no-op
+    }
+    toBuffer() {
+        return Buffer.concat(this.chunks);
+    }
+}
+exports.MemoryWriteStream = MemoryWriteStream;

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

@@ -32,12 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TemplateFs = void 0;
 const fs = __importStar(require("node:fs/promises"));
 const fsSync = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const readline = __importStar(require("node:readline"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const Xml = __importStar(require("../xml/index.js"));
 const Zip = __importStar(require("../zip/index.js"));
 const Utils = __importStar(require("./utils/index.js"));
@@ -67,6 +71,16 @@ class TemplateFs {
      * @type {boolean}
      */
     #isProcessing = false;
+    /**
+     * The keys for the Excel files in the template.
+     */
+    #excelKeys = {
+        contentTypes: "[Content_Types].xml",
+        sharedStrings: "xl/sharedStrings.xml",
+        styles: "xl/styles.xml",
+        workbook: "xl/workbook.xml",
+        workbookRels: "xl/_rels/workbook.xml.rels",
+    };
     /**
      * Creates a Template instance.
      *
@@ -149,17 +163,19 @@ class TemplateFs {
      * @returns The path of the sheet inside the workbook.
      * @throws {Error} If the sheet is not found.
      */
-    async #getSheetPath(sheetName) {
+    async #getSheetPathByName(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)
+        const workbookXml = 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("xl/_rels/workbook.xml.rels"));
-        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
-        if (!relMatch)
+        const relsXml = 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`);
+        }
         return "xl/" + relMatch[1].replace(/^\/?xl\//, "");
     }
     /**
@@ -209,8 +225,8 @@ class TemplateFs {
         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);
+        const sharedStringsPath = this.#excelKeys.sharedStrings;
+        const sheetPath = await this.#getSheetPathByName(sheetName);
         let sharedStringsContent = "";
         let sheetContent = "";
         if (this.fileKeys.has(sharedStringsPath)) {
@@ -269,30 +285,31 @@ class TemplateFs {
         this.#ensureNotDestroyed();
         this.#isProcessing = true;
         try {
+            if (sourceName === newName) {
+                throw new Error("Source and new sheet names cannot be the same");
+            }
             // Read workbook.xml and find the source sheet
-            const workbookXmlPath = "xl/workbook.xml";
+            const workbookXmlPath = this.#excelKeys.workbook;
             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)
+            const sheetMatch = workbookXml.match(Utils.sheetMatch(sourceName));
+            if (!sheetMatch || !sheetMatch[1]) {
                 throw new Error(`Sheet "${sourceName}" not found`);
-            const sourceRId = sheetMatch[1];
+            }
             // Check if a sheet with the new name already exists
             if (new RegExp(`<sheet[^>]+name="${newName}"`).test(workbookXml)) {
                 throw new Error(`Sheet "${newName}" already exists`);
             }
             // Read workbook.rels
             // Find the source sheet path by rId
-            const relsXmlPath = "xl/_rels/workbook.xml.rels";
+            const rId = sheetMatch[1];
+            const relsXmlPath = this.#excelKeys.workbookRels;
             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 relMatch = relsXml.match(Utils.relationshipMatch(rId));
+            if (!relMatch || !relMatch[1]) {
+                throw new Error(`Relationship "${rId}" not found`);
+            }
             const sourceTarget = relMatch[1]; // sheetN.xml
-            if (!sourceTarget)
-                throw new Error(`Relationship "${sourceRId}" not found`);
             const sourceSheetPath = "xl/" + sourceTarget.replace(/^\/?.*xl\//, "");
             // Get the index of the new sheet
             const sheetNumbers = [...this.fileKeys]
@@ -321,7 +338,7 @@ class TemplateFs {
             await this.#set(relsXmlPath, updatedRelsXml);
             // Read [Content_Types].xml
             // Update [Content_Types].xml
-            const contentTypesPath = "[Content_Types].xml";
+            const contentTypesPath = this.#excelKeys.contentTypes;
             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>");
@@ -379,18 +396,7 @@ class TemplateFs {
             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 sheetPath = await this.#getSheetPathByName(sheetName);
             const sheetXmlRaw = await this.#readFile(sheetPath);
             const sheetXml = Xml.extractXmlFromSheet(sheetXmlRaw);
             let nextRow = 0;
@@ -426,7 +432,7 @@ class TemplateFs {
             else {
                 updatedXml = sheetXml.replace(/<worksheet[^>]*>/, (match) => `${match}<sheetData>${rowsXml}</sheetData>`);
             }
-            await this.#set(sheetPath, updatedXml);
+            await this.#set(sheetPath, Utils.updateDimension(updatedXml));
         }
         finally {
             this.#isProcessing = false;
@@ -454,18 +460,8 @@ class TemplateFs {
             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\//, "");
+            // Get the path to the sheet
+            const sheetPath = await this.#getSheetPathByName(sheetName);
             // The temporary file for writing
             const fullPath = path.join(this.destination, ...sheetPath.split("/"));
             const tempPath = fullPath + ".tmp";
@@ -474,6 +470,13 @@ class TemplateFs {
             const output = fsSync.createWriteStream(tempPath, { encoding: "utf-8" });
             // Inserted rows flag
             let inserted = false;
+            let initialDimension = "";
+            const dimension = {
+                maxColumn: "A",
+                maxRow: 1,
+                minColumn: "A",
+                minRow: 1,
+            };
             const rl = readline.createInterface({
                 // Process all line breaks
                 crlfDelay: Infinity,
@@ -482,6 +485,21 @@ class TemplateFs {
             let isCollecting = false;
             let collection = "";
             for await (const line of rl) {
+                // Process <dimension>
+                if (!initialDimension && /<dimension\s+ref="[^"]*"/.test(line)) {
+                    const dimensionMatch = line.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));
+                        }
+                        initialDimension = line.match(/<dimension\s+ref="[^"]*"/)?.[0] || "";
+                    }
+                }
                 // Collect lines between <sheetData> and </sheetData>
                 if (!inserted && isCollecting) {
                     collection += line;
@@ -508,7 +526,13 @@ class TemplateFs {
                                 output.write(innerRows);
                             }
                         }
-                        const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                        const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                        if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                            dimension.maxColumn = newDimension.maxColumn;
+                        }
+                        if (newDimension.maxRow > dimension.maxRow) {
+                            dimension.maxRow = newDimension.maxRow;
+                        }
                         if (innerRows) {
                             const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
                             if (filteredRows)
@@ -549,7 +573,13 @@ class TemplateFs {
                         }
                     }
                     // new <row>
-                    const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    const { dimension: newDimension, rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                        dimension.maxColumn = newDimension.maxColumn;
+                    }
+                    if (newDimension.maxRow > dimension.maxRow) {
+                        dimension.maxRow = newDimension.maxRow;
+                    }
                     if (innerRows) {
                         const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
                         if (filteredRows) {
@@ -576,7 +606,13 @@ class TemplateFs {
                     // Insert opening tag
                     output.write("<sheetData>");
                     // Prepare the rows
-                    await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    const { dimension: newDimension } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    if (compareColumns(newDimension.maxColumn, dimension.maxColumn) > 0) {
+                        dimension.maxColumn = newDimension.maxColumn;
+                    }
+                    if (newDimension.maxRow > dimension.maxRow) {
+                        dimension.maxRow = newDimension.maxRow;
+                    }
                     // Insert closing tag
                     output.write("</sheetData>");
                     if (after) {
@@ -597,8 +633,42 @@ class TemplateFs {
             // Close the streams
             rl.close();
             output.end();
-            // Move the temporary file to the original location
-            await fs.rename(tempPath, fullPath);
+            // update dimension
+            {
+                const target = initialDimension;
+                const refRange = `${dimension.minColumn}${dimension.minRow}:${dimension.maxColumn}${dimension.maxRow}`;
+                const replacement = `<dimension ref="${refRange}"`;
+                let buffer = "";
+                let replaced = false;
+                const input = fsSync.createReadStream(tempPath, { encoding: "utf8" });
+                const output = fsSync.createWriteStream(fullPath);
+                await new Promise((resolve, reject) => {
+                    input.on("data", chunk => {
+                        buffer += chunk;
+                        if (!replaced) {
+                            const index = buffer.indexOf(target);
+                            if (index !== -1) {
+                                // Заменяем только первое вхождение
+                                buffer = buffer.replace(target, replacement);
+                                replaced = true;
+                            }
+                        }
+                        output.write(buffer);
+                        buffer = ""; // очищаем, т.к. мы уже записали
+                    });
+                    input.on("error", reject);
+                    output.on("error", reject);
+                    input.on("end", () => {
+                        // на всякий случай дописываем остаток
+                        if (buffer) {
+                            output.write(buffer);
+                        }
+                        output.end();
+                        resolve(true);
+                    });
+                });
+            }
+            await fs.unlink(tempPath);
         }
         finally {
             this.#isProcessing = false;
@@ -699,29 +769,39 @@ class TemplateFs {
      * @param {Object} data - The data to create the template from.
      * @param {string} data.source - The path or buffer of the Excel file.
      * @param {string} data.destination - The path to save the template to.
+     * @param {boolean} data.isUniqueDestination - Whether to add a random UUID to the destination path.
      * @returns {Promise<Template>} A new Template instance.
      * @throws {Error} If reading or writing files fails.
      * @experimental This API is experimental and might change in future versions.
      */
     static async from(data) {
-        const { destination, source } = data;
+        const { destination, isUniqueDestination = true, source } = data;
         if (!destination) {
             throw new Error("Destination is required");
         }
+        // add random uuid to destination
+        const destinationWithUuid = isUniqueDestination
+            ? path.join(destination, node_crypto_1.default.randomUUID())
+            : destination;
         const buffer = typeof source === "string"
             ? await fs.readFile(source)
             : source;
         const files = await Zip.read(buffer);
         // if destination exists, remove it
-        await fs.rm(destination, { force: true, recursive: true });
+        await fs.rm(destinationWithUuid, { force: true, recursive: true });
         // Write all files to the file system, preserving exact paths
-        await fs.mkdir(destination, { recursive: true });
+        await fs.mkdir(destinationWithUuid, { recursive: true });
         await Promise.all(Object.entries(files).map(async ([filePath, content]) => {
-            const fullPath = path.join(destination, ...filePath.split("/"));
+            const fullPath = path.join(destinationWithUuid, ...filePath.split("/"));
             await fs.mkdir(path.dirname(fullPath), { recursive: true });
             await fs.writeFile(fullPath, content);
         }));
-        return new TemplateFs(new Set(Object.keys(files)), destination);
+        return new TemplateFs(new Set(Object.keys(files)), destinationWithUuid);
     }
 }
 exports.TemplateFs = TemplateFs;
+const compareColumns = (a, b) => {
+    if (a === b)
+        return 0;
+    return a.length === b.length ? (a < b ? -1 : 1) : (a.length < b.length ? -1 : 1);
+};