@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/integration/calculate-formulas.js

@@ -0,0 +1,68 @@
+/**
+ * Formula Calculation Engine
+ *
+ * Provides `calculateFormulas()` as the primary function-style entry
+ * point. The same work runs when a host calls
+ * `Workbook.calculateFormulas()` — both paths dispatch through the
+ * engine registered via `installFormulaEngine()`.
+ *
+ * ## Architecture
+ *
+ * 1. **Snapshot** — immutable capture of all workbook state
+ * 2. **Normalize** — uniform FormulaInstance objects
+ * 3. **Parse** — tokenize → AST
+ * 4. **Compile** — bind AST → BoundExpr (resolve names, structured refs, sheets)
+ * 5. **Dependency Analysis** — topological sort
+ * 6. **Evaluate** — execute BoundExpr with RuntimeValue system
+ * 7. **Materialize** — build declarative WritebackPlan
+ * 8. **Apply** — write plan to live workbook
+ */
+import { calculateFormulasImpl } from "./calculate-formulas-impl.js";
+/**
+ * Recalculate all formula cells in a workbook.
+ *
+ * Evaluates every formula cell using the built-in calculation engine
+ * and updates each cell's `result` value. Formulas are evaluated lazily
+ * with recursive dependency resolution, memoization, and circular
+ * reference detection.
+ *
+ * All evaluation state is scoped to this invocation — concurrent calls
+ * for different workbooks are safe.
+ *
+ * **Supported formula features:**
+ * - Cell references: `A1`, `$B$2`, `Sheet1!A1`, `'Sheet Name'!A1:B10`
+ * - Operators: `+ - * / ^`, `& (concat)`, `= <> < > <= >=`, `%`
+ * - 433 built-in functions across math, text, logical, date, lookup,
+ *   statistical, financial, dynamic-array, database and engineering
+ *   categories.
+ * - Shared formulas, array constants, nested expressions
+ * - Dynamic array spill: FILTER, SORT, UNIQUE, SORTBY results are
+ *   written to adjacent cells. #SPILL! error if target cells are occupied.
+ * - CSE array formulas: `{=formula}` with a ref range distribute results
+ *   across the designated range.
+ * - Array arithmetic broadcasting: `{1,2,3} + {4;5;6}` produces a 3x3 matrix.
+ * - Implicit intersection: range references in scalar context pick the
+ *   value from the formula cell's row or column.
+ *
+ * **Unsupported formula behavior:**
+ * - If a formula uses a function the engine does not implement, the engine
+ *   returns `#NAME?`. However, if the cell already has a cached result
+ *   (e.g., pre-computed by Excel when the XLSX was saved), that cached
+ *   result is **preserved** — the engine will not overwrite usable data.
+ * - If no cached result exists, the cell's result becomes `#NAME?`.
+ *
+ * **Volatile functions:**
+ * - `RAND`, `RANDBETWEEN`, `NOW`, `TODAY` are re-evaluated on every call.
+ *   This is intentional — these functions are expected to produce fresh values.
+ *
+ * **Side effects:**
+ * - This function **mutates** the workbook by updating formula cells' `result`
+ *   property in-place. For dynamic array formulas, adjacent cells are also
+ *   written with spill results. If you need the original cached results
+ *   preserved, clone the workbook before calling this function.
+ *
+ * @param workbook - The workbook whose formulas should be recalculated
+ */
+export function calculateFormulas(workbook) {
+    calculateFormulasImpl(workbook);
+}

