HF-131 (6/7): thrown exceptions name the cell (issue #444)

[marcin-kordas-hoc]

What and why

Stacked on #1765. Closes #444: reading
a formula cell's value before it has been computed threw a plain Error('Value of the formula cell is not computed.') / Error('Array not computed yet.') — no way to trace which cell caused it.

Adds CellValueNotComputedError, a named, exported error class carrying the cell's address:

export class CellValueNotComputedError extends Error {
  constructor(public readonly address: SimpleCellAddress) {
    super(`Value of the formula cell (sheet = ${address.sheet}, row = ${address.row}, col = ${address.col}) is not computed.`)
  }
}

Replaces both throw sites (ScalarFormulaVertex.getCellValue, ArrayFormulaVertex.getCellValue).
Exported from src/index.ts, both as a named export and on the HyperFormula static namespace,
alongside CellError/DetailedCellError.

Verified

• npx tsc --noEmit — clean
• npx eslint src/ — 0 errors
• New test file, 4 cases across both vertex types
• Full private test suite reproduced against this branch's tip — no regressions beyond the same
  pre-existing branch-pinning mismatch as the rest of this stack

Stack

6 of 7 — stacked on #1765. Next: docs/hf-131-types-of-errors.

🤖 Generated with Claude Code

---

Note

Low Risk
Narrow change to error typing at two internal throw sites plus a new public export; callers that relied on exact generic Error message strings may need to catch CellValueNotComputedError instead.

Overview
Reading a formula cell before evaluation used to throw anonymous plain Error messages (Value of the formula cell is not computed. / Array not computed yet.), so callers could not identify which cell failed.

This PR introduces CellValueNotComputedError with a public address field (SimpleCellAddress) and a message that includes sheet, row, and col. ScalarFormulaVertex.getCellValue and ArrayFormulaVertex.getCellValue now throw this type instead of generic errors.

The class is exported from the package entry (named export and HyperFormula.CellValueNotComputedError static), and the unreleased CHANGELOG documents the behavior change for issue #444.

^{Reviewed by Cursor Bugbot for commit 1879bbb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-131 Verbose and actionable formula error messages

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit da37522. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	hyperformula-docs	1879bbb	Commit Preview URL Branch Preview URL	Sep 15 2026, 08:03 AM

[github-actions]

Performance comparison of head (1879bbb) vs base (e2ced02)

                                     testName |    base |    head |  change
---------------------------------------------------------------------------
                                      Sheet A |  492.38 |  495.18 |  +0.57%
                                      Sheet B |  155.56 |  156.49 |  +0.60%
                                      Sheet T |  139.44 |  136.91 |  -1.81%
                                Column ranges |   466.2 |  468.06 |  +0.40%
                                Sorted lookup | 14051.8 | 13806.5 |  -1.75%
Sheet A:  change value, add/remove row/column |   14.41 |   17.32 | +20.19%
 Sheet B: change value, add/remove row/column |  131.02 |  157.02 | +19.84%
                   Column ranges - add column |  145.92 |  159.83 |  +9.53%
                Column ranges - without batch |  447.95 |  465.54 |  +3.93%
                        Column ranges - batch |  112.34 |   118.1 |  +5.13%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.45%. Comparing base (e2ced02) to head (1879bbb).

Additional details and impacted files

@@                      Coverage Diff                       @@
##           fix/hf-131-rootless-origin    #1766      +/-   ##
==============================================================
+ Coverage                       97.43%   97.45%   +0.01%     
==============================================================
  Files                             195      195              
  Lines                           15862    15868       +6     
  Branches                         3500     3500              
==============================================================
+ Hits                            15455    15464       +9     
+ Misses                            399      396       -3     
  Partials                            8        8              

Files with missing lines	Coverage Δ
src/DependencyGraph/FormulaVertex.ts	86.71% <100.00%> (+2.46%)	⬆️
src/errors.ts	100.00% <100.00%> (ø)
src/index.ts	100.00% <100.00%> (ø)

🚀 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.

[Tobiadefami]

The implementation looks good.