@niicojs/excel 0.2.6 → 0.3.0

package/dist/index.d.cts

@@ -13,6 +13,10 @@ type ErrorType = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!'
  * Discriminator for cell content type
  */
 type CellType = 'number' | 'string' | 'boolean' | 'date' | 'error' | 'empty';
+/**
+ * Date handling strategy when serializing cell values.
+ */
+type DateHandling = 'jsDate' | 'excelSerial' | 'isoString';
 /**
  * Style definition for cells
  */
@@ -24,7 +28,17 @@ interface CellStyle {
     fontSize?: number;
     fontName?: string;
     fontColor?: string;
+    fontColorTheme?: number;
+    fontColorTint?: number;
+    fontColorIndexed?: number;
     fill?: string;
+    fillTheme?: number;
+    fillTint?: number;
+    fillIndexed?: number;
+    fillBgColor?: string;
+    fillBgTheme?: number;
+    fillBgTint?: number;
+    fillBgIndexed?: number;
     border?: BorderStyle;
     alignment?: Alignment;
     numberFormat?: string;
@@ -83,16 +97,29 @@ interface CellData {
  * Pivot table aggregation functions
  */
 type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+/**
+ * Sort order for pivot fields.
+ */
+type PivotSortOrder = 'asc' | 'desc';
+/**
+ * Filter configuration for pivot fields.
+ */
+interface PivotFieldFilter {
+    include?: string[];
+    exclude?: string[];
+}
 /**
  * Configuration for a value field in a pivot table
  */
 interface PivotValueConfig {
     /** Source field name (column header) */
     field: string;
-    /** Aggregation function */
-    aggregation: AggregationType;
+    /** Aggregation function (default: 'sum') */
+    aggregation?: AggregationType;
     /** Display name (e.g., "Sum of Sales") */
     name?: string;
+    /** Number format (e.g., '$#,##0.00', '0.00%') */
+    numberFormat?: string;
 }
 /**
  * Configuration for creating a pivot table
@@ -168,6 +195,40 @@ interface RichCellValue {
     /** Cell style */
     style?: CellStyle;
 }
+/**
+ * Configuration for creating an Excel Table (ListObject)
+ */
+interface TableConfig {
+    /** Table name (must be unique within the workbook) */
+    name: string;
+    /** Data range including headers (e.g., "A1:D10") */
+    range: string;
+    /** First row contains headers (default: true) */
+    headerRow?: boolean;
+    /** Show total row at the bottom (default: false) */
+    totalRow?: boolean;
+    /** Table style configuration */
+    style?: TableStyleConfig;
+}
+/**
+ * Table style configuration options
+ */
+interface TableStyleConfig {
+    /** Built-in table style name (e.g., "TableStyleMedium2", "TableStyleLight1") */
+    name?: string;
+    /** Show banded/alternating row colors (default: true) */
+    showRowStripes?: boolean;
+    /** Show banded/alternating column colors (default: false) */
+    showColumnStripes?: boolean;
+    /** Highlight first column with special formatting (default: false) */
+    showFirstColumn?: boolean;
+    /** Highlight last column with special formatting (default: false) */
+    showLastColumn?: boolean;
+}
+/**
+ * Aggregation functions available for table total row
+ */
+type TableTotalFunction = 'sum' | 'count' | 'average' | 'min' | 'max' | 'stdDev' | 'var' | 'countNums' | 'none';
 /**
  * Configuration for converting a sheet to JSON objects.
  */
@@ -200,6 +261,10 @@ interface SheetToJsonConfig {
      * If true, stop reading when an empty row is encountered. Defaults to true.
      */
     stopOnEmptyRow?: boolean;
+    /**
+     * How to serialize Date values. Defaults to 'jsDate'.
+     */
+    dateHandling?: DateHandling;
 }
 
 /**
@@ -315,6 +380,12 @@ declare class Range {
      * Get all values in the range as a 2D array
      */
     get values(): CellValue[][];
+    /**
+     * Get all values in the range as a 2D array with options
+     */
+    getValues(options?: {
+        createMissing?: boolean;
+    }): CellValue[][];
     /**
      * Set values in the range from a 2D array
      */
@@ -345,6 +416,122 @@ declare class Range {
     rows(): Generator<Cell[], void, unknown>;
 }
 
+/**
+ * Represents an Excel Table (ListObject) with auto-filter, banded styling, and total row.
+ */
+declare class Table {
+    private _name;
+    private _displayName;
+    private _worksheet;
+    private _range;
+    private _baseRange;
+    private _totalRow;
+    private _autoFilter;
+    private _style;
+    private _columns;
+    private _id;
+    private _dirty;
+    private _headerRow;
+    constructor(worksheet: Worksheet, config: TableConfig, tableId: number);
+    /**
+     * Get the table name
+     */
+    get name(): string;
+    /**
+     * Get the table display name
+     */
+    get displayName(): string;
+    /**
+     * Get the table ID
+     */
+    get id(): number;
+    /**
+     * Get the worksheet this table belongs to
+     */
+    get worksheet(): Worksheet;
+    /**
+     * Get the table range address string
+     */
+    get range(): string;
+    /**
+     * Get the base range excluding total row
+     */
+    get baseRange(): string;
+    /**
+     * Get the table range as RangeAddress
+     */
+    get rangeAddress(): RangeAddress;
+    /**
+     * Get column names
+     */
+    get columns(): string[];
+    /**
+     * Check if table has a total row
+     */
+    get hasTotalRow(): boolean;
+    /**
+     * Check if table has a header row
+     */
+    get hasHeaderRow(): boolean;
+    /**
+     * Check if table has auto-filter enabled
+     */
+    get hasAutoFilter(): boolean;
+    /**
+     * Get the current style configuration
+     */
+    get style(): TableStyleConfig;
+    /**
+     * Check if the table has been modified
+     */
+    get dirty(): boolean;
+    /**
+     * Set a total function for a column
+     * @param columnName - Name of the column (header text)
+     * @param fn - Aggregation function to use
+     * @returns this for method chaining
+     */
+    setTotalFunction(columnName: string, fn: TableTotalFunction): this;
+    /**
+     * Get total function for a column if set
+     */
+    getTotalFunction(columnName: string): TableTotalFunction | undefined;
+    /**
+     * Enable or disable auto-filter
+     * @param enabled - Whether auto-filter should be enabled
+     * @returns this for method chaining
+     */
+    setAutoFilter(enabled: boolean): this;
+    /**
+     * Update table style configuration
+     * @param style - Style options to apply
+     * @returns this for method chaining
+     */
+    setStyle(style: Partial<TableStyleConfig>): this;
+    /**
+     * Enable or disable the total row
+     * @param enabled - Whether total row should be shown
+     * @returns this for method chaining
+     */
+    setTotalRow(enabled: boolean): this;
+    /**
+     * Extract column names from the header row of the worksheet
+     */
+    private _extractColumns;
+    /**
+     * Write the SUBTOTAL formula to a total row cell
+     */
+    private _writeTotalRowFormula;
+    /**
+     * Get the auto-filter range (excludes total row if present)
+     */
+    private _getAutoFilterRange;
+    /**
+     * Generate the table definition XML
+     */
+    toXml(): string;
+}
+
 /**
  * Represents a worksheet in a workbook
  */
@@ -356,6 +543,17 @@ declare class Worksheet {
     private _dirty;
     private _mergedCells;
     private _sheetData;
+    private _columnWidths;
+    private _rowHeights;
+    private _frozenPane;
+    private _dataBoundsCache;
+    private _boundsDirty;
+    private _tables;
+    private _preserveXml;
+    private _tableRelIds;
+    private _sheetViewsDirty;
+    private _colsDirty;
+    private _tablePartsDirty;
     constructor(workbook: Workbook, name: string);
     /**
      * Get the workbook this sheet belongs to
@@ -385,6 +583,10 @@ declare class Worksheet {
      * Get a cell by address or row/col
      */
     cell(rowOrAddress: number | string, col?: number): Cell;
+    /**
+     * Get an existing cell without creating it.
+     */
+    getCellIfExists(rowOrAddress: number | string, col?: number): Cell | undefined;
     /**
      * Get a range of cells
      */
@@ -410,6 +612,81 @@ declare class Worksheet {
      * Get all cells in the worksheet
      */
     get cells(): Map<string, Cell>;
+    /**
+     * Set a column width (0-based index or column letter)
+     */
+    setColumnWidth(col: number | string, width: number): void;
+    /**
+     * Get a column width if set
+     */
+    getColumnWidth(col: number | string): number | undefined;
+    /**
+     * Set a row height (0-based index)
+     */
+    setRowHeight(row: number, height: number): void;
+    /**
+     * Get a row height if set
+     */
+    getRowHeight(row: number): number | undefined;
+    /**
+     * Freeze panes at a given row/column split (counts from top-left)
+     */
+    freezePane(rowSplit: number, colSplit: number): void;
+    /**
+     * Get current frozen pane configuration
+     */
+    getFrozenPane(): {
+        row: number;
+        col: number;
+    } | null;
+    /**
+     * Get all tables in the worksheet
+     */
+    get tables(): Table[];
+    /**
+     * Get column width entries
+     * @internal
+     */
+    getColumnWidths(): Map<number, number>;
+    /**
+     * Get row height entries
+     * @internal
+     */
+    getRowHeights(): Map<number, number>;
+    /**
+     * Set table relationship IDs for tableParts generation.
+     * @internal
+     */
+    setTableRelIds(ids: string[] | null): void;
+    /**
+     * Create an Excel Table (ListObject) from a data range.
+     *
+     * Tables provide structured data features like auto-filter, banded styling,
+     * and total row with aggregation functions.
+     *
+     * @param config - Table configuration
+     * @returns Table instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Create a table with default styling
+     * const table = sheet.createTable({
+     *   name: 'SalesData',
+     *   range: 'A1:D10',
+     * });
+     *
+     * // Create a table with total row
+     * const table = sheet.createTable({
+     *   name: 'SalesData',
+     *   range: 'A1:D10',
+     *   totalRow: true,
+     *   style: { name: 'TableStyleMedium2' }
+     * });
+     *
+     * table.setTotalFunction('Sales', 'sum');
+     * ```
+     */
+    createTable(config: TableConfig): Table;
     /**
      * Convert sheet data to an array of JSON objects.
      *
@@ -429,6 +706,7 @@ declare class Worksheet {
      * ```
      */
     toJson<T = Record<string, CellValue>>(config?: SheetToJsonConfig): T[];
+    private _serializeDate;
     /**
      * Get the bounds of data in the sheet (min/max row and column with data)
      */
@@ -437,6 +715,12 @@ declare class Worksheet {
      * Generate XML for this worksheet
      */
     toXml(): string;
+    private _buildSheetDataNode;
+    private _buildSheetViewsNode;
+    private _buildColsNode;
+    private _buildMergeCellsNode;
+    private _buildTablePartsNode;
+    private _buildPreservedWorksheet;
     /**
      * Build a cell XML node from a Cell object
      */
@@ -448,9 +732,10 @@ declare class Worksheet {
  * Excel stores strings in a shared table to reduce file size
  */
 declare class SharedStrings {
-    private strings;
+    private entries;
     private stringToIndex;
     private _dirty;
+    private _totalCount;
     /**
      * Parse shared strings from XML content
      */
@@ -477,6 +762,10 @@ declare class SharedStrings {
      * Get the count of strings
      */
     get count(): number;
+    /**
+     * Get total usage count of shared strings
+     */
+    get totalCount(): number;
     /**
      * Generate XML for the shared strings table
      */
@@ -495,6 +784,14 @@ declare class Styles {
     private _xmlNodes;
     private _dirty;
     private _styleCache;
+    private _styleObjectCache;
+    /**
+     * Generate a deterministic cache key for a style object.
+     * More efficient than JSON.stringify as it avoids the overhead of
+     * full JSON serialization and produces a consistent key regardless
+     * of property order.
+     */
+    private _getStyleKey;
     /**
      * Parse styles from XML content
      */
@@ -517,6 +814,10 @@ declare class Styles {
      * Uses caching to deduplicate identical styles
      */
     createStyle(style: CellStyle): number;
+    /**
+     * Clone an existing style by index, optionally overriding fields.
+     */
+    cloneStyle(index: number, overrides?: Partial<CellStyle>): number;
     private _findOrCreateFont;
     private _findOrCreateFill;
     private _findOrCreateBorder;
@@ -537,6 +838,8 @@ declare class Styles {
     toXml(): string;
     private _buildFontNode;
     private _buildFillNode;
+    private _toStyleColor;
+    private _colorsEqual;
     private _buildBorderNode;
     private _buildXfNode;
 }
@@ -547,6 +850,7 @@ declare class Styles {
  */
 declare class PivotCache {
     private _cacheId;
+    private _fileIndex;
     private _sourceSheet;
     private _sourceRange;
     private _fields;
@@ -554,11 +858,15 @@ declare class PivotCache {
     private _recordCount;
     private _refreshOnLoad;
     private _sharedItemsIndexMap;
-    constructor(cacheId: number, sourceSheet: string, sourceRange: string);
+    constructor(cacheId: number, sourceSheet: string, sourceRange: string, fileIndex: number);
     /**
      * Get the cache ID
      */
     get cacheId(): number;
+    /**
+     * Get the file index for this cache (used for file naming).
+     */
+    get fileIndex(): number;
     /**
      * Set refreshOnLoad option
      */
@@ -625,9 +933,11 @@ declare class PivotTable {
     private _columnFields;
     private _valueFields;
     private _filterFields;
+    private _fieldAssignments;
     private _pivotTableIndex;
+    private _cacheFileIndex;
     private _styles;
-    constructor(name: string, cache: PivotCache, targetSheet: string, targetCell: string, targetRow: number, targetCol: number, pivotTableIndex: number);
+    constructor(name: string, cache: PivotCache, targetSheet: string, targetCell: string, targetRow: number, targetCol: number, pivotTableIndex: number, cacheFileIndex: number);
     /**
      * Get the pivot table name
      */
@@ -648,6 +958,11 @@ declare class PivotTable {
      * Get the pivot table index (for file naming)
      */
     get index(): number;
+    /**
+     * Get the pivot cache file index used for rels.
+     * @internal
+     */
+    get cacheFileIndex(): number;
     /**
      * Set the styles reference for number format resolution
      * @internal
@@ -664,18 +979,38 @@ declare class PivotTable {
      */
     addColumnField(fieldName: string): this;
     /**
-     * Add a field to the values area with aggregation
-     * @param fieldName - Name of the source field (column header)
-     * @param aggregation - Aggregation function (sum, count, average, min, max)
-     * @param displayName - Optional display name (defaults to "Sum of FieldName")
-     * @param numberFormat - Optional number format (e.g., '$#,##0.00', '0.00%')
+     * Add a field to the values area with aggregation.
+     *
+     * Supports two call signatures:
+     * - Positional: `addValueField(fieldName, aggregation?, displayName?, numberFormat?)`
+     * - Object: `addValueField({ field, aggregation?, name?, numberFormat? })`
+     *
+     * @example
+     * // Positional arguments
+     * pivot.addValueField('Sales', 'sum', 'Total Sales', '$#,##0.00');
+     *
+     * // Object form
+     * pivot.addValueField({ field: 'Sales', aggregation: 'sum', name: 'Total Sales', numberFormat: '$#,##0.00' });
      */
+    addValueField(config: PivotValueConfig): this;
     addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string, numberFormat?: string): this;
     /**
      * Add a field to the filter (page) area
      * @param fieldName - Name of the source field (column header)
      */
     addFilterField(fieldName: string): this;
+    /**
+     * Set a sort order for a row or column field
+     * @param fieldName - Name of the field to sort
+     * @param order - Sort order ('asc' or 'desc')
+     */
+    sortField(fieldName: string, order: PivotSortOrder): this;
+    /**
+     * Filter items for a row, column, or filter field
+     * @param fieldName - Name of the field to filter
+     * @param filter - Filter configuration with include or exclude list
+     */
+    filterField(fieldName: string, filter: PivotFieldFilter): this;
     /**
      * Generate the pivotTableDefinition XML
      */
@@ -684,6 +1019,10 @@ declare class PivotTable {
      * Build a pivotField node for a given field index
      */
     private _buildPivotFieldNode;
+    /**
+     * Build item nodes for a pivot field, with optional filtering
+     */
+    private _buildItemNodes;
     /**
      * Build row items based on unique values in row fields
      */
@@ -724,6 +1063,9 @@ declare class Workbook {
     private _pivotTables;
     private _pivotCaches;
     private _nextCacheId;
+    private _nextCacheFileIndex;
+    private _nextTableId;
+    private _dateHandling;
     private constructor();
     /**
      * Load a workbook from a file path
@@ -753,6 +1095,20 @@ declare class Workbook {
      * Get styles
      */
     get styles(): Styles;
+    /**
+     * Get the workbook date handling strategy.
+     */
+    get dateHandling(): DateHandling;
+    /**
+     * Set the workbook date handling strategy.
+     */
+    set dateHandling(value: DateHandling);
+    /**
+     * Get the next unique table ID for this workbook.
+     * Table IDs must be unique across all worksheets.
+     * @internal
+     */
+    getNextTableId(): number;
     /**
      * Get a worksheet by name or index
      */
@@ -773,6 +1129,9 @@ declare class Workbook {
      * Copy a worksheet
      */
     copySheet(sourceName: string, newName: string): Worksheet;
+    private _createUniqueTableName;
+    private _sanitizeTableName;
+    private _hasTableName;
     /**
      * Create a new worksheet from an array of objects.
      *
@@ -872,11 +1231,16 @@ declare class Workbook {
     private _updateFiles;
     private _updateWorkbookXml;
     private _updateRelationshipsXml;
+    private _buildRelationshipInfo;
     private _updateContentTypes;
     /**
      * Generate all pivot table related files
      */
     private _updatePivotTableFiles;
+    /**
+     * Generate all table related files
+     */
+    private _updateTableFiles;
 }
 
 /**
@@ -905,6 +1269,6 @@ 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, RichCellValue, SheetFromDataConfig, SheetToJsonConfig };
+export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Table, Workbook, Worksheet, parseAddress, parseRange, toAddress, toRange };
+export type { AggregationType, Alignment, BorderStyle, BorderType, CellAddress, CellError, CellStyle, CellType, CellValue, ColumnConfig, DateHandling, ErrorType, PivotFieldAxis, PivotFieldFilter, PivotSortOrder, PivotTableConfig, PivotValueConfig, RangeAddress, RichCellValue, SheetFromDataConfig, SheetToJsonConfig, TableConfig, TableStyleConfig, TableTotalFunction };
 //# sourceMappingURL=index.d.cts.map