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

package/dist/types/csv/csv.base.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CSV Base class - Shared functionality for Node.js and Browser
+ *
+ * Uses native CSV parser (RFC 4180 compliant) with zero external dependencies.
+ * Date parsing uses native high-performance datetime utilities.
+ */
+import { type DateFormat } from "../utils/datetime";
+import { type CsvParseOptions, type CsvFormatOptions } from "./csv-core";
+import type { Workbook } from "../doc/workbook";
+import type { Worksheet } from "../doc/worksheet";
+/**
+ * CSV read options
+ */
+export interface CsvReadOptions {
+    /** Date format strings to try when parsing (default: ISO formats) */
+    dateFormats?: readonly DateFormat[];
+    /** Custom value mapper function */
+    map?(value: any, index: number): any;
+    /** Worksheet name to create (default: "Sheet1") */
+    sheetName?: string;
+    /** CSV parsing options */
+    parserOptions?: Partial<CsvParseOptions>;
+}
+/**
+ * CSV write options
+ */
+export interface CsvWriteOptions {
+    /** Date format for output (default: ISO format) */
+    dateFormat?: string;
+    /** Use UTC for dates (default: false) */
+    dateUTC?: boolean;
+    /** Worksheet name or ID to export */
+    sheetName?: string;
+    /** Worksheet ID to export */
+    sheetId?: number;
+    /** Output encoding (default: "utf8") */
+    encoding?: string;
+    /** Custom value mapper function */
+    map?(value: any, index: number): any;
+    /** Include empty rows (default: true) */
+    includeEmptyRows?: boolean;
+    /** CSV formatting options */
+    formatterOptions?: Partial<CsvFormatOptions>;
+}
+/**
+ * Create the default value mapper for CSV parsing
+ */
+export declare function createDefaultValueMapper(dateFormats: readonly DateFormat[], parserOptions?: Pick<CsvParseOptions, "decimalSeparator">): (datum: any) => any;
+/**
+ * Create the default value mapper for CSV writing
+ */
+export declare function createDefaultWriteMapper(dateFormat?: string, dateUTC?: boolean): (value: any) => any;
+/**
+ * Parse CSV content into a worksheet
+ */
+export declare function parseCsvToWorksheet(content: string, workbook: Workbook, options?: CsvReadOptions): Worksheet;
+/**
+ * Format worksheet as CSV string
+ */
+export declare function formatWorksheetToCsv(worksheet: Worksheet | undefined, options?: CsvWriteOptions): string;
+export { parseCsv, formatCsv, parseCsvStream } from "./csv-core";
+export type { CsvParseOptions, CsvFormatOptions, CsvParseResult } from "./csv-core";

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

@@ -0,0 +1,33 @@
+/**
+ * CSV class for Browser - No file system dependencies
+ *
+ * Provides:
+ * - load: Load from string or ArrayBuffer
+ * - writeString: Write to string
+ * - writeBuffer: Write to Uint8Array
+ */
+import { type CsvReadOptions, type CsvWriteOptions } from "./csv.base";
+import type { Workbook } from "../doc/workbook.browser";
+import type { Worksheet } from "../doc/worksheet";
+declare class CSV {
+    workbook: Workbook;
+    constructor(workbook: Workbook);
+    /**
+     * Load CSV from string or ArrayBuffer
+     */
+    load(data: string | ArrayBuffer | Uint8Array, options?: CsvReadOptions): Worksheet;
+    /**
+     * Write CSV to string
+     */
+    writeString(options?: CsvWriteOptions): string;
+    /**
+     * Write CSV to Uint8Array buffer
+     */
+    writeBuffer(options?: CsvWriteOptions): Uint8Array;
+    readFile(_filename: string, _options?: CsvReadOptions): Promise<never>;
+    read(_stream: any, _options?: CsvReadOptions): Promise<never>;
+    writeFile(_filename: string, _options?: CsvWriteOptions): Promise<never>;
+    write(_stream: any, _options?: CsvWriteOptions): Promise<never>;
+}
+export { CSV };
+export type { CsvReadOptions, CsvWriteOptions } from "./csv.base";

package/dist/types/csv/csv.d.ts

