@niicojs/excel 0.2.4 → 0.2.6

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,9 +9,6 @@ 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`)
@@ -142,47 +139,6 @@ 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
@@ -209,56 +165,6 @@ 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`:
@@ -320,7 +226,7 @@ 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({
+const data = sheet.toJson({
   fields: ['name', 'age', 'city'],
 });
 
@@ -332,26 +238,21 @@ interface Person {
 const people = sheet.toJson<Person>();
 
 // Starting from a specific position
-const data3 = sheet.toJson({
+const data = sheet.toJson({
   startRow: 2, // Skip first 2 rows (0-based)
   startCol: 1, // Start from column B
 });
 
 // Limiting the range
-const data4 = sheet.toJson({
+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 data5 = sheet.toJson({
+const data = sheet.toJson({
   stopOnEmptyRow: false, // Default is true
 });
-
-// Control how dates are serialized
-const data6 = sheet.toJson({
-  dateHandling: 'isoString', // 'jsDate' | 'excelSerial' | 'isoString'
-});
 ```
 
 ### Roundtrip Example
@@ -376,24 +277,11 @@ const readData = sheet.toJson();
 ## Saving
 
 ```typescript
-// 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 file
+await wb.toFile('output.xlsx');
 
-// Check if a cell exists without creating it
-const existingCell = sheet.getCellIfExists('A1');
-if (existingCell) {
-  console.log(existingCell.value);
-}
+// Save to buffer (Uint8Array)
+const buffer = await wb.toBuffer();
 ```
 
 ## Type Definitions
@@ -442,121 +330,9 @@ 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
-}
-
-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: