@niicojs/excel 0.3.4 → 0.3.5

package/dist/index.d.ts

@@ -93,82 +93,6 @@ interface CellData {
     /** Shared formula index */
     si?: number;
 }
-/**
- * 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 (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
- */
-interface PivotTableConfig {
-    /** Name of the pivot table */
-    name: string;
-    /** Source data range with sheet name (e.g., "Sheet1!A1:D100") */
-    source: string;
-    /** Target cell where pivot table will be placed (e.g., "Sheet2!A3") */
-    target: string;
-    /** Refresh the pivot table data when the file is opened (default: true) */
-    refreshOnLoad?: boolean;
-    /** Save pivot cache data in the file (default: true) */
-    saveData?: boolean;
-}
-/**
- * Internal representation of a pivot cache field
- */
-interface PivotCacheField {
-    /** Field name (from header row) */
-    name: string;
-    /** Field index (0-based) */
-    index: number;
-    /** Whether this field contains numbers */
-    isNumeric: boolean;
-    /** Whether this field contains dates */
-    isDate: boolean;
-    /** Whether this field contains boolean values */
-    hasBoolean: boolean;
-    /** Whether this field contains blank (null/undefined) values */
-    hasBlank: boolean;
-    /** Number format ID for this field (cache field numFmtId) */
-    numFmtId?: number;
-    /** Unique string values (for shared items) */
-    sharedItems: string[];
-    /** Min numeric value */
-    minValue?: number;
-    /** Max numeric value */
-    maxValue?: number;
-    /** Min date value (for date fields) */
-    minDate?: Date;
-    /** Max date value (for date fields) */
-    maxDate?: Date;
-}
-/**
- * Pivot field axis assignment
- */
-type PivotFieldAxis = 'row' | 'column' | 'filter' | 'value';
 /**
  * Configuration for creating a sheet from an array of objects
  */
@@ -237,6 +161,49 @@ interface TableStyleConfig {
     /** Highlight last column with special formatting (default: false) */
     showLastColumn?: boolean;
 }
+/**
+ * Pivot table aggregation functions.
+ */
+type PivotAggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+/**
+ * Pivot field sort order.
+ */
+type PivotSortOrder = 'asc' | 'desc';
+/**
+ * Filter definition for pivot fields.
+ * Use either include or exclude, not both.
+ */
+type PivotFieldFilter = {
+    include: string[];
+} | {
+    exclude: string[];
+};
+/**
+ * Value field configuration for pivot tables.
+ */
+interface PivotValueConfig {
+    /** Source field name */
+    field: string;
+    /** Aggregation type (default: 'sum') */
+    aggregation?: PivotAggregationType;
+    /** Display name for the value field */
+    name?: string;
+    /** Number format to apply to values */
+    numberFormat?: string;
+}
+/**
+ * Configuration for creating a PivotTable.
+ */
+interface PivotTableConfig {
+    /** Pivot table name */
+    name: string;
+    /** Source data range with sheet name, e.g. "Data!A1:E100" */
+    source: string;
+    /** Target cell with sheet name, e.g. "Summary!A3" */
+    target: string;
+    /** Refresh pivot when opening workbook (default: true) */
+    refreshOnLoad?: boolean;
+}
 /**
  * Aggregation functions available for table total row
  */
@@ -288,6 +255,16 @@ interface SheetToJsonConfig {
      */
     locale?: string;
 }
+/**
+ * Options for reading a workbook from file/buffer.
+ */
+interface WorkbookReadOptions {
+    /**
+     * Enable lazy parsing of ZIP entries and XML parts.
+     * Defaults to true.
+     */
+    lazy?: boolean;
+}
 
 /**
  * Represents a single cell in a worksheet
@@ -568,7 +545,6 @@ declare class Worksheet {
     private _xmlNodes;
     private _dirty;
     private _mergedCells;
-    private _sheetData;
     private _columnWidths;
     private _rowHeights;
     private _frozenPane;
@@ -576,10 +552,14 @@ declare class Worksheet {
     private _boundsDirty;
     private _tables;
     private _preserveXml;
+    private _rawXml;
+    private _lazyParse;
     private _tableRelIds;
+    private _pivotTableRelIds;
     private _sheetViewsDirty;
     private _colsDirty;
     private _tablePartsDirty;
+    private _pivotTablePartsDirty;
     constructor(workbook: Workbook, name: string);
     /**
      * Get the workbook this sheet belongs to
@@ -596,7 +576,10 @@ declare class Worksheet {
     /**
      * Parse worksheet XML content
      */
