@cj-tech-master/excelts 3.1.0 → 4.0.0

package/dist/types/modules/archive/zip-records.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ZIP record builders (PKWARE APPNOTE)
+ *
+ * Shared by streaming zip writer and buffer zip builder.
+ */
+export interface ZipLocalFileHeaderInput {
+    fileName: Uint8Array;
+    extraField: Uint8Array;
+    flags: number;
+    compressionMethod: number;
+    dosTime: number;
+    dosDate: number;
+    crc32: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    versionNeeded?: number;
+}
+export declare function buildLocalFileHeader(input: ZipLocalFileHeaderInput): Uint8Array;
+export interface ZipCentralDirectoryHeaderInput {
+    fileName: Uint8Array;
+    extraField: Uint8Array;
+    comment: Uint8Array;
+    flags: number;
+    compressionMethod: number;
+    dosTime: number;
+    dosDate: number;
+    crc32: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    localHeaderOffset: number;
+    versionMadeBy?: number;
+    versionNeeded?: number;
+    externalAttributes?: number;
+}
+export declare function buildCentralDirectoryHeader(input: ZipCentralDirectoryHeaderInput): Uint8Array;
+export interface ZipEndOfCentralDirectoryInput {
+    entryCount: number;
+    centralDirSize: number;
+    centralDirOffset: number;
+    comment: Uint8Array;
+}
+export declare function buildEndOfCentralDirectory(input: ZipEndOfCentralDirectoryInput): Uint8Array;
+export declare function buildDataDescriptor(crc32: number, compressedSize: number, uncompressedSize: number): Uint8Array<ArrayBuffer>;

package/dist/types/modules/csv/csv-core.d.ts