@@ -0,0 +1,105 @@
+/**
+ * CSV class for Node.js - Full streaming and file system support
+ *
+ * Features:
+ * - readFile: Read from file path (streaming)
+ * - writeFile: Write to file path (streaming)
+ * - read: Read from Node.js stream
+ * - write: Write to Node.js stream
+ * - createReadStream: Create a readable stream from worksheet
+ * - createWriteStream: Create a writable stream that writes to worksheet
+ */
+import { type Readable, type Writable } from "stream";
+import { type CsvReadOptions, type CsvWriteOptions } from "./csv.base";
+import type { Workbook } from "../doc/workbook";
+import type { Worksheet } from "../doc/worksheet";
+/**
+ * Extended read options for streaming
+ */
+export interface CsvStreamReadOptions extends CsvReadOptions {
+    /** High water mark for stream (default: 64KB) */
+    highWaterMark?: number;
+}
+/**
+ * Extended write options for streaming
+ */
+export interface CsvStreamWriteOptions extends CsvWriteOptions {
+    /** High water mark for stream (default: 64KB) */
+    highWaterMark?: number;
+}
+declare class CSV {
+    workbook: Workbook;
+    constructor(workbook: Workbook);
+    /**
+     * Read CSV from file using streaming
+     *
+     * @example
+     * ```ts
+     * const worksheet = await workbook.csv.readFile('data.csv');
+     * ```
+     */
+    readFile(filename: string, options?: CsvStreamReadOptions): Promise<Worksheet>;
+    /**
+     * Read CSV from Node.js readable stream
+     *
+     * Uses true streaming - processes data row by row without loading entire file into memory.
+     *
+     * @example
+     * ```ts
+     * const stream = fs.createReadStream('data.csv');
+     * const worksheet = await workbook.csv.read(stream);
+     * ```
+     */
+    read(stream: Readable, options?: CsvReadOptions): Promise<Worksheet>;
+    /**
+     * Write CSV to file using streaming
+     *
+     * @example
+     * ```ts
+     * await workbook.csv.writeFile('output.csv');
+     * ```
+     */
+    writeFile(filename: string, options?: CsvStreamWriteOptions): Promise<void>;
+    /**
+     * Write CSV to Node.js writable stream
+     *
+     * Uses true streaming - writes data row by row.
+     *
+     * @example
+     * ```ts
+     * const stream = fs.createWriteStream('output.csv');
+     * await workbook.csv.write(stream);
+     * ```
+     */
+    write(stream: Writable, options?: CsvWriteOptions): Promise<void>;
+    /**
+     * Write CSV to buffer
+     *
+     * Note: This loads the entire CSV into memory. For large files, use write() with a stream.
+     */
+    writeBuffer(options?: CsvWriteOptions): Promise<Buffer>;
+    /**
+     * Create a readable stream that outputs CSV rows from the worksheet
+     *
+     * @example
+     * ```ts
+     * const csvStream = workbook.csv.createReadStream();
+     * csvStream.pipe(fs.createWriteStream('output.csv'));
+     * ```
+     */
+    createReadStream(options?: CsvWriteOptions): Readable;
+    /**
+     * Create a writable stream that parses CSV and adds rows to a worksheet
+     *
+     * @example
+     * ```ts
+     * const csvWriter = workbook.csv.createWriteStream({ sheetName: 'Data' });
+     * fs.createReadStream('input.csv').pipe(csvWriter);
+     * await new Promise(resolve => csvWriter.on('finish', resolve));
+     * ```
+     */
+    createWriteStream(options?: CsvReadOptions): Writable;
+}
+export { CSV };
+export type { CsvReadOptions, CsvWriteOptions } from "./csv.base";
+export { CsvParserStream, CsvFormatterStream } from "./csv-stream";

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

@@ -0,0 +1,33 @@
+import type { Worksheet } from "./worksheet";
+interface AnchorModel {
+    nativeCol: number;
+    nativeRow: number;
+    nativeColOff: number;
+    nativeRowOff: number;
+}
+interface SimpleAddress {
+    col: number;
+    row: number;
+}
+type AddressInput = string | AnchorModel | SimpleAddress;
+declare class Anchor {
+    nativeCol: number;
+    nativeRow: number;
+    nativeColOff: number;
+    nativeRowOff: number;
+    worksheet?: Worksheet;
+    constructor(worksheet?: Worksheet, address?: AddressInput | null, offset?: number);
+    static asInstance(model: AddressInput | Anchor | null | undefined): Anchor | null;
+    get col(): number;
+    set col(v: number);
+    get row(): number;
+    set row(v: number);
+    get colWidth(): number;
+    get rowHeight(): number;
+    get model(): AnchorModel;
+    set model(value: AnchorModel);
+}
+export { Anchor };
+export type { AnchorModel };
+type IAnchor = Pick<InstanceType<typeof Anchor>, "col" | "row" | "nativeCol" | "nativeRow" | "nativeColOff" | "nativeRowOff">;
+export type { IAnchor };

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

