@js-ak/excel-toolbox 1.2.7 → 1.3.0

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

@@ -0,0 +1,428 @@
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import * as Xml from "../xml/index.js";
+import * as Zip from "../zip/index.js";
+import * as Utils from "./utils/index.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.
+ */
+export class TemplateFs {
+    /**
+     * Set of file paths (relative to the template) that will be used to create a new workbook.
+     * @type {Set<string>}
+     */
+    fileKeys;
+    /**
+     * The path where the template will be expanded.
+     * @type {string}
+     */
+    destination;
+    /**
+     * Flag indicating whether this template instance has been destroyed.
+     * @type {boolean}
+     */
+    destroyed = false;
+    /**
+     * Creates a Template instance.
+     *
+     * @param {Set<string>} fileKeys - Set of file paths (relative to the template) that will be used to create a new workbook.
+     * @param {string} destination - The path where the template will be expanded.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    constructor(fileKeys, destination) {
+        this.fileKeys = fileKeys;
+        this.destination = destination;
+    }
+    /**
+     * Removes the temporary directory created by this Template instance.
+     * @private
+     * @returns {Promise<void>}
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #cleanup() {
+        await fs.rm(this.destination, { force: true, recursive: true });
+    }
+    /**
+     * 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.");
+        }
+    }
+    /**
+     * Reads all files from the destination directory.
+     * @private
+     * @returns {Promise<Record<string, Buffer>>} An object with file keys and their contents as Buffers.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #readAllFromDestination() {
+        const result = {};
+        for (const key of this.fileKeys) {
+            const fullPath = path.join(this.destination, ...key.split("/"));
+            result[key] = await fs.readFile(fullPath);
+        }
+        return result;
+    }
+    /**
+     * Reads a single file from the destination directory.
+     * @private
+     * @param {string} pathKey - The Excel path of the file to read.
+     * @returns {Promise<Buffer>} The contents of the file as a Buffer.
+     * @throws {Error} If the file does not exist in the template.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async #readFile(pathKey) {
+        if (!this.fileKeys.has(pathKey)) {
+            throw new Error(`File "${pathKey}" not found in template.`);
+        }
+        const fullPath = path.join(this.destination, ...pathKey.split("/"));
+        return await fs.readFile(fullPath);
+    }
+    /**
+     * 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.#ensureNotDestroyed();
+        const { rows, sheetName, startRowNumber } = data;
+        const preparedRows = rows.map(row => Utils.toExcelColumnObject(row));
+        // Validation
+        Utils.checkStartRow(startRowNumber);
+        Utils.checkRows(preparedRows);
+        // Find the sheet
+        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("xl/workbook.xml"));
+        const sheetMatch = workbookXml.match(new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`));
+        if (!sheetMatch || !sheetMatch[1]) {
+            throw new Error(`Sheet "${sheetName}" not found`);
+        }
+        const rId = sheetMatch[1];
+        const relsXml = Xml.extractXmlFromSheet(await this.#readFile("xl/_rels/workbook.xml.rels"));
+        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
+        if (!relMatch || !relMatch[1]) {
+            throw new Error(`Relationship "${rId}" not found`);
+        }
+        const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+        const sheetXmlRaw = await this.#readFile(sheetPath);
+        const sheetXml = Xml.extractXmlFromSheet(sheetXmlRaw);
+        let nextRow = 0;
+        if (!startRowNumber) {
+            // Find the last row
+            let lastRowNumber = 0;
+            const rowMatches = [...sheetXml.matchAll(/<row[^>]+r="(\d+)"[^>]*>/g)];
+            if (rowMatches.length > 0) {
+                lastRowNumber = Math.max(...rowMatches.map((m) => parseInt(m[1], 10)));
+            }
+            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, updatedXml);
+    }
+    /**
+     * 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.#ensureNotDestroyed();
+        const { rows, sheetName, startRowNumber } = data;
+        if (!sheetName)
+            throw new Error("Sheet name is required");
+        // Read XML workbook to find sheet name and path
+        const workbookXml = Xml.extractXmlFromSheet(await this.#readFile("xl/workbook.xml"));
+        const sheetMatch = workbookXml.match(new RegExp(`<sheet[^>]+name="${sheetName}"[^>]+r:id="([^"]+)"[^>]*/>`));
+        if (!sheetMatch)
+            throw new Error(`Sheet "${sheetName}" not found`);
+        const rId = sheetMatch[1];
+        const relsXml = Xml.extractXmlFromSheet(await this.#readFile("xl/_rels/workbook.xml.rels"));
+        const relMatch = relsXml.match(new RegExp(`<Relationship[^>]+Id="${rId}"[^>]+Target="([^"]+)"[^>]*/>`));
+        if (!relMatch)
+            throw new Error(`Relationship "${rId}" not found`);
+        // Path to the desired sheet (sheet1.xml)
+        const sheetPath = "xl/" + relMatch[1].replace(/^\/?xl\//, "");
+        // The temporary file for writing
+        const fullPath = path.join(this.destination, ...sheetPath.split("/"));
+        const tempPath = fullPath + ".tmp";
+        // Streams for reading and writing
+        const input = fsSync.createReadStream(fullPath, { encoding: "utf-8" });
+        const output = fsSync.createWriteStream(tempPath, { encoding: "utf-8" });
+        // Inserted rows flag
+        let inserted = false;
+        const rl = readline.createInterface({
+            // Process all line breaks
+            crlfDelay: Infinity,
+            input,
+        });
+        let isCollecting = false;
+        let collection = "";
+        for await (const line of rl) {
+            // Collect lines between <sheetData> and </sheetData>
+            if (!inserted && isCollecting) {
+                collection += line;
+                if (line.includes("</sheetData>")) {
+                    const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
+                    isCollecting = false;
+                    inserted = true;
+                    const openTag = collection.match(/<sheetData[^>]*>/)?.[0] ?? "<sheetData>";
+                    const closeTag = "</sheetData>";
+                    const openIdx = collection.indexOf(openTag);
+                    const closeIdx = collection.lastIndexOf(closeTag);
+                    const beforeRows = collection.slice(0, openIdx + openTag.length);
+                    const innerRows = collection.slice(openIdx + openTag.length, closeIdx).trim();
+                    const afterRows = collection.slice(closeIdx);
+                    output.write(beforeRows);
+                    const innerRowsMap = Utils.parseRows(innerRows);
+                    if (innerRows) {
+                        if (startRowNumber) {
+                            const filteredRows = Utils.getRowsBelow(innerRowsMap, startRowNumber);
+                            if (filteredRows)
+                                output.write(filteredRows);
+                        }
+                        else {
+                            output.write(innerRows);
+                        }
+                    }
+                    const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                    if (innerRows) {
+                        const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
+                        if (filteredRows)
+                            output.write(filteredRows);
+                    }
+                    output.write(afterRows);
+                }
+                continue;
+            }
+            // Case 1: <sheetData> and </sheetData> on one line
+            const singleLineMatch = line.match(/(<sheetData[^>]*>)(.*)(<\/sheetData>)/);
+            if (!inserted && singleLineMatch) {
+                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
+                const fullMatch = singleLineMatch[0];
+                const before = line.slice(0, singleLineMatch.index);
+                const after = line.slice(singleLineMatch.index + fullMatch.length);
+                const openTag = "<sheetData>";
+                const closeTag = "</sheetData>";
+                const openIdx = fullMatch.indexOf(openTag);
+                const closeIdx = fullMatch.indexOf(closeTag);
+                const beforeRows = fullMatch.slice(0, openIdx + openTag.length);
+                const innerRows = fullMatch.slice(openIdx + openTag.length, closeIdx).trim();
+                const afterRows = fullMatch.slice(closeIdx);
+                if (before) {
+                    output.write(before);
+                }
+                output.write(beforeRows);
+                const innerRowsMap = Utils.parseRows(innerRows);
+                if (innerRows) {
+                    if (startRowNumber) {
+                        const filteredRows = Utils.getRowsBelow(innerRowsMap, startRowNumber);
+                        if (filteredRows) {
+                            output.write(filteredRows);
+                        }
+                    }
+                    else {
+                        output.write(innerRows);
+                    }
+                }
+                // new <row>
+                const { rowNumber: actualRowNumber } = await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                if (innerRows) {
+                    const filteredRows = Utils.getRowsAbove(innerRowsMap, actualRowNumber);
+                    if (filteredRows) {
+                        output.write(filteredRows);
+                    }
+                }
+                output.write(afterRows);
+                if (after) {
+                    output.write(after);
+                }
+                inserted = true;
+                continue;
+            }
+            // Case 2: <sheetData/>
+            if (!inserted && /<sheetData\s*\/>/.test(line)) {
+                const maxRowNumber = startRowNumber ?? Utils.getMaxRowNumber(line);
+                const fullMatch = line.match(/<sheetData\s*\/>/)?.[0] || "";
+                const matchIndex = line.indexOf(fullMatch);
+                const before = line.slice(0, matchIndex);
+                const after = line.slice(matchIndex + fullMatch.length);
+                if (before) {
+                    output.write(before);
+                }
+                // Insert opening tag
+                output.write("<sheetData>");
+                // Prepare the rows
+                await Utils.writeRowsToStream(output, rows, maxRowNumber);
+                // Insert closing tag
+                output.write("</sheetData>");
+                if (after) {
+                    output.write(after);
+                }
+                inserted = true;
+                continue;
+            }
+            // Case 3: <sheetData>
+            if (!inserted && /<sheetData[^>]*>/.test(line)) {
+                isCollecting = true;
+                collection += line;
+                continue;
+            }
+            // After inserting rows, just copy the remaining lines
+            output.write(line);
+        }
+        // Close the streams
+        rl.close();
+        output.end();
+        // Move the temporary file to the original location
+        await fs.rename(tempPath, fullPath);
+    }
+    /**
+     * 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.#ensureNotDestroyed();
+        // Guarantee integrity
+        await this.validate();
+        // Read the current files from the directory(in case they were changed manually)
+        const updatedFiles = await this.#readAllFromDestination();
+        const zipBuffer = await Zip.create(updatedFiles);
+        await this.#cleanup();
+        this.destroyed = true;
+        return zipBuffer;
+    }
+    /**
+     * Writes the modified Excel template to a writable stream.
+     *
+     * @param {Writable} output - The writable stream to write to.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async saveStream(output) {
+        this.#ensureNotDestroyed();
+        // Guarantee integrity
+        await this.validate();
+        await Zip.createWithStream(Array.from(this.fileKeys), this.destination, output);
+        await this.#cleanup();
+        this.destroyed = true;
+    }
+    /**
+     * 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.#ensureNotDestroyed();
+        if (!this.fileKeys.has(key)) {
+            throw new Error(`File "${key}" is not part of the original template.`);
+        }
+        const fullPath = path.join(this.destination, ...key.split("/"));
+        await fs.writeFile(fullPath, Buffer.isBuffer(content) ? content : Buffer.from(content));
+    }
+    /**
+     * Validates the template by checking all required files exist.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If any required files are missing.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    async validate() {
+        this.#ensureNotDestroyed();
+        for (const key of this.fileKeys) {
+            const fullPath = path.join(this.destination, ...key.split("/"));
+            try {
+                await fs.access(fullPath);
+            }
+            catch {
+                throw new Error(`Missing file in template directory: ${key}`);
+            }
+        }
+    }
+    /**
+     * Creates a Template instance from an Excel file source.
+     * Removes any existing files in the destination directory.
+     *
+     * @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.
+     * @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;
+        if (!destination) {
+            throw new Error("Destination is required");
+        }
+        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 });
+        // Write all files to the file system, preserving exact paths
+        await fs.mkdir(destination, { recursive: true });
+        await Promise.all(Object.entries(files).map(async ([filePath, content]) => {
+            const fullPath = path.join(destination, ...filePath.split("/"));
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, content);
+        }));
+        return new TemplateFs(new Set(Object.keys(files)), destination);
+    }
+}

package/build/esm/lib/template/utils/check-row.js

@@ -0,0 +1,20 @@
+/**
+ * Validates that each key in the given row object is a valid cell reference.
+ *
+ * This function checks that all keys in the provided row object are composed
+ * only of column letters (A-Z, case insensitive). If a key is found that does
+ * not match this pattern, an error is thrown with a message indicating the
+ * invalid cell reference.
+ *
+ * @param row - An object representing a row of data, where keys are cell
+ *              references and values are strings.
+ *
+ * @throws {Error} If any key in the row is not a valid column letter.
+ */
+export function checkRow(row) {
+    for (const key of Object.keys(row)) {
+        if (!/^[A-Z]+$/i.test(key)) {
+            throw new Error(`Invalid cell reference "${key}" in row. Only column letters (like "A", "B", "C") are allowed.`);
+        }
+    }
+}

