fix: an empty string is no longer coerced to 0 in numeric contexts (HF-361)

[marcin-kordas-hoc]

What

An empty string ('') was unconditionally coerced to 0 in numeric contexts. This aligns HyperFormula with Excel, where "" is text and is never a number.

ArithmeticHelper.coerceNonDateScalarToMaybeNumber carried an arg === '' → return 0 early exit. Removing it lets '' fall through to normal string→number parsing, which correctly finds no number. Blank cells are a different internal value (EmptyValue, handled one branch above) and are untouched — evaluateNullToZero keeps working exactly as before.

Reported by a customer via support: COUNT("") returned 1 where Excel returns 0, and =""+0 returned 0 where Excel returns #VALUE!. The reporter had already verified in Excel Online that both cases error there, and had ruled out every config option as a workaround (there is none — the behaviour was hardcoded).

What changes, and what does not

The distinction that matters for anyone reading this to estimate impact: aggregation over a cell reference or a range does not change. SUM, AVERAGE, MIN, MAX and COUNT have always ignored text found in a reference, and they still do, because the aggregation path filters strings out (strictlyNumbers) before this coercion is reached. Every value below is measured on both engines; the Excel column is measured live through the Microsoft Graph API against Excel Online.

Changes — arithmetic and number-typed arguments, in both the literal and the reference form (A1 holds an empty string):

Formula	Excel	before	after
=""+0 / =A1+1	#VALUE!	0 / 1	#VALUE!
=A1-1, =1-A1, =A1*2, =A1/1, =A1^2, =-A1, =A1%	#VALUE!	numbers	#VALUE!
=ROUND(A1, 0), =ABS(A1), =INT("")	#VALUE!	0	#VALUE!
=ACOT("") / =ACOT(A1)	#VALUE!	1.5707963268	#VALUE!
=DATE(A1, 2, 3)	#VALUE!	35	#VALUE!
=LN(""), =LOG10(""), =DATE("","","")	#VALUE!	#NUM!	#VALUE!
=COT(""), =COTH("")	#VALUE!	#DIV/0!	#VALUE!

Changes — an empty string written directly into an aggregation:

Formula	Excel	before	after
=COUNT("")	0	1	0
=SUM(""), =AVERAGE(""), =MIN(""), =MAX(""), =PRODUCT("")	#VALUE!	0	#VALUE!
=SUM(1, "")	#VALUE!	1	#VALUE!
=SUMSQ(""), =MEDIAN(""), =STDEV("")	#VALUE!	0 / #DIV/0!	#VALUE!

Changes for the better — an empty string produced mid-formula. This is the most common real shape of the bug, and the strongest argument for the change: before, all of these were wrong; now all match Excel.

Formula	Excel	before	after
=SUM(IF(TRUE,"",1))	#VALUE!	0	#VALUE!
=COUNT(IF(TRUE,"",1))	0	1	0
=SUM(LEFT("abc",0)), =LEFT("abc",0)+1	#VALUE!	0 / 1	#VALUE!
=ROUND(IF(TRUE,"",1),0), =SUM(A1&""), =SUM(CONCATENATE("",""))	#VALUE!	numbers	#VALUE!

Does not change — measured identical before and after, and matching Excel:

Formula	Excel	before and after
=SUM(A1), =MIN(A1), =MAX(A1), =COUNT(A1)	0	0
=AVERAGE(A1)	#DIV/0!	#DIV/0!
=COUNTA(A1)	1	1
=SUM(A1:C1) over 1, "", 2	3	3
=COUNT(A1:C1) over the same	2	2
=SUM({1,"",2}), =COUNT({1,"",2})	3, 2	3, 2
a blank cell, either evaluateNullToZero setting	—	unchanged
=COUNTIF(rng,""), =A1&"x", =A1="", =N(A1), =VALUE(A1)	—	unchanged

One class that moves away from Excel

Where Excel evaluates an argument as an array containing only text, it ignores the text; before, HyperFormula happened to agree by coercing '' to 0:

Formula	Excel	before	after
=SUM(IF(A1:A3>0,"",A1:A3))	0	0	#VALUE!
=SUM({""})	0	0	#VALUE!
=COUNT(IF({1,0},"",5))	1	1	0