@@ -0,0 +1,215 @@
+/**
+ * CSV Parser and Formatter - RFC 4180 compliant
+ *
+ * A lightweight, cross-platform CSV implementation that works in both
+ * Node.js and Browser environments with zero dependencies.
+ *
+ * High-performance RFC 4180 compliant CSV parser and formatter.
+ *
+ * @see https://tools.ietf.org/html/rfc4180
+ */
+/** Header array type (can include undefined to skip columns) */
+export type HeaderArray = (string | undefined | null)[];
+/** Header transform function */
+export type HeaderTransformFunction = (headers: string[]) => HeaderArray;
+/** Row types */
+export type RowArray = string[];
+export type RowMap = Record<string, string>;
+export type Row = RowArray | RowMap;
+/** Row transform callback */
+export type RowTransformCallback<T> = (error?: Error | null, row?: T | null) => void;
+/** Row transform function - sync or async */
+export type RowTransformFunction<I = Row, O = Row> = ((row: I) => O | null) | ((row: I, callback: RowTransformCallback<O>) => void);
+/** Row validate callback */
+export type RowValidateCallback = (error?: Error | null, isValid?: boolean, reason?: string) => void;
+/** Row validate function - sync or async */
+export type RowValidateFunction<T = Row> = ((row: T) => boolean) | ((row: T, callback: RowValidateCallback) => void);
+/**
+ * CSV parsing options
+ */
+export interface CsvParseOptions {
+    /** Field delimiter (default: ",") */
+    delimiter?: string;
+    /** Quote character (default: '"'), set to false or null to disable quoting */
+    quote?: string | false | null;
+    /** Escape character for quotes (default: '"'), set to false or null to disable */
+    escape?: string | false | null;
+    /** Skip empty lines (default: false) */
+    skipEmptyLines?: boolean;
+    /** Alias for skipEmptyLines */
+    ignoreEmpty?: boolean;
+    /** Trim whitespace from both sides of fields (default: false) */
+    trim?: boolean;
+    /** Left trim whitespace from fields (default: false) */
+    ltrim?: boolean;
+    /** Right trim whitespace from fields (default: false) */
+    rtrim?: boolean;
+    /**
+     * Header handling:
+     * - true: first row is headers, return objects
+     * - false: no headers, return arrays
+     * - string[]: use these as headers
+     * - function: transform first row headers
+     */
+    headers?: boolean | HeaderArray | HeaderTransformFunction;
+    /**
+     * If true and headers is string[], discard first row and use provided headers
+     */
+    renameHeaders?: boolean;
+    /** Comment character - lines starting with this are ignored */
+    comment?: string;
+    /**
+     * Decimal separator used when parsing numbers from CSV (default: ".").
+     *
+     * Note: core CSV parsing returns strings; number conversion is handled by higher-level
+     * consumers (e.g. the default value mapper in the CSV module).
+     *
+     * @deprecated Use CsvReadOptions.valueMapperOptions.decimalSeparator instead.
+     */
+    decimalSeparator?: "." | ",";
+    /** Maximum number of data rows to parse (excluding header) */
+    maxRows?: number;
+    /** Number of lines to skip at the beginning (before header detection) */
+    skipLines?: number;
+    /** Number of data rows to skip (after header detection) */
+    skipRows?: number;
+    /**
+     * Strict column handling:
+     * - If true, rows with column count mismatch emit 'data-invalid' event
+     * - If false (default), throws error on mismatch (unless discardUnmappedColumns)
+     */
+    strictColumnHandling?: boolean;
+    /**
+     * If true, discard columns that exceed header count
+     * Only valid when headers are specified
+     */
+    discardUnmappedColumns?: boolean;
+    /**
+     * Enable object mode (default: true for Node.js streams)
+     * - true: push row objects/arrays
+     * - false: push JSON strings
+     */
+    objectMode?: boolean;
+    /**
+     * Character encoding for input (default: "utf8")
+     * Only used in Node.js streaming context
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Synchronous transform function to apply to each row after parsing
+     * Return null/undefined to skip the row
+     * Works in both Node.js and Browser environments
+     *
+     * @example
+     * // With headers (row is Record<string, string>)
+     * transform: (row) => ({ ...row, name: row.name.toUpperCase() })
+     *
+     * // Without headers (row is string[])
+     * transform: (row) => [row[0].toUpperCase(), row[1]]
+     */
+    transform?: (row: Row) => Row | null | undefined;
+    /**
+     * Synchronous validate function to check each row
+     * Return false to mark row as invalid (will be in invalidRows)
+     * Can also return { isValid: boolean, reason?: string }
+     * Works in both Node.js and Browser environments
+     *
+     * @example
+     * // With headers
+     * validate: (row) => row.name !== ''
+     *
+     * // With custom reason
+     * validate: (row) => ({ isValid: row.age >= 18, reason: 'Must be adult' })
+     */
+    validate?: (row: Row) => boolean | {
+        isValid: boolean;
+        reason?: string;
+    };
+}
+/**
+ * CSV formatting options
+ */
+export interface CsvFormatOptions {
+    /** Field delimiter (default: ",") */
+    delimiter?: string;
+    /** Quote character (default: '"'), set to false or null to disable quoting */
+    quote?: string | false | null;
+    /** Escape character (default: same as quote) */
+    escape?: string | false | null;
+    /** Row delimiter (default: "\n") */
+    rowDelimiter?: string;
+    /**
+     * Decimal separator used when formatting numbers to CSV (default: ".").
+     * For European-style CSV, this is commonly "," (often together with delimiter ";").
+     */
+    decimalSeparator?: "." | ",";
+    /** Always quote all fields (default: false, only quote when necessary) */
+    alwaysQuote?: boolean;
+    /** Quote specific columns by name or index */
+    quoteColumns?: boolean | boolean[] | Record<string, boolean>;
+    /** Quote header fields */
+    quoteHeaders?: boolean | boolean[] | Record<string, boolean>;
+    /**
+     * Header handling:
+     * - true: auto-detect headers from first object
+     * - false/null: no headers
+     * - string[]: use these as headers
+     */
+    headers?: string[] | boolean | null;
+    /**
+     * Whether to write headers (default: true when headers is provided)
+     * Set to false to suppress header row output
+     */
+    writeHeaders?: boolean;
+    /** Include BOM for UTF-8 (default: false) */
+    writeBOM?: boolean;
+    /** Include final row delimiter (default: true) */
+    includeEndRowDelimiter?: boolean;
+    /** Write headers even when there's no data (default: false) */
+    alwaysWriteHeaders?: boolean;
+    /**
+     * Transform function to apply to each row before formatting
+     * Can be sync (returns row) or async (calls callback)
+     */
+    transform?: RowTransformFunction<Row, Row>;
+    /**
+     * Enable object mode (default: true for Node.js streams)
+     * - true: accept row objects/arrays directly
+     * - false: accept JSON strings
+     */
+    objectMode?: boolean;
+}
+/**
+ * Parsed CSV result with headers
+ */
+export interface CsvParseResult<T = string[]> {
+    /** Header row (if headers option was true) */
+    headers?: string[];
+    /** Data rows */
+    rows: T[];
+    /** Invalid rows (when strictColumnHandling is true) */
+    invalidRows?: {
+        row: string[];
+        reason: string;
+    }[];
+}
+/**
+ * Check if a transform function is synchronous (1 argument) vs async (2 arguments)
+ */
+export declare function isSyncTransform<I, O>(transform: RowTransformFunction<I, O>): transform is (row: I) => O | null;
+/**
+ * Check if a validate function is synchronous (1 argument) vs async (2 arguments)
+ */
+export declare function isSyncValidate<T>(validate: RowValidateFunction<T>): validate is (row: T) => boolean;
+/**
+ * Parse a CSV string into rows of fields
+ */
+export declare function parseCsv(input: string, options?: CsvParseOptions): string[][] | CsvParseResult<Record<string, string>>;
+/**
+ * Format data as a CSV string
+ */
+export declare function formatCsv(data: (string | number | boolean | null | undefined)[][] | Record<string, any>[], options?: CsvFormatOptions): string;
+/**
+ * Async CSV parser that yields rows one at a time
+ */
+export declare function parseCsvStream(input: string | AsyncIterable<string>, options?: CsvParseOptions): AsyncGenerator<string[] | Record<string, string>, void, unknown>;

