@js-ak/excel-toolbox 1.6.0 → 1.8.0

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

@@ -29,6 +29,7 @@ export declare class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     constructor(fileKeys: Set<string>, destination: string);
+    /** Public methods */
     /**
      * Copies a sheet from the template to a new name.
      *
@@ -91,6 +92,18 @@ export declare class TemplateFs {
         startRowNumber?: number;
         rows: AsyncIterable<unknown[]>;
     }): Promise<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[];
+    }): Promise<void>;
     /**
      * Saves the modified Excel template to a buffer.
      *
@@ -128,6 +141,7 @@ export declare class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     validate(): Promise<void>;
+    /** Static methods */
     /**
      * Creates a Template instance from an Excel file source.
      * Removes any existing files in the destination directory.

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

@@ -19,6 +19,7 @@ export declare class TemplateMemory {
      * @experimental This API is experimental and might change in future versions.
      */
     constructor(files: Record<string, Buffer>);
+    /** Public methods */
     /**
      * Copies a sheet from the template to a new name.
      *
@@ -118,7 +119,7 @@ export declare class TemplateMemory {
         baseSheetIndex?: number;
         baseSheetName?: string;
         gap?: number;
-    }): void;
+    }): Promise<void>;
     /**
      * Removes sheets from the workbook.
      *
@@ -130,7 +131,8 @@ export declare class TemplateMemory {
     removeSheets(data: {
         sheetNames?: string[];
         sheetIndexes?: number[];
-    }): void;
+    }): Promise<void>;
+    /** Static methods */
     /**
      * Creates a Template instance from an Excel file source.
      *

package/build/types/lib/template/utils/compare-columns.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compares two column strings and returns a number indicating their relative order.
+ *
+ * @param a - The first column string to compare.
+ * @param b - The second column string to compare.
+ * @returns 0 if the columns are equal, -1 if the first column is less than the second, or 1 if the first column is greater than the second.
+ */
+export declare function compareColumns(a: string, b: string): number;

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

@@ -4,6 +4,7 @@ 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 "./compare-columns.js";
 export * from "./escape-xml.js";
 export * from "./extract-xml-declaration.js";
 export * from "./get-by-path.js";

package/build/types/lib/xml/extract-rows-from-sheet-sync.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function extractRowsFromSheetSync(sheet: Buffer | string): {
+    rows: string[];
+    lastRowNumber: number;
+    mergeCells: {
+        ref: string;
+    }[];
+    xml: string;
+};

package/build/types/lib/xml/extract-rows-from-sheet.d.ts

@@ -18,11 +18,11 @@
  *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
  * @throws {Error} If the sheetData section is not found in the XML
  */
-export declare function extractRowsFromSheet(sheet: Buffer | string): {
+export declare function extractRowsFromSheet(sheet: Buffer | string): Promise<{
     rows: string[];
     lastRowNumber: number;
     mergeCells: {
         ref: string;
     }[];
     xml: string;
-};
+}>;

package/build/types/lib/xml/extract-xml-from-sheet-sync.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function extractXmlFromSheetSync(buffer: Buffer): string;

package/build/types/lib/xml/extract-xml-from-sheet.d.ts

@@ -8,7 +8,7 @@
  * @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 declare function extractXmlFromSheet(buffer: Buffer): string;
+export declare function extractXmlFromSheet(buffer: Buffer): Promise<string>;

package/build/types/lib/xml/index.d.ts

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-ak/excel-toolbox",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "excel-toolbox",
   "publishConfig": {
     "access": "public",
@@ -70,7 +70,6 @@
     "@semantic-release/release-notes-generator": "14.0.0",
     "@stylistic/eslint-plugin-ts": "4.2.0",
     "@types/node": "22.14.0",
-    "@types/pako": "2.0.3",
     "@vitest/coverage-v8": "3.1.2",
     "eslint": "9.24.0",
     "eslint-plugin-sort-destructure-keys": "2.0.0",
@@ -80,8 +79,5 @@
     "typescript": "5.8.3",
     "typescript-eslint": "8.29.0",
     "vitest": "3.1.2"
-  },
-  "dependencies": {
-    "pako": "2.1.0"
   }
 }