That agreement was coincidence, not support: HyperFormula's IF is not array-aware at all — =ROWS(IF(A1:A3>0,"",A1:A3)) is 1, so it collapses the argument to a single value regardless. The idiom is already broken independently of this change: =SUM(IF(A1:A3>5,"",A1:A3)) over 1, 2, 3 is 6 in Excel and 1 here, before and after. What changes is only that the collapsed value stops being silently read as 0. Worth its own ticket; not a reason to hold this one.

Integration risk, and a design question worth answering first

setCellContents(address, '') produces a text cell holding '' (STRING, ISBLANK false), not a blank one — only null/undefined produce a blank. Verified against the Handsontable Formulas plugin on the published package:

• Clearing cells with Delete is safe — core.js's emptySelectedCells pushes null.
• Paste is a real exposure — SheetClip.parse('a\t\tc') yields ["a","","c"], copyPaste.js feeds that to populateFromArray, and formulas.js's syncChangeWithEngine forwards to setCellContents with only date-specific normalisation. Nothing maps '' back to null.

Scope of that exposure, though, is narrower than it first looks: for a pasted '' cell, SUM and COUNT are unaffected — only arithmetic and number-typed arguments break.

The design question: should a written '' parse as EmptyValue rather than as text? That would fix the reported bug and remove the paste exposure at the same time, at the cost of a different divergence (ISTEXT, COUNTA and LEN on such a cell). This PR takes the narrower route — fix the coercion, leave cell parsing alone — but the alternative deserves an explicit yes or no before a breaking change ships.

Verification

• Paired tests: handsontable/hyperformula-tests#53, 27 new specs plus 8 assertions that pinned the old behaviour across coercions, function-ln, function-log10, function-cot, function-coth, function-acot and function-date (function-log changes an input, not an expectation).
• Full private suite green: 503/503 suites, 6271 passed, 3 skipped.
• Negative control: with this fix reverted, 16 of the 27 new specs fail — the spec detects the bug rather than passing vacuously.
• Excel column measured live via MS Graph (Excel Online); probe scripts and raw JSON retained.
• CI green, including browser-tests — the private suite runs under both Jest and Karma/Jasmine.

Definition of Done

• Production code + JSDoc explaining why '' is deliberately not special-cased
• Changelog entry under Changed as a breaking change
• Migration guide section (docs/guide/migration-from-3.x-to-4.0.md)
• Paired tests in hyperformula-tests
• Green CI

Note: this targets 4.0 and adds docs/guide/migration-from-3.x-to-4.0.md, the same new file #1754 creates. Whichever lands first establishes it; the second resolves a mechanical conflict.

🤖 Generated with Claude Code

---

Note

High Risk
Breaking formula semantics across arithmetic and numeric functions; sheets that relied on "" as zero or store '' in cells will see different results, though range aggregations are largely unchanged.

Overview
This is a breaking 4.0 change that stops treating an empty string ("") as 0 in numeric contexts, matching Excel: arithmetic, number-typed function arguments, and literals passed directly into aggregations (e.g. =""+0, =ROUND(A1,0) with text "", =COUNT(""), =SUM(1,"")) now yield #VALUE! or updated counts instead of silently using zero. Blank cells (EmptyValue, null/undefined in the API) are unchanged, and aggregations over cell/range references still skip non-numeric text the same way as before.

ArithmeticHelper.coerceNonDateScalarToMaybeNumber drops the '' → 0 shortcut so empty text falls through normal parsing and callers surface #VALUE!. NumericAggregationPlugin.reduce unwraps parenthesized references so SUM((A1)) follows the reference path (ignore text) like Excel, not the literal-coercion path.

Documentation adds an Unreleased changelog entry, a 3.x → 4.0 migration guide (including setCellContents(..., null) vs ''), and a docs nav link.

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

[qunabu]

Task linked: HF-361 COUNT("") and empty-string arithmetic return different results than Excel

