@js-ak/excel-toolbox 1.4.0 → 1.5.0

package/build/types/lib/template/utils/process-merge-cells.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function processMergeCells(sheetXml: string): {
+    initialMergeCells: string[];
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    modifiedXml: string;
+};

package/build/types/lib/template/utils/process-merge-finalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function processMergeFinalize(data: {
+    initialMergeCells: string[];
+    lastIndex: number;
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    resultRows: string[];
+    rowShift: number;
+    sharedStrings: string[];
+    sharedStringsHeader: string | null;
+    sheetMergeCells: string[];
+    sheetXml: string;
+}): {
+    shared: string;
+    sheet: string;
+};

package/build/types/lib/template/utils/process-rows.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function processRows(data: {
+    replacements: Record<string, unknown>;
+    sharedIndexMap: Map<string, number>;
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    sharedStrings: string[];
+    sheetMergeCells: string[];
+    sheetXml: string;
+}): {
+    lastIndex: number;
+    resultRows: string[];
+    rowShift: number;
+};

package/build/types/lib/template/utils/process-shared-strings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function processSharedStrings(sharedStringsXml: string): {
+    sharedIndexMap: Map<string, number>;
+    sharedStrings: string[];
+    sharedStringsHeader: string | null;
+    sheetMergeCells: string[];
+};

package/build/types/lib/template/utils/validate-worksheet-xml.d.ts

@@ -5,5 +5,21 @@ interface ValidationResult {
         details?: string;
     };
 }
+/**
+ * Validates an Excel worksheet XML against the expected structure and rules.
+ *
+ * Checks the following:
+ * 1. XML starts with <?xml declaration
+ * 2. Root element is worksheet
+ * 3. Required elements are present
+ * 4. row numbers are in ascending order
+ * 5. No duplicate row numbers
+ * 6. No overlapping merge ranges
+ * 7. All cells are within the specified dimension
+ * 8. All mergeCell tags refer to existing cells
+ *
+ * @param xml The raw XML content of the worksheet
+ * @returns A ValidationResult object indicating if the XML is valid, and an error message if it's not
+ */
 export declare function validateWorksheetXml(xml: string): ValidationResult;
 export {};

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

@@ -1,4 +1,7 @@
-import * as fs from "node:fs";
+interface WritableLike {
+    write(chunk: string | Buffer): boolean;
+    end?: () => void;
+}
 /**
  * Writes an async iterable of rows to an Excel XML file.
  *
@@ -20,6 +23,7 @@ import * as fs from "node:fs";
  *          last row number written to the file (i.e., the `startRowNumber`
  *          plus the number of rows written).
  */
-export declare function writeRowsToStream(output: fs.WriteStream, rows: AsyncIterable<unknown[]>, startRowNumber: number): Promise<{
+export declare function writeRowsToStream(output: WritableLike, rows: AsyncIterable<unknown[] | unknown[][]>, startRowNumber: number): Promise<{
     rowNumber: number;
 }>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-ak/excel-toolbox",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "excel-toolbox",
   "publishConfig": {
     "access": "public",
@@ -45,7 +45,8 @@
     "postbuild:esm": "node scripts/write-esm-package.js",
     "postbuild:cjs": "node scripts/write-cjs-package.js",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "repository": {
     "type": "git",
@@ -70,6 +71,7 @@
     "@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",
     "eslint-plugin-sort-exports": "0.9.1",
@@ -77,7 +79,7 @@
     "semantic-release": "24.0.0",
     "typescript": "5.8.3",
     "typescript-eslint": "8.29.0",
-    "vitest": "3.1.1"
+    "vitest": "3.1.2"
   },
   "dependencies": {
     "pako": "2.1.0"