@@ -0,0 +1,139 @@
+import { Note } from "./note";
+import type { Row } from "./row";
+import type { Column } from "./column";
+import type { Worksheet } from "./worksheet";
+import type { Workbook } from "./workbook";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellRichTextValue, CellErrorValue, DataValidation, CellValue, CellHyperlinkValue } from "../types";
+export type HyperlinkValueData = CellHyperlinkValue;
+export type FormulaResult = string | number | boolean | Date | CellErrorValue;
+export interface FormulaValueData {
+    shareType?: string;
+    ref?: string;
+    formula?: string;
+    sharedFormula?: string;
+    result?: FormulaResult;
+    date1904?: boolean;
+}
+interface FullAddress {
+    sheetName: string;
+    address: string;
+    row: number;
+    col: number;
+}
+export interface CellAddress {
+    address: string;
+    row: number;
+    col: number;
+    $col$row?: string;
+}
+export interface NoteText {
+    text: string;
+    font?: Record<string, unknown>;
+}
+export interface NoteConfig {
+    texts?: NoteText[];
+    margins?: {
+        insetmode?: string;
+        inset?: number[];
+    };
+    protection?: {
+        locked?: string;
+        lockText?: string;
+    };
+    editAs?: string;
+}
+export interface NoteModel {
+    type: string;
+    note: NoteConfig;
+}
+export interface CellModel {
+    address: string;
+    type: number;
+    value?: number | string | boolean | Date | CellRichTextValue | CellErrorValue | HyperlinkValueData;
+    style?: Partial<Style>;
+    comment?: NoteModel;
+    text?: string;
+    hyperlink?: string;
+    tooltip?: string;
+    master?: string;
+    shareType?: string;
+    ref?: string;
+    formula?: string;
+    sharedFormula?: string;
+    result?: FormulaResult;
+    richText?: CellRichTextValue;
+    sharedString?: number;
+    error?: CellErrorValue;
+    rawValue?: unknown;
+}
+export type CellValueType = CellValue;
+declare class Cell {
+    static Types: typeof import("./enums").ValueType;
+    private _row;
+    private _column;
+    private _address;
+    private _value;
+    style: Partial<Style>;
+    private _mergeCount;
+    private _comment?;
+    constructor(row: Row, column: Column, address: string);
+    get worksheet(): Worksheet;
+    get workbook(): Workbook;
+    destroy(): 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 border(): Partial<Borders> | undefined;
+    set border(value: Partial<Borders> | undefined);
+    get fill(): Fill | undefined;
+    set fill(value: Fill | undefined);
+    get protection(): Partial<Protection> | undefined;
+    set protection(value: Partial<Protection> | undefined);
+    private _mergeStyle;
+    get address(): string;
+    get row(): number;
+    get col(): number;
+    get $col$row(): string;
+    get type(): number;
+    get effectiveType(): number;
+    toCsvString(): string;
+    addMergeRef(): void;
+    releaseMergeRef(): void;
+    get isMerged(): boolean;
+    merge(master: Cell, ignoreStyle?: boolean): void;
+    unmerge(): void;
+    isMergedTo(master: Cell): boolean;
+    get master(): Cell;
+    get isHyperlink(): boolean;
+    get hyperlink(): string | undefined;
+    get value(): CellValueType;
+    set value(v: CellValueType);
+    get note(): string | NoteConfig | undefined;
+    set note(note: string | NoteConfig);
+    get comment(): Note | undefined;
+    set comment(comment: Note | NoteConfig | undefined);
+    get text(): string;
+    get html(): string;
+    toString(): string;
+    _upgradeToHyperlink(hyperlink: string): void;
+    get formula(): string | undefined;
+    get result(): FormulaResult | undefined;
+    get formulaType(): number;
+    get fullAddress(): FullAddress;
+    get name(): string;
+    set name(value: string);
+    get names(): string[];
+    set names(value: string[]);
+    addName(name: string): void;
+    removeName(name: string): void;
+    removeAllNames(): void;
+    private get _dataValidations();
+    get dataValidation(): DataValidation | undefined;
+    set dataValidation(value: DataValidation);
+    get model(): CellModel;
+    set model(value: CellModel);
+}
+export { Cell };

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

@@ -0,0 +1,121 @@
+import type { Cell, CellValueType } from "./cell";
+import type { Worksheet } from "./worksheet";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellValue } from "../types";
+/** 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(worksheet: Worksheet, cols: ColumnModel[]): Column[] | null;
+}
+export { Column };

package/dist/types/doc/defined-names.d.ts

@@ -0,0 +1,37 @@
+import { type DecodedRange } from "../utils/col-cache";
+import { CellMatrix } from "../utils/cell-matrix";
+import { Range } from "./range";
+import type { Address } from "../types";
+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/doc/image.d.ts

@@ -0,0 +1,64 @@
+import { Anchor, type AnchorModel } from "./anchor";
+import type { Worksheet } from "./worksheet";
+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/doc/modelcontainer.d.ts

@@ -0,0 +1,8 @@
+import { XLSX } from "../xlsx/xlsx";
+declare class ModelContainer {
+    model: any;
+    private _xlsx?;
+    constructor(model: any);
+    get xlsx(): XLSX;
+}
+export { ModelContainer };