package/dist/browser/modules/formula/integration/formula-instance.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Formula Instance — Unified model for all formula cell variants.
+ *
+ * The normalizer converts the heterogeneous formula representations found
+ * in the snapshot (normal, shared-master, shared-slave, CSE, dynamic-array)
+ * into a uniform `FormulaInstance` structure. After normalization, the
+ * compile and runtime layers do not need to know how a formula originated.
+ *
+ * ## Invariants
+ *
+ * - Every `FormulaInstance` has a non-empty `sourceText` (the formula to parse).
+ * - Shared-slave formulas have already been translated (offset applied) by
+ *   the snapshot builder, so `sourceText` is the final formula text.
+ * - `kind` is preserved so the materialize layer can determine the correct
+ *   writeback strategy (scalar vs. CSE vs. spill).
+ */
+import type { FormulaCellKind, WorkbookSnapshot } from "./workbook-snapshot.js";
+/**
+ * A normalized, engine-internal representation of a formula cell.
+ * This is the unit of work that enters the compile → evaluate pipeline.
+ */
+export interface FormulaInstance {
+    /** The worksheet name this formula belongs to. */
+    readonly sheetName: string;
+    /** The worksheet id (stable across renames). */
+    readonly sheetId: number;
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+    /** The final formula text to parse and evaluate. */
+    readonly sourceText: string;
+    /**
+     * The formula classification.
+     * - `"normal"` — standard scalar formula
+     * - `"shared-master"` — master of a shared formula group (treated as normal for eval)
+     * - `"shared-slave"` — slave with translated formula (treated as normal for eval)
+     * - `"cse"` — legacy CSE array formula; result distributed across `targetRef`
+     * - `"dynamic-array"` — dynamic array formula; result spills to adjacent cells
+     */
+    readonly kind: FormulaCellKind;
+    /**
+     * For CSE formulas: the target range in "A1:B2" format.
+     * For dynamic-array formulas: `undefined` (spill range is computed at runtime).
+     * For all other kinds: `undefined`.
+     */
+    readonly targetRef?: string;
+    /**
+     * Whether this formula was explicitly flagged as a dynamic array formula
+     * (from the XLSX `isDynamicArray` attribute).
+     */
+    readonly isDynamicArray: boolean;
+}
+/**
+ * Collect all formula instances from a workbook snapshot.
+ *
+ * Iterates every cell in every worksheet, selects cells with formulas,
+ * and normalizes them into `FormulaInstance` objects. The result is a
+ * flat list ordered by worksheet order then cell position.
+ *
+ * This replaces the old `collectFormulaCells()` function but operates
+ * entirely on snapshot data — no live workbook objects are touched.
+ */
+export declare function collectFormulaInstances(snapshot: WorkbookSnapshot): FormulaInstance[];

package/dist/browser/modules/formula/integration/formula-instance.js

@@ -0,0 +1,79 @@
+/**
+ * Formula Instance — Unified model for all formula cell variants.
+ *
+ * The normalizer converts the heterogeneous formula representations found
+ * in the snapshot (normal, shared-master, shared-slave, CSE, dynamic-array)
+ * into a uniform `FormulaInstance` structure. After normalization, the
+ * compile and runtime layers do not need to know how a formula originated.
+ *
+ * ## Invariants
+ *
+ * - Every `FormulaInstance` has a non-empty `sourceText` (the formula to parse).
+ * - Shared-slave formulas have already been translated (offset applied) by
+ *   the snapshot builder, so `sourceText` is the final formula text.
+ * - `kind` is preserved so the materialize layer can determine the correct
+ *   writeback strategy (scalar vs. CSE vs. spill).
+ */
+// ============================================================================
+// Normalizer
+// ============================================================================
+/**
+ * Collect all formula instances from a workbook snapshot.
+ *
+ * Iterates every cell in every worksheet, selects cells with formulas,
+ * and normalizes them into `FormulaInstance` objects. The result is a
+ * flat list ordered by worksheet order then cell position.
+ *
+ * This replaces the old `collectFormulaCells()` function but operates
+ * entirely on snapshot data — no live workbook objects are touched.
+ */
+export function collectFormulaInstances(snapshot) {
+    const instances = [];
+    for (const ws of snapshot.worksheets) {
+        collectFromWorksheet(ws, instances);
+    }
+    return instances;
+}
+/**
+ * Collect formula instances from a single worksheet snapshot.
+ */
+function collectFromWorksheet(ws, out) {
+    for (const cell of ws.cells.values()) {
+        if (cell.formulaKind === "none") {
+            continue;
+        }
+        if (!cell.formula) {
+            continue;
+        }
+        const instance = normalizeCell(ws, cell);
+        if (instance) {
+            out.push(instance);
+        }
+    }
+}
+/**
+ * Normalize a single cell snapshot into a FormulaInstance.
+ *
+ * This is where the different formula types are unified:
+ * - Normal formulas pass through directly.
+ * - Shared-master and shared-slave formulas are both treated as normal
+ *   for evaluation purposes (the slave's formula text is already translated).
+ * - CSE formulas carry their target ref for the materialize layer.
+ * - Dynamic-array formulas are flagged for spill handling.
+ */
+function normalizeCell(ws, cell) {
+    const formula = cell.formula;
+    if (!formula) {
+        return null;
+    }
+    return {
+        sheetName: ws.name,
+        sheetId: ws.id,
+        row: cell.row,
+        col: cell.col,
+        sourceText: formula,
+        kind: cell.formulaKind,
+        targetRef: cell.ref,
+        isDynamicArray: cell.isDynamicArray ?? false
+    };
+}

