LazilyTransformingAstService
Manages lazy application of formula AST transformations.
Problem
Section titled “Problem”Structural operations (adding/removing rows/columns, moving cells, renaming sheets) require updating every formula that references the affected area. Applying these transformations eagerly to all formulas after every operation is expensive, especially for large spreadsheets with many formulas.
Solution: Lazy Transformation
Section titled “Solution: Lazy Transformation”Instead of transforming all formulas immediately, this service stores transformations
in a queue. Each formula vertex (FormulaVertex) and column index entry (ValueIndex)
tracks its own version number. When a consumer needs up-to-date data, it calls
applyTransformations() with its current version and receives all transformations
accumulated since that version.
Compaction
Section titled “Compaction”Over time, the transformations array grows unboundedly. To prevent this memory leak,
the engine periodically triggers compaction when the number of accumulated
transformations reaches the configurable maxPendingLazyTransformations:
- All FormulaVertex instances are forced to apply pending transformations
(via
DependencyGraph.forceApplyPostponedTransformations()). - All ColumnIndex entries are forced to apply pending transformations
(via
ColumnSearchStrategy.forceApplyPostponedTransformations()). compact()is called, which advancesversionOffsetand clears the transformations array.UndoRedo.cleanupOrphanedOldData()removes any oldData entries that were written during forced application but belong to already-evicted undo entries.
The versionOffset ensures that version numbers remain globally consistent
after compaction: version() = versionOffset + transformations.length.
Constructors
Section titled “Constructors”constructor
Section titled “constructor”+ new LazilyTransformingAstService(stats: Statistics, maxPendingLazyTransformations: number): LazilyTransformingAstService
Defined in src/LazilyTransformingAstService.ts:54
Parameters:
| Name | Type |
|---|---|
stats | Statistics |
maxPendingLazyTransformations | number |
Returns: LazilyTransformingAstService
Properties
Section titled “Properties”parser
Section titled “parser”• parser? : ParserWithCaching
Defined in src/LazilyTransformingAstService.ts:49
undoRedo
Section titled “undoRedo”• undoRedo? : UndoRedo
Defined in src/LazilyTransformingAstService.ts:50
Methods
Section titled “Methods”addTransformation
Section titled “addTransformation”▸ addTransformation(transformation: FormulaTransformer): number
Defined in src/LazilyTransformingAstService.ts:66
Parameters:
| Name | Type |
|---|---|
transformation | FormulaTransformer |
Returns: number
applyTransformations
Section titled “applyTransformations”▸ applyTransformations(ast: Ast, address: SimpleCellAddress, version: number): [Ast, SimpleCellAddress, number]
Defined in src/LazilyTransformingAstService.ts:88
Parameters:
| Name | Type |
|---|---|
ast | Ast |
address | SimpleCellAddress |
version | number |
Returns: [Ast, SimpleCellAddress, number]
beginCombinedMode
Section titled “beginCombinedMode”▸ beginCombinedMode(sheet: number): void
Defined in src/LazilyTransformingAstService.ts:75
Parameters:
| Name | Type |
|---|---|
sheet | number |
Returns: void
commitCombinedMode
Section titled “commitCombinedMode”▸ commitCombinedMode(): number
Defined in src/LazilyTransformingAstService.ts:79
Returns: number
compact
Section titled “compact”▸ compact(): void
Defined in src/LazilyTransformingAstService.ts:135
Compacts the transformations array by discarding all entries that have already been applied by every consumer. Safe to call only after all FormulaVertex and ColumnIndex consumers have been brought up to the current version. After calling, UndoRedo.cleanupOrphanedOldData() must be invoked to remove oldData entries written during forceApplyPostponedTransformations for already-evicted undo entries.
Returns: void
getTransformationsFrom
Section titled “getTransformationsFrom”▸ getTransformationsFrom(version: number, filter?: undefined | function): IterableIterator‹FormulaTransformer›
Defined in src/LazilyTransformingAstService.ts:109
Parameters:
| Name | Type |
|---|---|
version | number |
filter? | undefined | function |
Returns: IterableIterator‹FormulaTransformer›
needsCompaction
Section titled “needsCompaction”▸ needsCompaction(): boolean
Defined in src/LazilyTransformingAstService.ts:123
Returns true when enough transformations have accumulated to justify the cost of forcing all consumers (FormulaVertex, ColumnIndex) to apply pending changes.
Returns: boolean
version
Section titled “version”▸ version(): number
Defined in src/LazilyTransformingAstService.ts:62
Returns: number