@worksheet-js/excel 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+interface ParserResult {
+    workbook: WorkbookData;
+    warnings?: string[];
+}
+interface WorkbookData {
+    sheets: SheetData[];
+    activeSheetIndex: number;
+}
+/** Visual style properties for a cell */
+interface CellStyle {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    fillColor?: string;
+    align?: 'left' | 'center' | 'right';
+    valign?: 'top' | 'middle' | 'bottom';
+    wrap?: 'overflow' | 'wrap' | 'clip';
+    numberFormat?: string;
+    decimals?: number;
+    borderTop?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    borderRight?: boolean;
+    borderStyle?: string;
+    borderColor?: string;
+    borderWeight?: number;
+    borderTopColor?: string;
+    borderTopStyle?: string;
+    borderTopWeight?: number;
+    borderBottomColor?: string;
+    borderBottomStyle?: string;
+    borderBottomWeight?: number;
+    borderLeftColor?: string;
+    borderLeftStyle?: string;
+    borderLeftWeight?: number;
+    borderRightColor?: string;
+    borderRightStyle?: string;
+    borderRightWeight?: number;
+    currencyCode?: string;
+    direction?: 'ltr' | 'rtl';
+}
+interface SheetData {
+    id: string;
+    name: string;
+    state: 'visible' | 'hidden' | 'veryHidden';
+    cells: Record<string, CellData>;
+    merges: MergeData[];
+    columnWidths: Record<number, number>;
+    rowHeights: Record<number, number>;
+    hiddenColumns?: number[];
+    hiddenRows?: number[];
+    defaultColWidth?: number;
+    defaultRowHeight?: number;
+    images?: ImageData[];
+    hyperlinks?: HyperlinkData[];
+    dataValidations?: DataValidationData[];
+    conditionalFormatting?: ConditionalFormattingData[];
+    autoFilter?: AutoFilterData;
+    pivotTables?: any[];
+}
+interface AutoFilterData {
+    ref: string;
+}
+interface CsvOptions {
+    delimiter?: string;
+    quoteChar?: string;
+    worksheetName?: string;
+}
+interface JsonOptions {
+    worksheetName?: string;
+}
+interface HtmlOptions {
+    worksheetName?: string;
+}
+interface CellData {
+    value: any;
+    formula?: string;
+    style?: ParsedStyle;
+    type: CellType;
+    note?: string;
+    comments?: any[];
+}
+type CellType = 'string' | 'number' | 'boolean' | 'error' | 'date' | 'empty';
+interface MergeData {
+    ref: string;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+interface ImageData {
+    id: string;
+    name: string;
+    buffer: Uint8Array;
+    extension: string;
+    anchor: {
+        type: 'oneCell' | 'twoCell' | 'absolute';
+        from?: AnchorMarker;
+        to?: AnchorMarker;
+        ext?: {
+            cx: number;
+            cy: number;
+        };
+        pos?: {
+            x: number;
+            y: number;
+        };
+    };
+}
+interface AnchorMarker {
+    col: number;
+    colOff: number;
+    row: number;
+    rowOff: number;
+}
+interface HyperlinkData {
+    ref: string;
+    target?: string;
+    location?: string;
+    display?: string;
+    tooltip?: string;
+}
+interface DataValidationData {
+    sqref: string;
+    type: string;
+    allowBlank: boolean;
+    showInputMessage: boolean;
+    showErrorMessage: boolean;
+    promptTitle?: string;
+    prompt?: string;
+    errorTitle?: string;
+    error?: string;
+    formula1?: string;
+    formula2?: string;
+}
+interface ConditionalFormattingData {
+    sqref: string;
+    rules: CFRuleData[];
+}
+interface CFRuleData {
+    type: string;
+    priority: number;
+    operator?: string;
+    text?: string;
+    formula?: string[];
+    style?: ParsedStyle;
+}
+interface ParsedStyle {
+    font?: {
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean;
+        strike?: boolean;
+        size?: number;
+        color?: string;
+        name?: string;
+    };
+    fill?: {
+        patternType?: string;
+        fgColor?: string;
+        bgColor?: string;
+    };
+    border?: {
+        left?: BorderStyle;
+        right?: BorderStyle;
+        top?: BorderStyle;
+        bottom?: BorderStyle;
+        diagonal?: BorderStyle & {
+            up?: boolean;
+            down?: boolean;
+        };
+    };
+    alignment?: {
+        horizontal?: 'left' | 'center' | 'right' | 'justify' | 'centerContinuous';
+        vertical?: 'top' | 'center' | 'bottom' | 'justify';
+        wrapText?: boolean;
+    };
+    numberFormat?: {
+        id: number;
+        formatCode: string;
+    };
+}
+interface BorderStyle {
+    style?: string;
+    color?: string;
+}
+interface Spreadsheet {
+    worksheets: any[];
+    current?: any;
+}
+interface SheetMeta {
+    worksheetName: string;
+    tabColor?: string;
+    hidden?: boolean;
+    minDimensions?: [number, number];
+    defaultColWidth?: number;
+    defaultRowHeight?: number;
+    minColWidth?: number;
+    minRowHeight?: number;
+    hiddenColumns?: number[];
+    hiddenRows?: number[];
+    frozenRows?: number;
+    frozenCols?: number;
+    direction?: 'ltr' | 'rtl';
+}
+
+/**
+ * @worksheet-js/excel - High-performance spreadsheet I/O engine
+ * (c) 2024-present Worksheet Systems <support@worksheet.js>
+ * All Rights Reserved.
+ *
+ * PROPRIETARY AND CONFIDENTIAL: Unauthorized copying of this file,
+ * via any medium is strictly prohibited.
+ */
+
+/**
+ * WorkbookExporter — Orchestrates exporting Spreadsheet state to .xlsx and .csv files.
+ */
+declare class WorkbookExporter {
+    /**
+     * Generates a binary XLSX buffer for the entire workbook.
+     *
+     * @param spreadsheet - The spreadsheet engine instance to export.
+     * @returns A promise resolving to the binary content of the .xlsx file.
+     */
+    static exportToBuffer(spreadsheet: Spreadsheet): Promise<Uint8Array>;
+    /**
+     * Generates a CSV string for a specific worksheet.
+     *
+     * @param spreadsheet - The spreadsheet engine instance.
+     * @param sheetIndex - The zero-based index of the sheet to export (default: 0).
+     */
+    static exportToCsv(spreadsheet: Spreadsheet, sheetIndex?: number): string;
+    /**
+     * Triggers a browser-initiated download of the spreadsheet data.
+     *
+     * @param spreadsheet - The spreadsheet engine instance.
+     * @param format - The target file format ('xlsx' or 'csv').
+     * @param filename - Optional custom filename.
+     */
+    static download(spreadsheet: Spreadsheet, format?: 'xlsx' | 'csv', filename?: string): Promise<void>;
+    private static _triggerDownload;
+    private static strToUint8;
+    private static getContentTypes;
+    private static getRootRels;
+    private static getWorkbookRels;
+}
+
+/**
+ * @worksheet-js/excel - High-performance spreadsheet I/O engine
+ * (c) 2024-present Worksheet Systems <support@worksheet.js>
+ * All Rights Reserved.
+ *
+ * PROPRIETARY AND CONFIDENTIAL: Unauthorized copying of this file,
+ * via any medium is strictly prohibited.
+ */
+
+declare class WorkbookLoader {
+    /**
+     * Parses an XLSX file from a binary buffer.
+     *
+     * @param buffer - The binary data of the XLSX file (e.g., from a File object).
+     * @returns A promise resolving to the parsed workbook data and suggested sheet metadata.
+     */
+    static loadFromBuffer(buffer: Uint8Array): Promise<{
+        result: ParserResult;
+        meta: SheetMeta[];
+    }>;
+    /**
+     * Parses a CSV file from a buffer or string.
+     *
+     * @param buffer - The CSV data.
+     * @param options - CSV parsing configuration (delimiter, etc.).
+     */
+    static loadFromCsvBuffer(buffer: Uint8Array | string, options?: CsvOptions): {
+        result: ParserResult;
+        meta: SheetMeta[];
+    };
+    /**
+     * Parses a TSV (Tab-Separated Values) file.
+     */
+    static loadFromTsvBuffer(buffer: Uint8Array | string, options?: Omit<CsvOptions, 'delimiter'>): {
+        result: ParserResult;
+        meta: SheetMeta[];
+    };
+    /**
+     * Parses a JSON data structure representing a spreadsheet.
+     */
+    static loadFromJsonBuffer(buffer: Uint8Array | string, options?: JsonOptions): {
+        result: ParserResult;
+        meta: SheetMeta[];
+    };
+    /**
+     * Extracts data from HTML `<table>` elements.
+     */
+    static loadFromHtmlBuffer(buffer: Uint8Array | string, options?: HtmlOptions): {
+        result: ParserResult;
+        meta: SheetMeta[];
+    };
+    private static createMetaFromResult;
+    private static parseAddress;
+}
+
+/**
+ * Parses a raw XLSX buffer completely into a unified internal DOM representation.
+ *
+ * @param buffer - The contents of the .xlsx file
+ * @returns Parsed structured DOM for Worksheet Systems models
+ */
+declare function parseXlsx(buffer: Uint8Array): Promise<ParserResult>;
+
+interface IUnzipper {
+    getFile(path: string): Promise<Uint8Array | null>;
+    getFileAsString(path: string): Promise<string | null>;
+    getFilesPrefix(prefix: string): Promise<Record<string, Uint8Array>>;
+    close(): void;
+}
+
+declare class SyncUnzipper implements IUnzipper {
+    private files;
+    constructor(buffer: Uint8Array);
+    getFile(path: string): Promise<Uint8Array | null>;
+    getFileAsString(path: string): Promise<string | null>;
+    getFilesPrefix(prefix: string): Promise<Record<string, Uint8Array>>;
+    close(): void;
+}
+
+/**
+ * Converts an Excel serial date to a JavaScript Date object.
+ * Excel stores dates as the number of days since Jan 1, 1900.
+ * It also incorrectly considers 1900 a leap year, adding an extra day (Feb 29, 1900).
+ *
+ * @param serial - The Excel serial date number
+ * @returns The converted JavaScript Date object
+ */
+declare function excelDateToJSDate(serial: number): Date;
+/**
+ * Checks if a given number format code likely represents a date/time.
+ *
+ * @param formatCode The numberFormat code string
+ */
+declare function isDateFormat(formatCode?: string): boolean;
+
+/**
+ * Parses a CSV buffer or string into a standard ParserResult.
+ * Complies with RFC-4180 (handles newlines inside quoted fields).
+ */
+declare function parseCsv(bufferOrString: Uint8Array | string, options?: CsvOptions): ParserResult;
+
+/**
+ * Parses an HTML buffer or string (looking for <table> tags) into a standard ParserResult.
+
+ * Best effort extraction of text content and basic layout from tr/td tags.
+ */
+declare function parseHtml(bufferOrString: Uint8Array | string, options?: HtmlOptions): ParserResult;
+
+/**
+ * Parses a JSON buffer or string into a standard ParserResult.
+
+ * Supports:
+ *  - Array of Arrays: `[["Header1", "Header2"], [1, 2]]`
+ *  - Array of Objects: `[{"Name": "Alice", "Age": 30}, {"Name": "Bob", "Age": 25}]`
+ */
+declare function parseJson(bufferOrString: Uint8Array | string, options?: JsonOptions): ParserResult;
+
+declare class ParserError extends Error {
+    readonly context?: Record<string, any> | undefined;
+    constructor(message: string, context?: Record<string, any> | undefined);
+}
+
+/**
+ * Parses a TSV or TXT buffer/string into a standard ParserResult.
+ * This is a thin wrapper over the Csv parser, defaulting the delimiter to a tab (\t).
+ */
+declare function parseTsv(bufferOrString: Uint8Array | string, options?: Omit<CsvOptions, 'delimiter'>): ParserResult;
+
+/**
+ * XmlWriter — Helper to generate OpenXML compliant XML strings.
+ * Minimal implementation for XLSX exporting.
+ */
+declare class XmlWriter {
+    static escape(str: string): string;
+    static workbook(sheetNames: string[], activeSheetIndex?: number, sheetStates?: string[]): string;
+    static worksheet(rows: Array<Array<{
+        v: any;
+        f?: string;
+    } | null | undefined>>, options?: {
+        merges?: Array<{
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        }>;
+        cols?: Map<number, number>;
+        rowHeights?: Map<number, number>;
+        hiddenCols?: Set<number>;
+        hiddenRows?: Set<number>;
+        frozenRows?: number;
+        frozenCols?: number;
+        tabColor?: string;
+        defaultColWidth?: number;
+        defaultRowHeight?: number;
+        defaultWidth?: number;
+        defaultHeight?: number;
+        styles?: Map<string, number>;
+        autoFilter?: string;
+        dataValidations?: any[];
+        hyperlinks?: any[];
+        conditionalFormatting?: any[];
+        drawingId?: string;
+        rightToLeft?: boolean;
+    }): string;
+    static coordsToAddr(x: number, y: number): string;
+    static coreProps(title?: string): string;
+    static appProps(): string;
+    static drawings(images: any[]): string;
+}
+
+export { type AnchorMarker, type AutoFilterData, type BorderStyle, type CFRuleData, type CellData, type CellStyle, type CellType, type ConditionalFormattingData, type CsvOptions, type DataValidationData, type HtmlOptions, type HyperlinkData, type ImageData, type JsonOptions, type MergeData, type ParsedStyle, ParserError, type ParserResult, type SheetData, type SheetMeta, type Spreadsheet, SyncUnzipper, type WorkbookData, WorkbookExporter, WorkbookLoader, XmlWriter, excelDateToJSDate, isDateFormat, parseCsv, parseHtml, parseJson, parseTsv, parseXlsx };