@cj-tech-master/excelts 3.1.0-canary.20260102041828.82ed571 → 3.1.0

package/dist/types/doc/pivot-table.d.ts

@@ -0,0 +1,152 @@
+import type { Table } from "./table";
+/**
+ * Interface representing the source data abstraction for pivot tables.
+ * This allows both Worksheet and Table to be used as pivot table data sources.
+ */
+export interface PivotTableSource {
+    /** Name of the worksheet containing the source data (used in pivotCacheDefinition) */
+    name: string;
+    /** Get row values by 1-indexed row number */
+    getRow(rowNumber: number): {
+        values: any[];
+    };
+    /** Get column values by 1-indexed column number */
+    getColumn(columnNumber: number): {
+        values: any[];
+    };
+    /** Get all sheet values as a sparse 2D array */
+    getSheetValues(): any[][];
+    /** Dimensions with short range reference (e.g., "A1:E10") */
+    dimensions: {
+        shortRange: string;
+    };
+}
+/**
+ * Model for creating a new pivot table.
+ * Pass this to worksheet.addPivotTable() to create a pivot table.
+ */
+export interface PivotTableModel {
+    /**
+     * Source worksheet for the pivot table data.
+     * Either sourceSheet or sourceTable must be provided (mutually exclusive).
+     */
+    sourceSheet?: PivotTableSource;
+    /**
+     * Source table for the pivot table data.
+     * Either sourceSheet or sourceTable must be provided (mutually exclusive).
+     * The table must have headerRow=true and contain at least one data row.
+     */
+    sourceTable?: Table;
+    /** Column names to use as row fields in the pivot table */
+    rows: string[];
+    /**
+     * Column names to use as column fields in the pivot table.
+     * If omitted or empty, Excel will use "Values" as the column field.
+     * @default []
+     */
+    columns?: string[];
+    /** Column names to aggregate as values in the pivot table */
+    values: string[];
+    /**
+     * Aggregation metric for the pivot table values.
+     * - 'sum': Sum of values (default)
+     * - 'count': Count of values
+     * @default 'sum'
+     */
+    metric?: "sum" | "count";
+    /**
+     * Controls whether pivot table style overrides worksheet column widths.
+     * - '0': Preserve worksheet column widths (useful for custom sizing)
+     * - '1': Apply pivot table style width/height (default Excel behavior)
+     * @default '1'
+     */
+    applyWidthHeightFormats?: "0" | "1";
+}
+/**
+ * Represents a cache field in a pivot table.
+ * Cache fields store unique values from source columns for row/column grouping.
+ */
+export interface CacheField {
+    /** Name of the field (column header from source) */
+    name: string;
+    /** Unique values for row/column fields, null for value fields */
+    sharedItems: any[] | null;
+    /** Minimum value for numeric fields */
+    minValue?: number;
+    /** Maximum value for numeric fields */
+    maxValue?: number;
+}
+/** Aggregation function types for pivot table data fields */
+export type PivotTableSubtotal = "sum" | "count" | "average" | "max" | "min" | "product" | "countNums" | "stdDev" | "stdDevP" | "var" | "varP";
+/**
+ * Data field configuration for pivot table aggregation.
+ * Defines how values are aggregated in the pivot table.
+ */
+export interface DataField {
+    /** Display name for the data field (e.g., "Sum of Sales") */
+    name: string;
+    /** Index of the source field in cacheFields */
+    fld: number;
+    /** Base field index for calculated fields */
+    baseField?: number;
+    /** Base item index for calculated fields */
+    baseItem?: number;
+    /** Aggregation function (default: 'sum') */
+    subtotal?: PivotTableSubtotal;
+}
+/**
+ * Internal pivot table representation used by the library.
+ * This is the processed model after calling makePivotTable().
+ */
+export interface PivotTable {
+    /** Source data adapter (always present for new pivot tables) */
+    source?: PivotTableSource;
+    /** Field indices for row fields */
+    rows: number[];
+    /** Field indices for column fields */
+    columns: number[];
+    /** Field indices for value fields */
+    values: number[];
+    /** Aggregation metric */
+    metric: "sum" | "count";
+    /** Cache fields with shared items */
+    cacheFields: CacheField[];
+    /** Cache ID for linking to pivot cache */
+    cacheId: string;
+    /** Width/height format setting */
+    applyWidthHeightFormats: "0" | "1";
+    /** 1-indexed table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.) */
+    tableNumber: number;
+    /** Flag indicating this pivot table was loaded from file (not newly created) */
+    isLoaded?: boolean;
+    /** Data fields for loaded pivot tables */
+    dataFields?: DataField[];
+    /** Cache definition for loaded pivot tables */
+    cacheDefinition?: ParsedCacheDefinition;
+    /** Cache records for loaded pivot tables */
+    cacheRecords?: ParsedCacheRecords;
+}
+/**
+ * Parsed cache definition from loaded pivot table files.
+ */
+export interface ParsedCacheDefinition {
+    sourceRef?: string;
+    sourceSheet?: string;
+    cacheFields: CacheField[];
+    recordCount?: number;
+    rId?: string;
+    isLoaded?: boolean;
+}
+/**
+ * Parsed cache records from loaded pivot table files.
+ */
+export interface ParsedCacheRecords {
+    records: Array<Array<{
+        type: string;
+        value?: any;
+    }>>;
+    count: number;
+    isLoaded?: boolean;
+}
+declare function makePivotTable(worksheet: any, model: PivotTableModel): PivotTable;
+export { makePivotTable };