package/build/esm/lib/template/utils/check-rows.js

@@ -0,0 +1,16 @@
+import { checkRow } from "./check-row.js";
+/**
+ * Validates an array of row objects to ensure each cell reference is valid.
+ * Each row object is checked to ensure that its keys (cell references) are
+ * composed of valid column letters (e.g., "A", "B", "C").
+ *
+ * @param rows An array of row objects, where each object represents a row
+ * of data with cell references as keys and cell values as strings.
+ *
+ * @throws {Error} If any cell reference in the rows is invalid.
+ */
+export function checkRows(rows) {
+    for (const row of rows) {
+        checkRow(row);
+    }
+}

package/build/esm/lib/template/utils/check-start-row.js

@@ -0,0 +1,15 @@
+/**
+ * Checks if startRow is a positive integer.
+ *
+ * @param startRow The start row to check.
+ *
+ * @throws {Error} If startRow is not a positive integer.
+ */
+export function checkStartRow(startRow) {
+    if (startRow === undefined) {
+        return;
+    }
+    if (!Number.isInteger(startRow) || startRow < 1) {
+        throw new Error(`Invalid startRow "${startRow}". Must be a positive integer.`);
+    }
+}

package/build/esm/lib/template/utils/column-index-to-letter.js

@@ -0,0 +1,14 @@
+/**
+ * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
+ *
+ * @param index - The 0-based column index.
+ * @returns The Excel-style letter for the given column index.
+ */
+export function columnIndexToLetter(index) {
+    let letters = "";
+    while (index >= 0) {
+        letters = String.fromCharCode((index % 26) + 65) + letters;
+        index = Math.floor(index / 26) - 1;
+    }
+    return letters;
+}

