@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/compile/bound-ast.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Bound Expression AST — The output of the compilation (binding) phase.
+ *
+ * After parsing produces a raw AST, the binder resolves all static symbols:
+ * - Defined names → resolved cell/range references or formula expressions
+ * - Structured references → resolved cell/range references
+ * - Sheet names → validated against the snapshot
+ * - Function names → validated against the registry
+ *
+ * The result is a `BoundExpr` tree where every reference is resolved and
+ * every function call is validated. The runtime evaluator only executes
+ * `BoundExpr` nodes — it never needs to perform symbol resolution.
+ *
+ * ## Node Types (compile output)
+ *
+ * After binding, only these node types exist:
+ *
+ * - `BoundLiteral` — number, string, boolean, error, null (missing)
+ * - `BoundCellRef` — resolved cell reference (sheet + row + col)
+ * - `BoundAreaRef` — resolved rectangular range (sheet + bounds)
+ * - `BoundColRangeRef` — resolved whole-column range
+ * - `BoundRowRangeRef` — resolved whole-row range
+ * - `BoundRef3D` — resolved 3D reference (multiple sheets)
+ * - `BoundBinaryOp` — binary operation
+ * - `BoundUnaryOp` — unary operation (including @)
+ * - `BoundPercent` — postfix %
+ * - `BoundCall` — function call (eagerly evaluated args)
+ * - `BoundSpecialCall` — special form (IF, LET, LAMBDA, etc.) with lazy args
+ * - `BoundArray` — array constant {1,2;3,4}
+ * - `BoundNameExpr` — UNRESOLVED name (only for names that must be resolved at runtime,
+ *   e.g. formula-based defined names that produce lambdas, or truly unknown names)
+ * - `BoundLambda` — LAMBDA expression (params + body)
+ */
+export declare const enum BoundExprKind {
+    Literal = 1,
+    CellRef = 2,
+    AreaRef = 3,
+    ColRangeRef = 4,
+    RowRangeRef = 5,
+    Ref3D = 6,
+    BinaryOp = 7,
+    UnaryOp = 8,
+    Percent = 9,
+    Call = 10,
+    SpecialCall = 11,
+    Array = 12,
+    NameExpr = 13,
+    Lambda = 14,
+    StructuredRef = 15
+}
+/**
+ * A resolved literal value.
+ */
+export interface BoundLiteral {
+    readonly kind: BoundExprKind.Literal;
+    /** number | string | boolean | null (for Missing/blank) */
+    readonly value: number | string | boolean | null;
+    /** If this is an error literal (e.g. #N/A), the error code. */
+    readonly errorCode?: string;
+}
+/**
+ * A fully resolved cell reference.
+ * After binding, sheet is always resolved (never undefined).
+ */
+export interface BoundCellRef {
+    readonly kind: BoundExprKind.CellRef;
+    /** Resolved sheet name. */
+    readonly sheet: string;
+    /** 1-based row number. */
+    readonly row: number;
+    /** 1-based column number. */
+    readonly col: number;
+}
+/**
+ * A fully resolved rectangular area reference.
+ */
+export interface BoundAreaRef {
+    readonly kind: BoundExprKind.AreaRef;
+    /** Resolved sheet name. */
+    readonly sheet: string;
+    /** 1-based bounds. */
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/**
+ * A resolved whole-column range (e.g. A:B).
+ * Row bounds are determined at runtime from sheet dimensions.
+ */
+export interface BoundColRangeRef {
+    readonly kind: BoundExprKind.ColRangeRef;
+    readonly sheet: string;
+    readonly leftCol: number;
+    readonly rightCol: number;
+}
+/**
+ * A resolved whole-row range (e.g. 1:5).
+ * Column bounds are determined at runtime from sheet dimensions.
+ */
+export interface BoundRowRangeRef {
+    readonly kind: BoundExprKind.RowRangeRef;
+    readonly sheet: string;
+    readonly topRow: number;
+    readonly bottomRow: number;
+}
+/**
+ * A resolved 3D reference spanning multiple sheets.
+ * The inner reference is either a cell or an area.
+ */
+export interface BoundRef3D {
+    readonly kind: BoundExprKind.Ref3D;
+    /** Sheet names in workbook order, from start to end (inclusive). */
+    readonly sheets: readonly string[];
+    /** The cell/area that is replicated across sheets. */
+    readonly inner: BoundCellRef | BoundAreaRef;
+}
+/**
+ * Binary operation with two sub-expressions.
+ */
+export interface BoundBinaryOp {
+    readonly kind: BoundExprKind.BinaryOp;
+    readonly op: string;
+    readonly left: BoundExpr;
+    readonly right: BoundExpr;
+}
+/**
+ * Unary operation (prefix +, -, or @ implicit intersection).
+ */
+export interface BoundUnaryOp {
+    readonly kind: BoundExprKind.UnaryOp;
+    readonly op: string;
+    readonly operand: BoundExpr;
+}
+/**
+ * Postfix percent operation.
+ */
+export interface BoundPercent {
+    readonly kind: BoundExprKind.Percent;
+    readonly operand: BoundExpr;
+}
+/**
+ * A standard (eager) function call.
+ * All arguments are evaluated before the function is called.
+ */
+export interface BoundCall {
+    readonly kind: BoundExprKind.Call;
+    /** Uppercase, canonical function name. */
+    readonly name: string;
+    /** Bound argument expressions. */
+    readonly args: readonly BoundExpr[];
+}
+/**
+ * Special form identifiers for lazy/short-circuit evaluation.
+ */
+export type SpecialFormName = "IF" | "IFERROR" | "IFNA" | "IFS" | "SWITCH" | "CHOOSE" | "LET" | "LAMBDA" | "INDIRECT" | "OFFSET" | "MAP" | "REDUCE" | "SCAN" | "MAKEARRAY" | "BYROW" | "BYCOL";
+/**
+ * A special-form function call with lazy argument evaluation.
+ * The evaluator handles these with custom logic (short-circuit, binding, etc.).
+ */
+export interface BoundSpecialCall {
+    readonly kind: BoundExprKind.SpecialCall;
+    readonly name: SpecialFormName;
+    /** Argument expressions (evaluated lazily by the evaluator). */
+    readonly args: readonly BoundExpr[];
+}
+/**
+ * Array constant: {1,2;3,4}.
+ */
+export interface BoundArray {
+    readonly kind: BoundExprKind.Array;
+    /** rows[i][j] = element expression. */
+    readonly rows: readonly (readonly BoundExpr[])[];
+}
+/**
+ * An unresolved name reference.
+ *
+ * This exists for names that cannot be fully resolved at compile time:
+ * - Formula-based defined names (e.g. =LAMBDA(x,y,x+y))
+ * - Names that resolve to lambdas stored in cells
+ * - LET-bound local variables (resolved at runtime from localBindings)
+ * - Truly unknown names (#NAME? at runtime)
+ *
+ * For names that resolve to simple cell/range references, the binder
+ * produces `BoundCellRef` or `BoundAreaRef` directly.
+ */
+export interface BoundNameExpr {
+    readonly kind: BoundExprKind.NameExpr;
+    /** The original name (case-preserved). */
+    readonly name: string;
+    /** Uppercase name for lookup. */
+    readonly upperName: string;
+}
+/**
+ * A LAMBDA expression with parameter names and a body.
+ * Produced by the binder when it encounters a LAMBDA special form.
+ */
+export interface BoundLambda {
+    readonly kind: BoundExprKind.Lambda;
+    /** Parameter names (uppercase). */
+    readonly params: readonly string[];
+    /** The body expression. */
+    readonly body: BoundExpr;
+}
+/**
+ * An unresolved structured reference that requires runtime context.
+ *
+ * This is produced by the binder when:
+ * - The table name is empty (implicit `@` syntax — needs current cell position)
+ * - The reference includes `#This Row` (needs current cell's row)
+ *
+ * The evaluator resolves these at runtime using the current cell address.
+ */
+export interface BoundStructuredRef {
+    readonly kind: BoundExprKind.StructuredRef;
+    /** Table name (empty string for implicit table). */
+    readonly tableName: string;
+    /** Column names. */
+    readonly columns: readonly string[];
+    /** Special items (#Headers, #Data, #Totals, #All, #This Row). */
+    readonly specials: readonly string[];
+}
+export type BoundExpr = BoundLiteral | BoundCellRef | BoundAreaRef | BoundColRangeRef | BoundRowRangeRef | BoundRef3D | BoundBinaryOp | BoundUnaryOp | BoundPercent | BoundCall | BoundSpecialCall | BoundArray | BoundNameExpr | BoundLambda | BoundStructuredRef;
+export declare function boundLiteral(value: number | string | boolean | null, errorCode?: string): BoundLiteral;
+export declare function boundCellRef(sheet: string, row: number, col: number): BoundCellRef;
+export declare function boundAreaRef(sheet: string, top: number, left: number, bottom: number, right: number): BoundAreaRef;
+export declare function boundCall(name: string, args: BoundExpr[]): BoundCall;
+export declare function boundSpecialCall(name: SpecialFormName, args: BoundExpr[]): BoundSpecialCall;
+export declare function boundNameExpr(name: string): BoundNameExpr;
+export declare function boundErrorLiteral(errorCode: string): BoundLiteral;

package/dist/browser/modules/formula/compile/bound-ast.js

@@ -0,0 +1,80 @@
+/**
+ * Bound Expression AST — The output of the compilation (binding) phase.
+ *
+ * After parsing produces a raw AST, the binder resolves all static symbols:
+ * - Defined names → resolved cell/range references or formula expressions
+ * - Structured references → resolved cell/range references
+ * - Sheet names → validated against the snapshot
+ * - Function names → validated against the registry
+ *
+ * The result is a `BoundExpr` tree where every reference is resolved and
+ * every function call is validated. The runtime evaluator only executes
+ * `BoundExpr` nodes — it never needs to perform symbol resolution.
+ *
+ * ## Node Types (compile output)
+ *
+ * After binding, only these node types exist:
+ *
+ * - `BoundLiteral` — number, string, boolean, error, null (missing)
+ * - `BoundCellRef` — resolved cell reference (sheet + row + col)
+ * - `BoundAreaRef` — resolved rectangular range (sheet + bounds)
+ * - `BoundColRangeRef` — resolved whole-column range
+ * - `BoundRowRangeRef` — resolved whole-row range
+ * - `BoundRef3D` — resolved 3D reference (multiple sheets)
+ * - `BoundBinaryOp` — binary operation
+ * - `BoundUnaryOp` — unary operation (including @)
+ * - `BoundPercent` — postfix %
+ * - `BoundCall` — function call (eagerly evaluated args)
+ * - `BoundSpecialCall` — special form (IF, LET, LAMBDA, etc.) with lazy args
+ * - `BoundArray` — array constant {1,2;3,4}
+ * - `BoundNameExpr` — UNRESOLVED name (only for names that must be resolved at runtime,
+ *   e.g. formula-based defined names that produce lambdas, or truly unknown names)
+ * - `BoundLambda` — LAMBDA expression (params + body)
+ */
+// ============================================================================
+// Bound Expression Tag Enum
+// ============================================================================
+export var BoundExprKind;
+(function (BoundExprKind) {
+    BoundExprKind[BoundExprKind["Literal"] = 1] = "Literal";
+    BoundExprKind[BoundExprKind["CellRef"] = 2] = "CellRef";
+    BoundExprKind[BoundExprKind["AreaRef"] = 3] = "AreaRef";
+    BoundExprKind[BoundExprKind["ColRangeRef"] = 4] = "ColRangeRef";
+    BoundExprKind[BoundExprKind["RowRangeRef"] = 5] = "RowRangeRef";
+    BoundExprKind[BoundExprKind["Ref3D"] = 6] = "Ref3D";
+    BoundExprKind[BoundExprKind["BinaryOp"] = 7] = "BinaryOp";
+    BoundExprKind[BoundExprKind["UnaryOp"] = 8] = "UnaryOp";
+    BoundExprKind[BoundExprKind["Percent"] = 9] = "Percent";
+    BoundExprKind[BoundExprKind["Call"] = 10] = "Call";
+    BoundExprKind[BoundExprKind["SpecialCall"] = 11] = "SpecialCall";
+    BoundExprKind[BoundExprKind["Array"] = 12] = "Array";
+    BoundExprKind[BoundExprKind["NameExpr"] = 13] = "NameExpr";
+    BoundExprKind[BoundExprKind["Lambda"] = 14] = "Lambda";
+    BoundExprKind[BoundExprKind["StructuredRef"] = 15] = "StructuredRef";
+})(BoundExprKind || (BoundExprKind = {}));
+// ============================================================================
+// Constructor Helpers
+// ============================================================================
+export function boundLiteral(value, errorCode) {
+    return errorCode !== undefined
+        ? { kind: BoundExprKind.Literal, value, errorCode }
+        : { kind: BoundExprKind.Literal, value };
+}
+export function boundCellRef(sheet, row, col) {
+    return { kind: BoundExprKind.CellRef, sheet, row, col };
+}
+export function boundAreaRef(sheet, top, left, bottom, right) {
+    return { kind: BoundExprKind.AreaRef, sheet, top, left, bottom, right };
+}
+export function boundCall(name, args) {
+    return { kind: BoundExprKind.Call, name, args };
+}
+export function boundSpecialCall(name, args) {
+    return { kind: BoundExprKind.SpecialCall, name, args };
+}
+export function boundNameExpr(name) {
+    return { kind: BoundExprKind.NameExpr, name, upperName: name.toUpperCase() };
+}
+export function boundErrorLiteral(errorCode) {
+    return { kind: BoundExprKind.Literal, value: null, errorCode };
+}

package/dist/browser/modules/formula/compile/compiled-formula.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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).
+ */
+import type { FormulaInstance } from "../integration/formula-instance.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { AstNode } from "../syntax/ast.js";
+import type { BoundExpr } from "./bound-ast.js";
+/**
+ * The complete compiled representation of a formula.
+ */
+export interface CompiledFormula {
+    /** The original formula instance metadata. */
+    readonly instance: FormulaInstance;
+    /** The bound expression tree (the evaluator executes this). */
+    readonly bound: BoundExpr;
+    /** Statically extractable dependencies. */
+    readonly staticDeps: StaticDependencySet;
+    /** Whether this formula uses volatile functions (RAND, NOW, etc.). */
+    readonly isVolatile: boolean;
+    /** Whether this formula contains INDIRECT/OFFSET (runtime-dependent refs). */
+    readonly hasDynamicRefs: boolean;
+    /** Whether this formula contains any lambda expressions. */
+    readonly containsLambda: boolean;
+    /**
+     * Whether the top-level function is a known dynamic array function
+     * (FILTER, SORT, UNIQUE, SEQUENCE, etc.). Determined once at compile
+     * time — consumers should use this flag instead of re-checking the AST
+     * or bound expression.
+     */
+    readonly isDynamicArrayFunction: boolean;
+    /**
+     * Whether the top-level function is SUBTOTAL or AGGREGATE. When an
+     * outer SUBTOTAL/AGGREGATE range aggregates a cell whose formula is
+     * itself a SUBTOTAL/AGGREGATE call, that cell must be skipped so its
+     * result is not double-counted. This flag lets `buildRangeArray`
+     * mark those cells with the array's `subtotalMask`.
+     */
+    readonly isSubtotalOutput: boolean;
+}
+/**
+ * A single cell dependency.
+ */
+export interface CellDep {
+    readonly sheet: string;
+    readonly row: number;
+    readonly col: number;
+}
+/**
+ * A rectangular area dependency.
+ */
+export interface AreaDep {
+    readonly sheet: string;
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+}
+/**
+ * All statically extractable dependencies of a formula.
+ */
+export interface StaticDependencySet {
+    /** Individual cell references. */
+    readonly cells: readonly CellDep[];
+    /** Range references. */
+    readonly areas: readonly AreaDep[];
+}
+/**
+ * Callback to resolve a defined name into its parsed/bound expression
+ * for dependency extraction. Returns the bound expression if the name
+ * resolves to a formula, or undefined if it can't be resolved.
+ */
+export type NameDepResolver = (name: string) => {
+    deps: StaticDependencySet;
+    hasDynamicRefs: boolean;
+    /**
+     * Whether the defined-name's formula (transitively) uses a volatile
+     * function like NOW/RAND/OFFSET/INDIRECT. The resolver must propagate
+     * this so the OUTER formula inherits volatility — otherwise the
+     * session result cache would hold stale values across calc runs.
+     */
+    isVolatile: boolean;
+} | undefined;
+/**
+ * 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
+ */
+export declare function extractStaticDeps(expr: BoundExpr, snapshot?: WorkbookSnapshot, nameResolver?: NameDepResolver): StaticDependencySet;
+/**
+ * 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).
+ */
+export declare function detectDynamicArrayFunction(ast: AstNode, bound: BoundExpr): boolean;
+/**
+ * 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]`.
+ */
+export declare function detectSubtotalOutput(ast: AstNode, bound: BoundExpr): boolean;
+/**
+ * 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`.
+ */
+export declare function analyzeExpr(expr: BoundExpr, nameResolver?: NameDepResolver): {
+    isVolatile: boolean;
+    hasDynamicRefs: boolean;
+    containsLambda: boolean;
+};