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

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

@@ -0,0 +1,333 @@
+import { Range, type RangeInput } from "./range";
+import { Row, type RowModel } from "./row";
+import { Column, type ColumnModel, type ColumnDefn } from "./column";
+import type { Cell, FormulaResult } from "./cell";
+import { Image, type ImageModel } from "./image";
+import { Table, type TableModel } from "./table";
+import { DataValidations } from "./data-validations";
+import { type PivotTable, type PivotTableModel } from "./pivot-table";
+import type { Workbook } from "./workbook";
+import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetView } from "../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 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 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 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: 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 };

package/dist/types/index.browser.d.ts

@@ -2,24 +2,18 @@
  * Browser entry point - No Node.js dependencies
  * This version is optimized for browser environments with minimal bundle size
  */
-export { Workbook } from "@excel/workbook";
-export { Worksheet } from "@excel/worksheet";
-export { Row } from "@excel/row";
-export { Column } from "@excel/column";
-export { Cell } from "@excel/cell";
-export { Range } from "@excel/range";
-export { Image } from "@excel/image";
-export * from "@excel/anchor";
-export { Table } from "@excel/table";
-export { DataValidations } from "@excel/data-validations";
-export * from "@excel/enums";
-export * from "@excel/types";
-export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
-export * from "@excel/utils/sheet-utils";
-export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "@csv/csv.browser";
-export { CsvParserStream, CsvFormatterStream } from "@csv/csv.browser";
-import { WorkbookWriter } from "@excel/stream/workbook-writer.browser";
-import { WorkbookReader } from "@excel/stream/workbook-reader.browser";
-import { WorksheetWriter } from "@excel/stream/worksheet-writer";
-import { WorksheetReader } from "@excel/stream/worksheet-reader";
-export { WorkbookWriter, WorkbookReader, WorksheetWriter, WorksheetReader };
+export { Workbook } from "./doc/workbook.browser";
+export { Worksheet } from "./doc/worksheet";
+export { Row } from "./doc/row";
+export { Column } from "./doc/column";
+export { Cell } from "./doc/cell";
+export { Range } from "./doc/range";
+export { Image } from "./doc/image";
+export * from "./doc/anchor";
+export { Table } from "./doc/table";
+export { DataValidations } from "./doc/data-validations";
+export * from "./doc/enums";
+export * from "./types";
+export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./doc/pivot-table";
+export * from "./utils/sheet-utils";
+export type { CsvReadOptions, CsvWriteOptions } from "./csv/csv";

package/dist/types/index.d.ts

@@ -1,23 +1,24 @@
-export { Workbook } from "@excel/workbook";
-export { Worksheet } from "@excel/worksheet";
-export { Row } from "@excel/row";
-export { Column } from "@excel/column";
-export { Cell } from "@excel/cell";
-export { Range } from "@excel/range";
-export { Image } from "@excel/image";
-export * from "@excel/anchor";
-export { Table } from "@excel/table";
-export { DataValidations } from "@excel/data-validations";
-export { WorkbookWriter } from "@excel/stream/workbook-writer";
-export { WorkbookReader } from "@excel/stream/workbook-reader";
-export { WorksheetWriter } from "@excel/stream/worksheet-writer";
-export { WorksheetReader } from "@excel/stream/worksheet-reader";
-export * from "@excel/enums";
-export * from "@excel/types";
-export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
-export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "@excel/stream/workbook-reader";
-export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "@excel/stream/worksheet-reader";
-export type { WorkbookWriterOptions, ZipOptions, ZlibOptions } from "@excel/stream/workbook-writer";
-export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "@csv/csv";
-export { CsvParserStream, CsvFormatterStream } from "@csv/csv";
-export * from "@excel/utils/sheet-utils";
+export { Workbook } from "./doc/workbook";
+export { Worksheet } from "./doc/worksheet";
+export { Row } from "./doc/row";
+export { Column } from "./doc/column";
+export { Cell } from "./doc/cell";
+export { Range } from "./doc/range";
+export { Image } from "./doc/image";
+export * from "./doc/anchor";
+export { Table } from "./doc/table";
+export { DataValidations } from "./doc/data-validations";
+export { WorkbookWriter } from "./stream/xlsx/workbook-writer";
+export { WorkbookReader } from "./stream/xlsx/workbook-reader";
+export { WorksheetWriter } from "./stream/xlsx/worksheet-writer";
+export { WorksheetReader } from "./stream/xlsx/worksheet-reader";
+export { ModelContainer } from "./doc/modelcontainer";
+export * from "./doc/enums";
+export * from "./types";
+export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "./doc/pivot-table";
+export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./stream/xlsx/workbook-reader";
+export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./stream/xlsx/worksheet-reader";
+export type { WorkbookWriterOptions, ZipOptions, ZlibOptions } from "./stream/xlsx/workbook-writer";
+export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "./csv/csv";
+export { CsvParserStream, CsvFormatterStream } from "./csv/csv";
+export * from "./utils/sheet-utils";

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

@@ -0,0 +1,27 @@
+import { EventEmitter } from "events";
+import type { WorkbookReader, InternalWorksheetOptions } from "./workbook-reader";
+export interface HyperlinkReaderOptions {
+    workbook: WorkbookReader;
+    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: WorkbookReader;
+    id: number;
+    iterator: AsyncIterable<unknown>;
+    options: InternalWorksheetOptions;
+    hyperlinks?: Record<string, Hyperlink>;
+    constructor({ workbook, id, iterator, options }: HyperlinkReaderOptions);
+    get count(): number;
+    each(fn: (hyperlink: Hyperlink, rId: string) => void): void;
+    read(): Promise<void>;
+}
+export { HyperlinkReader };

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

