@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/types/modules/formula/runtime/evaluator.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Evaluator — Execute BoundExpr using the RuntimeValue system.
+ *
+ * The evaluator operates on BoundExpr (from the compile phase),
+ * WorkbookSnapshot (from the snapshot phase), and RuntimeValue
+ * (the value system).
+ */
+import type { BoundExpr } from "../compile/bound-ast.js";
+import type { CompiledFormula } from "../compile/compiled-formula.js";
+import type { WorkbookSnapshot } from "../integration/workbook-snapshot.js";
+import type { RuntimeValue } from "./values.js";
+/**
+ * Cached formula evaluation result with both scalar and raw forms.
+ * The scalar form is used by dependent formulas (implicit intersection applied).
+ * The raw form preserves the full array for dynamic array / CSE materialization.
+ */
+interface CachedResult {
+    /** Scalar (implicit-intersected, dereferenced) result. */
+    readonly scalar: RuntimeValue;
+    /** Raw (full array) result. Only differs from scalar for array formulas. */
+    readonly raw: RuntimeValue;
+}
+/**
+ * Per-calculation mutable state.
+ */
+export declare class EvalSession {
+    /** Cells currently on the evaluation call stack (circular-ref detection). */
+    readonly evaluating: Set<string>;
+    /**
+     * Unified formula result cache.
+     * Each entry holds both the scalar form (for dependents) and the raw form
+     * (for materialize). This replaces the previous separate cache/rawCache
+     * pattern with a single, self-documenting structure.
+     */
+    readonly resultCache: Map<string, CachedResult>;
+    /** Cache for runtime name resolution (defined names that need parsing). */
+    readonly nameCache: Map<string, RuntimeValue>;
+    /** Fallback values for circular references during iterative calculation. */
+    readonly circularFallback: Map<string, RuntimeValue>;
+    /**
+     * Live spill map: cell key → (masterKey, row-offset, col-offset).
+     *
+     * Populated as soon as a dynamic-array formula is evaluated and yields
+     * an array result. Downstream formulas that read a cell inside the
+     * spill region look the master's cached array up via this map and
+     * return the correct element — even before materialize has written
+     * the ghost cells to the snapshot.
+     *
+     * This is the fix for "first-pass `=SUM(A1:A5)` over a `=SEQUENCE(5)`
+     * spill" — without the live map, `getCellValue("S", 2, 1)` returned
+     * BLANK and SUM only counted the master cell.
+     */
+    readonly liveSpills: Map<string, {
+        masterKey: string;
+        rowOffset: number;
+        colOffset: number;
+    }>;
+    /**
+     * Runtime dependency recorder — tracks cell accesses made during evaluation.
+     *
+     * When a formula with `hasDynamicRefs` (INDIRECT/OFFSET) is being evaluated,
+     * every `getCellValue` / `buildRangeArray` call records the accessed cell/range
+     * key here. After evaluation, these dynamic edges can be merged with the
+     * compiled static dependency set to produce a complete dependency graph.
+     *
+     * Key: formula cell key being evaluated → Set of accessed cell keys.
+     * Only populated for formulas that have `hasDynamicRefs === true`.
+     */
+    readonly dynamicDeps: Map<string, Set<string>>;
+    /**
+     * The formula cell key currently being recorded (null if recording is off).
+     * Set before evaluating a formula with dynamic refs, cleared after.
+     */
+    recordingKey: string | null;
+    /**
+     * Current LAMBDA invocation depth. Guards against unbounded recursion
+     * (e.g. `LAMBDA(x, x(x))(LAMBDA(x, x(x)))`) that would otherwise overflow
+     * the JS call stack. Excel documents a recursion limit of ~256.
+     */
+    lambdaDepth: number;
+    /**
+     * AST cache for INDIRECT re-parsing. INDIRECT receives a runtime string
+     * describing a reference; re-parsing it per invocation would be wasted
+     * work, so we memoise the `bound` expression keyed on the reference
+     * text. This belongs to the session (per-calculation lifetime) rather
+     * than the snapshot because the bindings depend on the evaluation
+     * context.
+     */
+    readonly indirectAstCache: Map<string, BoundExpr>;
+    makeKey(sheet: string, row: number, col: number): string;
+    /**
+     * Record a cell access for the currently-recording formula.
+     */
+    recordAccess(sheet: string, row: number, col: number): void;
+}
+/**
+ * The evaluation context. Carries the snapshot and compiled formula map
+ * for the evaluator to access cell values and resolve names at runtime.
+ * Short-lived per-calculation state (caches, iteration flags, etc.) lives
+ * on `EvalSession` instead.
+ */
+export interface EvalContext {
+    /** The workbook snapshot. */
+    readonly snapshot: WorkbookSnapshot;
+    /** Map from formula cell key to CompiledFormula. */
+    readonly compiledFormulas: ReadonlyMap<string, CompiledFormula>;
+    /** The current sheet name (for relative references). */
+    currentSheet: string;
+    /** Current cell address being evaluated. */
+    currentAddress?: {
+        sheet: string;
+        row: number;
+        col: number;
+    };
+    /** Local variable bindings from LET expressions. */
+    localBindings?: Map<string, RuntimeValue>;
+}
+/**
+ * Evaluate a BoundExpr to produce a RuntimeValue.
+ */
+export declare function evaluate(expr: BoundExpr, ctx: EvalContext, session: EvalSession): RuntimeValue;
+/**
+ * Evaluate a compiled formula and return its **scalar** result.
+ *
+ * This is the standard evaluation path for regular (non-array) formulas.
+ * The result is:
+ * 1. Evaluated from the bound expression tree
+ * 2. Implicit-intersected to a single value/reference
+ * 3. Dereferenced if it's a reference
+ * 4. Cached for subsequent lookups by dependent formulas
+ *
+ * Use `evaluateFormulaRaw` instead when the full array result is needed
+ * (dynamic array formulas, CSE formulas).
+ */
+export declare function evaluateFormula(compiled: CompiledFormula, ctx: EvalContext, session: EvalSession): RuntimeValue;
+/**
+ * Evaluate a compiled formula and return the **raw** (possibly array) result.
+ *
+ * This is the evaluation path for dynamic array and CSE formulas where
+ * the full array shape must be preserved for spill/distribution.
+ *
+ * Semantics:
+ * - Both scalar and raw forms are stored in `session.resultCache` as a
+ *   `CachedResult{scalar, raw}`. Dependent scalar formulas see the scalar
+ *   form; the materialize layer retrieves the raw form.
+ * - The return value is the full dereferenced result — may be an ArrayValue
+ *   with height > 1 or width > 1.
+ */
+export declare function evaluateFormulaRaw(compiled: CompiledFormula, ctx: EvalContext, session: EvalSession): RuntimeValue;
+export declare function implicitIntersect(val: RuntimeValue, ctx: EvalContext): RuntimeValue;
+export {};

