@niicojs/excel 0.2.7 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 niico
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 niico
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -9,6 +9,9 @@ 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`)
@@ -139,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
@@ -165,6 +209,105 @@ 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
+
+await wb.toFile('report.xlsx');
+```
+
+### Sorting Fields
+
+Sort row or column fields in ascending or descending order:
+
+```typescript
+pivot
+  .addRowField('Region')
+  .addRowField('Product')
+  .addColumnField('Year')
+  .sortField('Region', 'asc') // Sort regions A-Z
+  .sortField('Year', 'desc'); // Sort years newest first
+```
+
+### Filtering Fields
+
+Filter field values using include or exclude lists:
+
+```typescript
+// Include only specific values
+pivot.addRowField('Region').filterField('Region', { include: ['North', 'South'] });
+
+// Exclude specific values
+pivot.addColumnField('Product').filterField('Product', { exclude: ['Discontinued', 'Legacy'] });
+```
+
+### Value Fields with Number Formats
+
+Apply number formats to value fields:
+
+```typescript
+pivot
+  .addValueField('Sales', 'sum', 'Total Sales', '$#,##0.00')
+  .addValueField('Quantity', 'average', 'Avg Qty', '0.00')
+  .addValueField('Margin', 'sum', 'Margin %', '0.00%');
+
+// Or using object syntax
+pivot.addValueField({
+  field: 'Sales',
+  aggregation: 'sum',
+  name: 'Total Sales',
+  numberFormat: '$#,##0.00',
+});
+```
+
+### Pivot Table API Reference
+
+```typescript
+// Add fields to different areas
+pivot.addRowField(fieldName: string): PivotTable
+pivot.addColumnField(fieldName: string): PivotTable
+pivot.addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string, numberFormat?: string): PivotTable
+pivot.addValueField(config: PivotValueConfig): PivotTable
+pivot.addFilterField(fieldName: string): PivotTable
+
+// Sort a row or column field
+pivot.sortField(fieldName: string, order: 'asc' | 'desc'): PivotTable
+
+// Filter field values (use include OR exclude, not both)
+pivot.filterField(fieldName: string, filter: { include?: string[] } | { exclude?: string[] }): PivotTable
+
+// Aggregation types
+type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+
+// Value field config object
+interface PivotValueConfig {
+  field: string;
+  aggregation?: AggregationType; // default: 'sum'
+  name?: string; // default: 'Sum of {field}'
+  numberFormat?: string;
+}
+```
+
 ## Creating Sheets from Data
 
 Create sheets directly from arrays of objects with `addSheetFromData`:
@@ -226,7 +369,7 @@ 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({
+const data2 = sheet.toJson({
   fields: ['name', 'age', 'city'],
 });
 
@@ -238,21 +381,26 @@ interface Person {
 const people = sheet.toJson<Person>();
 
 // Starting from a specific position
-const data = sheet.toJson({
+const data3 = sheet.toJson({
   startRow: 2, // Skip first 2 rows (0-based)
   startCol: 1, // Start from column B
 });
 
 // Limiting the range
-const data = sheet.toJson({
+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 data = sheet.toJson({
+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
@@ -277,11 +425,24 @@ const readData = sheet.toJson();
 ## Saving
 
 ```typescript
-// Save to file
-await wb.toFile('output.xlsx');
+// Load from file
+const wb = await Workbook.fromFile('template.xlsx');
+
+// 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'
 
-// Save to buffer (Uint8Array)
-const buffer = await wb.toBuffer();
+// Check if a cell exists without creating it
+const existingCell = sheet.getCellIfExists('A1');
+if (existingCell) {
+  console.log(existingCell.value);
+}
 ```
 
 ## Type Definitions
@@ -330,9 +491,81 @@ interface SheetToJsonConfig {
   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
+}
+
+// Pivot table value field configuration
+interface PivotValueConfig {
+  field: string;
+  aggregation?: AggregationType;
+  name?: string;
+  numberFormat?: string;
+}
+
+type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+type PivotSortOrder = 'asc' | 'desc';
+
+interface PivotFieldFilter {
+  include?: string[]; // Show only these values
+  exclude?: string[]; // Hide these values (cannot use with include)
 }
 ```
 
+## 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: