@js-ak/excel-toolbox 1.3.2 → 1.4.1

package/build/esm/lib/template/utils/apply-replacements.js

@@ -0,0 +1,22 @@
+import { getByPath } from "./get-by-path.js";
+/**
+ * Replaces placeholders in the given content string with values from the replacements map.
+ *
+ * The function searches for placeholders in the format `${key}` within the content
+ * string, 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 content - The string containing placeholders to be replaced.
+ * @param replacements - An object where keys represent placeholder paths and values are the replacements.
+ * @returns A new string with placeholders replaced by corresponding values from the replacements object.
+ */
+export const applyReplacements = (content, replacements) => {
+    if (!content) {
+        return "";
+    }
+    return content.replace(/\$\{([^}]+)\}/g, (match, path) => {
+        const value = getByPath(replacements, path);
+        return value !== undefined ? String(value) : match;
+    });
+};

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

@@ -1,19 +1,14 @@
 /**
- * Validates that each key in the given row object is a valid cell reference.
+ * Validates an object representing a single row of data to ensure that its keys
+ * are valid Excel column references. Throws an error if any of the keys are
+ * invalid.
  *
- * 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.
+ * @param row An object with string keys that represent the cell references and
+ * string values that represent the values of those cells.
  */
 export function checkRow(row) {
     for (const key of Object.keys(row)) {
-        if (!/^[A-Z]+$/i.test(key)) {
+        if (!/^[A-Z]+$/i.test(key) || !/^[A-Z]$|^[A-Z][A-Z]$|^[A-Z][A-Z][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/column-index-to-letter.js

@@ -1,10 +1,21 @@
 /**
- * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
+ * Converts a zero-based column index to its corresponding Excel column letter.
  *
- * @param index - The 0-based column index.
- * @returns The Excel-style letter for the given column index.
+ * @throws Will throw an error if the input is not a positive integer.
+ * @param {number} index - The zero-based index of the column to convert.
+ * @returns {string} The corresponding Excel column letter.
+ *
+ * @example
+ * columnIndexToLetter(0); // returns "A"
+ * columnIndexToLetter(25); // returns "Z"
+ * columnIndexToLetter(26); // returns "AA"
+ * columnIndexToLetter(51); // returns "AZ"
+ * columnIndexToLetter(52); // returns "BA"
  */
 export function columnIndexToLetter(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`Invalid column index: ${index}. Must be a positive integer.`);
+    }
     let letters = "";
     while (index >= 0) {
         letters = String.fromCharCode((index % 26) + 65) + letters;

package/build/esm/lib/template/utils/extract-xml-declaration.js

@@ -0,0 +1,19 @@
+/**
+ * Extracts the XML declaration from a given XML string.
+ *
+ * The XML declaration is a string that looks like `<?xml ...?>` and is usually
+ * present at the beginning of an XML file. It contains information about the
+ * XML version, encoding, and standalone status.
+ *
+ * This function returns `null` if the input string does not have a valid XML
+ * declaration.
+ *
+ * @param xmlString - The XML string to extract the declaration from.
+ * @returns The extracted XML declaration string, or `null`.
+ */
+export function extractXmlDeclaration(xmlString) {
+    // const declarationRegex = /^<\?xml\s+[^?]+\?>/;
+    const declarationRegex = /^<\?xml\s+version\s*=\s*["'][^"']+["'](\s+(encoding|standalone)\s*=\s*["'][^"']+["'])*\s*\?>/;
+    const match = xmlString.trim().match(declarationRegex);
+    return match ? match[0] : null;
+}

package/build/esm/lib/template/utils/get-by-path.js

@@ -0,0 +1,15 @@
+/**
+ * Gets a value from an object by a given path.
+ *
+ * @param obj - The object to search.
+ * @param path - The path to the value, separated by dots.
+ * @returns The value at the given path, or undefined if not found.
+ */
+export function getByPath(obj, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}

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

@@ -6,7 +6,7 @@
  */
 export function getMaxRowNumber(line) {
     let result = 1;
-    const rowMatches = [...line.matchAll(/<row[^>]+r="(\d+)"[^>]*>/g)];
+    const rowMatches = [...line.matchAll(/<row[^>]+r="(\d+)"[^>]*>/gi)];
     for (const match of rowMatches) {
         const rowNum = parseInt(match[1], 10);
         if (rowNum >= result) {

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

@@ -1,11 +1,20 @@
+export * from "./apply-replacements.js";
 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 "./extract-xml-declaration.js";
+export * from "./get-by-path.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 "./process-merge-cells.js";
+export * from "./process-merge-finalize.js";
+export * from "./process-rows.js";
+export * from "./process-shared-strings.js";
 export * from "./to-excel-column-object.js";
+export * from "./update-dimension.js";
+export * from "./validate-worksheet-xml.js";
 export * from "./write-rows-to-stream.js";

package/build/esm/lib/template/utils/process-merge-cells.js

@@ -0,0 +1,37 @@
+/**
+ * Processes the sheet XML by extracting the initial <mergeCells> block and
+ * extracting all merge cell references. The function returns an object with
+ * three properties:
+ * - `initialMergeCells`: The initial <mergeCells> block as a string array.
+ * - `mergeCellMatches`: An array of objects with `from` and `to` properties,
+ *   representing the merge cell references.
+ * - `modifiedXml`: The modified sheet XML with the <mergeCells> block removed.
+ *
+ * @param sheetXml - The sheet XML string.
+ * @returns An object with the above three properties.
+ */
+export function processMergeCells(sheetXml) {
+    // Regular expression for finding <mergeCells> block
+    const mergeCellsBlockRegex = /<mergeCells[^>]*>[\s\S]*?<\/mergeCells>/;
+    // Find the first <mergeCells> block (if there are multiple, in xlsx usually there is only one)
+    const mergeCellsBlockMatch = sheetXml.match(mergeCellsBlockRegex);
+    const initialMergeCells = [];
+    const mergeCellMatches = [];
+    if (mergeCellsBlockMatch) {
+        const mergeCellsBlock = mergeCellsBlockMatch[0];
+        initialMergeCells.push(mergeCellsBlock);
+        // Extract <mergeCell ref="A1:B2"/> from this block
+        const mergeCellRegex = /<mergeCell ref="([A-Z]+\d+):([A-Z]+\d+)"\/>/g;
+        for (const match of mergeCellsBlock.matchAll(mergeCellRegex)) {
+            mergeCellMatches.push({ from: match[1], to: match[2] });
+        }
+    }
+    // Remove the <mergeCells> block from the XML
+    const modifiedXml = sheetXml.replace(mergeCellsBlockRegex, "");
+    return {
+        initialMergeCells,
+        mergeCellMatches,
+        modifiedXml,
+    };
+}
+;

package/build/esm/lib/template/utils/process-merge-finalize.js

@@ -0,0 +1,48 @@
+import { updateDimension } from "./update-dimension.js";
+/**
+ * Finalizes the processing of the merged sheet by updating the merge cells and
+ * inserting them into the sheet XML. It also returns the modified sheet XML and
+ * shared strings.
+ *
+ * @param {object} data - An object containing the following properties:
+ *   - `initialMergeCells`: The initial merge cells from the original sheet.
+ *   - `lastIndex`: The last processed position in the sheet XML.
+ *   - `mergeCellMatches`: An array of objects with `from` and `to` properties,
+ *     describing the merge cells.
+ *   - `resultRows`: An array of processed XML rows.
+ *   - `rowShift`: The total row shift.
+ *   - `sharedStrings`: An array of shared strings.
+ *   - `sharedStringsHeader`: The XML declaration of the shared strings.
+ *   - `sheetMergeCells`: An array of merge cell XML strings.
+ *   - `sheetXml`: The original sheet XML string.
+ *
+ * @returns An object with two properties:
+ *   - `shared`: The modified shared strings XML string.
+ *   - `sheet`: The modified sheet XML string with updated merge cells.
+ */
+export function processMergeFinalize(data) {
+    const { initialMergeCells, lastIndex, mergeCellMatches, resultRows, rowShift, sharedStrings, sharedStringsHeader, sheetMergeCells, sheetXml, } = data;
+    for (const { from, to } of mergeCellMatches) {
+        const [, fromCol, fromRow] = from.match(/^([A-Z]+)(\d+)$/);
+        const [, toCol, toRow] = to.match(/^([A-Z]+)(\d+)$/);
+        const fromRowNum = Number(fromRow);
+        // These rows have already been processed, don't add duplicates
+        if (fromRowNum <= lastIndex)
+            continue;
+        const newFrom = `${fromCol}${fromRowNum + rowShift}`;
+        const newTo = `${toCol}${Number(toRow) + rowShift}`;
+        sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+    }
+    resultRows.push(sheetXml.slice(lastIndex));
+    // Form XML for mergeCells if there are any
+    const mergeXml = sheetMergeCells.length
+        ? `<mergeCells count="${sheetMergeCells.length}">${sheetMergeCells.join("")}</mergeCells>`
+        : initialMergeCells;
+    // Insert mergeCells before the closing sheetData tag
+    const sheetWithMerge = resultRows.join("").replace(/<\/sheetData>/, `</sheetData>${mergeXml}`);
+    // Return modified sheet XML and shared strings
+    return {
+        shared: `${sharedStringsHeader}\n<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="${sharedStrings.length}" uniqueCount="${sharedStrings.length}">${sharedStrings.join("")}</sst>`,
+        sheet: updateDimension(sheetWithMerge),
+    };
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Processes a sheet XML by replacing table placeholders with real data and adjusting row numbers accordingly.
+ *
+ * @param data - An object containing the following properties:
+ *   - `replacements`: An object where keys are table names and values are arrays of objects with table data.
+ *   - `sharedIndexMap`: A Map of shared string indexes by their text content.
+ *   - `mergeCellMatches`: An array of objects with `from` and `to` properties, describing the merge cells.
+ *   - `sharedStrings`: An array of shared strings.
+ *   - `sheetMergeCells`: An array of merge cell XML strings.
+ *   - `sheetXml`: The sheet XML string.
+ *
+ * @returns An object with the following properties:
+ *   - `lastIndex`: The last processed position in the sheet XML.
+ *   - `resultRows`: An array of processed XML rows.
+ *   - `rowShift`: The total row shift.
+ */
+export function processRows(data) {
+    const { mergeCellMatches, replacements, sharedIndexMap, sharedStrings, sheetMergeCells, sheetXml, } = data;
+    const TABLE_REGEX = /\$\{table:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)\}/g;
+    // Array for storing resulting XML rows
+    const resultRows = [];
+    // Previous position of processed part of XML
+    let lastIndex = 0;
+    // Shift for row numbers
+    let rowShift = 0;
+    // Regular expression for finding <row> elements
+    const rowRegex = /<row[^>]*?>[\s\S]*?<\/row>/g;
+    // Process each <row> element
+    for (const match of sheetXml.matchAll(rowRegex)) {
+        // Full XML row
+        const fullRow = match[0];
+        // Start position of the row in XML
+        const matchStart = match.index;
+        // End position of the row in XML
+        const matchEnd = matchStart + fullRow.length;
+        // Add the intermediate XML chunk (if any) between the previous and the current row
+        if (lastIndex !== matchStart) {
+            resultRows.push(sheetXml.slice(lastIndex, matchStart));
+        }
+        lastIndex = matchEnd;
+        // Get row number from r attribute
+        const originalRowNumber = parseInt(fullRow.match(/<row[^>]* r="(\d+)"/)?.[1] ?? "1", 10);
+        // Update row number based on rowShift
+        const shiftedRowNumber = originalRowNumber + rowShift;
+        // Find shared string indexes in cells of the current row
+        const sharedValueIndexes = [];
+        // Regular expression for finding a cell
+        const cellRegex = /<c[^>]*?r="([A-Z]+\d+)"[^>]*?>([\s\S]*?)<\/c>/g;
+        for (const cell of fullRow.matchAll(cellRegex)) {
+            const cellTag = cell[0];
+            // Check if the cell is a shared string
+            const isShared = /t="s"/.test(cellTag);
+            const valueMatch = cellTag.match(/<v>(\d+)<\/v>/);
+            if (isShared && valueMatch) {
+                sharedValueIndexes.push(parseInt(valueMatch[1], 10));
+            }
+        }
+        // Get the text content of shared strings by their indexes
+        const sharedTexts = sharedValueIndexes.map(i => sharedStrings[i]?.replace(/<\/?si>/g, "") ?? "");
+        // Find table placeholders in shared strings
+        const tablePlaceholders = sharedTexts.flatMap(e => [...e.matchAll(TABLE_REGEX)]);
+        // If there are no table placeholders, just shift the row
+        if (tablePlaceholders.length === 0) {
+            const updatedRow = fullRow
+                .replace(/(<row[^>]* r=")(\d+)(")/, `$1${shiftedRowNumber}$3`)
+                .replace(/<c r="([A-Z]+)(\d+)"/g, (_, col) => `<c r="${col}${shiftedRowNumber}"`);
+            resultRows.push(updatedRow);
+            // Update mergeCells for regular row with rowShift
+            const calculatedRowNumber = originalRowNumber + rowShift;
+            for (const { from, to } of mergeCellMatches) {
+                const [, fromCol, fromRow] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, toCol] = to.match(/^([A-Z]+)(\d+)$/);
+                if (Number(fromRow) === calculatedRowNumber) {
+                    const newFrom = `${fromCol}${shiftedRowNumber}`;
+                    const newTo = `${toCol}${shiftedRowNumber}`;
+                    sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+                }
+            }
+            continue;
+        }
+        // Get the table name from the first placeholder
+        const firstMatch = tablePlaceholders[0];
+        const tableName = firstMatch?.[1];
+        if (!tableName)
+            throw new Error("Table name not found");
+        // Get data for replacement from replacements
+        const array = replacements[tableName];
+        if (!array)
+            continue;
+        if (!Array.isArray(array))
+            throw new Error("Table data is not an array");
+        const tableRowStart = shiftedRowNumber;
+        // Find mergeCells to duplicate (mergeCells that start with the current row)
+        const mergeCellsToDuplicate = mergeCellMatches.filter(({ from }) => {
+            const match = from.match(/^([A-Z]+)(\d+)$/);
+            if (!match)
+                return false;
+            // Row number of the merge cell start position is in the second group
+            const rowNumber = match[2];
+            return Number(rowNumber) === tableRowStart;
+        });
+        // Change the current row to multiple rows from the data array
+        for (let i = 0; i < array.length; i++) {
+            const rowData = array[i];
+            let newRow = fullRow;
+            // Replace placeholders in shared strings with real data
+            sharedValueIndexes.forEach((originalIdx, idx) => {
+                const originalText = sharedTexts[idx];
+                if (!originalText)
+                    throw new Error("Shared value not found");
+                // Replace placeholders ${tableName.field} with real data from array data
+                const replacedText = originalText.replace(TABLE_REGEX, (_, tbl, field) => tbl === tableName ? String(rowData?.[field] ?? "") : "");
+                // Add new text to shared strings if it doesn't exist
+                let newIndex;
+                if (sharedIndexMap.has(replacedText)) {
+                    newIndex = sharedIndexMap.get(replacedText);
+                }
+                else {
+                    newIndex = sharedStrings.length;
+                    sharedIndexMap.set(replacedText, newIndex);
+                    sharedStrings.push(`<si>${replacedText}</si>`);
+                }
+                // Replace the shared string index in the cell
+                newRow = newRow.replace(`<v>${originalIdx}</v>`, `<v>${newIndex}</v>`);
+            });
+            // Update row number and cell references
+            const newRowNum = shiftedRowNumber + i;
+            newRow = newRow
+                .replace(/<row[^>]* r="\d+"/, rowTag => rowTag.replace(/r="\d+"/, `r="${newRowNum}"`))
+                .replace(/<c r="([A-Z]+)\d+"/g, (_, col) => `<c r="${col}${newRowNum}"`);
+            resultRows.push(newRow);
+            // Add duplicate mergeCells for new rows
+            for (const { from, to } of mergeCellsToDuplicate) {
+                const [, colFrom, rowFrom] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, colTo, rowTo] = to.match(/^([A-Z]+)(\d+)$/);
+                const newFrom = `${colFrom}${Number(rowFrom) + i}`;
+                const newTo = `${colTo}${Number(rowTo) + i}`;
+                sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+            }
+        }
+        // It increases the row shift by the number of added rows minus one replaced
+        rowShift += array.length - 1;
+        const delta = array.length - 1;
+        const calculatedRowNumber = originalRowNumber + rowShift - array.length + 1;
+        if (delta > 0) {
+            for (const merge of mergeCellMatches) {
+                const fromRow = parseInt(merge.from.match(/\d+$/)[0], 10);
+                if (fromRow > calculatedRowNumber) {
+                    merge.from = merge.from.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                    merge.to = merge.to.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                }
+            }
+        }
+    }
+    return { lastIndex, resultRows, rowShift };
+}
+;

package/build/esm/lib/template/utils/process-shared-strings.js

@@ -0,0 +1,42 @@
+import { extractXmlDeclaration } from "./extract-xml-declaration.js";
+/**
+ * Processes the shared strings XML by extracting the XML declaration,
+ * extracting individual <si> elements, and storing them in an array.
+ *
+ * The function returns an object with four properties:
+ * - sharedIndexMap: A map of shared string content to their corresponding index
+ * - sharedStrings: An array of shared strings
+ * - sharedStringsHeader: The XML declaration of the shared strings
+ * - sheetMergeCells: An empty array, which is only used for type compatibility
+ *                    with the return type of processBuild.
+ *
+ * @param sharedStringsXml - The XML string of the shared strings
+ * @returns An object with the four properties above
+ */
+export function processSharedStrings(sharedStringsXml) {
+    // Final list of merged cells with all changes
+    const sheetMergeCells = [];
+    // Array for storing shared strings
+    const sharedStrings = [];
+    const sharedStringsHeader = extractXmlDeclaration(sharedStringsXml);
+    // Map for fast lookup of shared string index by content
+    const sharedIndexMap = new Map();
+    // Regular expression for finding <si> elements (shared string items)
+    const siRegex = /<si>([\s\S]*?)<\/si>/g;
+    // Parse sharedStringsXml and fill sharedStrings and sharedIndexMap
+    for (const match of sharedStringsXml.matchAll(siRegex)) {
+        const content = match[1];
+        if (!content)
+            continue;
+        const fullSi = `<si>${content}</si>`;
+        sharedIndexMap.set(content, sharedStrings.length);
+        sharedStrings.push(fullSi);
+    }
+    return {
+        sharedIndexMap,
+        sharedStrings,
+        sharedStringsHeader,
+        sheetMergeCells,
+    };
+}
+;

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

@@ -1,3 +1,4 @@
+import { columnIndexToLetter } from "./column-index-to-letter.js";
 /**
  * Converts an array of values into a Record<string, string> with Excel column names as keys.
  *
@@ -8,18 +9,9 @@
  * @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);
+        const key = columnIndexToLetter(i);
         result[key] = String(values[i]);
     }
     return result;

package/build/esm/lib/template/utils/update-dimension.js

@@ -0,0 +1,37 @@
+export function updateDimension(xml) {
+    const cellRefs = [...xml.matchAll(/<c r="([A-Z]+)(\d+)"/g)];
+    if (cellRefs.length === 0)
+        return xml;
+    let minCol = Infinity, maxCol = -Infinity;
+    let minRow = Infinity, maxRow = -Infinity;
+    for (const [, colStr, rowStr] of cellRefs) {
+        const col = columnLetterToNumber(colStr);
+        const row = parseInt(rowStr, 10);
+        if (col < minCol)
+            minCol = col;
+        if (col > maxCol)
+            maxCol = col;
+        if (row < minRow)
+            minRow = row;
+        if (row > maxRow)
+            maxRow = row;
+    }
+    const newRef = `${columnNumberToLetter(minCol)}${minRow}:${columnNumberToLetter(maxCol)}${maxRow}`;
+    return xml.replace(/<dimension ref="[^"]*"/, `<dimension ref="${newRef}"`);
+}
+function columnLetterToNumber(letters) {
+    let num = 0;
+    for (let i = 0; i < letters.length; i++) {
+        num = num * 26 + (letters.charCodeAt(i) - 64);
+    }
+    return num;
+}
+function columnNumberToLetter(num) {
+    let letters = "";
+    while (num > 0) {
+        const rem = (num - 1) % 26;
+        letters = String.fromCharCode(65 + rem) + letters;
+        num = Math.floor((num - 1) / 26);
+    }
+    return letters;
+}