@niicojs/excel 0.2.2 → 0.2.4

package/README.md

@@ -9,7 +9,12 @@ A TypeScript library for Excel/OpenXML manipulation with maximum format preserva
 - Full formula support (read/write/preserve)
 - Cell styles (fonts, fills, borders, alignment)
 - Merged cells
+- Column widths and row heights
+- Freeze panes
+- Pivot tables with fluent API
 - 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 +33,7 @@ import { Workbook } from '@niicojs/excel';
 
 // Create a new workbook
 const wb = Workbook.create();
+wb.addSheet('Sheet1');
 const sheet = wb.sheet('Sheet1');
 
 // Write data
@@ -136,6 +142,47 @@ sheet.unmergeCells('A1:C1');
 console.log(sheet.mergedCells); // ['A1:C3', 'D5:E10', ...]
 ```
 
+## Column Widths and Row Heights
+
+```typescript
+const sheet = wb.sheet(0);
+
+// Set column width (by letter or 0-based index)
+sheet.setColumnWidth('A', 20);
+sheet.setColumnWidth(1, 15); // Column B
+
+// Get column width
+const width = sheet.getColumnWidth('A'); // 20 or undefined
+
+// Set row height (0-based index)
+sheet.setRowHeight(0, 30); // First row
+
+// Get row height
+const height = sheet.getRowHeight(0); // 30 or undefined
+```
+
+## Freeze Panes
+
+```typescript
+const sheet = wb.sheet(0);
+
+// Freeze first row (header)
+sheet.freezePane(1, 0);
+
+// Freeze first column
+sheet.freezePane(0, 1);
+
+// Freeze first row and first column
+sheet.freezePane(1, 1);
+
+// Unfreeze
+sheet.freezePane(0, 0);
+
+// Get current freeze pane configuration
+const frozen = sheet.getFrozenPane();
+// { row: 1, col: 0 } or null
+```
+
 ## Sheet Operations
 
 ```typescript
@@ -146,7 +193,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,14 +209,191 @@ wb.copySheet('RawData', 'RawData_Backup');
 wb.deleteSheet('Summary');
 ```
 
+## Pivot Tables
+
+Create pivot tables with a fluent API:
+
+```typescript
+const wb = await Workbook.fromFile('sales-data.xlsx');
+
+// Create a pivot table from source data
+const pivot = wb.createPivotTable({
+  name: 'SalesPivot',
+  source: 'Data!A1:E100', // Source range with headers
+  target: 'Summary!A3', // Where to place the pivot table
+  refreshOnLoad: true, // Refresh when file opens (default: true)
+});
+
+// Configure fields using fluent API
+pivot
+  .addRowField('Region') // Group by region
+  .addRowField('Product') // Then by product
+  .addColumnField('Year') // Columns by year
+  .addValueField('Sales', 'sum', 'Total Sales') // Sum of sales
+  .addValueField('Quantity', 'count', 'Order Count') // Count of orders
+  .addFilterField('Category'); // Page filter
+
+// Sort and filter fields
+pivot
+  .sortField('Region', 'asc') // Sort ascending
+  .filterField('Product', { include: ['Widget', 'Gadget'] }); // Include only these
+
+await wb.toFile('report.xlsx');
+```
+
+### Pivot Table API
+
+```typescript
+// Add fields to different areas
+pivot.addRowField(fieldName: string): PivotTable
+pivot.addColumnField(fieldName: string): PivotTable
+pivot.addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string): PivotTable
+pivot.addFilterField(fieldName: string): PivotTable
+
+// Aggregation types: 'sum' | 'count' | 'average' | 'min' | 'max'
+
+// Sort a row or column field
+pivot.sortField(fieldName: string, order: 'asc' | 'desc'): PivotTable
+
+// Filter field values
+pivot.filterField(fieldName: string, filter: { include?: string[] } | { exclude?: string[] }): PivotTable
+```
+
+## 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 data2 = 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 data3 = sheet.toJson({
+  startRow: 2, // Skip first 2 rows (0-based)
+  startCol: 1, // Start from column B
+});
+
+// Limiting the range
+const data4 = sheet.toJson({
+  endRow: 10, // Stop at row 11 (0-based, inclusive)
+  endCol: 3, // Only read columns A-D
+});
+
+// Continue past empty rows
+const data5 = sheet.toJson({
+  stopOnEmptyRow: false, // Default is true
+});
+
+// Control how dates are serialized
+const data6 = sheet.toJson({
+  dateHandling: 'isoString', // 'jsDate' | 'excelSerial' | 'isoString'
+});
+```
+
+### 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
-// Save to file
-await wb.toFile('output.xlsx');
+// Load from file
+const wb = await Workbook.fromFile('template.xlsx');
 