package/dist/types/modules/csv/csv-stream.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CSV Streaming Support - Cross-Platform
+ *
+ * Provides true streaming CSV parsing and formatting using our cross-platform stream module.
+ * Works identically in both Node.js and Browser environments.
+ */
+import { Transform } from "../stream/index.d.ts";
+import type { IReadable } from "../stream/types.d.ts";
+import type { CsvParseOptions, CsvFormatOptions, RowTransformFunction, RowValidateFunction, Row } from "./csv-core.d.ts";
+/**
+ * Transform stream that parses CSV data row by row
+ *
+ * @example
+ * ```ts
+ * const parser = new CsvParserStream({ headers: true });
+ * readable.pipe(parser).on('data', (row) => console.log(row));
+ * ```
+ */
+export declare class CsvParserStream extends Transform {
+    private options;
+    private buffer;
+    private currentRow;
+    private currentField;
+    private currentFieldParts;
+    private currentFieldLength;
+    private inQuotes;
+    private lineNumber;
+    private rowCount;
+    private skippedDataRows;
+    private headerRow;
+    private headersEmitted;
+    private delimiter;
+    private quote;
+    private escape;
+    private quoteEnabled;
+    private trimField;
+    private decoder;
+    private _rowTransform;
+    private _rowValidator;
+    constructor(options?: CsvParseOptions);
+    /**
+     * Set a transform function to modify rows before emitting
+     * Supports both sync and async transforms
+     */
+    transform<I extends Row = Row, O extends Row = Row>(transformFunction: RowTransformFunction<I, O>): this;
+    /**
+     * Set a validate function to filter rows
+     * Invalid rows emit 'data-invalid' event
+     */
+    validate<T extends Row = Row>(validateFunction: RowValidateFunction<T>): this;
+    _transform(chunk: Uint8Array | string, _encoding: string, callback: (error?: Error | null, data?: Row) => void): void;
+    _flush(callback: (error?: Error | null) => void): void;
+    private flushCurrentRow;
+    private appendToField;
+    private takeCurrentField;
+    private processBuffer;
+    private buildRow;
+    private processPendingRows;
+    private transformAndValidateRow;
+    private validateRow;
+    private emitRow;
+}
+/**
+ * Options for CSV formatter stream
+ */
+export interface CsvFormatterStreamOptions extends CsvFormatOptions {
+    /** Whether input is objects (vs arrays) */
+    objectMode?: boolean;
+}
+/**
+ * Transform stream that formats rows to CSV
+ *
+ * @example
+ * ```ts
+ * const formatter = new CsvFormatterStream({ headers: ['name', 'age'] });
+ * formatter.pipe(writable);
+ * formatter.write(['Alice', 30]);
+ * formatter.write(['Bob', 25]);
+ * formatter.end();
+ * ```
+ */
+export declare class CsvFormatterStream extends Transform {
+    private options;
+    private delimiter;
+    private quote;
+    private escape;
+    private rowDelimiter;
+    private quoteEnabled;
+    private alwaysQuote;
+    private decimalSeparator;
+    private headerWritten;
+    private headers;
+    private shouldWriteHeaders;
+    private rowCount;
+    private _rowTransform;
+    private escapeQuoteRegex;
+    private escapedQuote;
+    constructor(options?: CsvFormatterStreamOptions);
+    /**
+     * Set a transform function to modify rows before formatting
+     */
+    transform<I extends Row = Row, O extends Row = Row>(transformFunction: RowTransformFunction<I, O>): this;
+    _transform(chunk: Row, _encoding: string, callback: (error?: Error | null, data?: string) => void): void;
+    _flush(callback: (error?: Error | null) => void): void;
+    private formatAndPush;
+    private formatRow;
+    private shouldQuoteField;
+    private formatField;
+}
+/**
+ * Create a readable stream from an array of rows
+ */
+export declare function createCsvReadableStream(rows: unknown[][], options?: CsvFormatOptions): IReadable<any>;
+/**
+ * Create parser stream factory
+ */
+export declare function createCsvParserStream(options?: CsvParseOptions): CsvParserStream;
+/**
+ * Create formatter stream factory
+ */
+export declare function createCsvFormatterStream(options?: CsvFormatterStreamOptions): CsvFormatterStream;

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

