@cj-tech-master/excelts 3.1.0 → 4.0.0-canary.20260103013222.0e5d37f

package/dist/browser/modules/excel/workbook.js

@@ -0,0 +1,314 @@
+/**
+ * Workbook - Cross-platform Excel Workbook
+ *
+ * Full functionality:
+ * - xlsx: File/stream/buffer support (file operations Node.js only)
+ * - csv: CSV read/write support (file operations Node.js only)
+ * - streaming: createStreamWriter/createStreamReader for large files
+ *
+ * Note: Browser build uses rolldown aliases to swap in browser-specific
+ * implementations for xlsx, csv, and stream modules.
+ */
+import { Worksheet } from "./worksheet.js";
+import { DefinedNames } from "./defined-names.js";
+import { XLSX } from "./xlsx/xlsx.browser.js";
+import { CSV } from "../csv/csv.browser.js";
+import { WorkbookWriter } from "./stream/workbook-writer.browser.js";
+import { WorkbookReader } from "./stream/workbook-reader.browser.js";
+// =============================================================================
+// Workbook Class
+// =============================================================================
+class Workbook {
+    // ===========================================================================
+    // Constructor
+    // ===========================================================================
+    constructor() {
+        this.category = "";
+        this.company = "";
+        this.created = new Date();
+        this.description = "";
+        this.keywords = "";
+        this.manager = "";
+        this.modified = this.created;
+        this.properties = {};
+        this.calcProperties = {};
+        this._worksheets = [];
+        this.subject = "";
+        this.title = "";
+        this.views = [];
+        this.media = [];
+        this.pivotTables = [];
+        this._definedNames = new DefinedNames();
+    }
+    // ===========================================================================
+    // Format Operations (xlsx, csv)
+    // ===========================================================================
+    /**
+     * xlsx file format operations
+     * Node.js: readFile, writeFile, read (stream), write (stream), load (buffer), writeBuffer
+     * Browser: load (buffer), writeBuffer
+     */
+    get xlsx() {
+        if (!this._xlsx) {
+            this._xlsx = new XLSX(this);
+        }
+        return this._xlsx;
+    }
+    /**
+     * csv file format operations
+     * Node.js: readFile, writeFile, read (stream), write (stream)
+     * Browser: load (string/buffer), writeString, writeBuffer
+     */
+    get csv() {
+        if (!this._csv) {
+            this._csv = new CSV(this);
+        }
+        return this._csv;
+    }
+    // ===========================================================================
+    // Static Factory Methods for Streaming
+    // ===========================================================================
+    /**
+     * 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
+     *   - Node.js: can use { filename } or { stream }
+     *   - Browser: must use { stream }
+     * @returns A new WorkbookWriter instance
+     *
+     * @example
+     * ```ts
+     * // Node.js with filename
+     * const writer = Workbook.createStreamWriter({ filename: "large-file.xlsx" });
+     *
+     * // Browser or Node.js with stream
+     * const writer = Workbook.createStreamWriter({ stream: writableStream });
+     *
+     * const sheet = writer.addWorksheet("Sheet1");
+     * for (let i = 0; i < 1000000; i++) {
+     *   sheet.addRow([i, `Row ${i}`]).commit();
+     * }
+     * await writer.commit();
+     * ```
+     */
+    static createStreamWriter(options) {
+        return new WorkbookWriter(options);
+    }
+    /**
+     * 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 (Node.js only) or readable stream
+     * @param options - Options for the workbook reader
+     * @returns A new WorkbookReader instance
+     *
+     * @example
+     * ```ts
+     * // Node.js with file path
+     * const reader = Workbook.createStreamReader("large-file.xlsx");
+     *
+     * // Browser or Node.js with stream
+     * const reader = Workbook.createStreamReader(readableStream);
+     *
+     * 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, options) {
+        return new WorkbookReader(input, options);
+    }
+    // ===========================================================================
+    // Worksheet Management
+    // ===========================================================================
+    get nextId() {
+        // Find the next unique spot to add worksheet
+        for (let i = 1; i < this._worksheets.length; i++) {
+            if (!this._worksheets[i]) {
+                return i;
+            }
+        }
+        return this._worksheets.length || 1;
+    }
+    /**
+     * Add a new worksheet and return a reference to it
+     */
+    addWorksheet(name, options) {
+        const id = this.nextId;
+        const lastOrderNo = this._worksheets.reduce((acc, ws) => ((ws && ws.orderNo) > acc ? ws.orderNo : acc), 0);
+        const worksheetOptions = {
+            ...options,
+            id,
+            name,
+            orderNo: lastOrderNo + 1,
+            workbook: this
+        };
+        const worksheet = new Worksheet(worksheetOptions);
+        this._worksheets[id] = worksheet;
+        return worksheet;
+    }
+    removeWorksheetEx(worksheet) {
+        delete this._worksheets[worksheet.id];
+    }
+    removeWorksheet(id) {
+        const worksheet = this.getWorksheet(id);
+        if (worksheet) {
+            worksheet.destroy();
+        }
+    }
+    /**
+     * Fetch sheet by name or id
+     */
+    getWorksheet(id) {
+        if (id === undefined) {
+            return this._worksheets.find(Boolean);
+        }
+        if (typeof id === "number") {
+            return this._worksheets[id];
+        }
+        if (typeof id === "string") {
+            return this._worksheets.find(worksheet => worksheet && worksheet.name === id);
+        }
+        return undefined;
+    }
+    /**
+     * Return a clone of worksheets in order
+     */
+    get worksheets() {
+        return this._worksheets
+            .slice(1)
+            .sort((a, b) => a.orderNo - b.orderNo)
+            .filter(Boolean);
+    }
+    /**
+     * Iterate over all sheets.
+     *
+     * Note: `workbook.worksheets.forEach` will still work but this is better.
+     */
+    eachSheet(callback) {
+        this.worksheets.forEach(sheet => {
+            callback(sheet, sheet.id);
+        });
+    }
+    // ===========================================================================
+    // Defined Names
+    // ===========================================================================
+    get definedNames() {
+        return this._definedNames;
+    }
+    // ===========================================================================
+    // Themes
+    // ===========================================================================
+    clearThemes() {
+        // Note: themes are not an exposed feature, meddle at your peril!
+        this._themes = undefined;
+    }
+    // ===========================================================================
+    // Images
+    // ===========================================================================
+    /**
+     * Add Image to Workbook and return the id
+     */
+    addImage(image) {
+        const id = this.media.length;
+        this.media.push({ ...image, type: "image" });
+        return id;
+    }
+    getImage(id) {
+        return this.media[Number(id)];
+    }
+    // ===========================================================================
+    // Model (Serialization)
+    // ===========================================================================
+    get model() {
+        return {
+            creator: this.creator || "Unknown",
+            lastModifiedBy: this.lastModifiedBy || "Unknown",
+            lastPrinted: this.lastPrinted,
+            created: this.created,
+            modified: this.modified,
+            properties: this.properties,
+            worksheets: this.worksheets.map(worksheet => worksheet.model),
+            sheets: this.worksheets.map(ws => ws.model).filter(Boolean),
+            definedNames: this._definedNames.model,
+            views: this.views,
+            company: this.company,
+            manager: this.manager,
+            title: this.title,
+            subject: this.subject,
+            keywords: this.keywords,
+            category: this.category,
+            description: this.description,
+            language: this.language,
+            revision: this.revision,
+            contentStatus: this.contentStatus,
+            themes: this._themes,
+            media: this.media,
+            pivotTables: this.pivotTables,
+            calcProperties: this.calcProperties
+        };
+    }
+    set model(value) {
+        this.creator = value.creator;
+        this.lastModifiedBy = value.lastModifiedBy;
+        this.lastPrinted = value.lastPrinted;
+        this.created = value.created;
+        this.modified = value.modified;
+        this.company = value.company;
+        this.manager = value.manager;
+        this.title = value.title;
+        this.subject = value.subject;
+        this.keywords = value.keywords;
+        this.category = value.category;
+        this.description = value.description;
+        this.language = value.language;
+        this.revision = value.revision;
+        this.contentStatus = value.contentStatus;
+        this.properties = value.properties;
+        this.calcProperties = value.calcProperties;
+        this._worksheets = [];
+        value.worksheets.forEach(worksheetModel => {
+            const { id, name, state } = worksheetModel;
+            const orderNo = value.sheets && value.sheets.findIndex(ws => ws.id === id);
+            const worksheet = (this._worksheets[id] = new Worksheet({
+                id,
+                name,
+                orderNo: orderNo !== -1 ? orderNo : undefined,
+                state,
+                workbook: this
+            }));
+            worksheet.model = worksheetModel;
+        });
+        this._definedNames.model = value.definedNames;
+        this.views = value.views;
+        this._themes = value.themes;
+        this.media = value.media || [];
+        // Handle pivot tables - either newly created or loaded from file
+        // Loaded pivot tables come from loadedPivotTables after reconciliation
+        this.pivotTables = value.pivotTables || value.loadedPivotTables || [];
+    }
+}
+// ===========================================================================
+// Static Properties
+// ===========================================================================
+/**
+ * Streaming workbook writer class for large files.
+ * @example
+ * // Node.js: new Workbook.Writer({ filename: "large.xlsx" })
+ * // Browser: new Workbook.Writer({ stream: writableStream })
+ */
+Workbook.Writer = WorkbookWriter;
+/**
+ * Streaming workbook reader class for large files.
+ * @example
+ * // Node.js: new Workbook.Reader("large.xlsx")
+ * // Browser: new Workbook.Reader(readableStream)
+ */
+Workbook.Reader = WorkbookReader;
+export { Workbook };