package/build/cjs/lib/xml/extract-xml-from-system-content.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractXmlFromSystemContent = void 0;
-const pako_1 = require("pako");
-/**
- * Extracts and decompresses XML content from Excel system files (e.g., workbook.xml, [Content_Types].xml).
- * Handles both compressed (raw DEFLATE) and uncompressed (plain XML) formats with comprehensive error handling.
- *
- * @param {Buffer} buffer - The file content to process, which may be:
- *                         - Raw XML text
- *                         - DEFLATE-compressed XML data (without zlib headers)
- * @param {string} name - The filename being processed (for error reporting)
- * @returns {string} - The extracted XML content as a sanitized UTF-8 string
- * @throws {Error} - With descriptive messages for various failure scenarios:
- *                  - Empty buffer
- *                  - Decompression failures
- *                  - Invalid XML content
- */
-const extractXmlFromSystemContent = (buffer, name) => {
-    // Validate input buffer
-    if (!buffer || buffer.length === 0) {
-        throw new Error(`Empty data buffer provided for file ${name}`);
-    }
-    let xml;
-    // Check for XML declaration in first 5 bytes (<?xml)
-    const startsWithXml = buffer.subarray(0, 5).toString("utf8").trim().startsWith("<?xml");
-    if (startsWithXml) {
-        // Case 1: Already uncompressed XML - convert directly to string
-        xml = buffer.toString("utf8");
-    }
-    else {
-        // Case 2: Attempt DEFLATE decompression
-        try {
-            const inflated = (0, pako_1.inflateRaw)(buffer, { to: "string" });
-            // Validate decompressed content contains XML declaration
-            if (inflated && inflated.includes("<?xml")) {
-                xml = inflated;
-            }
-            else {
-                throw new Error(`Decompressed data doesn't contain valid XML in ${name}`);
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : "Unknown error";
-            throw new Error(`Failed to decompress ${name}: ${message}`);
-        }
-    }
-    // Sanitize XML by removing illegal control characters (per XML 1.0 spec)
-    // Preserves tabs (0x09), newlines (0x0A), and carriage returns (0x0D)
-    xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");
-    return xml;
-};
-exports.extractXmlFromSystemContent = extractXmlFromSystemContent;

package/build/esm/lib/xml/extract-xml-from-system-content.js

@@ -1,49 +0,0 @@
-import { inflateRaw } from "pako";
-/**
- * Extracts and decompresses XML content from Excel system files (e.g., workbook.xml, [Content_Types].xml).
- * Handles both compressed (raw DEFLATE) and uncompressed (plain XML) formats with comprehensive error handling.
- *
- * @param {Buffer} buffer - The file content to process, which may be:
- *                         - Raw XML text
- *                         - DEFLATE-compressed XML data (without zlib headers)
- * @param {string} name - The filename being processed (for error reporting)
- * @returns {string} - The extracted XML content as a sanitized UTF-8 string
- * @throws {Error} - With descriptive messages for various failure scenarios:
- *                  - Empty buffer
- *                  - Decompression failures
- *                  - Invalid XML content
- */
-export const extractXmlFromSystemContent = (buffer, name) => {
-    // Validate input buffer
-    if (!buffer || buffer.length === 0) {
-        throw new Error(`Empty data buffer provided for file ${name}`);
-    }
-    let xml;
-    // Check for XML declaration in first 5 bytes (<?xml)
-    const startsWithXml = buffer.subarray(0, 5).toString("utf8").trim().startsWith("<?xml");
-    if (startsWithXml) {
-        // Case 1: Already uncompressed XML - convert directly to string
-        xml = buffer.toString("utf8");
-    }
-    else {
-        // Case 2: Attempt DEFLATE decompression
-        try {
-            const inflated = inflateRaw(buffer, { to: "string" });
-            // Validate decompressed content contains XML declaration
-            if (inflated && inflated.includes("<?xml")) {
-                xml = inflated;
-            }
-            else {
-                throw new Error(`Decompressed data doesn't contain valid XML in ${name}`);
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : "Unknown error";
-            throw new Error(`Failed to decompress ${name}: ${message}`);
-        }
-    }
-    // Sanitize XML by removing illegal control characters (per XML 1.0 spec)
-    // Preserves tabs (0x09), newlines (0x0A), and carriage returns (0x0D)
-    xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, "");
-    return xml;
-};

package/build/types/lib/xml/extract-xml-from-system-content.d.ts

@@ -1,15 +0,0 @@
-/**
- * Extracts and decompresses XML content from Excel system files (e.g., workbook.xml, [Content_Types].xml).
- * Handles both compressed (raw DEFLATE) and uncompressed (plain XML) formats with comprehensive error handling.
- *
- * @param {Buffer} buffer - The file content to process, which may be:
- *                         - Raw XML text
- *                         - DEFLATE-compressed XML data (without zlib headers)
- * @param {string} name - The filename being processed (for error reporting)
- * @returns {string} - The extracted XML content as a sanitized UTF-8 string
- * @throws {Error} - With descriptive messages for various failure scenarios:
- *                  - Empty buffer
- *                  - Decompression failures
- *                  - Invalid XML content
- */
-export declare const extractXmlFromSystemContent: (buffer: Buffer, name: string) => string;