@niicojs/excel 0.2.1 → 0.2.3

package/README.md

@@ -10,6 +10,8 @@ A TypeScript library for Excel/OpenXML manipulation with maximum format preserva
 - Cell styles (fonts, fills, borders, alignment)
 - Merged cells
 - Sheet operations (add, delete, rename, copy)
+- Create sheets from arrays of objects (`addSheetFromData`)
+- Convert sheets to JSON arrays (`toJson`)
 - Create new workbooks from scratch
 - TypeScript-first with full type definitions
 
@@ -28,6 +30,7 @@ import { Workbook } from '@niicojs/excel';
 
 // Create a new workbook
 const wb = Workbook.create();
+wb.addSheet('Sheet1');
 const sheet = wb.sheet('Sheet1');
 
 // Write data
@@ -146,7 +149,7 @@ wb.addSheet('Data');
 wb.addSheet('Summary', 0); // Insert at index 0
 
 // Get sheet names
-console.log(wb.sheetNames); // ['Summary', 'Sheet1', 'Data']
+console.log(wb.sheetNames); // ['Summary', 'Data']
 
 // Access sheets
 const sheet = wb.sheet('Data'); // By name
@@ -162,6 +165,115 @@ wb.copySheet('RawData', 'RawData_Backup');
 wb.deleteSheet('Summary');
 ```
 
+## Creating Sheets from Data
+
+Create sheets directly from arrays of objects with `addSheetFromData`:
+
+```typescript
+const wb = Workbook.create();
+
+// Simple usage - object keys become column headers
+const employees = [
+  { name: 'Alice', age: 30, city: 'Paris' },
+  { name: 'Bob', age: 25, city: 'London' },
+];
+
+wb.addSheetFromData({
+  name: 'Employees',
+  data: employees,
+});
+
+// Custom column configuration
+wb.addSheetFromData({
+  name: 'Custom',
+  data: employees,
+  columns: [
+    { key: 'name', header: 'Full Name' },
+    { key: 'age', header: 'Age (years)' },
+    { key: 'city', header: 'Location', style: { bold: true } },
+  ],
+});
+
+// With formulas and styles using RichCellValue
+const orderLines = [
+  { product: 'Widget', price: 10, qty: 5, total: { formula: 'B2*C2', style: { bold: true } } },
+  { product: 'Gadget', price: 20, qty: 3, total: { formula: 'B3*C3', style: { bold: true } } },
+];
+
+wb.addSheetFromData({
+  name: 'Orders',
+  data: orderLines,
+});
+
+// Other options
+wb.addSheetFromData({
+  name: 'Options',
+  data: employees,
+  headerStyle: false, // Don't bold headers
+  startCell: 'B3', // Start at B3 instead of A1
+});
+```
+
+## Converting Sheets to JSON
+
+Convert sheet data back to arrays of objects with `toJson`:
+
+```typescript
+const sheet = wb.sheet('Data');
+
+// Using first row as headers
+const data = sheet.toJson();
+// [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]
+
+// Using custom field names (first row is data, not headers)
+const data = sheet.toJson({
+  fields: ['name', 'age', 'city'],
+});
+
+// With TypeScript generics
+interface Person {
+  name: string | null;
+  age: number | null;
+}
+const people = sheet.toJson<Person>();
+
+// Starting from a specific position
+const data = sheet.toJson({
+  startRow: 2, // Skip first 2 rows (0-based)
+  startCol: 1, // Start from column B
+});
+
+// Limiting the range
+const data = sheet.toJson({
+  endRow: 10, // Stop at row 11 (0-based, inclusive)
+  endCol: 3, // Only read columns A-D
+});
+
+// Continue past empty rows
+const data = sheet.toJson({
+  stopOnEmptyRow: false, // Default is true
+});
+```
+
+### Roundtrip Example
+
+```typescript
+// Create from objects
+const originalData = [
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 },
+];
+
+const sheet = wb.addSheetFromData({
+  name: 'People',
+  data: originalData,
+});
+
+// Read back as objects
+const readData = sheet.toJson();
+// readData equals originalData
+```
+
 ## Saving
 
 ```typescript
@@ -187,6 +299,38 @@ type CellType = 'number' | 'string' | 'boolean' | 'date' | 'error' | 'empty';
 
 // Border types
 type BorderType = 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+