package/dist/types/doc/range.d.ts

@@ -0,0 +1,62 @@
+import type { Address } from "../types";
+interface RangeModel {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    sheetName?: string;
+}
+interface RowDimensions {
+    min: number;
+    max: number;
+}
+interface RowWithDimensions {
+    number: number;
+    dimensions?: RowDimensions;
+}
+export type RangeInput = Range | RangeModel | string | number | RangeInput[];
+declare class Range {
+    model: RangeModel;
+    constructor();
+    constructor(range: Range);
+    constructor(model: RangeModel);
+    constructor(rangeString: string);
+    constructor(args: RangeInput[]);
+    constructor(tl: string, br: string);
+    constructor(tl: string, br: string, sheetName: string);
+    constructor(top: number, left: number, bottom: number, right: number);
+    constructor(top: number, left: number, bottom: number, right: number, sheetName: string);
+    setTLBR(tl: string, br: string, sheetName?: string): void;
+    setTLBR(top: number, left: number, bottom: number, right: number, sheetName?: string): void;
+    private decode;
+    get top(): number;
+    set top(value: number);
+    get left(): number;
+    set left(value: number);
+    get bottom(): number;
+    set bottom(value: number);
+    get right(): number;
+    set right(value: number);
+    get sheetName(): string | undefined;
+    set sheetName(value: string | undefined);
+    get _serialisedSheetName(): string;
+    expand(top: number, left: number, bottom: number, right: number): void;
+    expandRow(row: RowWithDimensions | null | undefined): void;
+    expandToAddress(addressStr: string): void;
+    get tl(): string;
+    get $t$l(): string;
+    get br(): string;
+    get $b$r(): string;
+    get range(): string;
+    get $range(): string;
+    get shortRange(): string;
+    get $shortRange(): string;
+    get count(): number;
+    toString(): string;
+    intersects(other: Range): boolean;
+    contains(addressStr: string): boolean;
+    containsEx(address: Address): boolean;
+    forEachAddress(cb: (address: string, row: number, col: number) => void): void;
+}
+export { Range };
+export { Range as Dimensions };

package/dist/types/doc/row.d.ts

