@cj-tech-master/excelts 3.1.0 → 4.0.0

package/dist/types/modules/excel/column.d.ts

@@ -0,0 +1,122 @@
+import type { Cell, CellValueType } from "./cell.d.ts";
+import type { Worksheet } from "./worksheet.d.ts";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellValue } from "./types.d.ts";
+/** Header value type - can be a single value or array for multi-row headers */
+export type ColumnHeaderValue = CellValue | CellValue[];
+export interface ColumnDefn {
+    /** Column header value(s). Can be string, Date, number, or any CellValue type */
+    header?: ColumnHeaderValue;
+    key?: string;
+    width?: number;
+    outlineLevel?: number;
+    hidden?: boolean;
+    style?: Partial<Style>;
+}
+export interface ColumnModel {
+    min: number;
+    max: number;
+    width?: number;
+    style?: Partial<Style>;
+    isCustomWidth?: boolean;
+    hidden?: boolean;
+    outlineLevel?: number;
+    collapsed?: boolean;
+}
+/**
+ * Column defines the column properties for 1 column.
+ * This includes header rows, widths, key, (style), etc.
+ * Worksheet will condense the columns as appropriate during serialization
+ */
+declare class Column {
+    private _worksheet;
+    private _number;
+    private _header;
+    private _key;
+    /** The width of the column */
+    width?: number;
+    private _hidden;
+    private _outlineLevel;
+    /** Styles applied to the column */
+    style: Partial<Style>;
+    constructor(worksheet: Worksheet, number: number, defn?: ColumnDefn | false);
+    get number(): number;
+    get worksheet(): Worksheet;
+    /**
+     * Column letter key
+     */
+    get letter(): string;
+    get isCustomWidth(): boolean;
+    get defn(): ColumnDefn;
+    set defn(value: ColumnDefn | undefined);
+    /**
+     * Get header values as an array (for multi-row header support)
+     */
+    get headers(): CellValue[];
+    /**
+     * Can be a single value or an array for multi-row headers.
+     * Supports any CellValue type including Date, number, string, etc.
+     */
+    get header(): ColumnHeaderValue | undefined;
+    set header(value: ColumnHeaderValue | undefined);
+    /**
+     * The name of the properties associated with this column in each row
+     */
+    get key(): string | undefined;
+    set key(value: string | undefined);
+    /**
+     * Hides the column
+     */
+    get hidden(): boolean;
+    set hidden(value: boolean);
+    /**
+     * Set an outline level for columns
+     */
+    get outlineLevel(): number;
+    set outlineLevel(value: number | undefined);
+    /**
+     * Indicate the collapsed state based on outlineLevel
+     */
+    get collapsed(): boolean;
+    toString(): string;
+    equivalentTo(other: Column): boolean;
+    equivalentToModel(model: ColumnModel): boolean;
+    get isDefault(): boolean;
+    get headerCount(): number;
+    /**
+     * Iterate over all current cells in this column
+     */
+    eachCell(callback: (cell: Cell, rowNumber: number) => void): void;
+    /**
+     * Iterate over all current cells in this column including empty cells
+     */
+    eachCell(opt: {
+        includeEmpty?: boolean;
+    }, callback: (cell: Cell, rowNumber: number) => void): void;
+    /**
+     * The cell values in the column
+     */
+    get values(): CellValueType[];
+    set values(v: CellValueType[]);
+    /**
+     * Add a page break after this column.
+     * @param top - Optional top row limit for the page break (1-indexed)
+     * @param bottom - Optional bottom row limit for the page break (1-indexed)
+     */
+    addPageBreak(top?: number, bottom?: number): void;
+    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);
+    static toModel(columns: Column[]): ColumnModel[] | undefined;
+    static fromModel(cols: ColumnModel[]): Column[] | null;
+    static fromModel(worksheet: Worksheet, cols: ColumnModel[]): Column[] | null;
+}
+export { Column };

package/dist/types/modules/excel/defined-names.d.ts

