@js-ak/excel-toolbox 1.4.1 → 1.6.0

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

@@ -0,0 +1,753 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateMemory = void 0;
+const fs = __importStar(require("node:fs/promises"));
+const Xml = __importStar(require("../xml/index.js"));
+const Zip = __importStar(require("../zip/index.js"));
+const Utils = __importStar(require("./utils/index.js"));
+const memory_write_stream_js_1 = require("./memory-write-stream.js");
+/**
+ * A class for manipulating Excel templates by extracting, modifying, and repacking Excel files.
+ *
+ * @experimental This API is experimental and might change in future versions.
+ */
+class TemplateMemory {
+    files;
+    /**
+     * Flag indicating whether this template instance has been destroyed.
+     * @type {boolean}
+     */
+    destroyed = false;
+    /**
+     * Flag indicating whether this template instance is currently being processed.
+     * @type {boolean}
+     */
+    #isProcessing = false;
+    /**
+ * The keys for the Excel files in the template.
+ */
+    #excelKeys = {
+        contentTypes: "[Content_Types].xml",
+        sharedStrings: "xl/sharedStrings.xml",
+        styles: "xl/styles.xml",
+        workbook: "xl/workbook.xml",
+        workbookRels: "xl/_rels/workbook.xml.rels",
+    };
+    /**
+     * Creates a Template instance from a map of file paths to buffers.
+     *
+     * @param {Object<string, Buffer>} files - The files to create the template from.
+     * @throws {Error} If reading or writing files fails.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    constructor(files) {
+        this.files = files;
+    }
+    /**
+     * Ensures that this Template instance has not been destroyed.
+     * @private
+     * @throws {Error} If the template instance has already been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #ensureNotDestroyed() {
+        if (this.destroyed) {
+            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,
+        });
+    }
+    /**
+     * Extracts the XML content from an Excel sheet file.
+     *
+     * @param {string} fileKey - The file key of the sheet to extract.
+     * @returns {string} The XML content of the sheet.
+     * @throws {Error} If the file key is not found.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #extractXmlFromSheet(fileKey) {
+        if (!this.files[fileKey]) {
+            throw new Error(`${fileKey} not found`);
+        }
+        return Xml.extractXmlFromSheet(this.files[fileKey]);
+    }
+    /**
+     * Extracts row data from an Excel sheet file.
+     *
+     * @param {string} fileKey - The file key of the sheet to extract.
+     * @returns {Object} An object containing:
+     *   - rows: Array of raw XML strings for each <row> element
+     *   - lastRowNumber: Highest row number found in the sheet (1-based)
+     *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
+     *   - xml: The XML content of the sheet
+     * @throws {Error} If the file key is not found
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #extractRowsFromSheet(fileKey) {
+        if (!this.files[fileKey]) {
+            throw new Error(`${fileKey} not found`);
+        }
+        return Xml.extractRowsFromSheet(this.files[fileKey]);
+    }
+    /**
+     * Returns the Excel path of the sheet with the given name.
+     *
+     * @param sheetName - The name of the sheet to find.
+     * @returns The Excel path of the sheet.
+     * @throws {Error} If the sheet with the given name does not exist.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #getSheetPathByName(sheetName) {
+        // Find the sheet
+        const workbookXml = 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 relMatch = relsXml.match(Utils.relationshipMatch(rId));
+        if (!relMatch || !relMatch[1]) {
+            throw new Error(`Relationship "${rId}" not found`);
+        }
+        return "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+    }
+    /**
+     * Returns the Excel path of the sheet with the given ID.
+     *
+     * @param {number} id - The 1-based index of the sheet to find.
+     * @returns {string} The Excel path of the sheet.
+     * @throws {Error} If the sheet index is less than 1.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #getSheetPathById(id) {
+        if (id < 1) {
+            throw new Error("Sheet index must be greater than 0");
+        }
+        return `xl/worksheets/sheet${id}.xml`;
+    }
+    /**
+     * Replaces the contents of a file in the template.
+     *
+     * @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) {
+        this.files[key] = content;
+    }
+    /**
+     * Replaces placeholders in the given sheet with values from the replacements map.
+     *
+     * The function searches for placeholders in the format `${key}` within the sheet
+     * content, where `key` corresponds to a path in the replacements object.
+     * If a value is found for the key, it replaces the placeholder with the value.
+     * If no value is found, the original placeholder remains unchanged.
+     *
+     * @param sheetName - The name of the sheet to be replaced.
+     * @param replacements - An object where keys represent placeholder paths and values are the replacements.
+     * @returns A promise that resolves when the substitution is complete.
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #substitute(sheetName, replacements) {
+        const sharedStringsPath = this.#excelKeys.sharedStrings;
+        let sharedStringsContent = "";
+        let sheetContent = "";
+        if (this.files[sharedStringsPath]) {
+            sharedStringsContent = this.#extractXmlFromSheet(sharedStringsPath);
+        }
+        const sheetPath = this.#getSheetPathByName(sheetName);
+        if (this.files[sheetPath]) {
+            sheetContent = 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) {
+                const result = this.#expandTableRows(sheetContent, sharedStringsContent, replacements);
+                sheetContent = result.sheet;
+                sharedStringsContent = result.shared;
+            }
+        }
+        if (this.files[sharedStringsPath]) {
+            sharedStringsContent = Utils.applyReplacements(sharedStringsContent, replacements);
+            await this.#set(sharedStringsPath, Buffer.from(sharedStringsContent));
+        }
+        if (this.files[sheetPath]) {
+            sheetContent = Utils.applyReplacements(sheetContent, replacements);
+            await this.#set(sheetPath, Buffer.from(sheetContent));
+        }
+    }
+    /**
+     * Merges rows from other sheets into a base sheet.
+     *
+     * @param {Object} data
+     * @param {Object} data.additions
+     * @param {number[]} [data.additions.sheetIndexes] - The 1-based indexes of the sheets to extract rows from.
+     * @param {string[]} [data.additions.sheetNames] - The names of the sheets to extract rows from.
+     * @param {number} [data.baseSheetIndex=1] - The 1-based index of the sheet in the workbook to add rows to.
+     * @param {string} [data.baseSheetName] - The name of the sheet in the workbook to add rows to.
+     * @param {number} [data.gap=0] - The number of empty rows to insert between each added section.
+     * @throws {Error} If the base sheet index is less than 1.
+     * @throws {Error} If the base sheet name is not found.
+     * @throws {Error} If the sheet index is less than 1.
+     * @throws {Error} If the sheet name is not found.
+     * @throws {Error} If no sheets are found to merge.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #mergeSheets(data) {
+        const { additions, baseSheetIndex = 1, baseSheetName, gap = 0, } = data;
+        let fileKey = "";
+        if (baseSheetName) {
+            fileKey = this.#getSheetPathByName(baseSheetName);
+        }
+        if (baseSheetIndex && !fileKey) {
+            if (baseSheetIndex < 1) {
+                throw new Error("Base sheet index must be greater than 0");
+            }
+            fileKey = `xl/worksheets/sheet${baseSheetIndex}.xml`;
+        }
+        if (!fileKey) {
+            throw new Error("Base sheet not found");
+        }
+        const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, xml, } = 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)));
+        }
+        if (additions.sheetNames) {
+            sheetPaths.push(...(additions.sheetNames).map(e => this.#getSheetPathByName(e)));
+        }
+        if (sheetPaths.length === 0) {
+            throw new Error("No sheets found to merge");
+        }
+        for (const sheetPath of sheetPaths) {
+            if (!this.files[sheetPath]) {
+                throw new Error(`Sheet "${sheetPath}" not found`);
+            }
+            const { mergeCells, rows } = Xml.extractRowsFromSheet(this.files[sheetPath]);
+            const shiftedRows = Xml.shiftRowIndices(rows, currentRowOffset);
+            const shiftedMergeCells = mergeCells.map(cell => {
+                const [start, end] = cell.ref.split(":");
+                if (!start || !end) {
+                    return cell;
+                }
+                const shiftedStart = Utils.Common.shiftCellRef(start, currentRowOffset);
+                const shiftedEnd = Utils.Common.shiftCellRef(end, currentRowOffset);
+                return { ...cell, ref: `${shiftedStart}:${shiftedEnd}` };
+            });
+            allRows.push(...shiftedRows);
+            allMergeCells.push(...shiftedMergeCells);
+            currentRowOffset += Utils.Common.getMaxRowNumber(rows) + gap;
+        }
+        const mergedXml = Xml.buildMergedSheet(xml, allRows, allMergeCells);
+        this.#set(fileKey, mergedXml);
+    }
+    /**
+     * Removes sheets from the workbook.
+     *
+     * @param {Object} data - The data for sheet removal.
+     * @param {number[]} [data.sheetIndexes] - The 1-based indexes of the sheets to remove.
+     * @param {string[]} [data.sheetNames] - The names of the sheets to remove.
+     * @returns {void}
+     *
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    #removeSheets(data) {
+        const { sheetIndexes = [], sheetNames = [] } = data;
+        for (const sheetIndex of sheetIndexes) {
+            const sheetPath = `xl/worksheets/sheet${sheetIndex}.xml`;
+            if (!this.files[sheetPath]) {
+                continue;
+            }
+            delete this.files[sheetPath];
+            if (this.files["xl/workbook.xml"]) {
+                this.files["xl/workbook.xml"] = Buffer.from(Utils.Common.removeSheetFromWorkbook(this.files["xl/workbook.xml"].toString(), sheetIndex));
+            }
+            if (this.files["xl/_rels/workbook.xml.rels"]) {
+                this.files["xl/_rels/workbook.xml.rels"] = Buffer.from(Utils.Common.removeSheetFromRels(this.files["xl/_rels/workbook.xml.rels"].toString(), sheetIndex));
+            }
+            if (this.files["[Content_Types].xml"]) {
+                this.files["[Content_Types].xml"] = Buffer.from(Utils.Common.removeSheetFromContentTypes(this.files["[Content_Types].xml"].toString(), sheetIndex));
+            }
+        }
+        for (const sheetName of sheetNames) {
+            Utils.Common.removeSheetByName(this.files, sheetName);
+        }
+    }
+    /**
+     * Copies a sheet from the template to a new name.
+     *
+     * @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 {
+            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 = this.#excelKeys.workbook;
+            const workbookXml = this.#extractXmlFromSheet(this.#excelKeys.workbook);
+            // Find the source sheet
+            const sheetMatch = workbookXml.match(Utils.sheetMatch(sourceName));
+            if (!sheetMatch || !sheetMatch[1]) {
+                throw new Error(`Sheet "${sourceName}" not found`);
+            }
+            // 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 rId = sheetMatch[1];
+            const relsXmlPath = this.#excelKeys.workbookRels;
+            const relsXml = this.#extractXmlFromSheet(this.#excelKeys.workbookRels);
+            const relMatch = relsXml.match(Utils.relationshipMatch(rId));
+            if (!relMatch || !relMatch[1]) {
+                throw new Error(`Relationship "${rId}" not found`);
+            }
+            const sourceTarget = relMatch[1]; // sheetN.xml
+            const sourceSheetPath = "xl/" + sourceTarget.replace(/^\/?.*xl\//, "");
+            // Get the index of the new sheet
+            const sheetNumbers = Array.from(Object.keys(this.files))
+                .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 = this.files[sourceSheetPath];
+            if (!sheetContent) {
+                throw new Error(`Sheet "${sourceSheetPath}" not found`);
+            }
+            function copyBuffer(source) {
+                const target = Buffer.alloc(source.length);
+                source.copy(target);
+                return target;
+            }
+            await this.#set(newSheetPath, copyBuffer(sheetContent));
+            // Update workbook.xml
+            const updatedWorkbookXml = workbookXml.replace("</sheets>", `<sheet name="${newName}" sheetId="${nextSheetIndex}" r:id="${newRId}"/></sheets>`);
+            await this.#set(workbookXmlPath, Buffer.from(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, Buffer.from(updatedRelsXml));
+            // Read [Content_Types].xml
+            // Update [Content_Types].xml
+            const contentTypesPath = "[Content_Types].xml";
+            const contentTypesXml = 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));
+        }
+        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.
+     *
+     * @param {Object} data - The data for row insertion.
+     * @param {string} data.sheetName - The name of the sheet to insert rows into.
+     * @param {number} [data.startRowNumber] - The row number to start inserting from.
+     * @param {unknown[][]} data.rows - The rows to insert.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @throws {Error} If the row number is out of range.
+     * @throws {Error} If a column is out of range.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async insertRows(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        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 sheetPath = this.#getSheetPathByName(sheetName);
+            const sheetXml = this.#extractXmlFromSheet(sheetPath);
+            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("");
+            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, Buffer.from(updatedXml));
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Inserts rows into a specific sheet in the template using an async stream.
+     *
+     * @param {Object} data - The data for row insertion.
+     * @param {string} data.sheetName - The name of the sheet to insert rows into.
+     * @param {number} [data.startRowNumber] - The row number to start inserting from.
+     * @param {AsyncIterable<unknown[]>} data.rows - Async iterable of rows to insert.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @throws {Error} If the row number is out of range.
+     * @throws {Error} If a column is out of range.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async insertRowsStream(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        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 sheetPath = this.#getSheetPathByName(sheetName);
+            const sheetXml = this.#extractXmlFromSheet(sheetPath);
+            const output = new memory_write_stream_js_1.MemoryWriteStream();
+            let inserted = false;
+            // --- Case 1: <sheetData>...</sheetData> on one line ---
+            const singleLineMatch = sheetXml.match(/(<sheetData[^>]*>)(.*)(<\/sheetData>)/);
+            if (!inserted && singleLineMatch) {
+                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(sheetXml);
+                const openTag = singleLineMatch[1];
+                const innerRows = singleLineMatch[2].trim();
+                const closeTag = singleLineMatch[3];
+                const innerRowsMap = Utils.parseRows(innerRows);
+                output.write(sheetXml.slice(0, singleLineMatch.index));
+                output.write(openTag);
+                if (innerRows) {
+                    if (startRowNumber) {
+                        const filtered = Utils.getRowsBelow(innerRowsMap, startRowNumber);
+                        if (filtered)
+                            output.write(filtered);
+                    }
+                    else {
+                        output.write(innerRows);
+                    }
+                }
+                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                if (innerRows) {
+                    const filtered = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
+                    if (filtered)
+                        output.write(filtered);
+                }
+                output.write(closeTag);
+                output.write(sheetXml.slice(singleLineMatch.index + singleLineMatch[0].length));
+                inserted = true;
+            }
+            // --- Case 2: <sheetData/> ---
+            if (!inserted && /<sheetData\s*\/>/.test(sheetXml)) {
+                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(sheetXml);
+                const match = sheetXml.match(/<sheetData\s*\/>/);
+                const matchIndex = match.index;
+                output.write(sheetXml.slice(0, matchIndex));
+                output.write("<sheetData>");
+                await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                output.write("</sheetData>");
+                output.write(sheetXml.slice(matchIndex + match[0].length));
+                inserted = true;
+            }
+            // --- Case 3: Multiline <sheetData> ---
+            if (!inserted && sheetXml.includes("<sheetData")) {
+                const openTagMatch = sheetXml.match(/<sheetData[^>]*>/);
+                const closeTag = "</sheetData>";
+                if (!openTagMatch)
+                    throw new Error("Invalid sheetData structure");
+                const openTag = openTagMatch[0];
+                const openIdx = sheetXml.indexOf(openTag);
+                const closeIdx = sheetXml.lastIndexOf(closeTag);
+                if (closeIdx === -1)
+                    throw new Error("Missing </sheetData>");
+                const beforeRows = sheetXml.slice(0, openIdx + openTag.length);
+                const innerRows = sheetXml.slice(openIdx + openTag.length, closeIdx).trim();
+                const afterRows = sheetXml.slice(closeIdx + closeTag.length);
+                const innerRowsMap = Utils.parseRows(innerRows);
+                output.write(beforeRows);
+                if (innerRows) {
+                    if (startRowNumber) {
+                        const filtered = Utils.getRowsBelow(innerRowsMap, startRowNumber);
+                        if (filtered)
+                            output.write(filtered);
+                    }
+                    else {
+                        output.write(innerRows);
+                    }
+                }
+                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, Utils.getMaxRowNumber(innerRows));
+                if (innerRows) {
+                    const filtered = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
+                    if (filtered)
+                        output.write(filtered);
+                }
+                output.write(closeTag);
+                output.write(afterRows);
+                inserted = true;
+            }
+            if (!inserted)
+                throw new Error("Failed to locate <sheetData> for insertion");
+            // Save the buffer to the sheet
+            this.files[sheetPath] = output.toBuffer();
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Saves the modified Excel template to a buffer.
+     *
+     * @returns {Promise<Buffer>} The modified Excel template as a buffer.
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async save() {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            const zipBuffer = await Zip.create(this.files);
+            this.destroyed = true;
+            // Clear all buffers
+            for (const key in this.files) {
+                if (this.files.hasOwnProperty(key)) {
+                    this.files[key] = Buffer.alloc(0); // Clear the buffer
+                }
+            }
+            return zipBuffer;
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * 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) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            await this.#set(key, content);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Merges sheets into a base sheet.
+     *
+     * @param {Object} data
+     * @param {{ sheetIndexes?: number[]; sheetNames?: string[] }} data.additions - The sheets to merge.
+     * @param {number} [data.baseSheetIndex=1] - The 1-based index of the sheet to merge into.
+     * @param {string} [data.baseSheetName] - The name of the sheet to merge into.
+     * @param {number} [data.gap=0] - The number of empty rows to insert between each added section.
+     * @returns {void}
+     */
+    mergeSheets(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            this.#mergeSheets(data);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Removes sheets from the workbook.
+     *
+     * @param {Object} data
+     * @param {number[]} [data.sheetIndexes] - The 1-based indexes of the sheets to remove.
+     * @param {string[]} [data.sheetNames] - The names of the sheets to remove.
+     * @returns {void}
+     */
+    removeSheets(data) {
+        this.#ensureNotProcessing();
+        this.#ensureNotDestroyed();
+        this.#isProcessing = true;
+        try {
+            this.#removeSheets(data);
+        }
+        finally {
+            this.#isProcessing = false;
+        }
+    }
+    /**
+     * Creates a Template instance from an Excel file source.
+     *
+     * @param {Object} data - The data to create the template from.
+     * @param {string | Buffer} data.source - The path or buffer of the Excel file.
+     * @returns {Promise<TemplateMemory>} A new Template instance.
+     * @throws {Error} If reading the file fails.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    static async from(data) {
+        const { source } = data;
+        const buffer = typeof source === "string"
+            ? await fs.readFile(source)
+            : source;
+        const files = await Zip.read(buffer);
+        return new TemplateMemory(files);
+    }
+}
+exports.TemplateMemory = TemplateMemory;