@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/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/esm/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;
+}

package/dist/esm/modules/formula/integration/workbook-snapshot.js

@@ -0,0 +1,77 @@
+/**
+ * Workbook Snapshot — Immutable data layer for the formula engine.
+ *
+ * The snapshot captures all workbook state needed for formula compilation
+ * and evaluation as plain, read-only data structures. Runtime/compile code
+ * must depend only on these types — never on live Workbook/Worksheet/Cell
+ * objects.
+ *
+ * ## Design Principles
+ *
+ * 1. **Immutable** — all interfaces use `readonly` modifiers. The engine
+ *    must never mutate snapshot data.
+ * 2. **Self-contained** — every piece of information the engine needs
+ *    (cell values, formula text, table metadata, defined names, calc
+ *    properties) is captured up front.
+ * 3. **No @excel/ imports** — this file defines pure data types. The
+ *    concrete builder that populates these structures lives in
+ *    `workbook-adapter.ts` and is the only file that touches live objects.
+ */
+// ============================================================================
+// Cell Key Helpers
+// ============================================================================
+/**
+ * Build a snapshot cell key from row and column.
+ * This key format is used for the `WorksheetSnapshot.cells` map.
+ */
+export function snapshotCellKey(row, col) {
+    return `${row}:${col}`;
+}
+/**
+ * Build a formula cell key that includes the sheet name.
+ * Used by the dependency graph and eval session cache.
+ */
+export function formulaCellKey(sheet, row, col) {
+    return `${sheet}!${row}:${col}`;
+}
+/**
+ * Build a spill cell key using the worksheet id (stable across renames).
+ * Used by the spill engine for persistent tracking.
+ */
+export function spillCellKeyFromId(worksheetId, row, col) {
+    return `ws:${worksheetId}!${row}:${col}`;
+}
+// ============================================================================
+// Defined Name Resolution
+// ============================================================================
+/**
+ * Build the key used to store a sheet-scoped defined name.
+ * Format: `"SHEETNAME\0NAME"` (null character separator ensures no collisions).
+ */
+export function scopedNameKey(sheetName, name) {
+    return `${sheetName.toUpperCase()}\0${name.toUpperCase()}`;
+}
+/**
+ * Resolve a defined name considering scope precedence.
+ *
+ * Excel name resolution order:
+ * 1. Sheet-scoped name on `currentSheet` (if any)
+ * 2. Workbook-scoped (global) name
+ *
+ * @param definedNames - The defined names map from the snapshot
+ * @param name - The name to resolve (case-insensitive)
+ * @param currentSheet - The sheet where the formula is located
+ * @returns The matching DefinedNameSnapshot, or undefined
+ */
+export function resolveDefinedName(definedNames, name, currentSheet) {
+    // 1. Try sheet-scoped name first
+    if (currentSheet) {
+        const scopedKey = scopedNameKey(currentSheet, name);
+        const scoped = definedNames.get(scopedKey);
+        if (scoped) {
+            return scoped;
+        }
+    }
+    // 2. Fall back to global name
+    return definedNames.get(name.toUpperCase());
+}