@niicojs/excel 0.2.2 → 0.2.4

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
  */
@@ -83,6 +87,17 @@ 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
  */
@@ -168,6 +183,43 @@ interface RichCellValue {
     /** 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;
+    /**
+     * How to serialize Date values. Defaults to 'jsDate'.
+     */
+    dateHandling?: DateHandling;
+}
 
 /**
  * Represents a single cell in a worksheet
@@ -282,6 +334,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
      */
@@ -323,6 +381,11 @@ declare class Worksheet {
     private _dirty;
     private _mergedCells;
     private _sheetData;
+    private _columnWidths;
+    private _rowHeights;
+    private _frozenPane;
+    private _dataBoundsCache;
+    private _boundsDirty;
     constructor(workbook: Workbook, name: string);
     /**
      * Get the workbook this sheet belongs to
@@ -352,6 +415,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
      */
@@ -377,6 +444,57 @@ 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;
+    /**
+     * 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[];
+    private _serializeDate;
+    /**
+     * Get the bounds of data in the sheet (min/max row and column with data)
+     */
+    private _getDataBounds;
     /**
      * Generate XML for this worksheet
      */
@@ -439,6 +557,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
      */
@@ -461,6 +587,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;
@@ -491,6 +621,7 @@ declare class PivotCache {
     private _records;
     private _recordCount;
     private _refreshOnLoad;
+    private _dateGrouping;
     constructor(cacheId: number, sourceSheet: string, sourceRange: string);
     /**
      * Get the cache ID
@@ -562,6 +693,7 @@ declare class PivotTable {
     private _columnFields;
     private _valueFields;
     private _filterFields;
+    private _fieldAssignments;
     private _pivotTableIndex;
     constructor(name: string, cache: PivotCache, targetSheet: string, targetCell: string, targetRow: number, targetCol: number, pivotTableIndex: number);
     /**
@@ -606,6 +738,14 @@ declare class PivotTable {
      * @param fieldName - Name of the source field (column header)
      */
     addFilterField(fieldName: string): this;
+    /**
+     * Set a sort order for a row/column field
+     */
+    sortField(fieldName: string, order: PivotSortOrder): this;
+    /**
+     * Filter items for a field (include or exclude list)
+     */
+    filterField(fieldName: string, filter: PivotFieldFilter): this;
     /**
      * Generate the pivotTableDefinition XML
      */
@@ -614,6 +754,7 @@ declare class PivotTable {
      * Build a pivotField node for a given field index
      */
     private _buildPivotFieldNode;
+    private _resolveItemFilter;
     /**
      * Build row items based on unique values in row fields
      */
@@ -654,6 +795,7 @@ declare class Workbook {
     private _pivotTables;
     private _pivotCaches;
     private _nextCacheId;
+    private _dateHandling;
     private constructor();
     /**
      * Load a workbook from a file path
@@ -683,6 +825,14 @@ 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 a worksheet by name or index
      */
@@ -809,6 +959,18 @@ declare class Workbook {
     private _updatePivotTableFiles;
 }
 
+/**
+ * Converts a column index (0-based) to Excel column letters (A, B, ..., Z, AA, AB, ...)
+ * @param col - 0-based column index
+ * @returns Column letter(s)
+ */
+declare const colToLetter: (col: number) => string;
+/**
+ * Converts Excel column letters to a 0-based column index
+ * @param letters - Column letter(s) like 'A', 'B', 'AA'
+ * @returns 0-based column index
+ */
+declare const letterToCol: (letters: string) => number;
 /**
  * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
  * @param address - Cell address string
@@ -834,7 +996,15 @@ declare const parseRange: (range: string) => RangeAddress;
  * @returns Range string like 'A1:B10'
  */
 declare const toRange: (range: RangeAddress) => string;
+/**
+ * Normalizes a range so start is always top-left and end is bottom-right
+ */
+declare const normalizeRange: (range: RangeAddress) => RangeAddress;
+/**
+ * Checks if an address is within a range
+ */
+declare const isInRange: (addr: CellAddress, range: RangeAddress) => boolean;
 
-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 };
+export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Workbook, Worksheet, colToLetter, isInRange, letterToCol, normalizeRange, 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 };
 //# sourceMappingURL=index.d.cts.map