-// Save to buffer (Uint8Array)
-const buffer = await wb.toBuffer();
+// Or load from buffer
+const buffer = await fetch('https://example.com/file.xlsx').then((r) => r.arrayBuffer());
+const wb2 = await Workbook.fromBuffer(new Uint8Array(buffer));
+
+// Read data
+const sheet = wb.sheet('Sheet1');
+console.log(sheet.cell('A1').value); // The cell value
+console.log(sheet.cell('A1').formula); // The formula (if any)
+console.log(sheet.cell('A1').type); // 'string' | 'number' | 'boolean' | 'date' | 'error' | 'empty'
+
+// Check if a cell exists without creating it
+const existingCell = sheet.getCellIfExists('A1');
+if (existingCell) {
+  console.log(existingCell.value);
+}
 ```
 
 ## Type Definitions
@@ -187,8 +411,152 @@ 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
+  dateHandling?: 'jsDate' | 'excelSerial' | 'isoString'; // Default: 'jsDate'
+}
+
+// Pivot table configuration
+interface PivotTableConfig {
+  name: string;
+  source: string; // e.g., "Sheet1!A1:D100"
+  target: string; // e.g., "Sheet2!A3"
+  refreshOnLoad?: boolean; // Default: true
+}
+
+type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+type PivotSortOrder = 'asc' | 'desc';
+interface PivotFieldFilter {
+  include?: string[];
+  exclude?: string[];
+}
+```
+
+## Address Utilities
+
+Helper functions for working with Excel cell addresses:
+
+```typescript
+import {
+  colToLetter,
+  letterToCol,
+  parseAddress,
+  toAddress,
+  parseRange,
+  toRange,
+  normalizeRange,
+  isInRange,
+} from '@niicojs/excel';
+
+// Convert column index to letter (0-based)
+colToLetter(0); // 'A'
+colToLetter(25); // 'Z'
+colToLetter(26); // 'AA'
+
+// Convert column letter to index (0-based)
+letterToCol('A'); // 0
+letterToCol('Z'); // 25
+letterToCol('AA'); // 26
+
+// Parse cell address to row/col
+parseAddress('B3'); // { row: 2, col: 1 }
+parseAddress('$A$1'); // { row: 0, col: 0 } (absolute refs supported)
+
+// Convert row/col to address
+toAddress(0, 0); // 'A1'
+toAddress(9, 2); // 'C10'
+
+// Parse range string
+parseRange('A1:C10'); // { start: { row: 0, col: 0 }, end: { row: 9, col: 2 } }
+
+// Convert range object to string
+toRange({ start: { row: 0, col: 0 }, end: { row: 9, col: 2 } }); // 'A1:C10'
+
+// Normalize range (ensure start is top-left, end is bottom-right)
+normalizeRange({ start: { row: 5, col: 3 }, end: { row: 0, col: 0 } });
+// { start: { row: 0, col: 0 }, end: { row: 5, col: 3 } }
+
+// Check if address is within a range
+isInRange({ row: 2, col: 1 }, { start: { row: 0, col: 0 }, end: { row: 5, col: 5 } }); // true
+isInRange({ row: 10, col: 0 }, { start: { row: 0, col: 0 }, end: { row: 5, col: 5 } }); // false
 ```
 
+## Style Schema
+
+Supported style properties (CellStyle):
+
+```typescript
+interface CellStyle {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean | 'single' | 'double';
+  strike?: boolean;
+  fontSize?: number;
+  fontName?: string;
+  fontColor?: string; // Hex (RGB/RRGGBB/AARRGGBB)
+  fill?: string; // Hex (RGB/RRGGBB/AARRGGBB)
+  border?: {
+    top?: 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+    bottom?: 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+    left?: 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+    right?: 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+  };
+  alignment?: {
+    horizontal?: 'left' | 'center' | 'right' | 'justify';
+    vertical?: 'top' | 'middle' | 'bottom';
+    wrapText?: boolean;
+    textRotation?: number;
+  };
+  numberFormat?: string; // Excel format code
+}
+```
+
+## Performance and Large Files
+
+Tips for large sheets and high-volume writes:
+
+- Prefer `addSheetFromData` for bulk writes when possible.
+- Use `range.getValues({ createMissing: false })` to avoid creating empty cells during reads.
+- Keep shared strings small: prefer numbers/booleans where applicable.
+- Avoid frequent `toBuffer()` calls in loops; batch writes and serialize once.
+
+## Limitations
+
+The library focuses on preserving existing structure and editing common parts of workbooks.
+
+- Chart editing is not supported (charts are preserved only).
+- Conditional formatting and data validation are preserved but not editable yet.
+- Some advanced Excel features (sparklines, slicers, macros) are preserved only.
+
 ## Format Preservation
 
 When modifying existing Excel files, this library preserves: