Feature: Iterative Calculation

[sequba]

Context

Implements iterative calculation for circular references, similar to Microsoft Excel and Google Sheets.

When iterativeCalculationEnable is set to true, circular references are resolved using Gauss-Seidel iteration instead of returning #CYCLE! errors. The algorithm:

1. Initializes all cycle cells to iterativeCalculationInitialValue
2. Repeatedly evaluates cycle cells in address order until convergence or max iterations
3. Convergence: all cell changes are < iterativeCalculationConvergenceThreshold
4. Updates dependents of cycle cells after stabilization

New configuration options:

• iterativeCalculationEnable (boolean, default: false) - Enable iterative calculation
• iterativeCalculationMaxIterations (number, default: 100) - Maximum iterations before stopping
• iterativeCalculationConvergenceThreshold (number, default: 0.001) - Convergence threshold
• iterativeCalculationInitialValue (RawCellContent, default: 0) - Starting value for cycle cells

How did you test your changes?

• 54 unit tests covering:
  • Simple self-references (A1=A1+1)
  • Multi-cell cycles (A1→B1→A1)
  • Convergence scenarios (A1=B1/2, B1=A1/2)
  • Non-convergent/oscillating formulas
  • Error propagation in cycles
  • Config validation (invalid types, out-of-range values)
  • Partial recalculation with cycles
  • Mixed cycles with ranges and SUM functions
  • Different initial values (0, strings, booleans)

Types of changes

• New feature or improvement (a non-breaking change that adds functionality)

Related issues:

1. Fixes Feature: Iterative Calculation #1545

Checklist:

• I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
• I have signed the Contributor License Agreement.
• My change is compliant with the OpenDocument standard.
• My change is compatible with Microsoft Excel.
• My change is compatible with Google Sheets.
• I described my changes in the CHANGELOG.md file.
• My changes require a documentation update.
• My changes require a migration guide.

[github-actions]

Performance comparison of head (9f008fc) vs base (45ed5b8)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 503.06 | 496.96 | -1.21%
                                      Sheet B | 164.45 |  159.5 | -3.01%
                                      Sheet T | 142.21 | 138.55 | -2.57%
                                Column ranges | 476.91 | 473.88 | -0.64%
Sheet A:  change value, add/remove row/column |  16.14 |  16.03 | -0.68%
 Sheet B: change value, add/remove row/column | 141.44 | 135.24 | -4.38%
                   Column ranges - add column | 153.75 | 154.04 | +0.19%
                Column ranges - without batch | 456.01 | 457.21 | +0.26%
                        Column ranges - batch | 114.83 | 118.39 | +3.10%

[codecov]

Codecov Report

❌ Patch coverage is 98.23529% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.20%. Comparing base (45ed5b8) to head (9f008fc).

Files with missing lines	Patch %	Lines
src/Evaluator.ts	98.70%	2 Missing ⚠️
src/Config.ts	93.33%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1608      +/-   ##
===========================================
+ Coverage    97.18%   97.20%   +0.01%     
===========================================
  Files          172      172              
  Lines        14834    14988     +154     
  Branches      3257     3284      +27     
===========================================
+ Hits         14417    14569     +152     
- Misses         409      411       +2     
  Partials         8        8              

Files with missing lines	Coverage Δ
src/Config.ts	93.85% <93.33%> (-0.08%)	⬇️
src/Evaluator.ts	99.14% <98.70%> (-0.86%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.