feat: Implement new config param, allowCircularReferences

src/Config.ts

@@ -30,6 +30,7 @@ export class Config implements ConfigParams, ParserConfig {
 
   public static defaultConfig: ConfigParams = {
     accentSensitive: false,
+    allowCircularReferences: false,
     currencySymbol: ['$'],
     caseSensitive: false,
     caseFirst: 'lower',
@@ -78,6 +79,8 @@ export class Config implements ConfigParams, ParserConfig {
   /** @inheritDoc */
   public readonly accentSensitive: boolean
   /** @inheritDoc */
+  public readonly allowCircularReferences: boolean
+  /** @inheritDoc */
   public readonly caseFirst: 'upper' | 'lower' | 'false'
   /** @inheritDoc */
   public readonly dateFormats: string[]
@@ -164,6 +167,7 @@ export class Config implements ConfigParams, ParserConfig {
   constructor(options: Partial<ConfigParams> = {}, showDeprecatedWarns: boolean = true) {
     const {
       accentSensitive,
+      allowCircularReferences,
       caseSensitive,
       caseFirst,
       chooseAddressMappingPolicy,
@@ -209,6 +213,7 @@ export class Config implements ConfigParams, ParserConfig {
 
     this.useArrayArithmetic = configValueFromParam(useArrayArithmetic, 'boolean', 'useArrayArithmetic')
     this.accentSensitive = configValueFromParam(accentSensitive, 'boolean', 'accentSensitive')
+    this.allowCircularReferences = configValueFromParam(options.allowCircularReferences, 'boolean', 'allowCircularReferences')
     this.caseSensitive = configValueFromParam(caseSensitive, 'boolean', 'caseSensitive')
     this.caseFirst = configValueFromParam(caseFirst, ['upper', 'lower', 'false'], 'caseFirst')
     this.ignorePunctuation = configValueFromParam(ignorePunctuation, 'boolean', 'ignorePunctuation')

src/ConfigParams.ts

@@ -16,6 +16,12 @@ export interface ConfigParams {
    * @category String
    */
   accentSensitive: boolean,
+  /**
+   * When set to `true`, allows circular references in formulas (up to a fixed iteration limit).
+   * @default false
+   * @category Engine
+   */
+  allowCircularReferences: boolean,
   /**
    * When set to `true`, makes string comparison case-sensitive.
    *

src/Evaluator.ts

@@ -20,6 +20,7 @@ import {Ast, RelativeDependency} from './parser'
 import {Statistics, StatType} from './statistics'
 
 export class Evaluator {
+  private readonly iterationCount = 100
 
   constructor(
     private readonly config: Config,
@@ -43,6 +44,7 @@ export class Evaluator {
 
   public partialRun(vertices: Vertex[]): ContentChanges {
     const changes = ContentChanges.empty()
+    const cycled: Vertex[] = []
 
     this.stats.measure(StatType.EVALUATION, () => {
       this.dependencyGraph.graph.getTopSortedWithSccSubgraphFrom(vertices,
@@ -68,15 +70,17 @@ export class Evaluator {
           if (vertex instanceof RangeVertex) {
             vertex.clearCache()
           } else if (vertex instanceof FormulaVertex) {
-            const address = vertex.getAddress(this.lazilyTransformingAstService)
-            this.columnSearch.remove(getRawValue(vertex.valueOrUndef()), address)
-            const error = new CellError(ErrorType.CYCLE, undefined, vertex)
-            vertex.setCellValue(error)
-            changes.addChange(error, address)
+            const firstCycleChanges = this.iterateCircularDependencies([vertex], 1)
+            changes.addAll(firstCycleChanges)
+            cycled.push(vertex)
           }
         },
       )
     })
+
+    const cycledChanges = this.iterateCircularDependencies(cycled, this.iterationCount - 1)
+    changes.addAll(cycledChanges)
+
     return changes
   }
 
@@ -105,11 +109,8 @@ export class Evaluator {
    * Recalculates formulas in the topological sort order
    */
   private recomputeFormulas(cycled: Vertex[], sorted: Vertex[]): void {
-    cycled.forEach((vertex: Vertex) => {
-      if (vertex instanceof FormulaVertex) {
-        vertex.setCellValue(new CellError(ErrorType.CYCLE, undefined, vertex))
-      }
-    })
+    this.iterateCircularDependencies(cycled)
+
     sorted.forEach((vertex: Vertex) => {
       if (vertex instanceof FormulaVertex) {
         const newCellValue = this.recomputeFormulaVertexValue(vertex)
@@ -121,6 +122,143 @@ export class Evaluator {
     })
   }
 
+  private blockCircularDependencies(cycled: Vertex[]): ContentChanges {
+    const changes = ContentChanges.empty()
+
+    cycled.forEach((vertex: Vertex) => {
+      if (vertex instanceof RangeVertex) {
+        vertex.clearCache()
+      } else if (vertex instanceof FormulaVertex) {
+        const address = vertex.getAddress(this.lazilyTransformingAstService)
+        this.columnSearch.remove(getRawValue(vertex.valueOrUndef()), address)
+        const error = new CellError(ErrorType.CYCLE, undefined, vertex)
+        vertex.setCellValue(error)
+        changes.addChange(error, address)
+      }
+    })
+
+    return changes
+  }
+
+  /**
+   * Iterates over all circular dependencies (cycled vertices) for 100 iterations
+   * Handles cascading dependencies by processing cycles in dependency order
+   */
+  private iterateCircularDependencies(cycled: Vertex[], cycles = this.iterationCount): ContentChanges {
+    if (!this.config.allowCircularReferences) {
+      return this.blockCircularDependencies(cycled)
+    }
+
+    const changes = ContentChanges.empty()
+    cycled.forEach((vertex: Vertex) => {
+      if (vertex instanceof FormulaVertex && !vertex.isComputed()) {
+        vertex.setCellValue(0)
+      }
+    })
+
+    for (let i = 0; i < cycles; i++) {
+      this.clearCachesForCyclicRanges(cycled)
+
+      cycled.forEach((vertex: Vertex) => {
+        if (!(vertex instanceof FormulaVertex)) {
+          return
+        }
+
+        const address = vertex.getAddress(this.lazilyTransformingAstService)
+        const newCellValue = this.recomputeFormulaVertexValue(vertex)
+
+        if (i < cycles - 1) {
+          return
+        }
+
+        this.columnSearch.add(getRawValue(newCellValue), address)
+        changes.addChange(newCellValue, address)
+      })
+    }
+
+    const dependentChanges = this.updateNonCyclicDependents(cycled)
+    changes.addAll(dependentChanges)
+
+    return changes
+  }
+
+  /**
+   * Updates all non-cyclic cells that depend on the given cycled vertices
+   * Uses topological sorting to ensure correct dependency order
+   */
+  private updateNonCyclicDependents(cycled: Vertex[]): ContentChanges {
+    const changes = ContentChanges.empty()
+    const cyclicSet = new Set(cycled)
+
+    const dependents = new Set<Vertex>()
+    cycled.forEach(vertex => {
+      this.dependencyGraph.graph.adjacentNodes(vertex).forEach(dependent => {
+        if (!cyclicSet.has(dependent) && dependent instanceof FormulaVertex) {
+          dependents.add(dependent)
+        }
+      })
+    })
+
+    if (dependents.size === 0) {
+      return changes
+    }
+
+    const {sorted} = this.dependencyGraph.topSortWithScc()
+    const orderedDependents = sorted.filter(vertex => dependents.has(vertex))
+
+    orderedDependents.forEach(vertex => {
+      if (vertex instanceof FormulaVertex) {
+        const newCellValue = this.recomputeFormulaVertexValue(vertex)
+        const address = vertex.getAddress(this.lazilyTransformingAstService)
+        this.columnSearch.add(getRawValue(newCellValue), address)
+        changes.addChange(newCellValue, address)
+      }
+    })
+
+    return changes
+  }
+
+  /**
+   * Clears function caches for ranges that contain any of the given cyclic vertices
+   * This ensures fresh computation during circular dependency iteration
+   */
+  private clearCachesForCyclicRanges(cycled: Vertex[]): void {
+    const cyclicAddresses = new Set<string>()
+    cycled.forEach((vertex: Vertex) => {
+      if (vertex instanceof FormulaVertex) {
+        const address = vertex.getAddress(this.lazilyTransformingAstService)
+        cyclicAddresses.add(`${address.sheet}:${address.col}:${address.row}`)
+      }
+    })
+
+    const sheetsWithCycles = new Set<number>()
+    cycled.forEach((vertex: Vertex) => {
+      if (vertex instanceof FormulaVertex) {
+        const address = vertex.getAddress(this.lazilyTransformingAstService)
+        sheetsWithCycles.add(address.sheet)
+      }
+    })
+
+    sheetsWithCycles.forEach(sheet => {
+      for (const rangeVertex of this.dependencyGraph.rangeMapping.rangesInSheet(sheet)) {
+        const range = rangeVertex.range
+        let containsCyclicCell = false
+
+        for (const address of range.addresses(this.dependencyGraph)) {
+          const addressKey = `${address.sheet}:${address.col}:${address.row}`
+          if (cyclicAddresses.has(addressKey)) {
+            containsCyclicCell = true
+            break
+          }
+        }
+
+        if (containsCyclicCell) {
+          rangeVertex.clearCache()
+        }
+      }
+    })
+  }
+
   private recomputeFormulaVertexValue(vertex: FormulaVertex): InterpreterValue {
     const address = vertex.getAddress(this.lazilyTransformingAstService)
     if (vertex instanceof ArrayVertex && (vertex.array.size.isRef || !this.dependencyGraph.isThereSpaceForArray(vertex))) {