@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/cjs/modules/formula/compile/compiled-formula.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * Compiled Formula — The output of the full compilation pipeline.
+ *
+ * A `CompiledFormula` packages together:
+ * - The original `FormulaInstance` metadata
+ * - The bound expression tree (from the binder)
+ * - Static dependency information
+ * - Metadata flags (volatile, dynamic refs, etc.)
+ *
+ * ## Static Dependency Extraction
+ *
+ * Dependencies are extracted from the `BoundExpr` tree. Since names and
+ * structured refs are already resolved by the binder, the dependency
+ * extraction is a simple tree walk that collects `BoundCellRef` and
+ * `BoundAreaRef` nodes.
+ *
+ * Runtime-dependent references (INDIRECT, OFFSET) cannot be captured
+ * statically — the `hasDynamicRefs` flag marks formulas that may have
+ * additional runtime dependencies. Those functions re-parse their dynamic
+ * arguments at evaluation time using their own parser invocation (the raw
+ * AST is not retained on the CompiledFormula).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractStaticDeps = extractStaticDeps;
+exports.detectDynamicArrayFunction = detectDynamicArrayFunction;
+exports.detectSubtotalOutput = detectSubtotalOutput;
+exports.analyzeExpr = analyzeExpr;
+const token_types_1 = require("../syntax/token-types");
+const structured_ref_utils_1 = require("./structured-ref-utils");
+/**
+ * Extract static dependencies from a bound expression tree.
+ *
+ * @param expr - The bound expression tree to analyze
+ * @param snapshot - Optional snapshot for resolving structured references
+ * @param nameResolver - Optional resolver for formula-based defined name dependencies
+ */
+function extractStaticDeps(expr, snapshot, nameResolver) {
+    const cells = [];
+    const areas = [];
+    walkDeps(expr, cells, areas, snapshot?.tablesByName, nameResolver, new Set());
+    // Deduplicate — a formula like `=A1+A1+A1` would otherwise add three
+    // copies of A1 to the dep list, bloating both the dependency graph's
+    // intermediate storage and the `expandRefsToKeys` pass downstream. We
+    // use positional keys that mirror the Set<string> dedup logic that the
+    // graph builder already applies, so we can pay the cost here once
+    // instead of in every consumer. (R6 architectural note #5)
+    return { cells: dedupeCells(cells), areas: dedupeAreas(areas) };
+}
+function dedupeCells(cells) {
+    if (cells.length < 2) {
+        return cells;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const c of cells) {
+        const key = `${c.sheet}\u0000${c.row}\u0001${c.col}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+function dedupeAreas(areas) {
+    if (areas.length < 2) {
+        return areas;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const a of areas) {
+        const key = `${a.sheet}\u0000${a.top}\u0001${a.left}\u0002${a.bottom}\u0003${a.right}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(a);
+    }
+    return out;
+}
+function walkDeps(expr, cells, areas, tablesByName, nameResolver, visitedNames) {
+    switch (expr.kind) {
+        case 2 /* BoundExprKind.CellRef */:
+            cells.push({ sheet: expr.sheet, row: expr.row, col: expr.col });
+            break;
+        case 3 /* BoundExprKind.AreaRef */:
+            areas.push({
+                sheet: expr.sheet,
+                top: expr.top,
+                left: expr.left,
+                bottom: expr.bottom,
+                right: expr.right
+            });
+            break;
+        case 4 /* BoundExprKind.ColRangeRef */:
+            areas.push({
+                sheet: expr.sheet,
+                top: 1,
+                left: expr.leftCol,
+                bottom: 1048576,
+                right: expr.rightCol
+            });
+            break;
+        case 5 /* BoundExprKind.RowRangeRef */:
+            areas.push({
+                sheet: expr.sheet,
+                top: expr.topRow,
+                left: 1,
+                bottom: expr.bottomRow,
+                right: 16384
+            });
+            break;
+        case 6 /* BoundExprKind.Ref3D */:
+            for (const sheet of expr.sheets) {
+                if (expr.inner.kind === 2 /* BoundExprKind.CellRef */) {
+                    cells.push({ sheet, row: expr.inner.row, col: expr.inner.col });
+                }
+                else {
+                    areas.push({
+                        sheet,
+                        top: expr.inner.top,
+                        left: expr.inner.left,
+                        bottom: expr.inner.bottom,
+                        right: expr.inner.right
+                    });
+                }
+            }
+            break;
+        case 7 /* BoundExprKind.BinaryOp */:
+            walkDeps(expr.left, cells, areas, tablesByName, nameResolver, visitedNames);
+            walkDeps(expr.right, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case 8 /* BoundExprKind.UnaryOp */:
+            walkDeps(expr.operand, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case 9 /* BoundExprKind.Percent */:
+            walkDeps(expr.operand, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case 10 /* BoundExprKind.Call */:
+            for (const arg of expr.args) {
+                walkDeps(arg, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
+        case 11 /* BoundExprKind.SpecialCall */:
+            for (const arg of expr.args) {
+                walkDeps(arg, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
+        case 12 /* BoundExprKind.Array */:
+            for (const row of expr.rows) {
+                for (const elem of row) {
+                    walkDeps(elem, cells, areas, tablesByName, nameResolver, visitedNames);
+                }
+            }
+            break;
+        case 14 /* BoundExprKind.Lambda */:
+            walkDeps(expr.body, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case 15 /* BoundExprKind.StructuredRef */:
+            // Try to resolve structured reference to static deps using the table index.
+            // Only possible when we have the table name and the table exists in the snapshot.
+            if (tablesByName && expr.tableName) {
+                const resolved = tablesByName.get(expr.tableName.toLowerCase());
+                if (resolved) {
+                    const t = resolved.table;
+                    const geo = (0, structured_ref_utils_1.buildTableGeometry)(t);
+                    // Permissive column resolution — static-deps is conservative, so
+                    // unknown column names fall back to the full table width rather
+                    // than being treated as errors.
+                    const colRange = (0, structured_ref_utils_1.resolveStructuredRefColumns)(expr.columns, t, "permissive");
+                    if (colRange === "error") {
+                        // Not reachable in permissive mode, but guard for exhaustiveness.
+                        break;
+                    }
+                    // #This Row can't be resolved statically; we still record the data
+                    // range as a conservative dependency bound.
+                    const rowRange = (0, structured_ref_utils_1.resolveStructuredRefRows)(expr.specials, geo);
+                    let rowTop = geo.dataRowStart;
+                    let rowBottom = geo.dataRowEnd;
+                    if (rowRange !== "thisRow" && rowRange !== "error") {
+                        rowTop = rowRange.rowTop;
+                        rowBottom = rowRange.rowBottom;
+                    }
+                    areas.push({
+                        sheet: resolved.sheetName,
+                        top: rowTop,
+                        left: colRange.colLeft,
+                        bottom: rowBottom,
+                        right: colRange.colRight
+                    });
+                    break;
+                }
+            }
+            // Cannot resolve — no static deps (will be handled at runtime)
+            break;
+        case 1 /* BoundExprKind.Literal */:
+            // No static dependencies
+            break;
+        case 13 /* BoundExprKind.NameExpr */:
+            // Try to resolve the defined name and extract its dependencies.
+            // Guard against infinite recursion with visitedNames.
+            if (nameResolver && visitedNames && !visitedNames.has(expr.upperName)) {
+                visitedNames.add(expr.upperName);
+                const resolved = nameResolver(expr.upperName);
+                if (resolved) {
+                    for (const c of resolved.deps.cells) {
+                        cells.push(c);
+                    }
+                    for (const a of resolved.deps.areas) {
+                        areas.push(a);
+                    }
+                }
+            }
+            break;
+    }
+}
+// ============================================================================
+// Volatility / Dynamic Ref / Dynamic Array Detection
+// ============================================================================
+// Excel's volatile-function list: any formula containing one of these
+// must be re-evaluated on every calc pass, because the result can change
+// without any explicit input change. INDIRECT / OFFSET are additionally
+// flagged as "dynamic ref" (their dependency set isn't known at compile
+// time), but they're also volatile in the usual sense — the target
+// cell's value may change even when the INDIRECT string itself is
+// constant. INFO and CELL with the "row"/"col" info-type also qualify
+// but those require per-invocation arg inspection; the coarse opt-in
+// below is intentionally conservative.
+const VOLATILE_FUNCTIONS = new Set([
+    "RAND",
+    "RANDBETWEEN",
+    "RANDARRAY",
+    "NOW",
+    "TODAY",
+    "INDIRECT",
+    "OFFSET",
+    "INFO",
+    "CELL"
+]);
+const DYNAMIC_REF_FUNCTIONS = new Set(["INDIRECT", "OFFSET"]);
+/**
+ * Function names that naturally produce arrays and should trigger spill
+ * behavior even when `isDynamicArray` is not explicitly set in the XLSX model.
+ */
+const DYNAMIC_ARRAY_FUNCTION_NAMES = new Set([
+    "FILTER",
+    "SORT",
+    "UNIQUE",
+    "SORTBY",
+    "SEQUENCE",
+    "RANDARRAY",
+    "TOCOL",
+    "TOROW",
+    "CHOOSEROWS",
+    "CHOOSECOLS",
+    "VSTACK",
+    "HSTACK",
+    "WRAPROWS",
+    "WRAPCOLS",
+    "EXPAND",
+    "TAKE",
+    "DROP"
+]);
+/**
+ * Check if the formula's top-level expression is a known dynamic array
+ * function. Checks both the raw AST (for prefixed names like `_XLFN.FILTER`)
+ * and the bound expression (for the canonical uppercase name).
+ */
+function detectDynamicArrayFunction(ast, bound) {
+    // Check AST level (handles _XLFN. prefixed names)
+    if (ast.type === 9 /* NodeType.FunctionCall */) {
+        const upper = ast.name.toUpperCase();
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(upper)) {
+            return true;
+        }
+        const canonical = (0, token_types_1.stripFunctionPrefix)(upper);
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(canonical)) {
+            return true;
+        }
+    }
+    // Check bound expression level
+    if (bound.kind === 10 /* BoundExprKind.Call */ && DYNAMIC_ARRAY_FUNCTION_NAMES.has(bound.name)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if the formula's top-level expression is SUBTOTAL or AGGREGATE.
+ *
+ * Excel's SUBTOTAL/AGGREGATE functions deliberately skip any cell whose
+ * own source formula is itself a SUBTOTAL or AGGREGATE call — this is
+ * what makes the classic "totals row inside a filtered range" case not
+ * double-count. `buildRangeArray` reads this flag off the compiled
+ * formula to decide whether to set `subtotalMask[r][c]`.
+ */
+function detectSubtotalOutput(ast, bound) {
+    if (ast.type === 9 /* NodeType.FunctionCall */) {
+        const upper = ast.name.toUpperCase();
+        const canonical = (0, token_types_1.stripFunctionPrefix)(upper);
+        if (canonical === "SUBTOTAL" || canonical === "AGGREGATE") {
+            return true;
+        }
+    }
+    if (bound.kind === 10 /* BoundExprKind.Call */ &&
+        (bound.name === "SUBTOTAL" || bound.name === "AGGREGATE")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Analyze a bound expression for volatile functions and dynamic references.
+ *
+ * @param nameResolver - Optional; if a NameExpr resolves to a formula-based
+ *   defined name containing INDIRECT/OFFSET, the outer formula inherits
+ *   `hasDynamicRefs = true`.
+ */
+function analyzeExpr(expr, nameResolver) {
+    let isVolatile = false;
+    let hasDynamicRefs = false;
+    let containsLambda = false;
+    walkAnalyze(expr);
+    return { isVolatile, hasDynamicRefs, containsLambda };
+    function walkAnalyze(e) {
+        switch (e.kind) {
+            case 10 /* BoundExprKind.Call */:
+                if (VOLATILE_FUNCTIONS.has(e.name)) {
+                    isVolatile = true;
+                }
+                for (const arg of e.args) {
+                    walkAnalyze(arg);
+                }
+                break;
+            case 11 /* BoundExprKind.SpecialCall */:
+                if (DYNAMIC_REF_FUNCTIONS.has(e.name)) {
+                    hasDynamicRefs = true;
+                }
+                if (VOLATILE_FUNCTIONS.has(e.name)) {
+                    isVolatile = true;
+                }
+                for (const arg of e.args) {
+                    walkAnalyze(arg);
+                }
+                break;
+            case 14 /* BoundExprKind.Lambda */:
+                containsLambda = true;
+                walkAnalyze(e.body);
+                break;
+            case 13 /* BoundExprKind.NameExpr */:
+                // If the name resolves to a formula that contains dynamic refs
+                // or volatile functions, the outer formula inherits both flags.
+                // Forgetting to propagate `isVolatile` meant that a defined name
+                // pointing at `NOW()` stayed cached between calculations — the
+                // bug drove R5-P0-5.
+                if (nameResolver) {
+                    const resolved = nameResolver(e.upperName);
+                    if (resolved?.hasDynamicRefs) {
+                        hasDynamicRefs = true;
+                    }
+                    if (resolved?.isVolatile) {
+                        isVolatile = true;
+                    }
+                }
+                break;
+            case 7 /* BoundExprKind.BinaryOp */:
+                walkAnalyze(e.left);
+                walkAnalyze(e.right);
+                break;
+            case 8 /* BoundExprKind.UnaryOp */:
+                walkAnalyze(e.operand);
+                break;
+            case 9 /* BoundExprKind.Percent */:
+                walkAnalyze(e.operand);
+                break;
+            case 12 /* BoundExprKind.Array */:
+                for (const row of e.rows) {
+                    for (const elem of row) {
+                        walkAnalyze(elem);
+                    }
+                }
+                break;
+            default:
+                // Literal, CellRef, AreaRef, etc. — no children to analyze
+                break;
+        }
+    }
+}