+// Configuration for addSheetFromData
+interface SheetFromDataConfig<T> {
+  name: string;
+  data: T[];
+  columns?: ColumnConfig<T>[];
+  headerStyle?: boolean; // Default: true
+  startCell?: string; // Default: 'A1'
+}
+
+interface ColumnConfig<T> {
+  key: keyof T;
+  header?: string;
+  style?: CellStyle;
+}
+
+// Rich cell value for formulas/styles in data
+interface RichCellValue {
+  value?: CellValue;
+  formula?: string;
+  style?: CellStyle;
+}
+
+// Configuration for toJson
+interface SheetToJsonConfig {
+  fields?: string[];
+  startRow?: number;
+  startCol?: number;
+  endRow?: number;
+  endCol?: number;
+  stopOnEmptyRow?: boolean; // Default: true
+}
 ```
 
 ## Format Preservation

package/dist/index.cjs

@@ -823,6 +823,102 @@ const builder = new fastXmlParser.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
@@ -2525,13 +2621,20 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
    *     { key: 'age', header: 'Age (years)' },
    *   ],
    * });
+   *
+   * // With rich cell values (value, formula, style)
+   * const dataWithFormulas = [
+   *   { product: 'Widget', price: 10, qty: 5, total: { formula: 'B2*C2', style: { bold: true } } },
+   *   { product: 'Gadget', price: 20, qty: 3, total: { formula: 'B3*C3', style: { bold: true } } },
+   * ];
+   * const sheet3 = wb.addSheetFromData({
+   *   name: 'With Formulas',
+   *   data: dataWithFormulas,
+   * });
    * ```
    */ addSheetFromData(config) {
         const { name, data, columns, headerStyle = true, startCell = 'A1' } = config;
-        if (data.length === 0) {
-            // Create empty sheet if no data
-            return this.addSheet(name);
-        }
+        if (!data?.length) return this.addSheet(name);
         // Create the new sheet
         const sheet = this.addSheet(name);
         // Parse start cell
@@ -2562,17 +2665,41 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
                 const colConfig = columnConfigs[colIdx];
                 const value = rowData[colConfig.key];
                 const cell = sheet.cell(startRow + rowIdx, startCol + colIdx);
-                // Convert value to CellValue
-                cell.value = this._toCellValue(value);
-                // Apply column style if defined
+                // Check if value is a rich cell definition
+                if (this._isRichCellValue(value)) {
+                    const richValue = value;
+                    if (richValue.value !== undefined) cell.value = richValue.value;
+                    if (richValue.formula !== undefined) cell.formula = richValue.formula;
+                    if (richValue.style !== undefined) cell.style = richValue.style;
+                } else {
+                    // Convert value to CellValue
+                    cell.value = this._toCellValue(value);
+                }
+                // Apply column style if defined (merged with cell style)
                 if (colConfig.style) {
-                    cell.style = colConfig.style;
+                    cell.style = {
+                        ...cell.style,
+                        ...colConfig.style
+                    };
                 }
             }
         }
         return sheet;
     }
     /**
+   * Check if a value is a rich cell value object with value, formula, or style fields
+   */ _isRichCellValue(value) {
+        if (value === null || value === undefined) {
+            return false;
+        }
+        if (typeof value !== 'object' || value instanceof Date) {
+            return false;
+        }
+        // Check if it has at least one of the rich cell properties
+        const obj = value;
+        return 'value' in obj || 'formula' in obj || 'style' in obj;
+    }
+    /**
    * Infer column configuration from the first data object
    */ _inferColumns(sample) {
         return Object.keys(sample).map((key)=>({

package/dist/index.d.cts

@@ -156,6 +156,51 @@ interface ColumnConfig<T = Record<string, unknown>> {
     /** Cell style for data cells in this column */
     style?: CellStyle;
 }
+/**
+ * Rich cell value with optional formula and style.
+ * Use this when you need to set value, formula, or style for individual cells.
+ */
+interface RichCellValue {
+    /** Cell value */
+    value?: CellValue;
+    /** Formula (without leading '=') */
+    formula?: string;
+    /** Cell style */
+    style?: CellStyle;
+}
+/**
+ * Configuration for converting a sheet to JSON objects.
+ */
+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;
+}
 
 /**
  * Represents a single cell in a worksheet
@@ -365,6 +410,29 @@ declare class Worksheet {
      * Get all cells in the worksheet
      */
     get cells(): Map<string, Cell>;
+    /**
+     * 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[];
+    /**
+     * Get the bounds of data in the sheet (min/max row and column with data)
+     */
+    private _getDataBounds;
     /**
      * Generate XML for this worksheet
      */
@@ -723,9 +791,23 @@ declare class Workbook {
      *     { key: 'age', header: 'Age (years)' },
      *   ],
      * });
+     *
+     * // With rich cell values (value, formula, style)
+     * const dataWithFormulas = [
+     *   { product: 'Widget', price: 10, qty: 5, total: { formula: 'B2*C2', style: { bold: true } } },
+     *   { product: 'Gadget', price: 20, qty: 3, total: { formula: 'B3*C3', style: { bold: true } } },
+     * ];
+     * const sheet3 = wb.addSheetFromData({
+     *   name: 'With Formulas',
+     *   data: dataWithFormulas,
+     * });
      * ```
      */
     addSheetFromData<T extends object>(config: SheetFromDataConfig<T>): Worksheet;
+    /**
+     * Check if a value is a rich cell value object with value, formula, or style fields
+     */
+    private _isRichCellValue;
     /**
      * Infer column configuration from the first data object
      */
@@ -810,5 +892,5 @@ declare const parseRange: (range: string) => RangeAddress;
 declare const toRange: (range: RangeAddress) => string;
 
 export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Workbook, Worksheet, parseAddress, parseRange, toAddress, toRange };
-export type { AggregationType, Alignment, BorderStyle, BorderType, CellAddress, CellError, CellStyle, CellType, CellValue, ColumnConfig, ErrorType, PivotFieldAxis, PivotTableConfig, PivotValueConfig, RangeAddress, SheetFromDataConfig };
+export type { AggregationType, Alignment, BorderStyle, BorderType, CellAddress, CellError, CellStyle, CellType, CellValue, ColumnConfig, ErrorType, PivotFieldAxis, PivotTableConfig, PivotValueConfig, RangeAddress, RichCellValue, SheetFromDataConfig, SheetToJsonConfig };
 //# sourceMappingURL=index.d.cts.map