@niicojs/excel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,745 @@
+/**
+ * Cell value types - what a cell can contain
+ */
+type CellValue = number | string | boolean | Date | null | CellError;
+/**
+ * Represents an Excel error value
+ */
+interface CellError {
+    error: ErrorType;
+}
+type ErrorType = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#GETTING_DATA';
+/**
+ * Discriminator for cell content type
+ */
+type CellType = 'number' | 'string' | 'boolean' | 'date' | 'error' | 'empty';
+/**
+ * Style definition for cells
+ */
+interface CellStyle {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean | 'single' | 'double';
+    strike?: boolean;
+    fontSize?: number;
+    fontName?: string;
+    fontColor?: string;
+    fill?: string;
+    border?: BorderStyle;
+    alignment?: Alignment;
+    numberFormat?: string;
+}
+interface BorderStyle {
+    top?: BorderType;
+    bottom?: BorderType;
+    left?: BorderType;
+    right?: BorderType;
+}
+type BorderType = 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+interface Alignment {
+    horizontal?: 'left' | 'center' | 'right' | 'justify';
+    vertical?: 'top' | 'middle' | 'bottom';
+    wrapText?: boolean;
+    textRotation?: number;
+}
+/**
+ * Cell address with 0-indexed row and column
+ */
+interface CellAddress {
+    row: number;
+    col: number;
+}
+/**
+ * Range address with start and end cells
+ */
+interface RangeAddress {
+    start: CellAddress;
+    end: CellAddress;
+}
+/**
+ * Internal cell data representation
+ */
+interface CellData {
+    /** Cell type: n=number, s=string (shared), str=inline string, b=boolean, e=error, d=date */
+    t?: 'n' | 's' | 'str' | 'b' | 'e' | 'd';
+    /** Raw value */
+    v?: number | string | boolean;
+    /** Formula (without leading =) */
+    f?: string;
+    /** Style index */
+    s?: number;
+    /** Formatted text (cached) */
+    w?: string;
+    /** Number format */
+    z?: string;
+    /** Array formula range */
+    F?: string;
+    /** Dynamic array formula flag */
+    D?: boolean;
+    /** Shared formula index */
+    si?: number;
+}
+/**
+ * Pivot table aggregation functions
+ */
+type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+/**
+ * Configuration for a value field in a pivot table
+ */
+interface PivotValueConfig {
+    /** Source field name (column header) */
+    field: string;
+    /** Aggregation function */
+    aggregation: AggregationType;
+    /** Display name (e.g., "Sum of Sales") */
+    name?: 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;
+}
+/**
+ * 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;
+    /** Unique string values (for shared items) */
+    sharedItems: string[];
+    /** Min numeric value */
+    minValue?: number;
+    /** Max numeric value */
+    maxValue?: number;
+}
+/**
+ * Pivot field axis assignment
+ */
+type PivotFieldAxis = 'row' | 'column' | 'filter' | 'value';
+
+/**
+ * Represents a single cell in a worksheet
+ */
+declare class Cell {
+    private _row;
+    private _col;
+    private _data;
+    private _worksheet;
+    private _dirty;
+    constructor(worksheet: Worksheet, row: number, col: number, data?: CellData);
+    /**
+     * Get the cell address (e.g., 'A1')
+     */
+    get address(): string;
+    /**
+     * Get the 0-based row index
+     */
+    get row(): number;
+    /**
+     * Get the 0-based column index
+     */
+    get col(): number;
+    /**
+     * Get the cell type
+     */
+    get type(): CellType;
+    /**
+     * Get the cell value
+     */
+    get value(): CellValue;
+    /**
+     * Set the cell value
+     */
+    set value(val: CellValue);
+    /**
+     * Write a 2D array of values starting at this cell
+     */
+    set values(data: CellValue[][]);
+    /**
+     * Get the formula (without leading '=')
+     */
+    get formula(): string | undefined;
+    /**
+     * Set the formula (without leading '=')
+     */
+    set formula(f: string | undefined);
+    /**
+     * Get the formatted text (as displayed in Excel)
+     */
+    get text(): string;
+    /**
+     * Get the style index
+     */
+    get styleIndex(): number | undefined;
+    /**
+     * Set the style index
+     */
+    set styleIndex(index: number | undefined);
+    /**
+     * Get the cell style
+     */
+    get style(): CellStyle;
+    /**
+     * Set the cell style (merges with existing)
+     */
+    set style(style: CellStyle);
+    /**
+     * Check if cell has been modified
+     */
+    get dirty(): boolean;
+    /**
+     * Get internal cell data
+     */
+    get data(): CellData;
+    /**
+     * Check if this cell has a date number format
+     */
+    private _isDateFormat;
+    /**
+     * Convert Excel serial date to JavaScript Date
+     * Used when reading dates stored as numbers with date formats
+     */
+    _excelDateToJs(serial: number): Date;
+    /**
+     * Convert JavaScript Date to Excel serial date
+     * Used when writing dates as numbers for Excel compatibility
+     */
+    _jsDateToExcel(date: Date): number;
+}
+
+/**
+ * Represents a range of cells in a worksheet
+ */
+declare class Range {
+    private _worksheet;
+    private _range;
+    constructor(worksheet: Worksheet, range: RangeAddress);
+    /**
+     * Get the range address as a string
+     */
+    get address(): string;
+    /**
+     * Get the number of rows in the range
+     */
+    get rowCount(): number;
+    /**
+     * Get the number of columns in the range
+     */
+    get colCount(): number;
+    /**
+     * Get all values in the range as a 2D array
+     */
+    get values(): CellValue[][];
+    /**
+     * Set values in the range from a 2D array
+     */
+    set values(data: CellValue[][]);
+    /**
+     * Get all formulas in the range as a 2D array
+     */
+    get formulas(): (string | undefined)[][];
+    /**
+     * Set formulas in the range from a 2D array
+     */
+    set formulas(data: (string | undefined)[][]);
+    /**
+     * Get the style of the top-left cell
+     */
+    get style(): CellStyle;
+    /**
+     * Set style for all cells in the range
+     */
+    set style(style: CellStyle);
+    /**
+     * Iterate over all cells in the range
+     */
+    [Symbol.iterator](): Generator<Cell, void, unknown>;
+    /**
+     * Iterate over cells row by row
+     */
+    rows(): Generator<Cell[], void, unknown>;
+}
+
+/**
+ * Represents a worksheet in a workbook
+ */
+declare class Worksheet {
+    private _name;
+    private _workbook;
+    private _cells;
+    private _xmlNodes;
+    private _dirty;
+    private _mergedCells;
+    private _sheetData;
+    constructor(workbook: Workbook, name: string);
+    /**
+     * Get the workbook this sheet belongs to
+     */
+    get workbook(): Workbook;
+    /**
+     * Get the sheet name
+     */
+    get name(): string;
+    /**
+     * Set the sheet name
+     */
+    set name(value: string);
+    /**
+     * Parse worksheet XML content
+     */
+    parse(xml: string): void;
+    /**
+     * Parse the sheetData element to extract cells
+     */
+    private _parseSheetData;
+    /**
+     * Parse a cell XML node to CellData
+     */
+    private _parseCellNode;
+    /**
+     * Get a cell by address or row/col
+     */
+    cell(rowOrAddress: number | string, col?: number): Cell;
+    /**
+     * Get a range of cells
+     */
+    range(rangeStr: string): Range;
+    range(startRow: number, startCol: number, endRow: number, endCol: number): Range;
+    /**
+     * Merge cells in the given range
+     */
+    mergeCells(rangeOrStart: string, end?: string): void;
+    /**
+     * Unmerge cells in the given range
+     */
+    unmergeCells(rangeStr: string): void;
+    /**
+     * Get all merged cell ranges
+     */
+    get mergedCells(): string[];
+    /**
+     * Check if the worksheet has been modified
+     */
+    get dirty(): boolean;
+    /**
+     * Get all cells in the worksheet
+     */
+    get cells(): Map<string, Cell>;
+    /**
+     * Generate XML for this worksheet
+     */
+    toXml(): string;
+    /**
+     * Build a cell XML node from a Cell object
+     */
+    private _buildCellNode;
+}
+
+/**
+ * Manages the shared strings table from xl/sharedStrings.xml
+ * Excel stores strings in a shared table to reduce file size
+ */
+declare class SharedStrings {
+    private strings;
+    private stringToIndex;
+    private _dirty;
+    /**
+     * Parse shared strings from XML content
+     */
+    static parse(xml: string): SharedStrings;
+    /**
+     * Extract text from a string item (si element)
+     * Handles both simple <t> elements and rich text <r> elements
+     */
+    private extractText;
+    /**
+     * Get a string by index
+     */
+    getString(index: number): string | undefined;
+    /**
+     * Add a string and return its index
+     * If the string already exists, returns the existing index
+     */
+    addString(str: string): number;
+    /**
+     * Check if the shared strings table has been modified
+     */
+    get dirty(): boolean;
+    /**
+     * Get the count of strings
+     */
+    get count(): number;
+    /**
+     * Generate XML for the shared strings table
+     */
+    toXml(): string;
+}
+
+/**
+ * Manages the styles (xl/styles.xml)
+ */
+declare class Styles {
+    private _numFmts;
+    private _fonts;
+    private _fills;
+    private _borders;
+    private _cellXfs;
+    private _xmlNodes;
+    private _dirty;
+    private _styleCache;
+    /**
+     * Parse styles from XML content
+     */
+    static parse(xml: string): Styles;
+    /**
+     * Create an empty styles object with defaults
+     */
+    static createDefault(): Styles;
+    private _parseFont;
+    private _parseFill;
+    private _parseBorder;
+    private _parseCellXf;
+    private _parseAlignment;
+    /**
+     * Get a style by index
+     */
+    getStyle(index: number): CellStyle;
+    /**
+     * Create a style and return its index
+     * Uses caching to deduplicate identical styles
+     */
+    createStyle(style: CellStyle): number;
+    private _findOrCreateFont;
+    private _findOrCreateFill;
+    private _findOrCreateBorder;
+    private _findOrCreateNumFmt;
+    /**
+     * Check if styles have been modified
+     */
+    get dirty(): boolean;
+    /**
+     * Generate XML for styles
+     */
+    toXml(): string;
+    private _buildFontNode;
+    private _buildFillNode;
+    private _buildBorderNode;
+    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 _sourceSheet;
+    private _sourceRange;
+    private _fields;
+    private _records;
+    private _recordCount;
+    private _refreshOnLoad;
+    constructor(cacheId: number, sourceSheet: string, sourceRange: string);
+    /**
+     * Get the cache ID
+     */
+    get cacheId(): number;
+    /**
+     * Set refreshOnLoad option
+     */
+    set refreshOnLoad(value: boolean);
+    /**
+     * Get refreshOnLoad option
+     */
+    get refreshOnLoad(): 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;
+}
+
+/**
+ * Represents an Excel pivot table with a fluent API for configuration.
+ */
+declare class PivotTable {
+    private _name;
+    private _cache;
+    private _targetSheet;
+    private _targetCell;
+    private _targetRow;
+    private _targetCol;
+    private _rowFields;
+    private _columnFields;
+    private _valueFields;
+    private _filterFields;
+    private _pivotTableIndex;
+    constructor(name: string, cache: PivotCache, targetSheet: string, targetCell: string, targetRow: number, targetCol: number, pivotTableIndex: number);
+    /**
+     * Get the pivot table name
+     */
+    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;
+    /**
+     * Add a field to the row area
+     * @param fieldName - Name of the source field (column header)
+     */
+    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
+     * @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")
+     */
+    addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string): this;
+    /**
+     * Add a field to the filter (page) area
+     * @param fieldName - Name of the source field (column header)
+     */
+    addFilterField(fieldName: string): this;
+    /**
+     * Generate the pivotTableDefinition XML
+     */
+    toXml(): string;
+    /**
+     * Build a pivotField node for a given field index
+     */
+    private _buildPivotFieldNode;
+    /**
+     * 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.)
+     */
+    private _colToLetter;
+}
+
+/**
+ * Represents an Excel workbook (.xlsx file)
+ */
+declare class Workbook {
+    private _files;
+    private _sheets;
+    private _sheetDefs;
+    private _relationships;
+    private _sharedStrings;
+    private _styles;
+    private _dirty;
+    private _pivotTables;
+    private _pivotCaches;
+    private _nextCacheId;
+    private constructor();
+    /**
+     * Load a workbook from a file path
+     */
+    static fromFile(path: string): Promise<Workbook>;
+    /**
+     * Load a workbook from a buffer
+     */
+    static fromBuffer(data: Uint8Array): Promise<Workbook>;
+    /**
+     * Create a new empty workbook
+     */
+    static create(): Workbook;
+    /**
+     * Get sheet names
+     */
+    get sheetNames(): string[];
+    /**
+     * Get number of sheets
+     */
+    get sheetCount(): number;
+    /**
+     * Get shared strings table
+     */
+    get sharedStrings(): SharedStrings;
+    /**
+     * Get styles
+     */
+    get styles(): Styles;
+    /**
+     * Get a worksheet by name or index
+     */
+    sheet(nameOrIndex: string | number): Worksheet;
+    /**
+     * Add a new worksheet
+     */
+    addSheet(name: string, index?: number): Worksheet;
+    /**
+     * Delete a worksheet by name or index
+     */
+    deleteSheet(nameOrIndex: string | number): void;
+    /**
+     * Rename a worksheet
+     */
+    renameSheet(oldName: string, newName: string): void;
+    /**
+     * Copy a worksheet
+     */
+    copySheet(sourceName: string, newName: string): Worksheet;
+    /**
+     * 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
+     */
+    toFile(path: string): Promise<void>;
+    /**
+     * Save the workbook to a buffer
+     */
+    toBuffer(): Promise<Uint8Array>;
+    private _parseWorkbook;
+    private _parseRelationships;
+    private _updateFiles;
+    private _updateWorkbookXml;
+    private _updateRelationshipsXml;
+    private _updateContentTypes;
+    /**
+     * Generate all pivot table related files
+     */
+    private _updatePivotTableFiles;
+}
+
+/**
+ * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
+ * @param address - Cell address string
+ * @returns CellAddress with 0-based row and col
+ */
+declare const parseAddress: (address: string) => CellAddress;
+/**
+ * Converts row/col indices to an Excel cell address
+ * @param row - 0-based row index
+ * @param col - 0-based column index
+ * @returns Cell address string like 'A1'
+ */
+declare const toAddress: (row: number, col: number) => string;
+/**
+ * Parses an Excel range (e.g., 'A1:B10') to start/end addresses
+ * @param range - Range string
+ * @returns RangeAddress with start and end
+ */
+declare const parseRange: (range: string) => RangeAddress;
+/**
+ * Converts a RangeAddress to a range string
+ * @param range - RangeAddress object
+ * @returns Range string like 'A1:B10'
+ */
+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, ErrorType, PivotFieldAxis, PivotTableConfig, PivotValueConfig, RangeAddress };
+//# sourceMappingURL=index.d.ts.map