Fix approximate lookup type compatibility

[Tobiadefami]

Context

Approximate lookups currently handle values of different types differently depending on the search path.

Breaking change

This change introduces ApproximateMatchPolicy to make cross-type evaluation explicit.

MATCH, VLOOKUP, and HLOOKUP use sameType. Candidates whose type differs from the lookup key are skipped before comparison.

XLOOKUP uses totalOrder for both the linear and binary search paths, so cross-type candidates can be considered when choosing an approximate result.

approximateMatchPolicy is now required in SearchOptions. Existing callers that construct SearchOptions must provide either sameType or totalOrder.

This can change results for approximate lookups over mixed-type data.

How did you test your changes?

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:

1. Fixes #...

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.

---

Note

Medium Risk
Changes core lookup semantics for mixed-type ranges and may alter existing formula results for approximate XLOOKUP vs other lookup functions; risk is localized to MATCH/VLOOKUP/HLOOKUP/XLOOKUP evaluation paths.

Overview
Approximate lookups now take an explicit approximateMatchPolicy on SearchOptions, so linear, column-index, and binary search paths apply the same rules when the lookup value and candidates differ in type.

MATCH, VLOOKUP, and HLOOKUP pass sameType: approximate lower/upper bounds only consider candidates with the same scalar type as the lookup key (cross-type cells are skipped). XLOOKUP passes totalOrder, using the existing compare() ordering across numbers, strings, and booleans to match Excel (e.g. approximate XLOOKUP("a", …) against numeric keys can match).

Implementation updates thread the policy through AdvancedFind.findNormalizedValue, findLastOccurrenceInOrderedRange (via a shared returnApproximateResult gate), and ColumnIndex.find. Linear approximate search no longer seeds bounds with ±Infinity; it tracks the best index with NOT_FOUND until an eligible candidate appears. CHANGELOG and list-of-differences document the behavior.

^{Reviewed by Cursor Bugbot for commit 964a43e. 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	964a43e	Commit Preview URL Branch Preview URL	Aug 28 2026, 11:11 PM

[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.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

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

[github-actions]

Performance comparison of head (964a43e) vs base (114fd5d)

                                     testName |    base |    head |  change
---------------------------------------------------------------------------
                                      Sheet A |  492.88 |  492.13 |  -0.15%
                                      Sheet B |  157.59 |  158.32 |  +0.46%
                                      Sheet T |  138.23 |  139.46 |  +0.89%
                                Column ranges |  531.86 |  522.84 |  -1.70%
                                Sorted lookup | 15703.5 | 15071.2 |  -4.03%
Sheet A:  change value, add/remove row/column |   16.86 |   18.91 | +12.16%
 Sheet B: change value, add/remove row/column |  141.98 |  144.41 |  +1.71%
                   Column ranges - add column |  164.34 |  164.07 |  -0.16%
                Column ranges - without batch |  515.08 |  510.85 |  -0.82%
                        Column ranges - batch |  131.66 |  128.54 |  -2.37%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.33%. Comparing base (114fd5d) to head (964a43e).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1755   +/-   ##
========================================
  Coverage    97.32%   97.33%           
========================================
  Files          195      195           
  Lines        15739    15740    +1     
  Branches      3390     3385    -5     
========================================
+ Hits         15318    15320    +2     
+ Misses         421      420    -1     

Files with missing lines	Coverage Δ
src/Lookup/AdvancedFind.ts	98.03% <100.00%> (ø)
src/Lookup/ColumnIndex.ts	95.74% <100.00%> (-0.03%)	⬇️
src/Lookup/SearchStrategy.ts	100.00% <ø> (ø)
src/interpreter/binarySearch.ts	100.00% <100.00%> (+1.00%)	⬆️
src/interpreter/plugin/LookupPlugin.ts	97.26% <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.