# LazilyTransformingAstService Class

Manages lazy application of formula AST transformations.

# 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

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

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 advances versionOffset and 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

# constructor

+ new LazilyTransformingAstService(stats: Statistics, maxPendingLazyTransformations: number): LazilyTransformingAstService

Defined in src/LazilyTransformingAstService.ts:54 (opens new window)

Parameters:

Name	Type
`stats`	Statistics
`maxPendingLazyTransformations`	number

Returns: LazilyTransformingAstService

# Properties

# parser Optional

• parser? : ParserWithCaching

Defined in src/LazilyTransformingAstService.ts:49 (opens new window)

# undoRedo Optional

• undoRedo? : UndoRedo

Defined in src/LazilyTransformingAstService.ts:50 (opens new window)

# Methods

# addTransformation

▸ addTransformation(transformation: FormulaTransformer): number

Defined in src/LazilyTransformingAstService.ts:66 (opens new window)

Parameters:

Name	Type
`transformation`	FormulaTransformer

Returns: number

# applyTransformations

▸ applyTransformations(ast: Ast, address: SimpleCellAddress, version: number): [Ast, SimpleCellAddress, number]

Defined in src/LazilyTransformingAstService.ts:88 (opens new window)

Parameters:

Name	Type
`ast`	Ast
`address`	SimpleCellAddress
`version`	number

Returns: [Ast, SimpleCellAddress, number]

# beginCombinedMode

▸ beginCombinedMode(sheet: number): void

Defined in src/LazilyTransformingAstService.ts:75 (opens new window)

Parameters:

Name	Type
`sheet`	number

Returns: void

# commitCombinedMode

▸ commitCombinedMode(): number

Defined in src/LazilyTransformingAstService.ts:79 (opens new window)

Returns: number

# compact

▸ compact(): void

Defined in src/LazilyTransformingAstService.ts:135 (opens new window)

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

▸ getTransformationsFrom(version: number, filter?: undefined | function): IterableIterator‹FormulaTransformer›

Defined in src/LazilyTransformingAstService.ts:109 (opens new window)

Parameters:

Name	Type
`version`	number
`filter?`	undefined \| function

Returns: IterableIterator‹FormulaTransformer›

# needsCompaction

▸ needsCompaction(): boolean

Defined in src/LazilyTransformingAstService.ts:123 (opens new window)

Returns true when enough transformations have accumulated to justify the cost of forcing all consumers (FormulaVertex, ColumnIndex) to apply pending changes.

Returns: boolean

# version

▸ version(): number

Defined in src/LazilyTransformingAstService.ts:62 (opens new window)

Returns: number