package/dist/browser/modules/formula/integration/workbook-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workbook Adapter — Bridge between a host workbook (implementing the
+ * `WorkbookLike` / `WorksheetLike` / `CellLike` interfaces) and the
+ * engine's snapshot representation.
+ *
+ * This is the only file in the engine pipeline that walks a live host
+ * workbook; the rest of the pipeline consumes the immutable
+ * `WorkbookSnapshot` this file produces.
+ *
+ * ## Responsibilities
+ *
+ * 1. `buildWorkbookSnapshot()` — walk the host workbook and produce an
+ *    immutable `WorkbookSnapshot`.
+ * 2. Cell value conversion — Date → serial number, rich text → string,
+ *    shared formula translation, etc.
+ */
+import type { WorkbookLike } from "../materialize/types.js";
+import type { WorkbookSnapshot } from "./workbook-snapshot.js";
+/**
+ * Build a complete `WorkbookSnapshot` from a live workbook.
+ *
+ * This traverses all worksheets and cells once, converting everything to
+ * engine-internal snapshot types. The result is a fully self-contained,
+ * read-only data structure.
+ */
+export declare function buildWorkbookSnapshot(workbook: WorkbookLike): WorkbookSnapshot;

package/dist/browser/modules/formula/integration/workbook-adapter.js

