Evaluator Class

Responsible for computing cell values based on their formulas and dependencies.

Uses topological sorting for acyclic portions and iterative calculation for cycles. Maintains integration with column search index for VLOOKUP/MATCH optimization.

Evaluation Workflow

1. Topological Sort with SCC Detection

   • Sorts vertices (cells/ranges) by dependency order
   • Identifies Strongly Connected Components (SCCs) as cycles

2. Pre-cycle Evaluation

   • Computes all vertices that don't depend on cycles
   • These provide stable inputs for cycle resolution

3. Cycle Resolution (if cycles exist)

   • If iterative calculation disabled: sets #CYCLE! error on all cycle members
   • If enabled: iterates the cycle calculation until convergence or max iterations

4. Post-cycle Evaluation

   • Recomputes vertices that depend on cycle results
   • Uses subgraph traversal for efficiency

Iterative Calculation Algorithm

When circular references exist and enableIterativeCalculation is true:

1. Initialize all cycle cells to iterativeCalculationInitialValue
2. Repeat up to iterativeCalculationLimit times: a. Clear caches for ranges containing cycle cells b. Store current values c. Recompute all cycle cells in address order (Gauss-Seidel style) d. Check convergence: |new - old| < iterativeCalculationThreshold
3. If all cells converge, stop early; otherwise continue to max iterations

Entry Points

• recomputeWholeGraph(): Full evaluation from scratch (initial load or major changes)
• recomputeSubgraph(): Incremental evaluation starting from changed vertices
• evaluateSingleFormula(): One-off formula evaluation without side effects

Constructors

constructor

+ new Evaluator(config: Config, stats: Statistics, interpreter: Interpreter, lazilyTransformingAstService: LazilyTransformingAstService, dependencyGraph: DependencyGraph, columnSearch: ColumnSearchStrategy): Evaluator

Defined in src/Evaluator.ts:64 (opens new window)

Parameters:

Name	Type	Description
config	Config	Configuration including iterative calculation settings
stats	Statistics	Statistics collector for performance measurement
interpreter	Interpreter	AST interpreter for formula evaluation
lazilyTransformingAstService	LazilyTransformingAstService	Service for lazy AST transformations (address updates)
dependencyGraph	DependencyGraph	Graph of cell/range dependencies
columnSearch	ColumnSearchStrategy	Search index for efficient column lookups

Returns: Evaluator

Properties

interpreter Readonly

• interpreter: Interpreter

Defined in src/Evaluator.ts:76 (opens new window)

AST interpreter for formula evaluation

Methods

evaluateSingleFormula

▸ evaluateSingleFormula(ast: Ast, address: SimpleCellAddress, dependencies: RelativeDependency[]): InterpreterValue

Defined in src/Evaluator.ts:172 (opens new window)

Evaluates a formula without persisting the result or modifying the graph.

Used for one-off calculations like conditional formatting or data validation. Temporarily creates range vertices if needed, then cleans them up.

Parameters:

Name	Type	Description
ast	Ast	Parsed formula AST to evaluate
address	SimpleCellAddress	Cell address context for relative references
dependencies	RelativeDependency[]	Relative dependencies extracted from the formula

Returns: InterpreterValue

Computed value (number, string, boolean, error, or array)

---

recomputeSubgraph

▸ recomputeSubgraph(changedVertices: Vertex[]): ContentChanges

Defined in src/Evaluator.ts:118 (opens new window)

Performs incremental evaluation starting from a set of changed vertices.

More efficient than recomputeWholeGraph() when only a subset of cells have changed. Traverses only the subgraph reachable from the changed vertices.

Algorithm:

1. Traverse subgraph from starting vertices in topological order
2. Collect any cycles encountered during traversal
3. Mark vertices that depend on cycles for deferred processing
4. Process cycles via iterative calculation
5. Cycle dependents are handled inside iterateCircularDependencies

Parameters:

Name	Type	Description
changedVertices	Vertex[]	Starting vertices (typically cells that were directly modified)

Returns: ContentChanges

Content changes describing all value updates

---

recomputeWholeGraph

▸ recomputeWholeGraph(): void

Defined in src/Evaluator.ts:92 (opens new window)

Performs full evaluation of all formulas in the dependency graph.

Used for initial spreadsheet load or when dependencies have changed significantly. Performs topological sort to determine evaluation order and handles any cycles.

Complexity: O(V + E) for topological sort + O(I × C) for cycles where V=vertices, E=edges, I=iterations, C=cycle size

Returns: void