@cj-tech-master/excelts 4.0.0 → 4.0.1-canary.20260104072032.0453bbe

package/dist/browser/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";
+import { type CsvParseOptions, type CsvFormatOptions } from "@csv/csv-core";
+import { type DecimalSeparator } from "@csv/csv-number";
+import type { IReadable, IWritable } from "@stream/types";
+import type { Workbook } from "@excel/workbook";
+import type { Worksheet } from "@excel/worksheet";
+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/csv-stream";
+export { parseCsv, formatCsv } from "@csv/csv-core";
+export type { CsvParseOptions, CsvFormatOptions } from "@csv/csv-core";

package/dist/browser/modules/csv/csv.browser.js

@@ -0,0 +1,265 @@
+/**
+ * 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 { DateParser, DateFormatter } from "../../utils/datetime.js";
+import { parseCsv, formatCsv } from "./csv-core.js";
+import { CsvParserStream, CsvFormatterStream } from "./csv-stream.js";
+import { parseNumberFromCsv } from "./csv-number.js";
+import { pipeline } from "../stream/index.browser.js";
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_DATE_FORMATS = [
+    "YYYY-MM-DD[T]HH:mm:ssZ",
+    "YYYY-MM-DD[T]HH:mm:ss",
+    "MM-DD-YYYY",
+    "YYYY-MM-DD"
+];
+// =============================================================================
+// Value Mappers
+// =============================================================================
+const SpecialValues = {
+    true: true,
+    false: false,
+    "#N/A": { error: "#N/A" },
+    "#REF!": { error: "#REF!" },
+    "#NAME?": { error: "#NAME?" },
+    "#DIV/0!": { error: "#DIV/0!" },
+    "#NULL!": { error: "#NULL!" },
+    "#VALUE!": { error: "#VALUE!" },
+    "#NUM!": { error: "#NUM!" }
+};
+export function createDefaultValueMapper(dateFormats, options) {
+    const dateParser = DateParser.create(dateFormats);
+    const decimalSeparator = options?.decimalSeparator ?? ".";
+    return function mapValue(datum) {
+        if (datum === "") {
+            return null;
+        }
+        if (typeof datum === "string") {
+            const datumNumber = parseNumberFromCsv(datum, decimalSeparator);
+            if (!Number.isNaN(datumNumber) && datumNumber !== Infinity) {
+                return datumNumber;
+            }
+        }
+        else {
+            const datumNumber = Number(datum);
+            if (!Number.isNaN(datumNumber) && datumNumber !== Infinity) {
+                return datumNumber;
+            }
+        }
+        const date = dateParser.parse(datum);
+        if (date) {
+            return date;
+        }
+        const special = SpecialValues[datum];
+        if (special !== undefined) {
+            return special;
+        }
+        return datum;
+    };
+}
+export function createDefaultWriteMapper(dateFormat, dateUTC) {
+    const formatter = dateFormat
+        ? DateFormatter.create(dateFormat, { utc: dateUTC })
+        : DateFormatter.iso(dateUTC);
+    return function mapValue(value) {
+        if (value) {
+            if (value.text || value.hyperlink) {
+                return value.hyperlink || value.text || "";
+            }
+            if (value.formula || value.result) {
+                return value.result || "";
+            }
+            if (value instanceof Date) {
+                return formatter.format(value);
+            }
+            if (value.error) {
+                return value.error;
+            }
+            if (typeof value === "object") {
+                return JSON.stringify(value);
+            }
+        }
+        return value;
+    };
+}
+// =============================================================================
+// CSV Class
+// =============================================================================
+class CSV {
+    constructor(workbook) {
+        this.workbook = workbook;
+    }
+    // ---------------------------------------------------------------------------
+    // In-Memory Operations
+    // ---------------------------------------------------------------------------
+    load(content, options) {
+        let str;
+        if (typeof content === "string") {
+            str = content;
+        }
+        else if (content instanceof ArrayBuffer || content instanceof Uint8Array) {
+            str = new TextDecoder().decode(content);
+        }
+        else {
+            str = String(content);
+        }
+        const worksheet = this.workbook.addWorksheet(options?.sheetName);
+        const dateFormats = options?.dateFormats ?? DEFAULT_DATE_FORMATS;
+        const map = options?.map ||
+            createDefaultValueMapper(dateFormats, {
+                decimalSeparator: options?.valueMapperOptions?.decimalSeparator ?? options?.parserOptions?.decimalSeparator
+            });
+        const rows = parseCsv(str, options?.parserOptions);
+        for (const row of rows) {
+            worksheet.addRow(row.map(map));
+        }
+        return worksheet;
+    }
+    writeString(options) {
+        const worksheet = this.workbook.getWorksheet(options?.sheetName || options?.sheetId);
+        if (!worksheet) {
+            return "";
+        }
+        const { dateFormat, dateUTC } = options || {};
+        const map = options?.map || createDefaultWriteMapper(dateFormat, dateUTC);
+        const includeEmptyRows = options?.includeEmptyRows !== false;
+        const rows = [];
+        let lastRow = 1;
+        worksheet.eachRow((row, rowNumber) => {
+            if (includeEmptyRows) {
+                while (lastRow++ < rowNumber - 1) {
+                    rows.push([]);
+                }
+            }
+            const { values } = row;
+            values.shift();
+            rows.push(values.map(map));
+            lastRow = rowNumber;
+        });
+        return formatCsv(rows, options?.formatterOptions);
+    }
+    async writeBuffer(options) {
+        return new TextEncoder().encode(this.writeString(options));
+    }
+    // ---------------------------------------------------------------------------
+    // Stream Operations
+    // ---------------------------------------------------------------------------
+    async read(stream, options) {
+        const worksheet = this.workbook.addWorksheet(options?.sheetName);
+        const dateFormats = options?.dateFormats ?? DEFAULT_DATE_FORMATS;
+        const map = options?.map ||
+            createDefaultValueMapper(dateFormats, {
+                decimalSeparator: options?.valueMapperOptions?.decimalSeparator ?? options?.parserOptions?.decimalSeparator
+            });
+        const parser = new CsvParserStream(options?.parserOptions);
+        return new Promise((resolve, reject) => {
+            parser.on("data", (row) => worksheet.addRow(row.map(map)));
+            pipeline(stream, parser)
+                .then(() => resolve(worksheet))
+                .catch(reject);
+        });
+    }
+    async write(stream, options) {
+        const worksheet = this.workbook.getWorksheet(options?.sheetName || options?.sheetId);
+        if (!worksheet) {
+            stream.end();
+            return;
+        }
+        const { dateFormat, dateUTC } = options || {};
+        const map = options?.map || createDefaultWriteMapper(dateFormat, dateUTC);
+        const includeEmptyRows = options?.includeEmptyRows !== false;
+        const formatterOptions = { ...options?.formatterOptions };
+        const formatter = new CsvFormatterStream(formatterOptions);
+        const pipelinePromise = pipeline(formatter, stream);
+        let lastRow = 1;
+        worksheet.eachRow((row, rowNumber) => {
+            if (includeEmptyRows) {
+                while (lastRow++ < rowNumber - 1) {
+                    formatter.write([]);
+                }
+            }
+            const { values } = row;
+            values.shift();
+            formatter.write(values.map(map));
+            lastRow = rowNumber;
+        });
+        formatter.end();
+        await pipelinePromise;
+    }
+    createReadStream(options) {
+        const worksheet = this.workbook.getWorksheet(options?.sheetName || options?.sheetId);
+        const { dateFormat, dateUTC } = options || {};
+        const map = options?.map || createDefaultWriteMapper(dateFormat, dateUTC);
+        const includeEmptyRows = options?.includeEmptyRows !== false;
+        const formatter = new CsvFormatterStream({ ...options?.formatterOptions });
+        if (worksheet) {
+            setTimeout(() => {
+                let lastRow = 1;
+                worksheet.eachRow((row, rowNumber) => {
+                    if (includeEmptyRows) {
+                        while (lastRow++ < rowNumber - 1) {
+                            formatter.write([]);
+                        }
+                    }
+                    const { values } = row;
+                    values.shift();
+                    formatter.write(values.map(map));
+                    lastRow = rowNumber;
+                });
+                formatter.end();
+            }, 0);
+        }
+        else {
+            setTimeout(() => formatter.end(), 0);
+        }
+        return formatter;
+    }
+    createWriteStream(options) {
+        const worksheet = this.workbook.addWorksheet(options?.sheetName);
+        const dateFormats = options?.dateFormats ?? DEFAULT_DATE_FORMATS;
+        const map = options?.map ||
+            createDefaultValueMapper(dateFormats, {
+                decimalSeparator: options?.valueMapperOptions?.decimalSeparator ?? options?.parserOptions?.decimalSeparator
+            });
+        const parser = new CsvParserStream(options?.parserOptions);
+        parser.on("data", (row) => worksheet.addRow(row.map(map)));
+        return parser;
+    }
+    // ---------------------------------------------------------------------------
+    // File Operations (Browser stubs - overridden in Node.js)
+    // ---------------------------------------------------------------------------
+    async readFile(_filename, _options) {
+        throw new Error("csv.readFile() is not available in browser.\n" +
+            "Use csv.load(csvString) or csv.read(stream) instead.\n" +
+            "Example: const response = await fetch('/data.csv');\n" +
+            "         workbook.csv.load(await response.text());");
+    }
+    async writeFile(_filename, _options) {
+        throw new Error("csv.writeFile() is not available in browser.\n" +
+            "Use csv.writeBuffer() and trigger a download instead.\n" +
+            "Example: const buffer = await workbook.csv.writeBuffer();\n" +
+            "         download(new Blob([buffer]), 'output.csv');");
+    }
+}
+// =============================================================================
+// Standalone Functions (for backward compatibility)
+// =============================================================================
+export function parseCsvToWorksheet(content, workbook, options) {
+    const csv = new CSV(workbook);
+    return csv.load(content, options);
+}
+export function formatWorksheetToCsv(worksheet, options) {
+    if (!worksheet) {
+        return "";
+    }
+    const csv = new CSV(worksheet.workbook);
+    return csv.writeString({ ...options, sheetId: worksheet.id });
+}
+export { CSV };
+export { CsvParserStream, CsvFormatterStream } from "./csv-stream.js";
+export { parseCsv, formatCsv } from "./csv-core.js";

package/dist/browser/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/csv.browser";
+import type { Worksheet } from "@excel/worksheet";
+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/csv.browser";
+export { CsvParserStream, CsvFormatterStream } from "@csv/csv-stream";

package/dist/browser/modules/csv/csv.js

@@ -0,0 +1,29 @@
+/**
+ * CSV class - Node.js Version
+ *
+ * Extends browser CSV class with file system support.
+ */
+import fs from "fs";
+import { fileExists } from "../../utils/utils.browser.js";
+import { CSV as CSVBrowser } from "./csv.browser.js";
+class CSV extends CSVBrowser {
+    async readFile(filename, options) {
+        if (!(await fileExists(filename))) {
+            throw new Error(`File not found: ${filename}`);
+        }
+        const readStream = fs.createReadStream(filename, {
+            encoding: "utf8",
+            highWaterMark: options?.highWaterMark ?? 64 * 1024
+        });
+        return this.read(readStream, options);
+    }
+    async writeFile(filename, options) {
+        const writeStream = fs.createWriteStream(filename, {
+            encoding: (options?.encoding || "utf8"),
+            highWaterMark: options?.highWaterMark ?? 64 * 1024
+        });
+        return this.write(writeStream, options);
+    }
+}
+export { CSV };
+export { CsvParserStream, CsvFormatterStream } from "./csv-stream.js";

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

