fix: preserve zero results from AVERAGEIF

[Tobiadefami]

Context

AVERAGEIF returned a #DIV/0! error when matching values produced a valid average of 0.

This happened because the result used a logical OR fallback, which treated 0 as if no average had been
calculated. This change uses nullish coalescing so that only an absent result produces #DIV/0!, while a
valid zero is returned normally.

How did you test your changes?

Added a regression test where the matching values are -1 and 1, producing an average of 0.

The test was verified to fail with #DIV/0! before the fix and pass with 0 after the fix.

I also ran:

• The focused AVERAGEIF test suite: all 14 tests passed.
• npm run bundle:cjs: TypeScript and the CommonJS build completed successfully.
• Targeted linting: no errors.

Types of changes

• Breaking change (a fix or a feature because of which an existing functionality doesn't work as
  expected anymore)
• New feature or improvement (a non-breaking change that adds functionality)
• Bug fix (a non-breaking change that fixes an issue)
• Additional language file, or a change to an existing language file (translations)
• Change to the documentation

Related issues:

None.

Checklist:

• I have reviewed the guidelines about [Contributing to HyperFormula](https://
  hyperformula.handsontable.com/guide/contributing.html) 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](https://docs.oasis-open.org/office/OpenDocument/v1.3/
  os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard.
• My change is compatible with Microsoft Excel.
• My change is compatible with Google Sheets.
• I described my changes in the [CHANGELOG.md](https://github.com/handsontable/hyperformula/blob/master/
  CHANGELOG.md) file.
• My changes require a documentation update.
• My changes require a migration guide.

---

Note

Low Risk
Single-operator change in AVERAGEIF result handling with no impact on auth, data, or broader aggregation APIs.

Overview
AVERAGEIF now returns 0 when the conditional average is legitimately zero, instead of incorrectly surfacing #DIV/0!.

The bug came from using logical OR (||) after averageValue(): a computed average of 0 was treated like a missing result. ConditionalAggregationPlugin switches that fallback to nullish coalescing (??), so only undefined (no matching numeric cells / zero count) still maps to #DIV/0!. CHANGELOG documents the fix under Unreleased.

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

[cla-external-contractor-signup]

@Tobiadefami thanks for the pull request. No CLA step needed here — our records show you signed the Contributor License Agreement on 2026-07-31. That signature came from our previous signing form and has been carried over, so there is nothing for you to re-sign.

[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	2eb85e9	Commit Preview URL Branch Preview URL	Sep 02 2026, 10:45 AM

[github-actions]

Performance comparison of head (2eb85e9) vs base (50e7170)

                                     testName |    base |    head |  change
---------------------------------------------------------------------------
                                      Sheet A |  447.61 |     529 | +18.18%
                                      Sheet B |   137.2 |  179.41 | +30.77%
                                      Sheet T |  122.99 |  156.54 | +27.28%
                                Column ranges |  583.41 |  675.91 | +15.86%
                                Sorted lookup | 16772.7 | 18157.2 |  +8.25%
Sheet A:  change value, add/remove row/column |   13.04 |   13.34 |  +2.30%
 Sheet B: change value, add/remove row/column |  126.94 |  119.83 |  -5.60%
                   Column ranges - add column |  159.76 |  153.62 |  -3.84%
                Column ranges - without batch |  513.84 |  477.07 |  -7.16%
                        Column ranges - batch |  149.42 |  115.89 | -22.44%

[marcin-kordas-hoc]

Approving. Verified rather than eyeballed:

• Differential check of the fix: the same formulas that return 0 on this head return #DIV/0! on clean develop, so || → ?? does exactly what the description claims and nothing more. A genuine no-match case (=AVERAGEIF(A1:A2,">100")) still correctly returns #DIV/0!, so the fallback is not weakened.
• Paired tests (hyperformula-tests fix/averageif-zero-average, b163c40) run green against this head: 14/14 in function-averageif.spec.ts. The regression test is non-vacuous — it fails on develop without this fix.
• CHANGELOG entry present and linked, scope limited to the one expression.

Known and deliberately out of scope: AVERAGEIF's mapFunction still drops CellError values from matching rows (unlike AVERAGEIFS, which propagates them). That is the separate item we settled in the thread on #1732 — not a blocker here.

Note that merging still waits for the freeze to lift.

[codecov]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1733   +/-   ##
========================================
  Coverage    97.32%   97.32%           
========================================
  Files          195      195           
  Lines        15739    15739           
  Branches      3390     3390           
========================================
  Hits         15318    15318           
  Misses         421      421           

Files with missing lines	Coverage Δ
...interpreter/plugin/ConditionalAggregationPlugin.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.