@@ -0,0 +1,127 @@
+import { Cell, type CellModel, type CellAddress } from "./cell";
+import type { Worksheet } from "./worksheet";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellValue, RowValues } from "../types";
+interface RowDimensions {
+    min: number;
+    max: number;
+}
+export interface RowModel {
+    cells: CellModel[];
+    number: number;
+    min: number;
+    max: number;
+    height?: number;
+    style: Partial<Style>;
+    hidden: boolean;
+    outlineLevel: number;
+    collapsed: boolean;
+}
+declare class Row {
+    private _worksheet;
+    private _number;
+    private _cells;
+    style: Partial<Style>;
+    private _hidden?;
+    private _outlineLevel?;
+    height?: number;
+    constructor(worksheet: Worksheet, number: number);
+    /**
+     * The row number
+     */
+    get number(): number;
+    /**
+     * The worksheet that contains this row
+     */
+    get worksheet(): Worksheet;
+    /**
+     * Commit a completed row to stream.
+     * Inform Streaming Writer that this row (and all rows before it) are complete
+     * and ready to write. Has no effect on Worksheet document.
+     */
+    commit(): void;
+    /**
+     * Helps GC by breaking cyclic references
+     */
+    destroy(): void;
+    findCell(colNumber: number): Cell | undefined;
+    getCellEx(address: CellAddress): Cell;
+    /**
+     * Get cell by number, column letter or column key
+     */
+    getCell(col: string | number): Cell;
+    /**
+     * Cut one or more cells (cells to the right are shifted left)
+     *
+     * Note: this operation will not affect other rows
+     */
+    splice(start: number, count: number, ...inserts: CellValue[]): void;
+    /**
+     * Iterate over all non-null cells in a row
+     */
+    eachCell(callback: (cell: Cell, colNumber: number) => void): void;
+    /**
+     * Iterate over all cells in a row (including empty cells)
+     */
+    eachCell(opt: {
+        includeEmpty?: boolean;
+    }, callback: (cell: Cell, colNumber: number) => void): void;
+    addPageBreak(lft?: number, rght?: number): void;
+    /**
+     * Get a row as a sparse array
+     */
+    get values(): CellValue[];
+    /**
+     * Set the values by contiguous or sparse array, or by key'd object literal
+     */
+    set values(value: RowValues);
+    /**
+     * Get row values as a 0-based sparse array (column 1 => index 0).
+     *
+     * This is useful when you want to compare/stringify values without the
+     * leading separator produced by the 1-based sparse array returned by `values`.
+     */
+    getValues(): CellValue[];
+    /**
+     * Convenience stringification for row values.
+     *
+     * Equivalent to `row.getValues().join(separator)`.
+     */
+    valuesToString(separator?: string): string;
+    /**
+     * Returns true if the row includes at least one cell with a value
+     */
+    get hasValues(): boolean;
+    /**
+     * Number of cells including empty ones
+     */
+    get cellCount(): number;
+    /**
+     * Number of non-empty cells
+     */
+    get actualCellCount(): number;
+    /**
+     * Get the min and max column number for the non-null cells in this row or null
+     */
+    get dimensions(): RowDimensions | null;
+    private _applyStyle;
+    get numFmt(): string | NumFmt | undefined;
+    set numFmt(value: string | undefined);
+    get font(): Partial<Font> | undefined;
+    set font(value: Partial<Font> | undefined);
+    get alignment(): Partial<Alignment> | undefined;
+    set alignment(value: Partial<Alignment> | undefined);
+    get protection(): Partial<Protection> | undefined;
+    set protection(value: Partial<Protection> | undefined);
+    get border(): Partial<Borders> | undefined;
+    set border(value: Partial<Borders> | undefined);
+    get fill(): Fill | undefined;
+    set fill(value: Fill | undefined);
+    get hidden(): boolean;
+    set hidden(value: boolean);
+    get outlineLevel(): number;
+    set outlineLevel(value: number);
+    get collapsed(): boolean;
+    get model(): RowModel | null;
+    set model(value: RowModel);
+}
+export { Row };

package/dist/types/doc/table.d.ts

@@ -0,0 +1,81 @@
+import type { Address, CellFormulaValue, CellValue, Style, TableColumnProperties, TableStyleProperties } from "../types";
+import type { Worksheet } from "./worksheet";
+interface TableModel {
+    ref: string;
+    name: string;
+    displayName?: string;
+    columns: TableColumnProperties[];
+    rows: CellValue[][];
+    headerRow?: boolean;
+    totalsRow?: boolean;
+    style?: TableStyleProperties;
+    tl?: Address;
+    autoFilterRef?: string;
+    tableRef?: string;
+}
+declare class Column {
+    table: Table;
+    column: TableColumnProperties;
+    index: number;
+    constructor(table: Table, column: TableColumnProperties, index: number);
+    private _set;
+    get name(): string;
+    set name(value: string);
+    get filterButton(): boolean | undefined;
+    set filterButton(value: boolean | undefined);
+    get style(): Partial<Style> | undefined;
+    set style(value: Partial<Style> | undefined);
+    get totalsRowLabel(): string | undefined;
+    set totalsRowLabel(value: string | undefined);
+    get totalsRowFunction(): TableColumnProperties["totalsRowFunction"];
+    set totalsRowFunction(value: TableColumnProperties["totalsRowFunction"]);
+    get totalsRowResult(): CellValue;
+    set totalsRowResult(value: CellFormulaValue["result"]);
+    get totalsRowFormula(): string | undefined;
+    set totalsRowFormula(value: string | undefined);
+}
+declare class Table {
+    worksheet: Worksheet;
+    table: TableModel;
+    private _cache?;
+    constructor(worksheet: Worksheet, table?: TableModel);
+    getFormula(column: TableColumnProperties): string | null;
+    get width(): number;
+    get height(): number;
+    get filterHeight(): number;
+    get tableHeight(): number;
+    validate(): void;
+    store(): void;
+    load(worksheet: Worksheet): void;
+    get model(): TableModel;
+    set model(value: TableModel);
+    cacheState(): void;
+    commit(): void;
+    addRow(values: CellValue[], rowNumber?: number): void;
+    removeRows(rowIndex: number, count?: number): void;
+    getColumn(colIndex: number): Column;
+    addColumn(column: TableColumnProperties, values: CellValue[], colIndex?: number): void;
+    removeColumns(colIndex: number, count?: number): void;
+    private _assign;
+    get ref(): string;
+    set ref(value: string);
+    get name(): string;
+    set name(value: string);
+    get displayName(): string;
+    set displayName(value: string);
+    get headerRow(): boolean | undefined;
+    set headerRow(value: boolean | undefined);
+    get totalsRow(): boolean | undefined;
+    set totalsRow(value: boolean | undefined);
+    get theme(): TableStyleProperties["theme"];
+    set theme(value: TableStyleProperties["theme"]);
+    get showFirstColumn(): boolean | undefined;
+    set showFirstColumn(value: boolean | undefined);
+    get showLastColumn(): boolean | undefined;
+    set showLastColumn(value: boolean | undefined);
+    get showRowStripes(): boolean | undefined;
+    set showRowStripes(value: boolean | undefined);
+    get showColumnStripes(): boolean | undefined;
+    set showColumnStripes(value: boolean | undefined);
+}
+export { Table, type TableModel };

package/dist/types/doc/workbook.base.d.ts