@@ -0,0 +1,33 @@
+import type { Worksheet } from "@excel/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/browser/modules/excel/anchor.js

@@ -0,0 +1,97 @@
+import { colCache } from "./utils/col-cache.js";
+function isAnchorModel(value) {
+    return (typeof value === "object" &&
+        "nativeCol" in value &&
+        "nativeRow" in value &&
+        "nativeColOff" in value &&
+        "nativeRowOff" in value);
+}
+function isSimpleAddress(value) {
+    return typeof value === "object" && "col" in value && "row" in value;
+}
+class Anchor {
+    constructor(worksheet, address, offset = 0) {
+        this.worksheet = worksheet;
+        if (!address) {
+            this.nativeCol = 0;
+            this.nativeColOff = 0;
+            this.nativeRow = 0;
+            this.nativeRowOff = 0;
+        }
+        else if (typeof address === "string") {
+            const decoded = colCache.decodeAddress(address);
+            this.nativeCol = decoded.col + offset;
+            this.nativeColOff = 0;
+            this.nativeRow = decoded.row + offset;
+            this.nativeRowOff = 0;
+        }
+        else if (isAnchorModel(address)) {
+            this.nativeCol = address.nativeCol || 0;
+            this.nativeColOff = address.nativeColOff || 0;
+            this.nativeRow = address.nativeRow || 0;
+            this.nativeRowOff = address.nativeRowOff || 0;
+        }
+        else if (isSimpleAddress(address)) {
+            this.col = address.col + offset;
+            this.row = address.row + offset;
+        }
+        else {
+            this.nativeCol = 0;
+            this.nativeColOff = 0;
+            this.nativeRow = 0;
+            this.nativeRowOff = 0;
+        }
+    }
+    static asInstance(model) {
+        if (model == null) {
+            return null;
+        }
+        if (model instanceof Anchor) {
+            return model;
+        }
+        return new Anchor(undefined, model);
+    }
+    get col() {
+        return this.nativeCol + Math.min(this.colWidth - 1, this.nativeColOff) / this.colWidth;
+    }
+    set col(v) {
+        this.nativeCol = Math.floor(v);
+        this.nativeColOff = Math.floor((v - this.nativeCol) * this.colWidth);
+    }
+    get row() {
+        return this.nativeRow + Math.min(this.rowHeight - 1, this.nativeRowOff) / this.rowHeight;
+    }
+    set row(v) {
+        this.nativeRow = Math.floor(v);
+        this.nativeRowOff = Math.floor((v - this.nativeRow) * this.rowHeight);
+    }
+    get colWidth() {
+        return this.worksheet &&
+            this.worksheet.getColumn(this.nativeCol + 1) &&
+            this.worksheet.getColumn(this.nativeCol + 1).isCustomWidth
+            ? Math.floor(this.worksheet.getColumn(this.nativeCol + 1).width * 10000)
+            : 640000;
+    }
+    get rowHeight() {
+        return this.worksheet &&
+            this.worksheet.getRow(this.nativeRow + 1) &&
+            this.worksheet.getRow(this.nativeRow + 1).height
+            ? Math.floor(this.worksheet.getRow(this.nativeRow + 1).height * 10000)
+            : 180000;
+    }
+    get model() {
+        return {
+            nativeCol: this.nativeCol,
+            nativeColOff: this.nativeColOff,
+            nativeRow: this.nativeRow,
+            nativeRowOff: this.nativeRowOff
+        };
+    }
+    set model(value) {
+        this.nativeCol = value.nativeCol;
+        this.nativeColOff = value.nativeColOff;
+        this.nativeRow = value.nativeRow;
+        this.nativeRowOff = value.nativeRowOff;
+    }
+}
+export { Anchor };

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

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