@worksheet-js/excel 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+# END USER LICENSE AGREEMENT (EULA)
+
+**Product:** @worksheet-js/excel
+**Copyright:** (c) 2024-present Worksheet Systems <support@worksheet.js>
+**All Rights Reserved.**
+
+IMPORTANT: PLEASE READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THE SOFTWARE.
+
+### 1. PROPRIETARY RIGHTS
+
+The @worksheet-js/excel spreadsheet import/export engine ("Software") is a proprietary product of Worksheet Systems and is protected by copyright laws and international treaty provisions. All intellectual property rights in and to the Software are and shall remain the exclusive property of Worksheet Systems.
+
+### 2. GRANT OF LICENSE
+
+Subject to the terms and conditions of this Agreement and any applicable commercial terms, Worksheet Systems grants you a non-exclusive, non-transferable license to use the Software solely for your internal business purposes or as expressly permitted in a separate written agreement.
+
+### 3. RESTRICTIONS
+
+You shall not, and shall not permit any third party to:
+
+- Copy, modify, or create derivative works of the Software.
+- Reverse engineer, decompile, or disassemble the Software, or otherwise attempt to derive the source code, except to the extent such restriction is expressly prohibited by applicable law.
+- Sublicense, rent, lease, or lend the Software to any third party.
+- Remove or alter any copyright, trademark, or other proprietary notices contained in the Software.
+
+### 4. CONFIDENTIALITY
+
+The Software, including its structure, organization, and source code, constitutes valuable trade secrets and confidential information of Worksheet Systems. You agree to hold such information in strict confidence and not to disclose it to any third party.
+
+### 5. TERMINATION
+
+This license is effective until terminated. Your rights under this License will terminate automatically without notice if you fail to comply with any term(s) of this Agreement. Upon termination, you shall cease all use of the Software and destroy all copies in your possession.
+
+### 6. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+### 7. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL WORKSHEET SYSTEMS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE.
+
+### 8. GOVERNING LAW
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which Worksheet Systems is established, without regard to its conflict of law principles.

package/README.md

@@ -0,0 +1,78 @@
+# @worksheet-js/excel
+
+**High-performance spreadsheet I/O engine for XLSX, CSV, JSON, and HTML.**
+
+`@worksheet-js/excel` is an industrial-grade engine dedicated to importing and exporting spreadsheet data. It handles complex OpenXML parsing for XLSX files and provides simple utilities for common text-based formats.
+
+## ✨ Key Features
+
+- **XLSX Mastery**: Native support for large XLSX files using an optimized OpenXML reader.
+- **Style Preservation**: Extracts and preserves fonts, fills, borders, and number formats.
+- **Multi-Format Support**: Simplified I/O for CSV, TSV, JSON, and HTML tables.
+- **Advanced Extraction**: Handles merged cells, conditional formatting rules, and hyperlinks.
+- **Browser & Node.js**: Works seamlessly in both client-side and server-side environments.
+
+## ✨ Advanced Features
+
+### 🎨 High-Fidelity Style Extraction
+
+Unlike basic parsers, `@worksheet-js/excel` extracts complex styling metadata, including:
+
+- **Number Formats**: Currency, percentage, scientific, and custom accounting formats.
+- **Borders**: Per-side border styles (solid, dashed, double) and colors.
+- **Alignment**: Horizontal and vertical alignment, including text wrapping and indentations.
+
+### 🚀 Large File Optimization
+
+The engine uses a streaming-like OpenXML parser to handle workbooks with 100,000+ rows while maintaining a low memory footprint.
+
+## 📦 Installation
+
+```bash
+pnpm add @worksheet-js/excel
+```
+
+## 🚀 Usage
+
+### Loading a Workbook
+
+```typescript
+import { WorkbookLoader } from '@worksheet-js/excel';
+
+// Load from a browser File or ArrayBuffer
+const { result, meta } = await WorkbookLoader.loadFromBuffer(xlsxArrayBuffer);
+
+console.log(
+  'Sheet Names:',
+  result.workbook.sheets.map((s) => s.name)
+);
+```
+
+### Exporting a Workbook
+
+```typescript
+import { WorkbookExporter } from '@worksheet-js/excel';
+
+// Trigger a browser download of the current spreadsheet state
+await WorkbookExporter.download(spreadsheetInstance, 'xlsx', 'report.xlsx');
+```
+
+## 🛠️ API Reference
+
+### `WorkbookLoader` (Static Methods)
+
+- `loadFromBuffer(buffer: Uint8Array): Promise<{ result, meta }>`: The primary method for loading XLSX files.
+- `loadFromCsvBuffer(buffer: Uint8Array | string, options?: CsvOptions)`: Parses CSV data.
+- `loadFromJsonBuffer(buffer: Uint8Array | string, options?: JsonOptions)`: Parses structured JSON.
+- `loadFromHtmlBuffer(buffer: Uint8Array | string, options?: HtmlOptions)`: Extracts data from `<table>` elements.
+
+### `WorkbookExporter` (Static Methods)
+
+- `exportToBuffer(spreadsheet: Spreadsheet): Promise<Uint8Array>`: Generates an XLSX binary buffer.
+- `exportToCsv(spreadsheet: Spreadsheet, sheetIndex?: number): string`: Generates a CSV string.
+- `download(spreadsheet: Spreadsheet, format: 'xlsx' | 'csv', filename?: string)`: Triggers a browser-initiated file download.
+
+## 📄 License
+
+Copyright (c) 2024-present Worksheet Systems. All rights reserved.
+Proprietary software. Usage is subject to the [EULA](LICENSE) terms.

package/dist/index.d.mts

@@ -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 };