-    parse(xml: string): void;
+    parse(xml: string, options?: {
+        lazy?: boolean;
+    }): void;
+    private _ensureParsed;
     /**
      * Parse the sheetData element to extract cells
      */
@@ -684,6 +667,11 @@ declare class Worksheet {
      * @internal
      */
     setTableRelIds(ids: string[] | null): void;
+    /**
+     * Set pivot table relationship IDs for pivotTableParts generation.
+     * @internal
+     */
+    setPivotTableRelIds(ids: string[] | null): void;
     /**
      * Create an Excel Table (ListObject) from a data range.
      *
@@ -746,6 +734,7 @@ declare class Worksheet {
     private _buildColsNode;
     private _buildMergeCellsNode;
     private _buildTablePartsNode;
+    private _buildPivotTablePartsNode;
     private _buildPreservedWorksheet;
     /**
      * Build a cell XML node from a Cell object
@@ -762,10 +751,13 @@ declare class SharedStrings {
     private stringToIndex;
     private _dirty;
     private _totalCount;
+    private _rawXml;
+    private _parsed;
     /**
      * Parse shared strings from XML content
      */
     static parse(xml: string): SharedStrings;
+    private _parse;
     /**
      * Extract text from a string item (si element)
      * Handles both simple <t> elements and rich text <r> elements
@@ -812,6 +804,8 @@ declare class Styles {
     private _borders;
     private _cellXfs;
     private _xmlNodes;
+    private _rawXml;
+    private _parsed;
     private _dirty;
     private _styleCache;
     private _styleObjectCache;
@@ -826,6 +820,7 @@ declare class Styles {
      * Parse styles from XML content
      */
     static parse(xml: string): Styles;
+    private _parse;
     /**
      * Create an empty styles object with defaults
      */
@@ -874,228 +869,81 @@ declare class Styles {
     private _buildXfNode;
 }
 
-/**
- * Manages the pivot cache (definition and records) for a pivot table.
- * The cache stores source data metadata and cached values.
- */
-declare class PivotCache {
-    private _cacheId;
-    private _fileIndex;
-    private _sourceSheet;
-    private _sourceRange;
-    private _fields;
-    private _records;
-    private _recordCount;
-    private _saveData;
-    private _refreshOnLoad;
-    private _sharedItemsIndexMap;
-    private _blankItemIndexMap;
-    private _styles;
-    constructor(cacheId: number, sourceSheet: string, sourceRange: string, fileIndex: number);
-    /**
-     * Set styles reference for number format resolution.
-     * @internal
-     */
-    setStyles(styles: Styles): void;
-    /**
-     * Get the cache ID
-     */
-    get cacheId(): number;
-    /**
-     * Get the file index for this cache (used for file naming).
-     */
-    get fileIndex(): number;
-    /**
-     * Set refreshOnLoad option
-     */
-    set refreshOnLoad(value: boolean);
-    /**
-     * Set saveData option
-     */
-    set saveData(value: boolean);
-    /**
-     * Get refreshOnLoad option
-     */
-    get refreshOnLoad(): boolean;
-    /**
-     * Get saveData option
-     */
-    get saveData(): boolean;
-    /**
-     * Get the source sheet name
-     */
-    get sourceSheet(): string;
-    /**
-     * Get the source range
-     */
-    get sourceRange(): string;
-    /**
-     * Get the full source reference (Sheet!Range)
-     */
-    get sourceRef(): string;
-    /**
-     * Get the fields in this cache
-     */
-    get fields(): PivotCacheField[];
-    /**
-     * Get the number of data records
-     */
-    get recordCount(): number;
-    /**
-     * Build the cache from source data.
-     * @param headers - Array of column header names
-     * @param data - 2D array of data rows (excluding headers)
-     */
-    buildFromData(headers: string[], data: CellValue[][]): void;
-    /**
-     * Get field by name
-     */
-    getField(name: string): PivotCacheField | undefined;
-    /**
-     * Get field index by name
-     */
-    getFieldIndex(name: string): number;
-    /**
-     * Generate the pivotCacheDefinition XML
-     */
-    toDefinitionXml(recordsRelId: string): string;
-    /**
-     * Generate the pivotCacheRecords XML
-     */
-    toRecordsXml(): string;
-    private _formatDate;
-    private _formatNumber;
-    private _excelSerialToDate;
+interface PivotFieldMeta {
+    name: string;
+    sourceCol: number;
 }
-
 /**
- * Represents an Excel pivot table with a fluent API for configuration.
+ * Represents an Excel PivotTable with a fluent configuration API.
  */
 declare class PivotTable {
+    private _workbook;
     private _name;
-    private _cache;
-    private _targetSheet;
+    private _sourceSheetName;
+    private _sourceSheet;
+    private _sourceRange;
+    private _targetSheetName;
     private _targetCell;
-    private _targetRow;
-    private _targetCol;
+    private _refreshOnLoad;
+    private _cacheId;
+    private _pivotId;
+    private _cachePartIndex;
+    private _fields;
     private _rowFields;
     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, cacheFileIndex: number);
-    /**
-     * Get the pivot table name
-     */
+    private _valueFields;
+    private _sortOrders;
+    private _filters;
+    constructor(workbook: Workbook, config: PivotTableConfig, sourceSheetName: string, sourceSheet: Worksheet, sourceRange: RangeAddress, targetSheetName: string, targetCell: {
+        row: number;
+        col: number;
+    }, cacheId: number, pivotId: number, cachePartIndex: number, fields: PivotFieldMeta[]);
     get name(): string;
-    /**
-     * Get the target sheet name
-     */
-    get targetSheet(): string;
-    /**
-     * Get the target cell address
-     */
-    get targetCell(): string;
-    /**
-     * Get the pivot cache
-     */
-    get cache(): PivotCache;
-    /**
-     * 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
-     */
-    setStyles(styles: Styles): this;
-    /**
-     * Add a field to the row area
-     * @param fieldName - Name of the source field (column header)
-     */
+    get sourceSheetName(): string;
+    get sourceRange(): RangeAddress;
+    get targetSheetName(): string;
+    get targetCell(): {
+        row: number;
+        col: number;
+    };
+    get refreshOnLoad(): boolean;
+    get cacheId(): number;
+    get pivotId(): number;
+    get cachePartIndex(): number;
     addRowField(fieldName: string): this;
-    /**
-     * Add a field to the column area
-     * @param fieldName - Name of the source field (column header)
-     */
     addColumnField(fieldName: string): this;
-    /**
-     * 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')
-     */
+    addValueField(fieldName: string, aggregation?: PivotAggregationType, displayName?: string, numberFormat?: string): this;
+    addValueField(config: PivotValueConfig): this;
     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;
+    toPivotCacheDefinitionXml(): string;
+    toPivotCacheRecordsXml(): string;
+    toPivotCacheDefinitionRelsXml(): string;
     /**
-     * Generate the pivotTableDefinition XML
-     */
-    toXml(): string;
-    /**
-     * 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
-     */
-    private _buildRowItems;
-    /**
-     * Build column items based on unique values in column fields
-     */
-    private _buildColItems;
-    /**
-     * Calculate the location reference for the pivot table output
-     */
-    private _calculateLocationRef;
-    /**
-     * Estimate number of rows in pivot table output
-     */
-    private _estimateRowCount;
-    /**
-     * Estimate number of columns in pivot table output
-     */
-    private _estimateColCount;
-    /**
-     * Convert 0-based column index to letter (A, B, ..., Z, AA, etc.)
+     * @internal
      */
-    private _colToLetter;
+    buildPivotPartsXml(): {
+        cacheDefinitionXml: string;
+        cacheRecordsXml: string;
+        cacheRelsXml: string;
+        pivotTableXml: string;
+    };
+    toPivotTableDefinitionXml(): string;
+    private _buildPivotCacheDefinitionXml;
+    private _buildPivotCacheRecordsXml;
+    private _buildPivotTableDefinitionXml;
+    private _buildCacheFieldNode;
+    private _buildTargetAreaRef;
+    private _estimateOutputRows;
+    private _buildPivotCacheData;
+    private _buildSharedItemNode;
+    private _buildRawCacheValueNode;
+    private _assertFieldExists;
+    private _fieldIndex;
+    private _aggregationLabel;
+    private _distinctKey;
 }
 
 /**
@@ -1108,23 +956,25 @@ declare class Workbook {
     private _relationships;
     private _sharedStrings;
     private _styles;
+    private _sharedStringsXml;
+    private _stylesXml;
+    private _lazy;
     private _dirty;
-    private _pivotTables;
-    private _pivotCaches;
-    private _nextCacheId;
-    private _nextCacheFileIndex;
     private _nextTableId;
+    private _pivotTables;
+    private _nextPivotTableId;
+    private _nextPivotCacheId;
     private _dateHandling;
     private _locale;
     private constructor();
     /**
      * Load a workbook from a file path
      */
-    static fromFile(path: string): Promise<Workbook>;
+    static fromFile(path: string, options?: WorkbookReadOptions): Promise<Workbook>;
     /**
      * Load a workbook from a buffer
      */
-    static fromBuffer(data: Uint8Array): Promise<Workbook>;
+    static fromBuffer(data: Uint8Array, options?: WorkbookReadOptions): Promise<Workbook>;
     /**
      * Create a new empty workbook
      */
@@ -1167,6 +1017,16 @@ declare class Workbook {
      * @internal
      */
     getNextTableId(): number;
+    /**
+     * Get all pivot tables in the workbook.
+     */
+    get pivotTables(): PivotTable[];
+    /**
+     * Create a new pivot table.
+     */
+    createPivotTable(config: PivotTableConfig): PivotTable;
+    private _extractPivotFields;
+    private _normalizeRange;
     /**
      * Get a worksheet by name or index
      */
@@ -1247,35 +1107,6 @@ declare class Workbook {
      * Convert an unknown value to a CellValue
      */
     private _toCellValue;
-    /**
-     * Create a pivot table from source data.
-     *
-     * @param config - Pivot table configuration
-     * @returns PivotTable instance for fluent configuration
-     *
-     * @example
-     * ```typescript
-     * const pivot = wb.createPivotTable({
-     *   name: 'SalesPivot',
-     *   source: 'DataSheet!A1:D100',
-     *   target: 'PivotSheet!A3',
-     * });
-     *
-     * pivot
-     *   .addRowField('Region')
-     *   .addColumnField('Product')
-     *   .addValueField('Sales', 'sum', 'Total Sales');
-     * ```
-     */
-    createPivotTable(config: PivotTableConfig): PivotTable;
-    /**
-     * Parse a sheet reference like "Sheet1!A1:D100" into sheet name and range
-     */
-    private _parseSheetRef;
-    /**
-     * Extract headers and data from a source range
-     */
-    private _extractSourceData;
     /**
      * Save the workbook to a file
      */
@@ -1291,14 +1122,14 @@ declare class Workbook {
     private _updateRelationshipsXml;
     private _buildRelationshipInfo;
     private _updateContentTypes;
-    /**
-     * Generate all pivot table related files
-     */
-    private _updatePivotTableFiles;
     /**
      * Generate all table related files
      */
     private _updateTableFiles;
+    /**
+     * Generate pivot cache/table parts and worksheet relationships.
+     */
+    private _updatePivotFiles;
 }
 
 /**
@@ -1326,7 +1157,23 @@ declare const parseRange: (range: string) => RangeAddress;
  * @returns Range string like 'A1:B10'
  */
 declare const toRange: (range: RangeAddress) => string;
+/**
+ * Parses a qualified sheet + address reference.
+ * Supports Sheet!A1 and 'Sheet Name'!A1.
+ */
+declare const parseSheetAddress: (reference: string) => {
+    sheet: string;
+    address: CellAddress;
+};
+/**
+ * Parses a qualified sheet + range reference.
+ * Supports Sheet!A1:B10 and 'Sheet Name'!A1:B10.
+ */
+declare const parseSheetRange: (reference: string) => {
+    sheet: string;
+    range: RangeAddress;
+};
 
-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 };
+export { Cell, PivotTable, Range, SharedStrings, Styles, Table, Workbook, Worksheet, parseAddress, parseRange, parseSheetAddress, parseSheetRange, toAddress, toRange };
+export type { Alignment, BorderStyle, BorderType, CellAddress, CellError, CellStyle, CellType, CellValue, ColumnConfig, DateHandling, ErrorType, PivotAggregationType, PivotFieldFilter, PivotSortOrder, PivotTableConfig, PivotValueConfig, RangeAddress, RichCellValue, SheetFromDataConfig, SheetToJsonConfig, TableConfig, TableStyleConfig, TableTotalFunction, WorkbookReadOptions };
 //# sourceMappingURL=index.d.ts.map