@js-ak/excel-toolbox 1.5.0 → 1.7.0

package/build/types/lib/template/utils/write-rows-to-stream.d.ts

@@ -13,17 +13,30 @@ interface WritableLike {
  * 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 declare function writeRowsToStream(output: WritableLike, rows: AsyncIterable<unknown[] | unknown[][]>, startRowNumber: number): Promise<{
+    dimension: {
+        maxColumn: string;
+        maxRow: number;
+        minColumn: string;
+        minRow: number;
+    };
     rowNumber: number;
 }>;
 export {};

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.5.0",
+  "version": "1.7.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;