package/build/esm/lib/template/utils/escape-xml.js

@@ -0,0 +1,21 @@
+/**
+ * Escapes special characters in a string for use in an XML document.
+ *
+ * Replaces:
+ * - `&` with `&`
+ * - `<` with `&lt;`
+ * - `>` with `&gt;`
+ * - `"` with `&quot;`
+ * - `'` with `&apos;`
+ *
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+export function escapeXml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}

package/build/esm/lib/template/utils/get-max-row-number.js

@@ -0,0 +1,17 @@
+/**
+ * Finds the maximum row number in a list of <row> elements
+ * and returns the maximum row number + 1.
+ * @param {string} line - The line of XML to parse.
+ * @returns {number} - The maximum row number found + 1.
+ */
+export function getMaxRowNumber(line) {
+    let result = 1;
+    const rowMatches = [...line.matchAll(/<row[^>]+r="(\d+)"[^>]*>/g)];
+    for (const match of rowMatches) {
+        const rowNum = parseInt(match[1], 10);
+        if (rowNum >= result) {
+            result = rowNum + 1;
+        }
+    }
+    return result;
+}

package/build/esm/lib/template/utils/get-rows-above.js

@@ -0,0 +1,20 @@
+/**
+ * Filters out all rows in the given map that have a row number
+ * lower than or equal to the given minRow, and returns the
+ * filtered rows as a single string. Useful for removing rows
+ * from a template that are positioned above a certain row
+ * number.
+ *
+ * @param {Map<number, string>} map - The map of row numbers to row content
+ * @param {number} minRow - The minimum row number to include in the output
+ * @returns {string} The filtered rows, concatenated into a single string
+ */
+export function getRowsAbove(map, minRow) {
+    const filteredRows = [];
+    for (const [key, value] of map.entries()) {
+        if (key > minRow) {
+            filteredRows.push(value);
+        }
+    }
+    return filteredRows.join("");
+}