[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	Updated (UTC)
❌ Deployment failed View logs	hyperformula-docs	a24a523	Sep 23 2026, 07:04 AM

[github-actions]

Performance comparison of head (a24a523) vs base (c920375)

                                     testName |    base |    head | change
--------------------------------------------------------------------------
                                      Sheet A |  494.85 |  491.69 | -0.64%
                                      Sheet B |  163.06 |   158.8 | -2.61%
                                      Sheet T |  145.47 |   144.7 | -0.53%
                                Column ranges |  477.59 |  476.78 | -0.17%
                                Sorted lookup | 14323.2 | 14483.2 | +1.12%
Sheet A:  change value, add/remove row/column |   15.58 |   15.38 | -1.28%
 Sheet B: change value, add/remove row/column |  133.83 |  123.43 | -7.77%
                   Column ranges - add column |   152.5 |  144.33 | -5.36%
                Column ranges - without batch |  464.58 |  439.46 | -5.41%
                        Column ranges - batch |  119.26 |  112.27 | -5.86%

[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 c99427b. Configure here.}

[cursor]

Redundant migration guide search tags

Low Severity

Tags empty string and coercion repeat the h2 Changes to empty string coercion, which search already indexes from headings. The multi-word empty string tag also matches empty and string separately, so generic queries can surface this migration page.

 

^{Triggered by learned rule: VuePress tags frontmatter invariants}

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

[Tobiadefami]

Could we preserve reference handling through parentheses? With B1 containing ="", =SUM((B1)) returns 0 in Excel Online and on base, but #VALUE! on this head.

A possible fix is to recursively look through parentheses when checking for CELL_REFERENCE in NumericAggregationPlugin.reduce(). I tested this temporarily: it fixes the regression while preserving rejection of literal empty strings. All 195 tests across 16 checked suites passed.

[marcin-kordas-hoc]

@Tobiadefami reproduced and fixed — thanks for catching it, and sorry it sat this long.

SUM((B1)) was going through the same numeric-coercion path a literal gets, because (B1) reaches NumericAggregationPlugin#reduce as a PARENTHESIS AST node wrapping the CELL_REFERENCE, and the reducer's reference check only matched a bare CELL_REFERENCE node. Fixed by unwrapping PARENTHESIS before that check — the same pattern already used in FunctionPlugin#runFunctionWithReferenceArgument and InformationPlugin — so it's a one-line fix at a single shared choke point rather than a per-function patch.

That choke point (reduce()) is the shared implementation behind the whole numeric-aggregation family, not just SUM: COUNT, AVERAGE, MIN, MAX, PRODUCT, SUMSQ, STDEV.S/P (and their A-suffixed variants) all reproduced the identical #VALUE! regression through one extra pair of parentheses, and all are fixed by this single change. MIN/MAX weren't in your report but I checked them too since they share reduce() — same bug, same fix.

Verified against Excel Online (MS Graph, live session): parentheses are fully transparent to reference handling in every case I measured — single and double parens, the whole aggregation family, and a parenthesized range containing an embedded "". Your reading was exactly right.

Added 8 specs to the paired repo (empty-string-coercion.spec.ts), written and confirmed failing against the previous head before the fix existed, passing after, and reconfirmed failing with the source fix reverted and the tests kept (negative control). Local Jest: 503/503 suites, 6279 passing.

One caveat I want to be explicit about: I could not run the Karma/Jasmine browser leg locally — no headless browser in my environment — so I pushed rather than claim it green. CI is running it now on a24a523dd; please treat the browser result there as the real verdict, not my local run.

MEDIAN does not share this bug (different code path, no reference-detection special case at all) — flagging separately rather than folding it in here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.32%. Comparing base (c920375) to head (a24a523).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1768   +/-   ##
========================================
  Coverage    97.32%   97.32%           
========================================
  Files          195      195           
  Lines        15739    15739           
  Branches      3390     3460   +70     
========================================
  Hits         15318    15318           
+ Misses         421      413    -8     
- Partials         0        8    +8     

Files with missing lines	Coverage Δ
src/interpreter/ArithmeticHelper.ts	98.66% <ø> (-0.01%)	⬇️
src/interpreter/plugin/NumericAggregationPlugin.ts	97.47% <100.00%> (+0.01%)	⬆️

... and 5 files 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.