@@ -0,0 +1,324 @@
+/**
+ * Workbook Adapter — Bridge between a host workbook (implementing the
+ * `WorkbookLike` / `WorksheetLike` / `CellLike` interfaces) and the
+ * engine's snapshot representation.
+ *
+ * This is the only file in the engine pipeline that walks a live host
+ * workbook; the rest of the pipeline consumes the immutable
+ * `WorkbookSnapshot` this file produces.
+ *
+ * ## Responsibilities
+ *
+ * 1. `buildWorkbookSnapshot()` — walk the host workbook and produce an
+ *    immutable `WorkbookSnapshot`.
+ * 2. Cell value conversion — Date → serial number, rich text → string,
+ *    shared formula translation, etc.
+ */
+import { dateToExcel } from "../../../utils/utils.base.js";
+import { CellValueTypeLike } from "../materialize/types.js";
+import { snapshotCellKey, scopedNameKey } from "./workbook-snapshot.js";
+// ============================================================================
+// Build Workbook Snapshot
+// ============================================================================
+/**
+ * Build a complete `WorkbookSnapshot` from a live workbook.
+ *
+ * This traverses all worksheets and cells once, converting everything to
+ * engine-internal snapshot types. The result is a fully self-contained,
+ * read-only data structure.
+ */
+export function buildWorkbookSnapshot(workbook) {
+    const worksheets = [];
+    const worksheetsByName = new Map();
+    const worksheetsById = new Map();
+    const date1904 = workbook.properties?.date1904 ?? false;
+    for (const ws of workbook.worksheets) {
+        const wsSnapshot = buildWorksheetSnapshot(ws, date1904);
+        worksheets.push(wsSnapshot);
+        worksheetsByName.set(ws.name.toLowerCase(), wsSnapshot);
+        worksheetsById.set(ws.id, wsSnapshot);
+    }
+    const definedNames = buildDefinedNames(workbook);
+    // Build table-by-name index for O(1) lookup
+    const tablesByName = new Map();
+    for (const wsSnapshot of worksheets) {
+        for (const table of wsSnapshot.tables) {
+            if (table.name) {
+                tablesByName.set(table.name.toLowerCase(), {
+                    table,
+                    sheetName: wsSnapshot.name
+                });
+            }
+        }
+    }
+    const calcProperties = {
+        fullCalcOnLoad: workbook.calcProperties?.fullCalcOnLoad,
+        iterate: workbook.calcProperties?.iterate,
+        iterateCount: workbook.calcProperties?.iterateCount,
+        iterateDelta: workbook.calcProperties?.iterateDelta
+    };
+    const properties = {
+        date1904
+    };
+    return {
+        worksheets,
+        worksheetsByName,
+        worksheetsById,
+        definedNames,
+        tablesByName,
+        calcProperties,
+        properties
+    };
+}
+// ============================================================================
+// Build Worksheet Snapshot
+// ============================================================================
+function buildWorksheetSnapshot(ws, date1904) {
+    const cells = new Map();
+    const hiddenRows = new Set();
+    // Use includeEmpty so we observe the `hidden` flag on rows that have
+    // no populated cells — a user may hide an empty row (e.g. filter UI)
+    // and SUBTOTAL(1xx,…) still needs to treat that row as hidden.
+    ws.eachRow({ includeEmpty: true }, (row, rowNumber) => {
+        if (row.hidden) {
+            hiddenRows.add(rowNumber);
+        }
+        row.eachCell((cell, colNumber) => {
+            const cellSnapshot = buildCellSnapshot(cell, rowNumber, colNumber, date1904);
+            if (cellSnapshot) {
+                cells.set(snapshotCellKey(rowNumber, colNumber), cellSnapshot);
+            }
+        });
+    });
+    const dims = ws.dimensions;
+    const dimensions = dims
+        ? { top: dims.top, left: dims.left, bottom: dims.bottom, right: dims.right }
+        : null;
+    const tables = buildTables(ws);
+    return {
+        id: ws.id,
+        name: ws.name,
+        dimensions,
+        cells,
+        hiddenRows,
+        tables
+    };
+}
+// ============================================================================
+// Build Cell Snapshot
+// ============================================================================
+function buildCellSnapshot(cell, row, col, date1904) {
+    const cellType = cell.type;
+    // Skip truly empty cells
+    if (cellType === CellValueTypeLike.Null) {
+        return null;
+    }
+    // ── Formula cells ──
+    if (cellType === CellValueTypeLike.Formula) {
+        return buildFormulaCellSnapshot(cell, row, col, date1904);
+    }
+    // ── Non-formula cells ──
+    const value = convertCellValue(cell.value, date1904);
+    return {
+        row,
+        col,
+        value,
+        formulaKind: "none"
+    };
+}
+function buildFormulaCellSnapshot(cell, row, col, date1904) {
+    const model = cell.model;
+    const formula = cell.formula; // triggers shared formula translation for slaves
+    if (formula == null) {
+        // Formula cell with no parseable formula — capture the cached result
+        const cachedResult = convertFormulaResult(cell.result, date1904);
+        return {
+            row,
+            col,
+            value: cachedResult,
+            formulaKind: "none",
+            cachedResult
+        };
+    }
+    // Determine formula kind
+    const kind = classifyFormulaKind(model);
+    // Capture the cached result from the XLSX
+    const cachedResult = convertFormulaResult(cell.result, date1904);
+    return {
+        row,
+        col,
+        value: cachedResult,
+        formulaKind: kind,
+        formula,
+        ref: model.ref,
+        isDynamicArray: model.isDynamicArray ?? undefined,
+        cachedResult
+    };
+}
+/**
+ * Classify a formula cell's kind based on its model properties.
+ */
+function classifyFormulaKind(model) {
+    if (model.isDynamicArray) {
+        return "dynamic-array";
+    }
+    if (model.shareType === "array" && model.ref) {
+        return "cse";
+    }
+    if (model.shareType === "shared") {
+        // shared-master has formula + ref, shared-slave has sharedFormula
+        if (model.formula && model.ref) {
+            return "shared-master";
+        }
+        if (model.sharedFormula) {
+            return "shared-slave";
+        }
+    }
+    return "normal";
+}
+// ============================================================================
+// Value Conversion
+// ============================================================================
+/**
+ * Convert a live cell value to a snapshot value.
+ * - Dates → Excel serial number
+ * - Rich text → plain string
+ * - Errors → SnapshotErrorValue
+ * - All other types pass through
+ */
+function convertCellValue(value, date1904) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (value instanceof Date) {
+        return dateToExcel(value, date1904);
+    }
+    if (typeof value === "object" && "error" in value) {
+        // Gate the error code through the known set so user-supplied values
+        // like `{ error: "anything" }` can't pollute the snapshot. Unknown
+        // strings fall back to #VALUE! — matches Excel's default diagnostic
+        // when it reads an unrecognised error value from a persisted file.
+        const raw = value.error;
+        const KNOWN_ERRORS = new Set([
+            "#N/A",
+            "#NULL!",
+            "#DIV/0!",
+            "#VALUE!",
+            "#REF!",
+            "#NAME?",
+            "#NUM!",
+            "#GETTING_DATA",
+            "#CALC!",
+            "#SPILL!",
+            "#CONNECT!",
+            "#BLOCKED!",
+            "#UNKNOWN!",
+            "#FIELD!",
+            "#BUSY!"
+        ]);
+        const code = KNOWN_ERRORS.has(raw) ? raw : "#VALUE!";
+        return { error: code };
+    }
+    // Rich text → plain string
+    if (typeof value === "object" && "richText" in value) {
+        return (value.richText || []).map(r => r.text).join("");
+    }
+    // Hyperlink / other objects with text
+    if (typeof value === "object" && "text" in value) {
+        return value.text;
+    }
+    return null;
+}
+/**
+ * Convert a formula result to a snapshot value.
+ */
+function convertFormulaResult(result, date1904) {
+    if (result === undefined || result === null) {
+        return null;
+    }
+    return convertCellValue(result, date1904);
+}
+// ============================================================================
+// Build Tables
+// ============================================================================
+function buildTables(ws) {
+    if (!ws.getTables) {
+        return [];
+    }
+    const tables = [];
+    for (const t of ws.getTables()) {
+        const model = t.table;
+        if (!model || !model.tl) {
+            continue;
+        }
+        const columns = (model.columns || []).map(c => ({
+            name: c.name
+        }));
+        tables.push({
+            name: model.name || model.displayName || "",
+            columns,
+            topLeft: { row: model.tl.row, col: model.tl.col },
+            dataRowCount: (model.rows || []).length,
+            hasHeaderRow: model.headerRow !== false,
+            hasTotalsRow: model.totalsRow === true
+        });
+    }
+    return tables;
+}
+// ============================================================================
+// Build Defined Names
+// ============================================================================
+function buildDefinedNames(workbook) {
+    const map = new Map();
+    if (!workbook.definedNames) {
+        return map;
+    }
+    // Build a sheet-id-to-name lookup for resolving localSheetId → sheet name.
+    //
+    // `localSheetId` stores the 0-based position in the XLSX-model sheet list,
+    // which in this library corresponds to the index in `workbook.worksheets`
+    // (the filtered+ordered view, see `workbook.xlsx/xform/book/workbook-xform.ts`
+    // line 50-94 where `index` is incremented per rendered sheet).
+    //
+    // Iterate the array exactly once and capture the position directly — avoids
+    // an O(n²) `indexOf` over a fresh array each call. Any caller that has
+    // deleted sheets after creating scoped names is responsible for updating
+    // `localSheetId` to match the new positions; this layer just reflects the
+    // workbook's current state.
+    const sheetIdToName = new Map();
+    const liveSheets = workbook.worksheets;
+    for (let idx = 0; idx < liveSheets.length; idx++) {
+        sheetIdToName.set(idx, liveSheets[idx].name);
+    }
+    // getAllEntries() returns self-contained entries — no second lookup needed.
+    const entries = workbook.definedNames.getAllEntries();
+    for (const entry of entries) {
+        if (!entry.ranges || entry.ranges.length === 0) {
+            continue;
+        }
+        // Convert numeric localSheetId → sheet name string for the snapshot
+        let scope;
+        if (entry.localSheetId !== undefined) {
+            scope = sheetIdToName.get(entry.localSheetId);
+        }
+        const snapshot = {
+            name: entry.name,
+            ranges: [...entry.ranges],
+            ...(scope ? { scope } : {})
+        };
+        const key = scope ? scopedNameKey(scope, entry.name) : entry.name.toUpperCase();
+        if (!map.has(key)) {
+            map.set(key, snapshot);
+        }
+    }
+    return map;
+}