@@ -0,0 +1,60 @@
+/**
+ * CSV class - Cross-Platform Base Implementation
+ *
+ * Provides CSV read/write functionality for both Node.js and Browser.
+ * Node.js version (csv.ts) extends this with file system support.
+ */
+import { type DateFormat } from "../../utils/datetime.d.ts";
+import { type CsvParseOptions, type CsvFormatOptions } from "./csv-core.d.ts";
+import { type DecimalSeparator } from "./csv-number.d.ts";
+import type { IReadable, IWritable } from "../stream/types.d.ts";
+import type { Workbook } from "../excel/workbook.d.ts";
+import type { Worksheet } from "../excel/worksheet.d.ts";
+export interface CsvReadOptions {
+    dateFormats?: readonly DateFormat[];
+    map?(value: any, index: number): any;
+    sheetName?: string;
+    parserOptions?: Partial<CsvParseOptions>;
+    /** Options for the default value mapper (string -> number/date/etc). */
+    valueMapperOptions?: DefaultValueMapperOptions;
+}
+export interface CsvWriteOptions {
+    dateFormat?: string;
+    dateUTC?: boolean;
+    sheetName?: string;
+    sheetId?: number;
+    encoding?: string;
+    map?(value: any, index: number): any;
+    includeEmptyRows?: boolean;
+    formatterOptions?: Partial<CsvFormatOptions>;
+}
+export interface CsvStreamReadOptions extends CsvReadOptions {
+    highWaterMark?: number;
+}
+export interface CsvStreamWriteOptions extends CsvWriteOptions {
+    highWaterMark?: number;
+}
+export interface DefaultValueMapperOptions {
+    decimalSeparator?: DecimalSeparator;
+}
+export declare function createDefaultValueMapper(dateFormats: readonly DateFormat[], options?: DefaultValueMapperOptions): (datum: any) => any;
+export declare function createDefaultWriteMapper(dateFormat?: string, dateUTC?: boolean): (value: any) => any;
+declare class CSV {
+    workbook: Workbook;
+    constructor(workbook: Workbook);
+    load(content: string | ArrayBuffer | Uint8Array, options?: CsvReadOptions): Worksheet;
+    writeString(options?: CsvWriteOptions): string;
+    writeBuffer(options?: CsvWriteOptions): Promise<Uint8Array>;
+    read(stream: IReadable<any>, options?: CsvReadOptions): Promise<Worksheet>;
+    write(stream: IWritable<any>, options?: CsvWriteOptions): Promise<void>;
+    createReadStream(options?: CsvWriteOptions): IReadable<any>;
+    createWriteStream(options?: CsvReadOptions): IWritable<any>;
+    readFile(_filename: string, _options?: CsvStreamReadOptions): Promise<Worksheet>;
+    writeFile(_filename: string, _options?: CsvStreamWriteOptions): Promise<void>;
+}
+export declare function parseCsvToWorksheet(content: string, workbook: Workbook, options?: CsvReadOptions): Worksheet;
+export declare function formatWorksheetToCsv(worksheet: Worksheet | undefined, options?: CsvWriteOptions): string;
+export { CSV };
+export { CsvParserStream, CsvFormatterStream } from "./csv-stream.d.ts";
+export { parseCsv, formatCsv } from "./csv-core.d.ts";
+export type { CsvParseOptions, CsvFormatOptions } from "./csv-core.d.ts";

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

@@ -0,0 +1,14 @@
+/**
+ * CSV class - Node.js Version
+ *
+ * Extends browser CSV class with file system support.
+ */
+import { CSV as CSVBrowser, type CsvStreamReadOptions, type CsvStreamWriteOptions } from "./csv.browser.d.ts";
+import type { Worksheet } from "../excel/worksheet.d.ts";
+declare class CSV extends CSVBrowser {
+    readFile(filename: string, options?: CsvStreamReadOptions): Promise<Worksheet>;
+    writeFile(filename: string, options?: CsvStreamWriteOptions): Promise<void>;
+}
+export { CSV };
+export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "./csv.browser.d.ts";
+export { CsvParserStream, CsvFormatterStream } from "./csv-stream.d.ts";

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

@@ -0,0 +1,33 @@
+import type { Worksheet } from "./worksheet.d.ts";
+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/modules/excel/cell.d.ts

@@ -0,0 +1,138 @@
+import { Note } from "./note.d.ts";
+import type { Row } from "./row.d.ts";
+import type { Column } from "./column.d.ts";
+import type { Worksheet } from "./worksheet.d.ts";
+import type { Workbook } from "./workbook.d.ts";
+import type { Style, NumFmt, Font, Alignment, Protection, Borders, Fill, CellRichTextValue, CellErrorValue, DataValidation, CellValue, CellHyperlinkValue } from "./types.d.ts";
+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 | CellHyperlinkValue;
+    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.d.ts").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 };