package/dist/types/modules/formula/runtime/function-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Function Registry — Declarative function descriptors and native implementations.
+ *
+ * Each function is described by a `FunctionDescriptor` that carries metadata
+ * about arity and the implementation itself. The evaluator uses this metadata
+ * to validate arguments and invoke functions.
+ *
+ * Special forms (IF, LET, LAMBDA, etc.) are NOT registered here — they
+ * are handled directly by the evaluator's special-form dispatch.
+ */
+import type { RuntimeValue } from "./values.js";
+/**
+ * A function descriptor with metadata and implementation.
+ */
+export interface FunctionDescriptor {
+    /** Canonical uppercase name. */
+    readonly name: string;
+    /** Minimum number of arguments. */
+    readonly minArity: number;
+    /** Maximum number of arguments. Infinity for variadic. */
+    readonly maxArity: number;
+    /**
+     * The function implementation.
+     * Receives eagerly evaluated arguments as `RuntimeValue[]`.
+     * Returns a `RuntimeValue`.
+     */
+    readonly invoke: (args: RuntimeValue[]) => RuntimeValue;
+}
+/**
+ * Register a function descriptor. The descriptor is stored under its
+ * canonical (unprefixed) name only — `_XLFN.` / `_XLFN._XLWS.` prefix
+ * variants are resolved dynamically in `lookupFunction`. This keeps the
+ * registry small and avoids triple-entry bookkeeping for 200+ functions.
+ */
+export declare function registerFunction(desc: FunctionDescriptor): void;
+/**
+ * Look up a function by uppercase name. Accepts `_XLFN.` and
+ * `_XLFN._XLWS.` prefixed variants by stripping the prefix before lookup
+ * (a no-op for plain names, so plain lookups also go through a single
+ * Map.get call — avoiding the double-lookup pattern used previously).
+ */
+export declare function lookupFunction(name: string): FunctionDescriptor | undefined;
+/**
+ * Convenience: define and register an eager function.
+ */
+export declare function defineEager(name: string, minArity: number, maxArity: number, invoke: (args: RuntimeValue[]) => RuntimeValue): FunctionDescriptor;
+export declare function ensureRegistryInitialized(): void;

