@cj-tech-master/excelts 1.4.5 → 1.5.0

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

@@ -1,12 +1,16 @@
-import { Worksheet } from "./worksheet.js";
-import { DefinedNames } from "./defined-names.js";
+import { Worksheet, type WorksheetModel } from "./worksheet.js";
+import { DefinedNames, type DefinedNameModel } from "./defined-names.js";
 import { XLSX } from "../xlsx/xlsx.js";
 import { CSV } from "../csv/csv.js";
-interface WorksheetModel {
-    id: number;
-    name: string;
-    state?: string;
-    [key: string]: any;
+import type { PivotTable } from "./pivot-table.js";
+import type { AddWorksheetOptions, CalculationProperties, Image, WorkbookProperties, WorkbookView, Buffer as ExcelBuffer } from "../types.js";
+interface WorkbookMedia {
+    type: string;
+    extension: string;
+    filename?: string;
+    buffer?: ExcelBuffer;
+    base64?: string;
+    name?: string;
 }
 interface WorkbookModel {
     creator?: string;
@@ -14,11 +18,11 @@ interface WorkbookModel {
     lastPrinted?: Date;
     created: Date;
     modified: Date;
-    properties: any;
+    properties: Partial<WorkbookProperties>;
     worksheets: WorksheetModel[];
     sheets?: WorksheetModel[];
-    definedNames: any;
-    views: any[];
+    definedNames: DefinedNameModel[];
+    views: WorkbookView[];
     company: string;
     manager: string;
     title: string;
@@ -29,17 +33,10 @@ interface WorkbookModel {
     language?: string;
     revision?: number;
     contentStatus?: string;
-    themes?: any;
-    media: any[];
-    pivotTables: any[];
-    calcProperties: any;
-}
-interface AddWorksheetOptions {
-    properties?: any;
-    views?: any[];
-    pageSetup?: any;
-    headerFooter?: any;
-    [key: string]: any;
+    themes?: unknown;
+    media: WorkbookMedia[];
+    pivotTables: PivotTable[];
+    calcProperties: Partial<CalculationProperties>;
 }
 declare class Workbook {
     category: string;
@@ -49,38 +46,61 @@ declare class Workbook {
     keywords: string;
     manager: string;
     modified: Date;
-    properties: any;
-    calcProperties: any;
-    _worksheets: Worksheet[];
+    properties: Partial<WorkbookProperties>;
+    calcProperties: Partial<CalculationProperties>;
+    private _worksheets;
     subject: string;
     title: string;
-    views: any[];
-    media: any[];
-    pivotTables: any[];
-    _definedNames: DefinedNames;
+    views: WorkbookView[];
+    media: WorkbookMedia[];
+    pivotTables: PivotTable[];
+    private _definedNames;
     creator?: string;
     lastModifiedBy?: string;
     lastPrinted?: Date;
     language?: string;
     revision?: number;
     contentStatus?: string;
-    _themes?: any;
-    _xlsx?: XLSX;
-    _csv?: CSV;
+    private _themes?;
+    private _xlsx?;
+    private _csv?;
     constructor();
+    /**
+     * xlsx file format operations
+     */
     get xlsx(): XLSX;
+    /**
+     * csv file format operations
+     */
     get csv(): CSV;
     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[];
-    eachSheet(iteratee: (sheet: Worksheet, id: number) => void): void;
+    /**
+     * 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;
-    addImage(image: any): number;
-    getImage(id: number): any;
+    /**
+     * 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/worksheet.d.ts

@@ -1,22 +1,49 @@
-import { Range } from "./range.js";
-import { Row } from "./row.js";
-import { Table } from "./table.js";
+import { Range, type RangeInput } from "./range.js";
+import { Row, type RowModel } from "./row.js";
+import { Column, type ColumnModel, type ColumnDefn } from "./column.js";
+import type { Cell, FormulaResult } from "./cell.js";
+import { Image, type ImageModel } from "./image.js";
+import { Table, type TableModel } from "./table.js";
 import { DataValidations } from "./data-validations.js";
-import type { RowBreak } from "../types.js";
+import { type PivotTable, type PivotTableModel } from "./pivot-table.js";
+import type { Workbook } from "./workbook.js";
+import type { AddImageRange, AutoFilter, CellValue, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetView } from "../types.js";
+type DataValidationModel = {
+    [address: string]: DataValidation | undefined;
+};
+interface SheetProtection {
+    sheet?: boolean;
+    objects?: boolean;
+    scenarios?: boolean;
+    selectLockedCells?: boolean;
+    selectUnlockedCells?: boolean;
+    formatCells?: boolean;
+    formatColumns?: boolean;
+    formatRows?: boolean;
+    insertColumns?: boolean;
+    insertRows?: boolean;
+    insertHyperlinks?: boolean;
+    deleteColumns?: boolean;
+    deleteRows?: boolean;
+    sort?: boolean;
+    autoFilter?: boolean;
+    pivotTables?: boolean;
+    algorithmName?: string;
+    hashValue?: string;
+    saltValue?: string;
+    spinCount?: number;
+}
 interface WorksheetOptions {
-    workbook?: any;
+    workbook?: Workbook;
     id?: number;
     orderNo?: number;
     name?: string;
     state?: string;
-    properties?: any;
-    pageSetup?: any;
-    headerFooter?: any;
-    views?: any[];
-    autoFilter?: any;
-}
-interface EachRowOptions {
-    includeEmpty?: boolean;
+    properties?: Partial<WorksheetProperties>;
+    pageSetup?: Partial<PageSetup>;
+    headerFooter?: Partial<HeaderFooter>;
+    views?: Partial<WorksheetView>[];
+    autoFilter?: AutoFilter | null;
 }
 interface PageSetupMargins {
     left: number;
@@ -47,7 +74,6 @@ interface PageSetup {
     horizontalCentered: boolean;
     verticalCentered: boolean;
     rowBreaks: RowBreak[];
-    colBreaks: any;
     printTitlesRow?: string;
     printTitlesColumn?: string;
 }
@@ -64,117 +90,263 @@ interface HeaderFooter {
 interface WorksheetModel {
     id: number;
     name: string;
-    dataValidations: any;
-    properties: any;
+    dataValidations: DataValidationModel;
+    properties: Partial<WorksheetProperties>;
     state: string;
     pageSetup: PageSetup;
     headerFooter: HeaderFooter;
     rowBreaks: RowBreak[];
-    views: any[];
-    autoFilter: any;
-    media: any[];
-    sheetProtection: any;
-    tables: any[];
-    pivotTables: any[];
-    conditionalFormattings: any[];
-    cols?: any[];
-    rows?: any[];
+    views: Partial<WorksheetView>[];
+    autoFilter: AutoFilter | null;
+    media: ImageModel[];
+    sheetProtection: SheetProtection | null;
+    tables: TableModel[];
+    pivotTables: PivotTable[];
+    conditionalFormattings: ConditionalFormattingOptions[];
+    cols?: ColumnModel[];
+    rows?: RowModel[];
     dimensions?: Range;
     merges?: string[];
     mergeCells?: string[];
 }
 declare class Worksheet {
-    _workbook: any;
+    private _workbook;
     id: number;
     orderNo: number;
-    _name: string;
+    private _name;
     state: string;
-    _rows: any[];
-    _columns: any[];
-    _keys: {
-        [key: string]: any;
-    };
-    _merges: {
-        [key: string]: Range;
-    };
-    rowBreaks: any[];
-    properties: any;
+    private _rows;
+    private _columns;
+    private _keys;
+    private _merges;
+    rowBreaks: RowBreak[];
+    properties: Partial<WorksheetProperties>;
     pageSetup: PageSetup;
     headerFooter: HeaderFooter;
     dataValidations: DataValidations;
-    views: any[];
-    autoFilter: any;
-    _media: any[];
-    sheetProtection: any;
+    views: Partial<WorksheetView>[];
+    autoFilter: AutoFilter | null;
+    private _media;
+    sheetProtection: SheetProtection | null;
     tables: {
         [key: string]: Table;
     };
-    pivotTables: any[];
-    conditionalFormattings: any[];
-    _headerRowCount?: number;
+    pivotTables: PivotTable[];
+    conditionalFormattings: ConditionalFormattingOptions[];
+    private _headerRowCount?;
     constructor(options: WorksheetOptions);
     get name(): string;
     set name(name: string | undefined);
-    get workbook(): any;
+    /**
+     * The workbook that contains this worksheet
+     */
+    get workbook(): Workbook;
+    /**
+     * When you're done with this worksheet, call this to remove from workbook
+     */
     destroy(): void;
+    /**
+     * Get the bounding range of the cells in this worksheet
+     */
     get dimensions(): Range;
-    get columns(): any[];
-    set columns(value: any[]);
-    getColumnKey(key: string): any;
-    setColumnKey(key: string, value: any): void;
+    /**
+     * Get the current columns array
+     */
+    get columns(): Column[];
+    /**
+     * Add column headers and define column keys and widths.
+     *
+     * Note: these column structures are a workbook-building convenience only,
+     * apart from the column width, they will not be fully persisted.
+     */
+    set columns(value: ColumnDefn[]);
+    getColumnKey(key: string): Column | undefined;
+    setColumnKey(key: string, value: Column): void;
     deleteColumnKey(key: string): void;
-    eachColumnKey(f: (column: any, key: string) => void): void;
-    getColumn(c: string | number): any;
-    spliceColumns(start: number, count: number, ...inserts: any[][]): void;
-    get lastColumn(): any;
+    eachColumnKey(f: (column: Column, key: string) => void): void;
+    /**
+     * Access an individual column by key, letter and 1-based column number
+     */
+    getColumn(c: string | number): Column;
+    /**
+     * Cut one or more columns (columns to the right are shifted left)
+     * and optionally insert more
+     *
+     * If column properties have been defined, they will be cut or moved accordingly
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     *
+     * Also: If the worksheet has more rows than values in the column inserts,
+     * the rows will still be shifted as if the values existed
+     */
+    spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
+    /**
+     * Get the last column in a worksheet
+     */
+    get lastColumn(): Column;
+    /**
+     * The total column size of the document. Equal to the maximum cell count from all of the rows
+     */
     get columnCount(): number;
+    /**
+     * A count of the number of columns that have values
+     */
     get actualColumnCount(): number;
     _commitRow(row: Row): void;
     get _lastRowNumber(): number;
     get _nextRow(): number;
-    get lastRow(): any;
-    findRow(r: number): any;
-    findRows(start: number, length: number): any[];
+    /**
+     * Get the last editable row in a worksheet (or undefined if there are none)
+     */
+    get lastRow(): Row | undefined;
+    /**
+     * Tries to find and return row for row number, else undefined
+     *
+     * @param r - The 1-indexed row number
+     */
+    findRow(r: number): Row | undefined;
+    /**
+     * Tries to find and return rows for row number start and length, else undefined
+     *
+     * @param start - The 1-indexed starting row number
+     * @param length - The length of the expected array
+     */
+    findRows(start: number, length: number): (Row | undefined)[];
+    /**
+     * The total row size of the document. Equal to the row number of the last row that has values.
+     */
     get rowCount(): number;
+    /**
+     * A count of the number of rows that have values. If a mid-document row is empty, it will not be included in the count.
+     */
     get actualRowCount(): number;
-    getRow(r: number): any;
-    getRows(start: number, length: number): any[] | undefined;
-    addRow(value: any, style?: string): any;
-    addRows(value: any[], style?: string): any[];
-    insertRow(pos: number, value: any, style?: string): any;
-    insertRows(pos: number, values: any[], style?: string): any[] | undefined;
+    /**
+     * Get or create row by 1-based index
+     */
+    getRow(r: number): Row;
+    /**
+     * Get or create rows by 1-based index
+     */
+    getRows(start: number, length: number): Row[] | undefined;
+    /**
+     * Add a couple of Rows by key-value, after the last current row, using the column keys,
+     * or add a row by contiguous Array (assign to columns A, B & C)
+     */
+    addRow(value: RowValues, style?: string): Row;
+    /**
+     * Add multiple rows by providing an array of arrays or key-value pairs
+     */
+    addRows(value: RowValues[], style?: string): Row[];
+    /**
+     * Insert a Row by key-value, at the position (shifting down all rows from position),
+     * using the column keys, or add a row by contiguous Array (assign to columns A, B & C)
+     */
+    insertRow(pos: number, value: RowValues, style?: string): Row;
+    /**
+     * Insert multiple rows at position (shifting down all rows from position)
+     * by providing an array of arrays or key-value pairs
+     */
+    insertRows(pos: number, values: RowValues[], style?: string): Row[] | undefined;
     _setStyleOption(pos: number, style?: string): void;
     _copyStyle(src: number, dest: number, styleEmpty?: boolean): void;
+    /**
+     * Duplicate rows and insert new rows
+     */
     duplicateRow(rowNum: number, count: number, insert?: boolean): void;
-    spliceRows(start: number, count: number, ...inserts: any[]): void;
-    eachRow(iteratee: (row: Row, rowNumber: number) => void): void;
-    eachRow(options: EachRowOptions, iteratee: (row: Row, rowNumber: number) => void): void;
-    getSheetValues(): any[];
-    findCell(r: number | string, c?: number): any;
-    getCell(r: number | string, c?: number): any;
-    mergeCells(...cells: any[]): void;
-    mergeCellsWithoutStyle(...cells: any[]): void;
+    /**
+     * Cut one or more rows (rows below are shifted up)
+     * and optionally insert more
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     */
+    spliceRows(start: number, count: number, ...inserts: RowValues[]): void;
+    /**
+     * Iterate over all rows that have values in a worksheet
+     */
+    eachRow(callback: (row: Row, rowNumber: number) => void): void;
+    /**
+     * Iterate over all rows (including empty rows) in a worksheet
+     */
+    eachRow(opt: {
+        includeEmpty?: boolean;
+    }, callback: (row: Row, rowNumber: number) => void): void;
+    /**
+     * Return all rows as sparse array
+     */
+    getSheetValues(): CellValue[][];
+    /**
+     * Returns the cell at [r,c] or address given by r. If not found, return undefined
+     */
+    findCell(r: number | string, c?: number): Cell | undefined;
+    /**
+     * Get or create cell at [r,c] or address given by r
+     */
+    getCell(r: number | string, c?: number): Cell;
+    /**
+     * Merge cells, either:
+     *
+     * tlbr string, e.g. `'A4:B5'`
+     *
+     * tl string, br string, e.g. `'G10', 'H11'`
+     *
+     * t, l, b, r numbers, e.g. `10,11,12,13`
+     */
+    mergeCells(...cells: RangeInput[]): void;
+    mergeCellsWithoutStyle(...cells: RangeInput[]): void;
     _mergeCellsInternal(dimensions: Range, ignoreStyle?: boolean): void;
-    _unMergeMaster(master: any): void;
+    _unMergeMaster(master: Cell): void;
     get hasMerges(): boolean;
-    unMergeCells(...cells: any[]): void;
-    fillFormula(range: string, formula: string, results?: any[][] | any[] | ((row: number, col: number) => any), shareType?: string): void;
-    addImage(imageId: number, range: any): void;
-    getImages(): any[];
-    addBackgroundImage(imageId: number): void;
-    getBackgroundImageId(): number | undefined;
-    protect(password?: string, options?: any): Promise<void>;
+    /**
+     * Scan the range and if any cell is part of a merge, un-merge the group.
+     * Note this function can affect multiple merges and merge-blocks are
+     * atomic - either they're all merged or all un-merged.
+     */
+    unMergeCells(...cells: RangeInput[]): void;
+    fillFormula(range: string, formula: string, results?: FormulaResult[][] | FormulaResult[] | ((row: number, col: number) => FormulaResult | undefined), shareType?: string): void;
+    /**
+     * Using the image id from `Workbook.addImage`,
+     * embed an image within the worksheet to cover a range
+     */
+    addImage(imageId: string | number, range: AddImageRange): void;
+    getImages(): Image[];
+    /**
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     */
+    addBackgroundImage(imageId: string | number): void;
+    getBackgroundImageId(): string | undefined;
+    /**
+     * Protect the worksheet with optional password and options
+     */
+    protect(password?: string, options?: Partial<SheetProtection>): Promise<void>;
     unprotect(): void;
-    addTable(model: any): Table;
+    /**
+     * Add a new table and return a reference to it
+     */
+    addTable(model: TableProperties): Table;
+    /**
+     * Fetch table by name
+     */
     getTable(name: string): Table;
+    /**
+     * Delete table by name
+     */
     removeTable(name: string): void;
+    /**
+     * Fetch all tables in the worksheet
+     */
     getTables(): Table[];
-    addPivotTable(model: any): any;
-    addConditionalFormatting(cf: any): void;
-    removeConditionalFormatting(filter: number | ((value: any, index: number, array: any[]) => boolean)): void;
+    addPivotTable(model: PivotTableModel): PivotTable;
+    /**
+     * Add conditional formatting rules
+     */
+    addConditionalFormatting(cf: ConditionalFormattingOptions): void;
+    /**
+     * Delete conditional formatting rules
+     */
+    removeConditionalFormatting(filter: number | ((value: ConditionalFormattingOptions, index: number, array: ConditionalFormattingOptions[]) => boolean)): void;
     get model(): WorksheetModel;
     _parseRows(model: WorksheetModel): void;
     _parseMergeCells(model: WorksheetModel): void;
     set model(value: WorksheetModel);
 }
-export { Worksheet };
+export { Worksheet, type WorksheetModel };

package/dist/types/stream/xlsx/worksheet-reader.d.ts

@@ -12,11 +12,9 @@ declare class WorksheetReader extends EventEmitter {
     options: any;
     name: string;
     state?: string;
-    _columns: any[] | null;
-    _keys: {
-        [key: string]: any;
-    };
-    _dimensions: any;
+    private _columns;
+    private _keys;
+    private _dimensions;
     hyperlinks?: {
         [key: string]: any;
     };