feat: implement SORT dynamic array function (HF-69)#1707
feat: implement SORT dynamic array function (HF-69)#1707marcin-kordas-hoc wants to merge 1 commit into
Conversation
✅ Deploy Preview for hyperformula-dev-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Task linked: HF-28 Modern dynamic array functions |
Add SORT(array, [sort_index], [sort_order], [by_col]) as a dynamic array
function, mirroring the SEQUENCE/FILTER machinery. Ordering reuses
ArithmeticHelper (mixed types, empties, collation) and is stable, so ties
keep input order. sort_order is validated strictly to {1,-1}; sort_index is
bounds-checked; errors in the input range propagate. Output shape equals the
input shape.
Includes i18n for all 17 language packs, docs (built-in-functions,
known-limitations), a changelog entry, and the shared ADR.
Source: https://app.clickup.com/t/86c89q1tt
ADR: docs/adr/2026-07-13-sort-unique-array-functions.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
marcin-kordas-hoc
force-pushed
the
feature/HF-69-sort
branch
from
5648f53 to
05389bf
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 05389bf. Configure here.
| r1[keyIndex] as InternalNoErrorScalarValue, | ||
| r2[keyIndex] as InternalNoErrorScalarValue, | ||
| )) | ||
| return SimpleRangeValue.onlyValues(rows) |
There was a problem hiding this comment.
Empty sort result crashes evaluation
High Severity
When the input range has zero height (for example inverted endpoints like B2:B1), the row-sort path builds an empty rows array and passes it to SimpleRangeValue.onlyValues. That constructor reads _data[0].length, so evaluation throws an uncaught TypeError instead of returning a sorted range or a cell error. Excel treats inverted ranges as normalized spans, so this is a plausible user input.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit 05389bf. Configure here.
Performance comparison of head (05389bf) vs base (033f8ac) |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## develop #1707 +/- ##
===========================================
+ Coverage 97.15% 97.17% +0.01%
===========================================
Files 176 177 +1
Lines 15404 15460 +56
Branches 3409 3421 +12
===========================================
+ Hits 14966 15023 +57
+ Misses 438 437 -1
🚀 New features to boost your workflow:
|
2 participants
What & why
Implements SORT (
HF-69, child of HF-28 "Modern dynamic array functions", sibling of the shipped SEQUENCE and of VSTACK/HSTACK). AddsSORT(array, [sort_index], [sort_order], [by_col])as a dynamic array function.Tests: handsontable/hyperformula-tests#24 (paired).
Sibling PR: #1708 (UNIQUE / HF-68).
ADR:
docs/adr/2026-07-13-sort-unique-array-functions.md.Behavior
sort_index(default 1): 1-based index into the sort dimension.sort_order:1ascending (default) or-1descending.by_col:FALSE(default) reorders rows;TRUEreorders columns.ArithmeticHelper(mixed types: numbers < text < logical; empties; locale collation viacaseSensitive/accentSensitive) and is stable — ties keep input order.Design
Mirrors the SEQUENCE/FILTER machinery:
sizeOfResultArrayMethod+vectorizationForbidden: true, runtime viarunFunctionreturningSimpleRangeValue/CellError, parse-time size method returning a freshArraySize(the input'sisRefflag is dropped — a ref-flagged size is treated as scalar and would collapse the spill).Notes — divergences from Excel (surfaced here + inline + in tests)
sort_orderis strictly{1, -1}; any other value →#VALUE!. Excel documents only{1,-1}; the reported "sort_order=0does not error" quirk is undocumented and could not be re-verified against live Excel in this environment, so the strict documented contract was chosen (see ADRdec_2,con_1). Flagged for live-Excel/Kuba confirmation.sort_index(e.g.{1,2}) is not supported in v1 (documented inknown-limitations.md; ADRdec_6).dec_7).Error-type map
sort_order ∉ {1,-1}→#VALUE!(BadMode) ·sort_index < 1→#VALUE!(LessThanOne) ·sort_index >dimension →#VALUE!(ValueLarge) · in-range error → propagate · wrong arity →#N/A.Definition of Done
SortPlugin.ts, registered viaplugin/index.ts)built-in-functions.md,known-limitations.mdSource: https://app.clickup.com/t/86c89q1tt