package/dist/types/modules/formula/runtime/values.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Runtime Value System — The engine's canonical value representation.
+ *
+ * Every value that flows through the formula evaluator is a `RuntimeValue`.
+ * This is a properly tagged discriminated union that all function
+ * implementations operate on directly — no adapter layer.
+ *
+ * ## Design Principles
+ *
+ * 1. **No Date objects** — dates are represented as their Excel serial
+ *    number (a plain `number`). Date formatting is an output concern.
+ * 2. **No monkey-patched arrays** — `ArrayValue` is a proper type with
+ *    explicit `height`, `width`, and optional origin metadata.
+ * 3. **Reference is a first-class value** — `ReferenceValue` can flow
+ *    through the evaluator and be passed to functions.
+ * 4. **Error codes are strict** — `ErrorValue` uses a typed code enum.
+ * 5. **Lambda is a value** — `LambdaValue` is part of the value union.
+ */
+import type { BoundExpr } from "../compile/bound-ast.js";
+import type { ErrorCode } from "../integration/workbook-snapshot.js";
+export declare const enum RVKind {
+    /** Empty cell / blank. Numeric value 0, string value "". */
+    Blank = 0,
+    /** A number (includes dates as serial numbers). */
+    Number = 1,
+    /** A string. */
+    String = 2,
+    /** A boolean (TRUE / FALSE). */
+    Boolean = 3,
+    /** An error value (#N/A, #VALUE!, etc.). */
+    Error = 4,
+    /** A 2D array of scalar values. */
+    Array = 5,
+    /** A cell or area reference (lazy — not yet resolved to values). */
+    Reference = 6,
+    /** A lambda (closure). */
+    Lambda = 7
+}
+export interface BlankValue {
+    readonly kind: RVKind.Blank;
+}
+export interface NumberValue {
+    readonly kind: RVKind.Number;
+    readonly value: number;
+}
+export interface StringValue {
+    readonly kind: RVKind.String;
+    readonly value: string;
+}
+export interface BooleanValue {
+    readonly kind: RVKind.Boolean;
+    readonly value: boolean;
+}
+export interface ErrorValue {
+    readonly kind: RVKind.Error;
+    readonly code: ErrorCode;
+}
+/**
+ * A 2D array of scalar values.
+ *
+ * `rows[r][c]` is a `ScalarValue`. Arrays are always rectangular.
+ * Origin metadata (for implicit intersection) is carried inline.
+ */
+export interface ArrayValue {
+    readonly kind: RVKind.Array;
+    /** Rows of scalar values. rows[0] is the first row. */
+    readonly rows: readonly (readonly ScalarValue[])[];
+    /** Number of rows. */
+    readonly height: number;
+    /** Number of columns. */
+    readonly width: number;
+    /** Origin row in the worksheet (1-based). Used for implicit intersection. */
+    readonly originRow?: number;
+    /** Origin column in the worksheet (1-based). Used for implicit intersection. */
+    readonly originCol?: number;
+    /**
+     * Per-cell mask marking cells whose source formula is SUBTOTAL or
+     * AGGREGATE. When a range is passed to an outer SUBTOTAL/AGGREGATE
+     * call, those cells must be skipped so their results are not
+     * double-counted (Excel semantics — standard totals-row behavior).
+     *
+     * Same shape as `rows`: `subtotalMask[r][c]` is true when the cell
+     * should be excluded from outer SUBTOTAL/AGGREGATE aggregation.
+     * Omitted when no cell in the array is a SUBTOTAL/AGGREGATE output.
+     */
+    readonly subtotalMask?: readonly (readonly boolean[])[];
+    /**
+     * Per-row mask marking rows whose source worksheet row is hidden.
+     * Used by SUBTOTAL's 1xx-variant codes (101-111) and by AGGREGATE
+     * options 5/7 to skip hidden rows. `hiddenRowMask[r]` is true when
+     * row `r` of the array should be excluded under those semantics.
+     * Omitted when no row in the array is hidden.
+     */
+    readonly hiddenRowMask?: readonly boolean[];
+}
+/**
+ * The shape of a reference.
+ */
+export type RefArea = {
+    readonly sheet: string;
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+};
+/**
+ * A reference value that represents one or more areas in the workbook.
+ *
+ * References are first-class values in the new engine — they can be
+ * passed to functions, returned from functions, and stored in variables.
+ * They are resolved to actual values lazily when needed.
+ */
+export interface ReferenceValue {
+    readonly kind: RVKind.Reference;
+    /** The areas this reference covers. Usually one, but UNION produces multiple. */
+    readonly areas: readonly RefArea[];
+    /** Whether this reference originated from a single-cell ref (A1) vs an area ref (A1:A1). */
+    readonly singleCell?: boolean;
+}
+/**
+ * A lambda closure value.
+ */
+export interface LambdaValue {
+    readonly kind: RVKind.Lambda;
+    /** Parameter names (uppercase). */
+    readonly params: readonly string[];
+    /** The body expression to evaluate when called. */
+    readonly body: BoundExpr;
+    /** Captured variable bindings from the enclosing scope. */
+    readonly closureBindings?: ReadonlyMap<string, RuntimeValue>;
+}
+/**
+ * A scalar value (non-array, non-reference, non-lambda).
+ */
+export type ScalarValue = BlankValue | NumberValue | StringValue | BooleanValue | ErrorValue;
+/**
+ * Any value that can flow through the evaluator.
+ */
+export type RuntimeValue = BlankValue | NumberValue | StringValue | BooleanValue | ErrorValue | ArrayValue | ReferenceValue | LambdaValue;
+/** The singleton blank value. */
+export declare const BLANK: BlankValue;
+/** Common error values. */
+export declare const ERRORS: {
+    readonly VALUE: ErrorValue;
+    readonly REF: ErrorValue;
+    readonly NAME: ErrorValue;
+    readonly DIV0: ErrorValue;
+    readonly NA: ErrorValue;
+    readonly NUM: ErrorValue;
+    readonly NULL: ErrorValue;
+    readonly SPILL: ErrorValue;
+    readonly CALC: ErrorValue;
+};
+export declare function rvNumber(value: number): NumberValue;
+export declare function rvString(value: string): StringValue;
+export declare function rvBoolean(value: boolean): BooleanValue;
+export declare function rvError(code: ErrorCode): ErrorValue;
+export declare function rvArray(rows: ScalarValue[][], originRow?: number, originCol?: number, subtotalMask?: readonly (readonly boolean[])[], hiddenRowMask?: readonly boolean[]): ArrayValue;
+export declare function rvRef(sheet: string, top: number, left: number, bottom: number, right: number): ReferenceValue;
+export declare function rvCellRef(sheet: string, row: number, col: number): ReferenceValue;
+export declare function rvLambda(params: string[], body: BoundExpr, closureBindings?: ReadonlyMap<string, RuntimeValue>): LambdaValue;
+export declare function isError(v: RuntimeValue): v is ErrorValue;
+export declare function isArray(v: RuntimeValue): v is ArrayValue;
+export declare function isLambda(v: RuntimeValue): v is LambdaValue;
+export declare function isScalar(v: RuntimeValue): v is ScalarValue;
+/**
+ * Coerce a runtime value to a number.
+ * - Blank → 0
+ * - Number → itself
+ * - Boolean → 1 / 0
+ * - String → parse or #VALUE!
+ * - Error → propagate
+ */
+export declare function toNumberRV(v: RuntimeValue): NumberValue | ErrorValue;
+/**
+ * Coerce a runtime value to a string.
+ */
+export declare function toStringRV(v: RuntimeValue): string;
+/**
+ * Coerce a runtime value to a boolean.
+ */
+export declare function toBooleanRV(v: RuntimeValue): BooleanValue | ErrorValue;
+/**
+ * Structural equality of scalar values.
+ *
+ * - Different kinds → false
+ * - Number / Boolean / Blank → strict value equality (Blank always equal)
+ * - String → case-insensitive comparison (Excel semantics)
+ * - Error → not equal (errors do not compare equal to each other)
+ */
+/**
+ * Three-way compare two scalars that share a kind.
+ *
+ * Returns a negative number if `a < b`, zero if equal, positive if `a > b`.
+ * Returns `NaN` when the kinds differ or cannot be ordered (e.g. errors);
+ * callers decide how to surface the incomparability — sort helpers usually
+ * skip NaN pairs, while comparison operators route to a kind-priority
+ * tiebreak. Strings are compared case-insensitively to match Excel.
+ */
+export declare function compareScalarsSameKind(a: ScalarValue, b: ScalarValue): number;
+export declare function scalarEquals(a: ScalarValue, b: ScalarValue): boolean;
+/**
+ * Get the top-left scalar from any value (for implicit intersection fallback).
+ */
+export declare function topLeft(v: RuntimeValue): ScalarValue;
+/**
+ * Convert a SnapshotCellValue to a RuntimeValue.
+ */
+export declare function fromSnapshotValue(v: number | string | boolean | {
+    error: string;
+} | null): ScalarValue;