@@ -0,0 +1,139 @@
+import { EventEmitter } from "events";
+import { Readable } from "stream";
+import { StylesXform } from "../../xlsx/xform/style/styles-xform";
+import { WorksheetReader } from "./worksheet-reader";
+import { HyperlinkReader } from "./hyperlink-reader";
+import type { WorksheetState, Font, WorkbookProperties } from "../../types";
+/** Internal options type that includes undocumented 'prep' value */
+export interface InternalWorksheetOptions {
+    worksheets?: "emit" | "ignore" | "prep";
+    sharedStrings?: "cache" | "emit" | "ignore";
+    hyperlinks?: "cache" | "emit" | "ignore";
+    styles?: "cache" | "ignore";
+    entries?: "emit" | "ignore";
+}
+/** Rich text item from shared strings */
+export interface SharedStringRichText {
+    richText: Array<{
+        font: Partial<Font> | null;
+        text: string | null;
+    }>;
+}
+/** Shared string value - either plain text or rich text */
+export type SharedStringValue = string | SharedStringRichText;
+/** Relationship entry from workbook.xml.rels */
+export interface WorkbookRelationship {
+    Id: string;
+    Target: string;
+    Type?: string;
+}
+/** Sheet metadata from workbook.xml */
+export interface SheetMetadata {
+    id: number;
+    name: string;
+    state?: WorksheetState;
+    rId: string;
+}
+/** Workbook model parsed from workbook.xml */
+export interface WorkbookModel {
+    sheets?: SheetMetadata[];
+    properties?: Partial<WorkbookProperties>;
+    views?: unknown[];
+    definedNames?: unknown[];
+}
+/** Properties parsed from workbook.xml (workbookPr element) */
+export interface WorkbookPropertiesXform {
+    model?: Partial<WorkbookProperties>;
+}
+/** Entry event payload */
+interface EntryPayload {
+    type: "shared-strings" | "styles" | "workbook" | "worksheet" | "hyperlinks";
+    id?: string;
+}
+/** Parse event types */
+export type ParseEventType = EntryPayload["type"];
+export interface SharedStringEvent {
+    eventType: "shared-strings";
+    value: {
+        index: number;
+        text: SharedStringValue;
+    };
+}
+export interface WorksheetReadyEvent {
+    eventType: "worksheet";
+    value: WorksheetReader;
+}
+export interface HyperlinksEvent {
+    eventType: "hyperlinks";
+    value: HyperlinkReader;
+}
+export type ParseEvent = SharedStringEvent | WorksheetReadyEvent | HyperlinksEvent;
+/**
+ * Options for WorkbookReader
+ */
+export interface WorkbookReaderOptions {
+    /**
+     * Specifies whether to emit worksheets ('emit') or not ('ignore').
+     * @default 'emit'
+     */
+    worksheets?: "emit" | "ignore";
+    /**
+     * Specifies whether to cache shared strings ('cache'), emit them ('emit'), or ignore them ('ignore').
+     * @default 'cache'
+     */
+    sharedStrings?: "cache" | "emit" | "ignore";
+    /**
+     * Specifies whether to cache hyperlinks ('cache'), emit them ('emit'), or ignore them ('ignore').
+     * @default 'ignore'
+     */
+    hyperlinks?: "cache" | "emit" | "ignore";
+    /**
+     * Specifies whether to cache styles ('cache') or ignore them ('ignore').
+     * @default 'ignore'
+     */
+    styles?: "cache" | "ignore";
+    /**
+     * Specifies whether to emit entries ('emit') or not ('ignore').
+     * @default 'ignore'
+     */
+    entries?: "emit" | "ignore";
+}
+declare class WorkbookReader extends EventEmitter {
+    input: string | Readable;
+    options: {
+        worksheets: "emit" | "ignore";
+        sharedStrings: "cache" | "emit" | "ignore";
+        hyperlinks: "cache" | "emit" | "ignore";
+        styles: "cache" | "ignore";
+        entries: "emit" | "ignore";
+    };
+    styles: StylesXform;
+    stream?: Readable;
+    sharedStrings?: SharedStringValue[];
+    workbookRels?: WorkbookRelationship[];
+    properties?: WorkbookPropertiesXform;
+    model?: WorkbookModel;
+    constructor(input: string | Readable, options?: WorkbookReaderOptions);
+    _getStream(input: string | Readable): Readable;
+    read(input?: string | Readable, options?: WorkbookReaderOptions): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<WorksheetReader>;
+    parse(input?: string | Readable, options?: WorkbookReaderOptions): AsyncIterableIterator<ParseEvent>;
+    _emitEntry(payload: EntryPayload): void;
+    _parseRels(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseWorkbook(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseSharedStrings(entry: NodeJS.ReadableStream): AsyncIterableIterator<{
+        index: number;
+        text: SharedStringValue;
+    }>;
+    _parseStyles(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseWorksheet(iterator: AsyncIterable<unknown>, sheetNo: string): IterableIterator<WorksheetReadyEvent>;
+    _parseHyperlinks(iterator: AsyncIterable<unknown>, sheetNo: string): IterableIterator<HyperlinksEvent>;
+}
+declare const WorkbookReaderOptions: {
+    readonly worksheets: readonly ["emit", "ignore"];
+    readonly sharedStrings: readonly ["cache", "emit", "ignore"];
+    readonly hyperlinks: readonly ["cache", "emit", "ignore"];
+    readonly styles: readonly ["cache", "ignore"];
+    readonly entries: readonly ["emit", "ignore"];
+};
+export { WorkbookReader, WorkbookReaderOptions };