@@ -0,0 +1,111 @@
+/**
+ * WorkbookBase - Platform-independent base class for Workbook
+ *
+ * This file contains all the shared logic between Node.js and Browser versions.
+ * Platform-specific features (xlsx, csv, streaming) are added by subclasses.
+ */
+import { Worksheet, type WorksheetModel } from "./worksheet";
+import { DefinedNames, type DefinedNameModel } from "./defined-names";
+import type { PivotTable } from "./pivot-table";
+import type { AddWorksheetOptions, CalculationProperties, Image, WorkbookProperties, WorkbookView, Buffer as ExcelBuffer } from "../types";
+/** Internal media type - more flexible than public Media type */
+export interface WorkbookMedia {
+    type: string;
+    extension: string;
+    filename?: string;
+    buffer?: ExcelBuffer | Uint8Array;
+    base64?: string;
+    name?: string;
+}
+/** Internal model type for serialization */
+export interface WorkbookModel {
+    creator?: string;
+    lastModifiedBy?: string;
+    lastPrinted?: Date;
+    created: Date;
+    modified: Date;
+    properties: Partial<WorkbookProperties>;
+    worksheets: WorksheetModel[];
+    sheets?: WorksheetModel[];
+    definedNames: DefinedNameModel[];
+    views: WorkbookView[];
+    company: string;
+    manager: string;
+    title: string;
+    subject: string;
+    keywords: string;
+    category: string;
+    description: string;
+    language?: string;
+    revision?: number;
+    contentStatus?: string;
+    themes?: unknown;
+    media: WorkbookMedia[];
+    pivotTables: PivotTable[];
+    /** Loaded pivot tables from file - used during reconciliation */
+    loadedPivotTables?: any[];
+    calcProperties: Partial<CalculationProperties>;
+}
+/**
+ * Base class for Workbook containing all platform-independent functionality.
+ *
+ * Subclasses add:
+ * - Node.js: xlsx (full), csv, streaming (createStreamWriter/Reader)
+ * - Browser: xlsx (buffer only), no csv, no streaming
+ */
+export declare abstract class WorkbookBase {
+    category: string;
+    company: string;
+    created: Date;
+    description: string;
+    keywords: string;
+    manager: string;
+    modified: Date;
+    subject: string;
+    title: string;
+    creator?: string;
+    lastModifiedBy?: string;
+    lastPrinted?: Date;
+    language?: string;
+    revision?: number;
+    contentStatus?: string;
+    properties: Partial<WorkbookProperties>;
+    calcProperties: Partial<CalculationProperties>;
+    views: WorkbookView[];
+    media: WorkbookMedia[];
+    pivotTables: PivotTable[];
+    protected _worksheets: Worksheet[];
+    protected _definedNames: DefinedNames;
+    protected _themes?: unknown;
+    constructor();
+    get nextId(): number;
+    /**
+     * Add a new worksheet and return a reference to it
+     */
+    addWorksheet(name?: string, options?: AddWorksheetOptions): Worksheet;
+    removeWorksheetEx(worksheet: Worksheet): void;
+    removeWorksheet(id: number | string): void;
+    /**
+     * Fetch sheet by name or id
+     */
+    getWorksheet(id?: number | string): Worksheet | undefined;
+    /**
+     * Return a clone of worksheets in order
+     */
+    get worksheets(): Worksheet[];
+    /**
+     * Iterate over all sheets.
+     *
+     * Note: `workbook.worksheets.forEach` will still work but this is better.
+     */
+    eachSheet(callback: (sheet: Worksheet, id: number) => void): void;
+    get definedNames(): DefinedNames;
+    clearThemes(): void;
+    /**
+     * Add Image to Workbook and return the id
+     */
+    addImage(image: Image): number;
+    getImage(id: number | string): WorkbookMedia | undefined;
+    get model(): WorkbookModel;
+    set model(value: WorkbookModel);
+}