package/build/esm/lib/template/utils/get-rows-below.js

@@ -0,0 +1,20 @@
+/**
+ * Filters out all rows in the given map that have a row number
+ * greater than or equal to the given maxRow, and returns the
+ * filtered rows as a single string. Useful for removing rows
+ * from a template that are positioned below a certain row
+ * number.
+ *
+ * @param {Map<number, string>} map - The map of row numbers to row content
+ * @param {number} maxRow - The maximum row number to include in the output
+ * @returns {string} The filtered rows, concatenated into a single string
+ */
+export function getRowsBelow(map, maxRow) {
+    const filteredRows = [];
+    for (const [key, value] of map.entries()) {
+        if (key < maxRow) {
+            filteredRows.push(value);
+        }
+    }
+    return filteredRows.join("");
+}

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

@@ -0,0 +1,11 @@
+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 "./escape-xml.js";
+export * from "./get-max-row-number.js";
+export * from "./get-rows-above.js";
+export * from "./get-rows-below.js";
+export * from "./parse-rows.js";
+export * from "./to-excel-column-object.js";
+export * from "./write-rows-to-stream.js";

package/build/esm/lib/template/utils/parse-rows.js

@@ -0,0 +1,27 @@
+export function parseRows(innerRows) {
+    const rowsMap = new Map();
+    // Regex to match all <row> elements
+    // 1. `(<row[^>]+r="(\d+)"[^>]*\/>)` - for self-closing tags (<row ... />)
+    // 2. `|(<row[^>]+r="(\d+)"[^>]*>[\s\S]*?<\/row>)` — for self-closing tags (<row ... />)
+    const rowRegex = /(<row[^>]+r="(\d+)"[^>]*\/>)|(<row[^>]+r="(\d+)"[^>]*>[\s\S]*?<\/row>)/g;
+    let match;
+    while ((match = rowRegex.exec(innerRows)) !== null) {
+        // if this is a self-closing tag (<row ... />)
+        if (match[1]) {
+            const fullRow = match[1];
+            const rowNumber = match[2];
+            if (!rowNumber)
+                throw new Error("Row number not found");
+            rowsMap.set(Number(rowNumber), fullRow);
+        }
+        // if this is a regular tag (<row>...</row>)
+        else if (match[3]) {
+            const fullRow = match[3];
+            const rowNumber = match[4];
+            if (!rowNumber)
+                throw new Error("Row number not found");
+            rowsMap.set(Number(rowNumber), fullRow);
+        }
+    }
+    return rowsMap;
+}

package/build/esm/lib/template/utils/to-excel-column-object.js

@@ -0,0 +1,26 @@
+/**
+ * Converts an array of values into a Record<string, string> with Excel column names as keys.
+ *
+ * The column names are generated in the standard Excel column naming convention (A, B, ..., Z, AA, AB, ...).
+ * The corresponding values are converted to strings using the String() function.
+ *
+ * @param values - The array of values to convert
+ * @returns The resulting Record<string, string>
+ */
+export function toExcelColumnObject(values) {
+    const toExcelColumn = (index) => {
+        let column = "";
+        let i = index;
+        while (i >= 0) {
+            column = String.fromCharCode((i % 26) + 65) + column;
+            i = Math.floor(i / 26) - 1;
+        }
+        return column;
+    };
+    const result = {};
+    for (let i = 0; i < values.length; i++) {
+        const key = toExcelColumn(i);
+        result[key] = String(values[i]);
+    }
+    return result;
+}