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

package/dist/types/modules/excel/utils/iterate-stream.d.ts

@@ -0,0 +1,14 @@
+type Listener = (...args: any[]) => void;
+interface EventEmitterLike {
+    on(event: string, listener: Listener): this;
+    removeListener(event: string, listener: Listener): this;
+}
+interface Readable extends EventEmitterLike {
+    resume(): void;
+    pause(): void;
+    on(event: "data", listener: (chunk: any) => void): this;
+    on(event: "end", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+}
+declare function iterateStream(stream: Readable): AsyncGenerator<any>;
+export { iterateStream };

package/dist/types/modules/excel/utils/ooxml-paths.d.ts

@@ -0,0 +1,64 @@
+export declare const OOXML_PATHS: {
+    readonly contentTypes: "[Content_Types].xml";
+    readonly rootRels: "_rels/.rels";
+    readonly docPropsApp: "docProps/app.xml";
+    readonly docPropsCore: "docProps/core.xml";
+    readonly xlWorkbook: "xl/workbook.xml";
+    readonly xlWorkbookRels: "xl/_rels/workbook.xml.rels";
+    readonly xlSharedStrings: "xl/sharedStrings.xml";
+    readonly xlStyles: "xl/styles.xml";
+    readonly xlTheme1: "xl/theme/theme1.xml";
+};
+export declare function normalizeZipPath(path: string): string;
+export declare function getWorksheetNoFromWorksheetPath(path: string): number | undefined;
+export declare function getWorksheetNoFromWorksheetRelsPath(path: string): number | undefined;
+export declare function isMediaPath(path: string): boolean;
+export declare function getMediaFilenameFromPath(path: string): string | undefined;
+export declare function isThemePath(path: string): boolean;
+export declare function getThemeNameFromPath(path: string): string | undefined;
+export declare function isBinaryEntryPath(path: string): boolean;
+export declare function getDrawingNameFromPath(path: string): string | undefined;
+export declare function getDrawingNameFromRelsPath(path: string): string | undefined;
+export declare function getVmlDrawingNameFromPath(path: string): string | undefined;
+export declare function getCommentsIndexFromPath(path: string): string | undefined;
+export declare function getTableNameFromPath(path: string): string | undefined;
+export declare function getPivotTableNameFromPath(path: string): string | undefined;
+export declare function getPivotTableNameFromRelsPath(path: string): string | undefined;
+export declare function getPivotCacheDefinitionNameFromPath(path: string): string | undefined;
+export declare function getPivotCacheDefinitionNameFromRelsPath(path: string): string | undefined;
+export declare function getPivotCacheRecordsNameFromPath(path: string): string | undefined;
+export declare function toContentTypesPartName(zipPath: string): string;
+export declare function themePath(themeName: string): string;
+export declare function mediaPath(filename: string): string;
+export declare function worksheetPath(sheetId: number | string): string;
+export declare function worksheetRelsPath(sheetId: number | string): string;
+export declare function worksheetRelTarget(sheetId: number | string): string;
+export declare function commentsPath(sheetId: number | string): string;
+export declare function commentsPathFromName(commentName: string): string;
+export declare function vmlDrawingPath(sheetId: number | string): string;
+export declare function tablePath(target: string): string;
+export declare function drawingPath(drawingName: string): string;
+export declare function drawingRelsPath(drawingName: string): string;
+export declare function pivotCacheDefinitionPath(n: number | string): string;
+export declare function pivotCacheDefinitionRelsPath(n: number | string): string;
+export declare function pivotCacheRecordsPath(n: number | string): string;
+export declare function pivotCacheRecordsRelTarget(n: number | string): string;
+export declare function pivotTablePath(n: number | string): string;
+export declare function pivotTableRelsPath(n: number | string): string;
+export declare function pivotCacheDefinitionRelTargetFromPivotTable(n: number | string): string;
+export declare const OOXML_REL_TARGETS: {
+    readonly workbookStyles: "styles.xml";
+    readonly workbookSharedStrings: "sharedStrings.xml";
+    readonly workbookTheme1: "theme/theme1.xml";
+};
+export declare function pivotCacheDefinitionRelTargetFromWorkbook(n: number | string): string;
+export declare function commentsRelTargetFromWorksheet(sheetId: number | string): string;
+export declare function vmlDrawingRelTargetFromWorksheet(sheetId: number | string): string;
+export declare function drawingRelTargetFromWorksheet(drawingName: string): string;
+export declare function vmlDrawingRelTargetFromWorksheetName(vmlName: string): string;
+export declare function commentsRelTargetFromWorksheetName(commentName: string): string;
+export declare function pivotTableRelTargetFromWorksheet(n: number | string): string;
+export declare function pivotTableRelTargetFromWorksheetName(pivotName: string): string;
+export declare function tableRelTargetFromWorksheet(target: string): string;
+export declare function tableRelTargetFromWorksheetName(name: string): string;
+export declare function mediaRelTargetFromRels(filename: string): string;

package/dist/types/modules/excel/utils/parse-sax.d.ts

@@ -0,0 +1,113 @@
+/**
+ * High-performance SAX XML parser
+ *
+ * Minimal implementation optimized for Excel XML parsing.
+ * Supports: opentag, text, closetag, error events.
+ * Zero external dependencies.
+ *
+ * Based on XML 1.0 specification with optimizations for common Excel XML patterns.
+ */
+export interface SaxEvent {
+    eventType: "opentag" | "text" | "closetag";
+    value: any;
+}
+export interface SaxesTagPlain {
+    name: string;
+    attributes: Record<string, string>;
+    isSelfClosing: boolean;
+}
+export interface SaxesOptions {
+    xmlns?: boolean;
+    position?: boolean;
+    fileName?: string;
+    fragment?: boolean;
+}
+type TextHandler = (text: string) => void;
+type OpenTagHandler = (tag: SaxesTagPlain) => void;
+type CloseTagHandler = (tag: SaxesTagPlain) => void;
+type ErrorHandler = (err: Error) => void;
+export declare class SaxesParser {
+    private trackPosition;
+    private fileName?;
+    private fragment;
+    private state;
+    private chunk;
+    private i;
+    private prevI;
+    private text;
+    private name;
+    private q;
+    private tags;
+    private tag;
+    private attribList;
+    private entity;
+    private entityReturnState;
+    private openWakaBang;
+    private sawRoot;
+    private closedRoot;
+    private carriedFromPrevious?;
+    private _closed;
+    private reportedTextBeforeRoot;
+    private reportedTextAfterRoot;
+    line: number;
+    column: number;
+    private positionAtNewLine;
+    private chunkPosition;
+    ENTITIES: Record<string, string>;
+    private textHandler?;
+    private openTagHandler?;
+    private closeTagHandler?;
+    private errorHandler?;
+    constructor(opt?: SaxesOptions);
+    get closed(): boolean;
+    get position(): number;
+    private _init;
+    on(name: "text", handler: TextHandler): void;
+    on(name: "opentag", handler: OpenTagHandler): void;
+    on(name: "closetag", handler: CloseTagHandler): void;
+    on(name: "error", handler: ErrorHandler): void;
+    off(name: string): void;
+    private makeError;
+    fail(message: string): this;
+    write(chunk: string | null): this;
+    close(): this;
+    private getCode;
+    private unget;
+    private processState;
+    private sText;
+    private handleTextInRoot;
+    private handleTextOutsideRoot;
+    private sOpenWaka;
+    private sOpenWakaBang;
+    private sOpenTag;
+    private sOpenTagSlash;
+    private sAttrib;
+    private sAttribName;
+    private sAttribNameSawWhite;
+    private sAttribValue;
+    private sAttribValueQuoted;
+    private sAttribValueClosed;
+    private sCloseTag;
+    private sCloseTagSawWhite;
+    private sComment;
+    private sCommentEnding;
+    private sCommentEnded;
+    private sCData;
+    private sCDataEnding;
+    private sCDataEnding2;
+    private sPI;
+    private sPIEnding;
+    private sDoctype;
+    private sDoctypeQuote;
+    private sDoctypeDTD;
+    private sDoctypeDTDQuoted;
+    private sEntity;
+    private parseEntity;
+    private skipSpaces;
+    private openTag;
+    private openSelfClosingTag;
+    private closeTag;
+    private end;
+}
+declare function parseSax(iterable: any): AsyncGenerator<SaxEvent[]>;
+export { parseSax };

package/dist/types/modules/excel/utils/shared-formula.d.ts

@@ -0,0 +1,2 @@
+declare function slideFormula(formula: string, fromCell: string, toCell: string): string;
+export { slideFormula };

package/dist/types/modules/excel/utils/shared-strings.d.ts

@@ -0,0 +1,12 @@
+declare class SharedStrings {
+    private _values;
+    private _totalRefs;
+    private _hash;
+    constructor();
+    get count(): number;
+    get values(): any[];
+    get totalRefs(): number;
+    getString(index: number): any;
+    add(value: any): number;
+}
+export { SharedStrings };

package/dist/types/modules/excel/utils/sheet-utils.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Utility functions for ExcelTS
+ * Provides convenient helper functions for common spreadsheet operations
+ */
+import { Workbook } from "../workbook";
+import type { Worksheet } from "../worksheet";
+import type { CellValue } from "../types";
+/**
+ * Cell address object (0-indexed)
+ */
+export interface CellAddress {
+    /** 0-indexed column number */
+    c: number;
+    /** 0-indexed row number */
+    r: number;
+}
+/**
+ * Range object with start and end addresses
+ */
+export interface Range {
+    /** Start cell (top-left) */
+    s: CellAddress;
+    /** End cell (bottom-right) */
+    e: CellAddress;
+}
+/**
+ * Row data for JSON conversion
+ */
+export type JSONRow = Record<string, CellValue>;
+/**
+ * Decode column string to 0-indexed number
+ * @example decodeCol("A") => 0, decodeCol("Z") => 25, decodeCol("AA") => 26
+ */
+export declare function decodeCol(colstr: string): number;
+/**
+ * Encode 0-indexed column number to string
+ * @example encodeCol(0) => "A", encodeCol(25) => "Z", encodeCol(26) => "AA"
+ */
+export declare function encodeCol(col: number): string;
+/**
+ * Decode row string to 0-indexed number
+ * @example decodeRow("1") => 0, decodeRow("10") => 9
+ */
+export declare function decodeRow(rowstr: string): number;
+/**
+ * Encode 0-indexed row number to string
+ * @example encodeRow(0) => "1", encodeRow(9) => "10"
+ */
+export declare function encodeRow(row: number): string;
+/**
+ * Decode cell address string to CellAddress object
+ * @example decodeCell("A1") => {c: 0, r: 0}, decodeCell("B2") => {c: 1, r: 1}
+ */
+export declare function decodeCell(cstr: string): CellAddress;
+/**
+ * Encode CellAddress object to cell address string
+ * @example encodeCell({c: 0, r: 0}) => "A1", encodeCell({c: 1, r: 1}) => "B2"
+ */
+export declare function encodeCell(cell: CellAddress): string;
+/**
+ * Decode range string to Range object
+ * @example decodeRange("A1:B2") => {s: {c: 0, r: 0}, e: {c: 1, r: 1}}
+ */
+export declare function decodeRange(range: string): Range;
+/**
+ * Encode Range object to range string
+ */
+export declare function encodeRange(range: Range): string;
+export declare function encodeRange(start: CellAddress, end: CellAddress): string;
+/** Origin can be cell address string, cell object, row number, or -1 to append */
+export type Origin = string | CellAddress | number;
+export interface JSON2SheetOpts {
+    /** Use specified field order (default Object.keys) */
+    header?: string[];
+    /** Use specified date format in string output */
+    dateFormat?: string;
+    /** Store dates as type d (default is n) */
+    cellDates?: boolean;
+    /** If true, do not include header row in output */
+    skipHeader?: boolean;
+    /** If true, emit #NULL! error cells for null values */
+    nullError?: boolean;
+}
+export interface SheetAddJSONOpts extends JSON2SheetOpts {
+    /** Use specified cell as starting point */
+    origin?: Origin;
+}
+/**
+ * Create a worksheet from an array of objects (xlsx compatible)
+ * @example
+ * const ws = jsonToSheet([{name: "Alice", age: 30}, {name: "Bob", age: 25}])
+ */
+export declare function jsonToSheet(data: JSONRow[], opts?: JSON2SheetOpts): Worksheet;
+/**
+ * Add data from an array of objects to an existing worksheet (xlsx compatible)
+ */
+export declare function sheetAddJson(worksheet: Worksheet, data: JSONRow[], opts?: SheetAddJSONOpts): Worksheet;
+export interface Sheet2JSONOpts {
+    /**
+     * Control output format:
+     * - 1: Generate an array of arrays
+     * - "A": Row object keys are literal column labels (A, B, C, ...)
+     * - string[]: Use specified strings as keys in row objects
+     * - undefined: Read and disambiguate first row as keys
+     */
+    header?: 1 | "A" | string[];
+    /**
+     * Override Range:
+     * - number: Use worksheet range but set starting row to the value
+     * - string: Use specified range (A1-Style bounded range string)
+     * - undefined: Use worksheet range
+     */
+    range?: number | string;
+    /** Use raw values (true, default) or formatted text strings with trim (false) */
+    raw?: boolean;
+    /** Default value for empty cells */
+    defval?: CellValue;
+    /** Include blank lines in the output */
+    blankrows?: boolean;
+    /**
+     * Override format for date values (not applied to time-only formats).
+     * When provided, Date values will be formatted using this format string.
+     * @example "dd/mm/yyyy" or "yyyy-mm-dd"
+     */
+    dateFormat?: string;
+}
+/**
+ * Convert worksheet to JSON array (xlsx compatible)
+ * @example
+ * // Default: array of objects with first row as headers
+ * const data = sheetToJson(worksheet)
+ * // => [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
+ *
+ * // Array of arrays
+ * const aoa = sheetToJson(worksheet, { header: 1 })
+ * // => [["name", "age"], ["Alice", 30], ["Bob", 25]]
+ *
+ * // Column letters as keys
+ * const cols = sheetToJson(worksheet, { header: "A" })
+ * // => [{A: "name", B: "age"}, {A: "Alice", B: 30}]
+ */
+export declare function sheetToJson<T = JSONRow>(worksheet: Worksheet, opts?: Sheet2JSONOpts): T[];
+export interface Sheet2CSVOpts {
+    /** Field separator (default: ",") */
+    FS?: string;
+    /** Record separator (default: "\n") */
+    RS?: string;
+    /** Skip blank rows */
+    blankrows?: boolean;
+    /** Force quote all fields */
+    forceQuotes?: boolean;
+}
+/**
+ * Convert worksheet to CSV string
+ */
+export declare function sheetToCsv(worksheet: Worksheet, opts?: Sheet2CSVOpts): string;
+/**
+ * Create a new workbook
+ */
+export declare function bookNew(): Workbook;
+/**
+ * Append worksheet to workbook (xlsx compatible)
+ * @example
+ * const wb = bookNew();
+ * const ws = jsonToSheet([{a: 1, b: 2}]);
+ * bookAppendSheet(wb, ws, "Sheet1");
+ */
+export declare function bookAppendSheet(workbook: Workbook, worksheet: Worksheet, name?: string): void;
+export interface AOA2SheetOpts {
+    /** Use specified cell as starting point */
+    origin?: Origin;
+    /** Use specified date format in string output */
+    dateFormat?: string;
+    /** Store dates as type d (default is n) */
+    cellDates?: boolean;
+}
+/**
+ * Create a worksheet from an array of arrays (xlsx compatible)
+ * @example
+ * const ws = aoaToSheet([["Name", "Age"], ["Alice", 30], ["Bob", 25]])
+ */
+export declare function aoaToSheet(data: CellValue[][], opts?: AOA2SheetOpts): Worksheet;
+/**
+ * Add data from an array of arrays to an existing worksheet (xlsx compatible)
+ */
+export declare function sheetAddAoa(worksheet: Worksheet, data: CellValue[][], opts?: AOA2SheetOpts): Worksheet;
+/**
+ * Convert worksheet to array of arrays
+ */
+export declare function sheetToAoa(worksheet: Worksheet): CellValue[][];

package/dist/types/modules/excel/utils/stream-buf.d.ts

@@ -0,0 +1,126 @@
+/**
+ * StreamBuf - Cross-Platform Multi-purpose Read-Write Stream
+ *
+ * A unified implementation that works in both Node.js and Browser environments
+ * using the cross-platform EventEmitter from modules/stream.
+ *
+ * Features:
+ * - As MemBuf: write data, then call toBuffer() to consolidate
+ * - As StreamHub: pipe to multiple writable streams
+ * - As readable stream: feed data into writable part and read from it
+ */
+import { EventEmitter } from "../../stream/index";
+import { StringBuf } from "./string-buf";
+type TextEncoding = "utf-8" | "utf8" | BufferEncoding;
+interface StreamBufOptions {
+    bufSize?: number;
+    batch?: boolean;
+}
+/**
+ * StreamBuf is a multi-purpose read-write stream that works in both
+ * Node.js and Browser environments.
+ *
+ * It extends EventEmitter to provide stream-like events:
+ * - 'data': emitted when data is written (flowing mode)
+ * - 'readable': emitted when data is available to read
+ * - 'finish': emitted when end() is called
+ * - 'error': emitted on errors
+ * - 'drain': emitted when buffer drains (after pipe)
+ */
+declare class StreamBuf extends EventEmitter {
+    private bufSize;
+    private buffers;
+    private batch;
+    private corked;
+    private paused;
+    private encoding;
+    private pipes;
+    private _ended;
+    private _writableStream;
+    private _writableStreamWriter;
+    private _asyncWriteQueue;
+    constructor(options?: StreamBufOptions);
+    /**
+     * Returns true if the stream is writable (not ended)
+     * Required for compatibility with Node.js pipe()
+     */
+    get writable(): boolean;
+    /**
+     * Consolidate all buffers into a single Uint8Array
+     */
+    toBuffer(): Uint8Array | null;
+    private _getWritableBuffer;
+    private _pipeChunk;
+    private _writeToBuffers;
+    /**
+     * Write data to the stream
+     */
+    write(data: Uint8Array | string | StringBuf | ArrayBuffer | ArrayBufferView, encoding?: TextEncoding | Function, callback?: Function): Promise<boolean>;
+    /**
+     * Cork the stream - buffer writes until uncork
+     */
+    cork(): void;
+    private _flush;
+    /**
+     * Uncork the stream - flush buffered writes
+     */
+    uncork(): void;
+    /**
+     * End the stream
+     */
+    end(chunk?: any, encoding?: TextEncoding, callback?: Function): void;
+    /**
+     * Read from the stream
+     */
+    read(size?: number): Uint8Array;
+    /**
+     * Read from the stream and return as string.
+     * Cross-platform compatible - works identically in Node.js and Browser.
+     */
+    readString(encoding?: TextEncoding): string;
+    /**
+     * Set encoding for string reads
+     */
+    setEncoding(encoding: string): void;
+    /**
+     * Pause the stream
+     */
+    pause(): void;
+    /**
+     * Resume the stream
+     */
+    resume(): void;
+    /**
+     * Check if stream is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Pipe to a writable stream
+     */
+    pipe<T extends {
+        write: Function;
+        end?: Function;
+    }>(destination: T): T;
+    /**
+     * Pipe to a native WritableStream (browser Streams API).
+     * This properly handles async writes and waits for completion before finish.
+     */
+    pipeTo(writableStream: WritableStream<Uint8Array>): void;
+    /**
+     * Remove a piped destination
+     */
+    unpipe(destination: any): void;
+    /**
+     * Put data back at the front (not implemented)
+     */
+    unshift(): void;
+    /**
+     * Wrap a stream (not implemented)
+     */
+    wrap(): void;
+    /**
+     * Push data to the stream (alias for write)
+     */
+    push(chunk: any): boolean;
+}
+export { StreamBuf };

package/dist/types/modules/excel/utils/string-buf.d.ts

@@ -0,0 +1,29 @@
+/**
+ * StringBuf - Cross-Platform String Buffer
+ *
+ * A way to keep string memory operations to a minimum while building XML strings.
+ * Uses TextEncoder and Uint8Array for cross-platform compatibility (Node.js + Browser).
+ */
+interface StringBufOptions {
+    size?: number;
+    encoding?: string;
+}
+/**
+ * StringBuf - efficient string builder using Uint8Array
+ * Works identically in Node.js and Browser environments.
+ */
+declare class StringBuf {
+    private _buf;
+    private _inPos;
+    private _buffer;
+    constructor(options?: StringBufOptions);
+    get length(): number;
+    get capacity(): number;
+    get buffer(): Uint8Array;
+    toBuffer(): Uint8Array;
+    reset(position?: number): void;
+    private _grow;
+    addText(text: string): void;
+    addStringBuf(inBuf: StringBuf): void;
+}
+export { StringBuf };

package/dist/types/modules/excel/utils/under-dash.d.ts

@@ -0,0 +1,7 @@
+export declare function isEqual(a: any, b: any): boolean;
+export declare function escapeHtml(html: string): string;
+export declare function isUndefined(val: any): val is undefined;
+export declare function isObject(val: any): val is Record<string, any>;
+export declare function deepMerge<T = any>(...args: any[]): T;
+export declare function cloneDeep(obj: any, preserveUndefined?: boolean): any;
+export declare function get<T = any>(obj: any, path: string, defaultValue?: T): T;

package/dist/types/modules/excel/utils/xml-stream.d.ts

@@ -0,0 +1,34 @@
+interface Attributes {
+    [key: string]: any;
+}
+declare class XmlStream {
+    private _xml;
+    private _chunks;
+    private _stack;
+    private _rollbacks;
+    leaf?: boolean;
+    open?: boolean;
+    constructor();
+    private _consolidate;
+    get tos(): string | undefined;
+    get cursor(): number;
+    openXml(docAttributes?: Attributes): void;
+    openNode(name: string, attributes?: Attributes): void;
+    addAttribute(name: string, value: any): void;
+    addAttributes(attrs: Attributes): void;
+    writeText(text: any): void;
+    writeXml(xml: string): void;
+    closeNode(): void;
+    leafNode(name: string, attributes?: Attributes, text?: any): void;
+    closeAll(): void;
+    addRollback(): number;
+    commit(): void;
+    rollback(): void;
+    get xml(): string;
+    static StdDocAttributes: {
+        version: string;
+        encoding: string;
+        standalone: string;
+    };
+}
+export { XmlStream };