package/dist/types/doc/workbook.browser.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workbook Browser version - No Node.js dependencies
+ *
+ * Extends WorkbookBase with:
+ * - xlsx: Buffer-based operations (load, writeBuffer)
+ * - csv: Buffer-based operations (load, writeString, writeBuffer)
+ * - streaming: NOT supported (throws error)
+ */
+import { WorkbookBase } from "./workbook.base";
+import { XLSX } from "../xlsx/xlsx.browser";
+import { CSV } from "../csv/csv.browser";
+declare class Workbook extends WorkbookBase {
+    private _xlsx?;
+    private _csv?;
+    /**
+     * xlsx file format operations
+     * Supports: load (buffer), writeBuffer
+     * NOT supported: readFile, writeFile, read (stream), write (stream)
+     */
+    get xlsx(): XLSX;
+    /**
+     * CSV file format operations
+     * Supports: load (string/buffer), writeString, writeBuffer
+     * NOT supported: readFile, writeFile, read (stream), write (stream)
+     */
+    get csv(): CSV;
+    /**
+     * @deprecated Streaming is not available in browser
+     * @throws Error with helpful message
+     */
+    static createStreamWriter(_options?: unknown): never;
+    /**
+     * @deprecated Streaming is not available in browser
+     * @throws Error with helpful message
+     */
+    static createStreamReader(_input?: unknown, _options?: unknown): never;
+}
+export { Workbook };

package/dist/types/doc/workbook.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Workbook - Node.js version with full functionality
+ *
+ * Extends WorkbookBase with:
+ * - xlsx: Full file/stream/buffer support
+ * - csv: CSV read/write support
+ * - streaming: createStreamWriter/createStreamReader for large files
+ */
+import { WorkbookBase } from "./workbook.base";
+import { XLSX } from "../xlsx/xlsx";
+import { CSV } from "../csv/csv";
+import { WorkbookWriter, type WorkbookWriterOptions } from "../stream/xlsx/workbook-writer";
+import { WorkbookReader, type WorkbookReaderOptions } from "../stream/xlsx/workbook-reader";
+import type { Readable } from "stream";
+declare class Workbook extends WorkbookBase {
+    /**
+     * Streaming workbook writer class for large files.
+     * @example new Workbook.Writer({ filename: "large.xlsx" })
+     */
+    static Writer: typeof WorkbookWriter;
+    /**
+     * Streaming workbook reader class for large files.
+     * @example new Workbook.Reader("large.xlsx")
+     */
+    static Reader: typeof WorkbookReader;
+    private _xlsx?;
+    private _csv?;
+    /**
+     * xlsx file format operations
+     * Supports: readFile, writeFile, read (stream), write (stream), load (buffer), writeBuffer
+     */
+    get xlsx(): XLSX;
+    /**
+     * csv file format operations
+     * Supports: readFile, writeFile, read (stream), write (stream)
+     */
+    get csv(): CSV;
+    /**
+     * Create a streaming workbook writer for large files.
+     * This is more memory-efficient than using Workbook for large datasets.
+     *
+     * @param options - Options for the workbook writer
+     * @returns A new WorkbookWriter instance
+     *
+     * @example
+     * ```ts
+     * const writer = Workbook.createStreamWriter({ filename: "large-file.xlsx" });
+     * const sheet = writer.addWorksheet("Sheet1");
+     * for (let i = 0; i < 1000000; i++) {
+     *   sheet.addRow([i, `Row ${i}`]).commit();
+     * }
+     * await writer.commit();
+     * ```
+     */
+    static createStreamWriter(options?: WorkbookWriterOptions): WorkbookWriter;
+    /**
+     * Create a streaming workbook reader for large files.
+     * This is more memory-efficient than using Workbook.xlsx.readFile for large datasets.
+     *
+     * @param input - File path or readable stream
+     * @param options - Options for the workbook reader
+     * @returns A new WorkbookReader instance
+     *
+     * @example
+     * ```ts
+     * const reader = Workbook.createStreamReader("large-file.xlsx");
+     * for await (const event of reader) {
+     *   if (event.eventType === "worksheet") {
+     *     const worksheet = event.value;
+     *     for await (const row of worksheet) {
+     *       console.log(row.values);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    static createStreamReader(input: string | Readable, options?: WorkbookReaderOptions): WorkbookReader;
+}
+export { Workbook };