@@ -0,0 +1,37 @@
+import { type DecodedRange } from "./utils/col-cache.d.ts";
+import { CellMatrix } from "./utils/cell-matrix.d.ts";
+import { Range } from "./range.d.ts";
+import type { Address } from "./types.d.ts";
+interface DefinedNameCell {
+    sheetName?: string;
+    address: string;
+    row: number;
+    col: number;
+    mark?: boolean;
+}
+type CellLocation = Address | DecodedRange;
+interface DefinedNameModel {
+    name: string;
+    ranges: string[];
+}
+declare class DefinedNames {
+    matrixMap: Record<string, CellMatrix>;
+    constructor();
+    getMatrix(name: string): CellMatrix;
+    add(locStr: string, name: string): void;
+    addEx(location: CellLocation, name: string): void;
+    remove(locStr: string, name: string): void;
+    removeEx(location: CellLocation, name: string): void;
+    removeAllNames(location: CellLocation): void;
+    forEach(callback: (name: string, cell: DefinedNameCell) => void): void;
+    getNames(addressStr: string): string[];
+    getNamesEx(address: Address): string[];
+    _explore(matrix: CellMatrix, cell: DefinedNameCell): Range;
+    getRanges(name: string, matrix?: CellMatrix): DefinedNameModel;
+    normaliseMatrix(matrix: CellMatrix, sheetName: string): void;
+    spliceRows(sheetName: string, start: number, numDelete: number, numInsert: number): void;
+    spliceColumns(sheetName: string, start: number, numDelete: number, numInsert: number): void;
+    get model(): DefinedNameModel[];
+    set model(value: DefinedNameModel[]);
+}
+export { DefinedNames, type DefinedNameModel };

package/dist/types/modules/excel/image.d.ts

@@ -0,0 +1,64 @@
+import { Anchor, type AnchorModel } from "./anchor.d.ts";
+import type { Worksheet } from "./worksheet.d.ts";
+interface ImageHyperlinks {
+    hyperlink?: string;
+    tooltip?: string;
+}
+interface ImageExt {
+    width?: number;
+    height?: number;
+}
+interface ImageRange {
+    tl: Anchor;
+    br?: Anchor;
+    ext?: ImageExt;
+    editAs?: string;
+    hyperlinks?: ImageHyperlinks;
+}
+interface BackgroundModel {
+    type: "background";
+    imageId: string;
+}
+interface ImageRangeModel {
+    tl: AnchorModel;
+    br?: AnchorModel;
+    ext?: ImageExt;
+    editAs?: string;
+}
+interface ImageModel {
+    type: "image";
+    imageId: string;
+    hyperlinks?: ImageHyperlinks;
+    range: ImageRangeModel;
+}
+type Model = BackgroundModel | ImageModel;
+type ImageModelInput = ModelInput;
+interface RangeInput {
+    tl?: AnchorModel | {
+        col: number;
+        row: number;
+    } | string;
+    br?: AnchorModel | {
+        col: number;
+        row: number;
+    } | string;
+    ext?: ImageExt;
+    editAs?: string;
+    hyperlinks?: ImageHyperlinks;
+}
+interface ModelInput {
+    type: string;
+    imageId: string;
+    range?: string | RangeInput | ImageRangeModel;
+    hyperlinks?: ImageHyperlinks;
+}
+declare class Image {
+    worksheet: Worksheet;
+    type?: string;
+    imageId?: string;
+    range?: ImageRange;
+    constructor(worksheet: Worksheet, model?: ModelInput);
+    get model(): Model;
+    set model({ type, imageId, range, hyperlinks }: ModelInput);
+}
+export { Image, type Model as ImageModel, type ImageModelInput };

package/dist/types/modules/excel/pivot-table.d.ts

@@ -0,0 +1,152 @@
+import type { Table } from "./table.d.ts";
+/**
+ * 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/modules/excel/range.d.ts

@@ -0,0 +1,62 @@
+import type { Address } from "./types.d.ts";
+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/modules/excel/row.d.ts

@@ -0,0 +1,127 @@
+import { Cell, type CellModel, type CellAddress } from "./cell.d.ts";
+import type { Worksheet } from "./worksheet.d.ts";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellValue, RowValues } from "./types.d.ts";
+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/modules/excel/stream/hyperlink-reader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * HyperlinkReader - Streaming Hyperlink Reader
+ *
+ * Cross-platform implementation.
+ */
+import { EventEmitter } from "../../stream/index.d.ts";
+import type { InternalWorksheetOptions } from "./workbook-reader.browser.d.ts";
+export interface HyperlinkReaderOptions<TWorkbook = unknown> {
+    workbook: TWorkbook;
+    id: number;
+    iterator: AsyncIterable<unknown>;
+    options: InternalWorksheetOptions;
+}
+/** Hyperlink relationship parsed from worksheet rels */
+export interface Hyperlink {
+    type: number;
+    rId: string;
+    target: string;
+    targetMode: string;
+}
+declare class HyperlinkReader extends EventEmitter {
+    workbook: unknown;
+    id: number;
+    iterator: AsyncIterable<unknown>;
+    options: InternalWorksheetOptions;
+    hyperlinks?: Record<string, Hyperlink>;
+    private _hyperlinkCount;
+    constructor({ workbook, id, iterator, options }: HyperlinkReaderOptions);
+    get count(): number;
+    each(fn: (hyperlink: Hyperlink, rId: string) => void): void;
+    read(): Promise<void>;
+}
+export { HyperlinkReader };