@js-ak/excel-toolbox 1.5.0 → 1.7.0

package/build/esm/lib/template/utils/validate-worksheet-xml.js

@@ -30,9 +30,7 @@ export function validateWorksheetXml(xml) {
     const requiredElements = [
         { name: "sheetViews", tag: "<sheetViews>" },
         { name: "sheetFormatPr", tag: "<sheetFormatPr" },
-        { name: "cols", tag: "<cols>" },
         { name: "sheetData", tag: "<sheetData>" },
-        { name: "mergeCells", tag: "<mergeCells" },
     ];
     for (const { name, tag } of requiredElements) {
         if (!xml.includes(tag)) {
@@ -97,59 +95,82 @@ export function validateWorksheetXml(xml) {
         }
     }
     // 4. Check mergeCells
-    const mergeCellsStart = xml.indexOf("<mergeCells");
-    const mergeCellsEnd = xml.indexOf("</mergeCells>");
-    if (mergeCellsStart === -1 || mergeCellsEnd === -1) {
-        return createError("Invalid mergeCells structure");
-    }
-    const mergeCellsContent = xml.substring(mergeCellsStart, mergeCellsEnd);
-    const countMatch = mergeCellsContent.match(/count="(\d+)"/);
-    if (!countMatch) {
-        return createError("Count attribute not specified for mergeCells");
-    }
-    const mergeCellTags = mergeCellsContent.match(/<mergeCell\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/g);
-    if (!mergeCellTags) {
-        return createError("No merged cells found");
-    }
-    // Check if the number of mergeCells matches the count attribute
-    if (mergeCellTags.length !== parseInt(countMatch[1])) {
-        return createError("Mismatch in the number of merged cells", `Expected: ${countMatch[1]}, found: ${mergeCellTags.length}`);
-    }
-    // Check for duplicates of mergeCell
-    const mergeRefs = new Set();
-    const duplicates = new Set();
-    for (const mergeTag of mergeCellTags) {
-        const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
-        if (!refMatch) {
-            return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
-        }
-        const ref = refMatch[1];
-        if (mergeRefs.has(ref)) {
-            duplicates.add(ref);
+    if (xml.includes("<mergeCells")) {
+        const mergeCellsStart = xml.indexOf("<mergeCells");
+        const mergeCellsEnd = xml.indexOf("</mergeCells>");
+        if (mergeCellsStart === -1 || mergeCellsEnd === -1) {
+            return createError("Invalid mergeCells structure");
+        }
+        const mergeCellsContent = xml.substring(mergeCellsStart, mergeCellsEnd);
+        const countMatch = mergeCellsContent.match(/count="(\d+)"/);
+        if (!countMatch) {
+            return createError("Count attribute not specified for mergeCells");
+        }
+        const mergeCellTags = mergeCellsContent.match(/<mergeCell\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/g);
+        if (!mergeCellTags) {
+            return createError("No merged cells found");
+        }
+        // Check if the number of mergeCells matches the count attribute
+        if (mergeCellTags.length !== parseInt(countMatch[1])) {
+            return createError("Mismatch in the number of merged cells", `Expected: ${countMatch[1]}, found: ${mergeCellTags.length}`);
+        }
+        // Check for duplicates of mergeCell
+        const mergeRefs = new Set();
+        const duplicates = new Set();
+        for (const mergeTag of mergeCellTags) {
+            const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
+            if (!refMatch) {
+                return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
+            }
+            const ref = refMatch[1];
+            if (mergeRefs.has(ref)) {
+                duplicates.add(ref);
+            }
+            else {
+                mergeRefs.add(ref);
+            }
         }
-        else {
-            mergeRefs.add(ref);
+        if (duplicates.size > 0) {
+            return createError("Duplicates of merged cells found", `Duplicates: ${Array.from(duplicates).join(", ")}`);
+        }
+        // Check for overlapping merge ranges
+        const mergedRanges = Array.from(mergeRefs).map(ref => {
+            const [start, end] = ref.split(":");
+            return {
+                endCol: end.match(/[A-Z]+/)?.[0] || "",
+                endRow: parseInt(end.match(/\d+/)?.[0] || "0"),
+                startCol: start.match(/[A-Z]+/)?.[0] || "",
+                startRow: parseInt(start.match(/\d+/)?.[0] || "0"),
+            };
+        });
+        for (let i = 0; i < mergedRanges.length; i++) {
+            for (let j = i + 1; j < mergedRanges.length; j++) {
+                const a = mergedRanges[i];
+                const b = mergedRanges[j];
+                if (rangesIntersect(a, b)) {
+                    return createError("Found intersecting merged cells", `Intersecting: ${getRangeString(a)} and ${getRangeString(b)}`);
+                }
+            }
         }
-    }
-    if (duplicates.size > 0) {
-        return createError("Duplicates of merged cells found", `Duplicates: ${Array.from(duplicates).join(", ")}`);
-    }
-    // Check for overlapping merge ranges
-    const mergedRanges = Array.from(mergeRefs).map(ref => {
-        const [start, end] = ref.split(":");
-        return {
-            endCol: end.match(/[A-Z]+/)?.[0] || "",
-            endRow: parseInt(end.match(/\d+/)?.[0] || "0"),
-            startCol: start.match(/[A-Z]+/)?.[0] || "",
-            startRow: parseInt(start.match(/\d+/)?.[0] || "0"),
-        };
-    });
-    for (let i = 0; i < mergedRanges.length; i++) {
-        for (let j = i + 1; j < mergedRanges.length; j++) {
-            const a = mergedRanges[i];
-            const b = mergedRanges[j];
-            if (rangesIntersect(a, b)) {
-                return createError("Found intersecting merged cells", `Intersecting: ${getRangeString(a)} and ${getRangeString(b)}`);
+        // 6. Additional check: all mergeCell tags refer to existing cells
+        for (const mergeTag of mergeCellTags) {
+            const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
+            if (!refMatch) {
+                return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
+            }
+            const [cell1, cell2] = refMatch[1].split(":");
+            const cell1Col = cell1.match(/[A-Z]+/)?.[0];
+            const cell1Row = parseInt(cell1.match(/\d+/)?.[0] || "0");
+            const cell2Col = cell2.match(/[A-Z]+/)?.[0];
+            const cell2Row = parseInt(cell2.match(/\d+/)?.[0] || "0");
+            if (!cell1Col || !cell2Col || isNaN(cell1Row) || isNaN(cell2Row)) {
+                return createError("Invalid merged cell coordinates", `Merged cells: ${refMatch[1]}`);
+            }
+            // Check if the merged cells exist
+            const cell1Exists = allCells.some(c => c.row === cell1Row && c.col === cell1Col);
+            const cell2Exists = allCells.some(c => c.row === cell2Row && c.col === cell2Col);
+            if (!cell1Exists || !cell2Exists) {
+                return createError("Merged cell reference points to non-existent cells", `Merged cells: ${refMatch[1]}, missing: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
             }
         }
     }
@@ -178,27 +199,6 @@ export function validateWorksheetXml(xml) {
             return createError("Cell is outside the specified area (by column)", `Cell: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
         }
     }
-    // 6. Additional check: all mergeCell tags refer to existing cells
-    for (const mergeTag of mergeCellTags) {
-        const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
-        if (!refMatch) {
-            return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
-        }
-        const [cell1, cell2] = refMatch[1].split(":");
-        const cell1Col = cell1.match(/[A-Z]+/)?.[0];
-        const cell1Row = parseInt(cell1.match(/\d+/)?.[0] || "0");
-        const cell2Col = cell2.match(/[A-Z]+/)?.[0];
-        const cell2Row = parseInt(cell2.match(/\d+/)?.[0] || "0");
-        if (!cell1Col || !cell2Col || isNaN(cell1Row) || isNaN(cell2Row)) {
-            return createError("Invalid merged cell coordinates", `Merged cells: ${refMatch[1]}`);
-        }
-        // Check if the merged cells exist
-        const cell1Exists = allCells.some(c => c.row === cell1Row && c.col === cell1Col);
-        const cell2Exists = allCells.some(c => c.row === cell2Row && c.col === cell2Col);
-        if (!cell1Exists || !cell2Exists) {
-            return createError("Merged cell reference points to non-existent cells", `Merged cells: ${refMatch[1]}, missing: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
-        }
-    }
     return { isValid: true };
 }
 // A function to check if two ranges intersect

package/build/esm/lib/template/utils/write-rows-to-stream.js

@@ -10,34 +10,74 @@ import { prepareRowToCells } from "./prepare-row-to-cells.js";
  * for the first row written to the file. Subsequent rows are written
  * with incrementing row numbers.
  *
- * @param output - A file write stream to write the Excel XML to.
- * @param rows - An async iterable of rows, where each row is an array
- *               of values.
- * @param startRowNumber - The starting row number to use for the first
- *                         row written to the file.
- *
- * @returns An object with a single property `rowNumber`, which is the
- *          last row number written to the file (i.e., the `startRowNumber`
- *          plus the number of rows written).
+ * @param {WritableLike} output - A file write stream to write the Excel XML to.
+ * @param {AsyncIterable<unknown[] | unknown[][]>} rows - An async iterable of rows, where each row is an array
+ *                                                        of values or an array of arrays of values.
+ * @param {number} startRowNumber - The starting row number to use for the first
+ *                                 row written to the file.
+ * @returns {Promise<{
+ *   dimension: {
+ *     maxColumn: string;
+ *     maxRow: number;
+ *     minColumn: string;
+ *     minRow: number;
+ *   };
+ *   rowNumber: number;
+ * }>} An object containing:
+ *   - dimension: The boundaries of the written data (min/max columns and rows)
+ *   - rowNumber: The last row number written to the file
  */
 export async function writeRowsToStream(output, rows, startRowNumber) {
     let rowNumber = startRowNumber;
+    const dimension = {
+        maxColumn: "A",
+        maxRow: startRowNumber,
+        minColumn: "A",
+        minRow: startRowNumber,
+    };
+    // Функция для сравнения колонок (A < B, AA > Z и т.д.)
+    const compareColumns = (a, b) => {
+        if (a === b)
+            return 0;
+        return a.length === b.length ? (a < b ? -1 : 1) : (a.length < b.length ? -1 : 1);
+    };
+    const processRow = (row, currentRowNumber) => {
+        const cells = prepareRowToCells(row, currentRowNumber);
+        if (cells.length === 0)
+            return;
+        output.write(`<row r="${currentRowNumber}">${cells.map(cell => cell.cellXml).join("")}</row>`);
+        // Обновление границ
+        const firstCellRef = cells[0]?.cellRef;
+        const lastCellRef = cells[cells.length - 1]?.cellRef;
+        if (firstCellRef) {
+            const colLetters = firstCellRef.match(/[A-Z]+/)?.[0] || "";
+            if (compareColumns(colLetters, dimension.minColumn) < 0) {
+                dimension.minColumn = colLetters;
+            }
+        }
+        if (lastCellRef) {
+            const colLetters = lastCellRef.match(/[A-Z]+/)?.[0] || "";
+            if (compareColumns(colLetters, dimension.maxColumn) > 0) {
+                dimension.maxColumn = colLetters;
+            }
+        }
+        dimension.maxRow = currentRowNumber;
+    };
     for await (const row of rows) {
-        // Transform the row into XML
+        if (!row.length)
+            continue;
         if (Array.isArray(row[0])) {
             for (const subRow of row) {
-                const cells = prepareRowToCells(subRow, rowNumber);
-                // Write the row to the file
-                output.write(`<row r="${rowNumber}">${cells.join("")}</row>`);
+                if (!subRow.length)
+                    continue;
+                processRow(subRow, rowNumber);
                 rowNumber++;
             }
         }
         else {
-            const cells = prepareRowToCells(row, rowNumber);
-            // Write the row to the file
-            output.write(`<row r="${rowNumber}">${cells.join("")}</row>`);
+            processRow(row, rowNumber);
             rowNumber++;
         }
     }
-    return { rowNumber };
+    return { dimension, rowNumber };
 }

package/build/esm/lib/xml/extract-rows-from-sheet-sync.js

@@ -0,0 +1,64 @@
+import { extractXmlFromSheetSync } from "./extract-xml-from-sheet-sync.js";
+/**
+ * Parses a worksheet (either as Buffer or string) to extract row data,
+ * last row number, and merge cell information from Excel XML format.
+ *
+ * This function is particularly useful for processing Excel files in
+ * Open XML Spreadsheet format (.xlsx).
+ *
+ * @param {Buffer|string} sheet - The worksheet content to parse, either as:
+ *                               - Buffer (binary Excel sheet)
+ *                               - string (raw XML content)
+ * @returns {{
+ *   rows: string[],
+ *   lastRowNumber: number,
+ *   mergeCells: {ref: string}[]
+ * }} 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"}])
+ * @throws {Error} If the sheetData section is not found in the XML
+ */
+export function extractRowsFromSheetSync(sheet) {
+    // Convert Buffer input to XML string if needed
+    const xml = typeof sheet === "string"
+        ? sheet
+        : extractXmlFromSheetSync(sheet);
+    // Extract the sheetData section containing all rows
+    const sheetDataMatch = xml.match(/<sheetData[^>]*>([\s\S]*?)<\/sheetData>/);
+    if (!sheetDataMatch) {
+        throw new Error("sheetData not found in worksheet XML");
+    }
+    const sheetDataContent = sheetDataMatch[1] || "";
+    // Extract all <row> elements using regex
+    const rowMatches = [...sheetDataContent.matchAll(/<row\b[^>]*\/>|<row\b[^>]*>[\s\S]*?<\/row>/g)];
+    const rows = rowMatches.map(match => match[0]);
+    // Calculate the highest row number present in the sheet
+    const lastRowNumber = rowMatches
+        .map(match => {
+        // Extract row number from r="..." attribute (1-based)
+        const rowNumMatch = match[0].match(/r="(\d+)"/);
+        return rowNumMatch?.[1] ? parseInt(rowNumMatch[1], 10) : null;
+    })
+        .filter((row) => row !== null) // Type guard to filter out nulls
+        .reduce((max, current) => Math.max(max, current), 0); // Find maximum row number
+    // Extract all merged cell ranges from the worksheet
+    const mergeCells = [];
+    const mergeCellsMatch = xml.match(/<mergeCells[^>]*>([\s\S]*?)<\/mergeCells>/);
+    if (mergeCellsMatch) {
+        // Find all mergeCell entries with ref attributes
+        const mergeCellMatches = mergeCellsMatch[1]?.match(/<mergeCell[^>]+ref="([^"]+)"[^>]*>/g) || [];
+        mergeCellMatches.forEach(match => {
+            const refMatch = match.match(/ref="([^"]+)"/);
+            if (refMatch?.[1]) {
+                mergeCells.push({ ref: refMatch[1] }); // Store the cell range (e.g., "A1:B2")
+            }
+        });
+    }
+    return {
+        lastRowNumber,
+        mergeCells,
+        rows,
+        xml,
+    };
+}

package/build/esm/lib/xml/extract-rows-from-sheet.js

@@ -19,9 +19,11 @@ import { extractXmlFromSheet } from "./extract-xml-from-sheet.js";
  *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
  * @throws {Error} If the sheetData section is not found in the XML
  */
-export function extractRowsFromSheet(sheet) {
+export async function extractRowsFromSheet(sheet) {
     // Convert Buffer input to XML string if needed
-    const xml = typeof sheet === "string" ? sheet : extractXmlFromSheet(sheet);
+    const xml = typeof sheet === "string"
+        ? sheet
+        : await extractXmlFromSheet(sheet);
     // Extract the sheetData section containing all rows
     const sheetDataMatch = xml.match(/<sheetData[^>]*>([\s\S]*?)<\/sheetData>/);
     if (!sheetDataMatch) {

package/build/esm/lib/xml/extract-xml-from-sheet-sync.js

@@ -0,0 +1,40 @@
+import { inflateRawSync } from "node:zlib";
+/**
+ * Extracts and parses XML content from an Excel worksheet file (e.g., xl/worksheets/sheet1.xml).
+ * Handles both compressed (raw deflate) and uncompressed (plain XML) formats.
+ *
+ * This function is designed to work with Excel Open XML (.xlsx) worksheet files,
+ * which may be stored in either compressed or uncompressed format within the ZIP container.
+ *
+ * @param {Buffer} buffer - The file content to process, which may be:
+ *                         - Raw XML text
+ *                         - Deflate-compressed XML data (without zlib headers)
+ * @returns {string} - The extracted XML content as a UTF-8 string
+ * @throws {Error} - If the buffer is empty or cannot be processed
+ */
+export function extractXmlFromSheetSync(buffer) {
+    if (!buffer || buffer.length === 0) {
+        throw new Error("Empty buffer provided");
+    }
+    let xml;
+    // Check if the buffer starts with an XML declaration (<?xml)
+    const head = buffer.subarray(0, 1024).toString("utf8").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "").trim();
+    const isXml = /^<\?xml[\s\S]+<\w+[\s>]/.test(head);
+    if (isXml) {
+        // Case 1: Already uncompressed XML - convert directly to string
+        xml = buffer.toString("utf8");
+    }
+    else {
+        // Case 2: Attempt to decompress as raw deflate data
+        try {
+            xml = inflateRawSync(buffer).toString("utf8");
+        }
+        catch (err) {
+            throw new Error("Failed to decompress sheet XML: " + (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    // Sanitize XML by removing control characters (except tab, newline, carriage return)
+    // This handles potential corruption from binary data or encoding issues
+    xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");
+    return xml;
+}

package/build/esm/lib/xml/extract-xml-from-sheet.js

@@ -1,4 +1,6 @@
-import { inflateRaw } from "pako";
+import util from "node:util";
+import zlib from "node:zlib";
+const inflateRaw = util.promisify(zlib.inflateRaw);
 /**
  * Extracts and parses XML content from an Excel worksheet file (e.g., xl/worksheets/sheet1.xml).
  * Handles both compressed (raw deflate) and uncompressed (plain XML) formats.
@@ -9,35 +11,30 @@ import { inflateRaw } from "pako";
  * @param {Buffer} buffer - The file content to process, which may be:
  *                         - Raw XML text
  *                         - Deflate-compressed XML data (without zlib headers)
- * @returns {string} - The extracted XML content as a UTF-8 string
+ * @returns {Promise<string>} - The extracted XML content as a UTF-8 string
  * @throws {Error} - If the buffer is empty or cannot be processed
  */
-export function extractXmlFromSheet(buffer) {
+export async function extractXmlFromSheet(buffer) {
     if (!buffer || buffer.length === 0) {
         throw new Error("Empty buffer provided");
     }
     let xml;
     // Check if the buffer starts with an XML declaration (<?xml)
-    const startsWithXml = buffer.subarray(0, 5).toString("utf8").trim().startsWith("<?xml");
-    if (startsWithXml) {
+    const head = buffer.subarray(0, 1024).toString("utf8").replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "").trim();
+    const isXml = /^<\?xml[\s\S]+<\w+[\s>]/.test(head);
+    if (isXml) {
         // Case 1: Already uncompressed XML - convert directly to string
         xml = buffer.toString("utf8");
     }
     else {
         // Case 2: Attempt to decompress as raw deflate data
-        const inflated = inflateRaw(buffer, { to: "string" });
-        // Validate the decompressed content contains worksheet data
-        if (inflated && inflated.includes("<sheetData")) {
-            xml = inflated;
+        try {
+            xml = (await inflateRaw(buffer)).toString("utf8");
         }
-        else {
-            throw new Error("Decompressed data does not contain sheetData");
+        catch (err) {
+            throw new Error("Failed to decompress sheet XML: " + (err instanceof Error ? err.message : String(err)));
         }
     }
-    // Fallback: If no XML obtained yet, try direct UTF-8 conversion
-    if (!xml) {
-        xml = buffer.toString("utf8");
-    }
     // Sanitize XML by removing control characters (except tab, newline, carriage return)
     // This handles potential corruption from binary data or encoding issues
     xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");

package/build/esm/lib/xml/index.js

@@ -1,5 +1,6 @@
 export * from "./build-merged-sheet.js";
+export * from "./extract-rows-from-sheet-sync.js";
 export * from "./extract-rows-from-sheet.js";
+export * from "./extract-xml-from-sheet-sync.js";
 export * from "./extract-xml-from-sheet.js";
-export * from "./extract-xml-from-system-content.js";
 export * from "./shift-row-indices.js";

package/build/types/lib/merge-sheets-to-base-file-process-sync.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Merges rows from other Excel files into a base Excel file.
+ *
+ * This function is a process-friendly version of mergeSheetsToBaseFile.
+ * It takes a single object with the following properties:
+ * - additions: An array of objects with two properties:
+ *   - files: A dictionary of file paths to their corresponding XML content
+ *   - sheetIndexes: The 1-based indexes of the sheet to extract rows from
+ * - baseFiles: A dictionary of file paths to their corresponding XML content
+ * - baseSheetIndex: The 1-based index of the sheet in the base file to add rows to
+ * - gap: The number of empty rows to insert between each added section
+ * - sheetNamesToRemove: The names of sheets to remove from the output file
+ * - sheetsToRemove: The 1-based indices of sheets to remove from the output file
+ *
+ * The function returns a dictionary of file paths to their corresponding XML content.
+ */
+export declare function mergeSheetsToBaseFileProcessSync(data: {
+    additions: {
+        files: Record<string, Buffer>;
+        sheetIndexes: number[];
+    }[];
+    baseFiles: Record<string, Buffer>;
+    baseSheetIndex: number;
+    gap: number;
+    sheetNamesToRemove: string[];
+    sheetsToRemove: number[];
+}): void;

package/build/types/lib/merge-sheets-to-base-file-process.d.ts

@@ -24,4 +24,4 @@ export declare function mergeSheetsToBaseFileProcess(data: {
     gap: number;
     sheetNamesToRemove: string[];
     sheetsToRemove: number[];
-}): void;
+}): Promise<void>;

package/build/types/lib/template/template-fs.d.ts

@@ -135,6 +135,7 @@ export declare 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.
@@ -142,5 +143,6 @@ export declare class TemplateFs {
     static from(data: {
         destination: string;
         source: string | Buffer;
+        isUniqueDestination?: boolean;
     }): Promise<TemplateFs>;
 }

package/build/types/lib/template/template-memory.d.ts

@@ -11,6 +11,13 @@ export declare class TemplateMemory {
      * @type {boolean}
      */
     destroyed: boolean;
+    /**
+     * 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: Record<string, Buffer>);
     /**
      * Copies a sheet from the template to a new name.
@@ -55,6 +62,20 @@ export declare class TemplateMemory {
         startRowNumber?: number;
         rows: unknown[][];
     }): Promise<void>;
+    /**
+     * 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.
+     */
     insertRowsStream(data: {
         sheetName: string;
         startRowNumber?: number;
@@ -79,6 +100,46 @@ export declare class TemplateMemory {
      * @experimental This API is experimental and might change in future versions.
      */
     set(key: string, content: Buffer): Promise<void>;
+    /**
+     * 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: {
+        additions: {
+            sheetIndexes?: number[];
+            sheetNames?: string[];
+        };
+        baseSheetIndex?: number;
+        baseSheetName?: string;
+        gap?: number;
+    }): void;
+    /**
+     * 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: {
+        sheetNames?: string[];
+        sheetIndexes?: number[];
+    }): void;
+    /**
+     * 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 from(data: {
         source: string | Buffer;
     }): Promise<TemplateMemory>;

package/build/types/lib/template/utils/index.d.ts

@@ -1,3 +1,4 @@
+export * as Common from "../../utils/index.js";
 export * from "./apply-replacements.js";
 export * from "./check-row.js";
 export * from "./check-rows.js";
@@ -14,6 +15,7 @@ export * from "./process-merge-cells.js";
 export * from "./process-merge-finalize.js";
 export * from "./process-rows.js";
 export * from "./process-shared-strings.js";
+export * from "./regexp.js";
 export * from "./to-excel-column-object.js";
 export * from "./update-dimension.js";
 export * from "./validate-worksheet-xml.js";

package/build/types/lib/template/utils/prepare-row-to-cells.d.ts

@@ -1 +1,5 @@
-export declare function prepareRowToCells(row: unknown[], rowNumber: number): string[];
+export declare function prepareRowToCells(row: unknown[], rowNumber: number): {
+    cellRef: string;
+    cellValue: string;
+    cellXml: string;
+}[];

package/build/types/lib/template/utils/regexp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Creates a regular expression to match a relationship element with a specific ID.
+ *
+ * @param {string} id - The relationship ID to match (e.g. "rId1")
+ * @returns {RegExp} A regular expression that matches a Relationship XML element with the given ID and captures the Target attribute value
+ * @example
+ * const regex = relationshipMatch("rId1");
+ * const xml = '<Relationship Id="rId1" Target="worksheets/sheet1.xml"/>';
+ * const match = xml.match(regex);
+ * // match[1] === "worksheets/sheet1.xml"
+ */
+export declare function relationshipMatch(id: string): RegExp;
+/**
+ * Creates a regular expression to match a sheet element with a specific name.
+ *
+ * @param {string} sheetName - The name of the sheet to match
+ * @returns {RegExp} A regular expression that matches a sheet XML element with the given name and captures the r:id attribute value
+ * @example
+ * const regex = sheetMatch("Sheet1");
+ * const xml = '<sheet name="Sheet1" sheetId="1" r:id="rId1"/>';
+ * const match = xml.match(regex);
+ * // match[1] === "rId1"
+ */
+export declare function sheetMatch(sheetName: string): RegExp;

package/build/types/lib/template/utils/update-dimension.d.ts

@@ -1 +1,16 @@
+/**
+ * Updates the dimension element in an Excel worksheet XML string based on the actual cell references.
+ *
+ * This function scans the XML for all cell references and calculates the minimum and maximum
+ * column/row values to determine the actual used range in the worksheet. It then updates
+ * the dimension element to reflect this range.
+ *
+ * @param {string} xml - The worksheet XML string to process
+ * @returns {string} The XML string with updated dimension element
+ * @example
+ * // XML with cells from A1 to C3
+ * const xml = '....<dimension ref="A1:B2"/>.....<c r="C3">...</c>...';
+ * const updated = updateDimension(xml);
+ * // Returns XML with dimension updated to ref="A1:C3"
+ */
 export declare function updateDimension(xml: string): string;