@niicojs/excel 0.2.2 → 0.2.3

package/dist/index.js

@@ -821,6 +821,102 @@ const builder = new XMLBuilder(builderOptions);
         return this._cells;
     }
     /**
+   * Convert sheet data to an array of JSON objects.
+   *
+   * @param config - Configuration options
+   * @returns Array of objects where keys are field names and values are cell values
+   *
+   * @example
+   * ```typescript
+   * // Using first row as headers
+   * const data = sheet.toJson();
+   *
+   * // Using custom field names
+   * const data = sheet.toJson({ fields: ['name', 'age', 'city'] });
+   *
+   * // Starting from a specific row/column
+   * const data = sheet.toJson({ startRow: 2, startCol: 1 });
+   * ```
+   */ toJson(config = {}) {
+        const { fields, startRow = 0, startCol = 0, endRow, endCol, stopOnEmptyRow = true } = config;
+        // Get the bounds of data in the sheet
+        const bounds = this._getDataBounds();
+        if (!bounds) {
+            return [];
+        }
+        const effectiveEndRow = endRow ?? bounds.maxRow;
+        const effectiveEndCol = endCol ?? bounds.maxCol;
+        // Determine field names
+        let fieldNames;
+        let dataStartRow;
+        if (fields) {
+            // Use provided field names, data starts at startRow
+            fieldNames = fields;
+            dataStartRow = startRow;
+        } else {
+            // Use first row as headers
+            fieldNames = [];
+            for(let col = startCol; col <= effectiveEndCol; col++){
+                const cell = this._cells.get(toAddress(startRow, col));
+                const value = cell?.value;
+                fieldNames.push(value != null ? String(value) : `column${col}`);
+            }
+            dataStartRow = startRow + 1;
+        }
+        // Read data rows
+        const result = [];
+        for(let row = dataStartRow; row <= effectiveEndRow; row++){
+            const obj = {};
+            let hasData = false;
+            for(let colOffset = 0; colOffset < fieldNames.length; colOffset++){
+                const col = startCol + colOffset;
+                const cell = this._cells.get(toAddress(row, col));
+                const value = cell?.value ?? null;
+                if (value !== null) {
+                    hasData = true;
+                }
+                const fieldName = fieldNames[colOffset];
+                if (fieldName) {
+                    obj[fieldName] = value;
+                }
+            }
+            // Stop on empty row if configured
+            if (stopOnEmptyRow && !hasData) {
+                break;
+            }
+            result.push(obj);
+        }
+        return result;
+    }
+    /**
+   * Get the bounds of data in the sheet (min/max row and column with data)
+   */ _getDataBounds() {
+        if (this._cells.size === 0) {
+            return null;
+        }
+        let minRow = Infinity;
+        let maxRow = -Infinity;
+        let minCol = Infinity;
+        let maxCol = -Infinity;
+        for (const cell of this._cells.values()){
+            if (cell.value !== null) {
+                minRow = Math.min(minRow, cell.row);
+                maxRow = Math.max(maxRow, cell.row);
+                minCol = Math.min(minCol, cell.col);
+                maxCol = Math.max(maxCol, cell.col);
+            }
+        }
+        if (minRow === Infinity) {
+            return null;
+        }
+        return {
+            minRow,
+            maxRow,
+            minCol,
+            maxCol
+        };
+    }
+    /**
    * Generate XML for this worksheet
    */ toXml() {
         // Build sheetData from cells

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niicojs/excel",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "typescript library to manipulate excel files",
   "homepage": "https://github.com/niicojs/excel#readme",
   "bugs": {

package/src/index.ts

@@ -29,6 +29,8 @@ export type {
   SheetFromDataConfig,
   ColumnConfig,
   RichCellValue,
+  // Sheet to JSON types
+  SheetToJsonConfig,
 } from './types';
 
 // Utility exports

package/src/types.ts

@@ -204,3 +204,42 @@ export interface RichCellValue {
   /** Cell style */
   style?: CellStyle;
 }
+
+/**
+ * Configuration for converting a sheet to JSON objects.
+ */
+export interface SheetToJsonConfig {
+  /**
+   * Field names to use for each column.
+   * If provided, the first row of data starts at row 1 (or startRow).
+   * If not provided, the first row is used as field names.
+   */
+  fields?: string[];
+
+  /**
+   * Starting row (0-based). Defaults to 0.
+   * If fields are not provided, this row contains the headers.
+   * If fields are provided, this is the first data row.
+   */
+  startRow?: number;
+
+  /**
+   * Starting column (0-based). Defaults to 0.
+   */
+  startCol?: number;
+
+  /**
+   * Ending row (0-based, inclusive). Defaults to the last row with data.
+   */
+  endRow?: number;
+
+  /**
+   * Ending column (0-based, inclusive). Defaults to the last column with data.
+   */
+  endCol?: number;
+
+  /**
+   * If true, stop reading when an empty row is encountered. Defaults to true.
+   */
+  stopOnEmptyRow?: boolean;
+}

package/src/worksheet.ts

@@ -1,4 +1,4 @@
-import type { CellData, RangeAddress } from './types';
+import type { CellData, RangeAddress, SheetToJsonConfig, CellValue } from './types';
 import type { Workbook } from './workbook';
 import { Cell, parseCellRef } from './cell';
 import { Range } from './range';
@@ -280,6 +280,117 @@ export class Worksheet {
     return this._cells;
   }
 
+  /**
+   * Convert sheet data to an array of JSON objects.
+   *
+   * @param config - Configuration options
+   * @returns Array of objects where keys are field names and values are cell values
+   *
+   * @example
+   * ```typescript
+   * // Using first row as headers
+   * const data = sheet.toJson();
+   *
+   * // Using custom field names
+   * const data = sheet.toJson({ fields: ['name', 'age', 'city'] });
+   *
+   * // Starting from a specific row/column
+   * const data = sheet.toJson({ startRow: 2, startCol: 1 });
+   * ```
+   */
+  toJson<T = Record<string, CellValue>>(config: SheetToJsonConfig = {}): T[] {
+    const { fields, startRow = 0, startCol = 0, endRow, endCol, stopOnEmptyRow = true } = config;
+
+    // Get the bounds of data in the sheet
+    const bounds = this._getDataBounds();
+    if (!bounds) {
+      return [];
+    }
+
+    const effectiveEndRow = endRow ?? bounds.maxRow;
+    const effectiveEndCol = endCol ?? bounds.maxCol;
+
+    // Determine field names
+    let fieldNames: string[];
+    let dataStartRow: number;
+
+    if (fields) {
+      // Use provided field names, data starts at startRow
+      fieldNames = fields;
+      dataStartRow = startRow;
+    } else {
+      // Use first row as headers
+      fieldNames = [];
+      for (let col = startCol; col <= effectiveEndCol; col++) {
+        const cell = this._cells.get(toAddress(startRow, col));
+        const value = cell?.value;
+        fieldNames.push(value != null ? String(value) : `column${col}`);
+      }
+      dataStartRow = startRow + 1;
+    }
+
+    // Read data rows
+    const result: T[] = [];
+
+    for (let row = dataStartRow; row <= effectiveEndRow; row++) {
+      const obj: Record<string, CellValue> = {};
+      let hasData = false;
+
+      for (let colOffset = 0; colOffset < fieldNames.length; colOffset++) {
+        const col = startCol + colOffset;
+        const cell = this._cells.get(toAddress(row, col));
+        const value = cell?.value ?? null;
+
+        if (value !== null) {
+          hasData = true;
+        }
+
+        const fieldName = fieldNames[colOffset];
+        if (fieldName) {
+          obj[fieldName] = value;
+        }
+      }
+
+      // Stop on empty row if configured
+      if (stopOnEmptyRow && !hasData) {
+        break;
+      }
+
+      result.push(obj as T);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the bounds of data in the sheet (min/max row and column with data)
+   */
+  private _getDataBounds(): { minRow: number; maxRow: number; minCol: number; maxCol: number } | null {
+    if (this._cells.size === 0) {
+      return null;
+    }
+
+    let minRow = Infinity;
+    let maxRow = -Infinity;
+    let minCol = Infinity;
+    let maxCol = -Infinity;
+
+    for (const cell of this._cells.values()) {
+      if (cell.value !== null) {
+        minRow = Math.min(minRow, cell.row);
+        maxRow = Math.max(maxRow, cell.row);
+        minCol = Math.min(minCol, cell.col);
+        maxCol = Math.max(maxCol, cell.col);
+      }
+    }
+
+    if (minRow === Infinity) {
+      return null;
+    }
+
+    return { minRow, maxRow, minCol, maxCol };
+  }
+
   /**
    * Generate XML for this worksheet
    */