package/dist/types/modules/formula/syntax/ast.d.ts

@@ -0,0 +1,129 @@
+/**
+ * AST Node Types for Formula Parser
+ *
+ * Defines the Abstract Syntax Tree node types as a proper discriminated union.
+ * Each node variant carries only the data relevant to its type.
+ */
+export declare const enum NodeType {
+    Number = 1,
+    String = 2,
+    Boolean = 3,
+    Error = 4,
+    CellRef = 5,
+    RangeRef = 6,
+    BinaryOp = 7,
+    UnaryOp = 8,
+    FunctionCall = 9,
+    Array = 10,
+    Percent = 11,
+    Name = 12,
+    ColRangeRef = 13,
+    RowRangeRef = 14,
+    StructuredRef = 15,
+    Missing = 16
+}
+export interface NumberNode {
+    type: NodeType.Number;
+    value: number;
+}
+export interface StringNode {
+    type: NodeType.String;
+    value: string;
+}
+export interface BooleanNode {
+    type: NodeType.Boolean;
+    value: boolean;
+}
+export interface ErrorNode {
+    type: NodeType.Error;
+    value: string;
+}
+export interface CellRefNode {
+    type: NodeType.CellRef;
+    /** Uppercase column letters, e.g. "A" */
+    col: string;
+    /** Row number as string, e.g. "1" */
+    row: string;
+    colAbsolute: boolean;
+    rowAbsolute: boolean;
+    /** Optional sheet name for cross-sheet references */
+    sheet?: string;
+    /** Optional end sheet name for 3D references (e.g. Sheet1:Sheet3!A1) */
+    endSheet?: string;
+}
+export interface RangeRefNode {
+    type: NodeType.RangeRef;
+    /** Top-left cell */
+    start: CellRefNode;
+    /** Bottom-right cell */
+    end: CellRefNode;
+    /** Sheet name — both start and end share same sheet */
+    sheet?: string;
+    /** Optional end sheet name for 3D references (e.g. Sheet1:Sheet3!A1:B2) */
+    endSheet?: string;
+}
+export interface BinaryOpNode {
+    type: NodeType.BinaryOp;
+    op: string;
+    left: AstNode;
+    right: AstNode;
+}
+export interface UnaryOpNode {
+    type: NodeType.UnaryOp;
+    op: string;
+    operand: AstNode;
+}
+export interface FunctionCallNode {
+    type: NodeType.FunctionCall;
+    name: string;
+    args: AstNode[];
+}
+export interface ArrayNode {
+    type: NodeType.Array;
+    /** rows[i][j] = element */
+    rows: AstNode[][];
+}
+export interface PercentNode {
+    type: NodeType.Percent;
+    operand: AstNode;
+}
+export interface NameNode {
+    type: NodeType.Name;
+    name: string;
+}
+export interface ColRangeRefNode {
+    type: NodeType.ColRangeRef;
+    /** Start column (e.g. "A") */
+    startCol: string;
+    /** End column (e.g. "B") */
+    endCol: string;
+    /** Optional sheet name */
+    sheet?: string;
+    /** Optional end sheet name for 3D references */
+    endSheet?: string;
+}
+export interface RowRangeRefNode {
+    type: NodeType.RowRangeRef;
+    /** Start row (1-based) */
+    startRow: number;
+    /** End row (1-based) */
+    endRow: number;
+    /** Optional sheet name */
+    sheet?: string;
+    /** Optional end sheet name for 3D references */
+    endSheet?: string;
+}
+export interface StructuredRefNode {
+    type: NodeType.StructuredRef;
+    /** Table name (empty string for implicit [@Col] syntax) */
+    tableName: string;
+    /** Column references (e.g. ["Column1", "Column2"] for a column range) */
+    columns: string[];
+    /** Special items (e.g. ["#Headers", "#Data", "#Totals", "#All", "#This Row"]) */
+    specials: string[];
+}
+/** Represents an omitted/missing argument in a function call (e.g., the middle arg in IF(A1,,0)). */
+export interface MissingNode {
+    type: NodeType.Missing;
+}
+export type AstNode = NumberNode | StringNode | BooleanNode | ErrorNode | CellRefNode | RangeRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | ArrayNode | PercentNode | NameNode | ColRangeRefNode | RowRangeRefNode | StructuredRefNode | MissingNode;

package/dist/types/modules/formula/syntax/parser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Formula Parser
+ *
+ * Converts a token stream into an Abstract Syntax Tree (AST).
+ * Implements a Pratt parser (top-down operator precedence) for correct
+ * handling of operator precedence and associativity.
+ *
+ * Excel operator precedence (highest to lowest):
+ *   1. Unary + / - / %
+ *   2. ^  (exponentiation, right-assoc)
+ *   3. * /
+ *   4. + -
+ *   5. &  (concatenation)
+ *   6. = <> < > <= >=  (comparison)
+ */
+import { type AstNode } from "./ast.js";
+import { type Token } from "./token-types.js";
+export declare function parse(tokens: Token[]): AstNode;