package/dist/browser/modules/excel/worksheet.d.ts

@@ -0,0 +1,333 @@
+import { Range, type RangeInput } from "@excel/range";
+import { Row, type RowModel } from "@excel/row";
+import { Column, type ColumnModel, type ColumnDefn } from "@excel/column";
+import type { Cell, FormulaResult } from "@excel/cell";
+import { Image, type ImageModel } from "@excel/image";
+import { Table, type TableModel } from "@excel/table";
+import { DataValidations } from "@excel/data-validations";
+import { type PivotTable, type PivotTableModel } from "@excel/pivot-table";
+import type { Workbook } from "@excel/workbook";
+import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetView } from "@excel/types";
+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?: Workbook;
+    id?: number;
+    orderNo?: number;
+    name?: string;
+    state?: string;
+    properties?: Partial<WorksheetProperties>;
+    pageSetup?: Partial<PageSetup>;
+    headerFooter?: Partial<HeaderFooter>;
+    views?: Partial<WorksheetView>[];
+    autoFilter?: AutoFilter | null;
+}
+interface PageSetupMargins {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    header: number;
+    footer: number;
+}
+interface PageSetup {
+    margins: PageSetupMargins;
+    orientation: string;
+    horizontalDpi: number;
+    verticalDpi: number;
+    fitToPage: boolean;
+    pageOrder: string;
+    blackAndWhite: boolean;
+    draft: boolean;
+    cellComments: string;
+    errors: string;
+    scale: number;
+    fitToWidth: number;
+    fitToHeight: number;
+    paperSize?: number;
+    showRowColHeaders: boolean;
+    showGridLines: boolean;
+    firstPageNumber?: number;
+    horizontalCentered: boolean;
+    verticalCentered: boolean;
+    rowBreaks: RowBreak[];
+    printTitlesRow?: string;
+    printTitlesColumn?: string;
+}
+interface HeaderFooter {
+    differentFirst: boolean;
+    differentOddEven: boolean;
+    oddHeader: string | null;
+    oddFooter: string | null;
+    evenHeader: string | null;
+    evenFooter: string | null;
+    firstHeader: string | null;
+    firstFooter: string | null;
+}
+interface WorksheetModel {
+    id: number;
+    name: string;
+    dataValidations: DataValidationModel;
+    properties: Partial<WorksheetProperties>;
+    state: string;
+    pageSetup: PageSetup;
+    headerFooter: HeaderFooter;
+    rowBreaks: RowBreak[];
+    colBreaks: ColBreak[];
+    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 {
+    private _workbook;
+    id: number;
+    orderNo: number;
+    private _name;
+    state: string;
+    private _rows;
+    private _columns;
+    private _keys;
+    private _merges;
+    rowBreaks: RowBreak[];
+    colBreaks: ColBreak[];
+    properties: Partial<WorksheetProperties>;
+    pageSetup: PageSetup;
+    headerFooter: HeaderFooter;
+    dataValidations: DataValidations;
+    views: Partial<WorksheetView>[];
+    autoFilter: AutoFilter | null;
+    private _media;
+    sheetProtection: SheetProtection | null;
+    tables: {
+        [key: string]: Table;
+    };
+    pivotTables: PivotTable[];
+    conditionalFormattings: ConditionalFormattingOptions[];
+    private _headerRowCount?;
+    constructor(options: WorksheetOptions);
+    get name(): string;
+    set name(name: string | undefined);
+    /**
+     * 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 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: 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 limitation: 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 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): 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;
+    /**
+     * Cut one or more rows (rows below are shifted up)
+     * and optionally insert more
+     *
+     * Known limitation: 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: Cell): void;
+    get hasMerges(): boolean;
+    /**
+     * 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;
+    /**
+     * 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: 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, type WorksheetModel };