feat: implement SORT dynamic array function (HF-69)#1707
Open
marcin-kordas-hoc wants to merge 1 commit into
Open
feat: implement SORT dynamic array function (HF-69)#1707marcin-kordas-hoc wants to merge 1 commit into
marcin-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. |
Contributor
|
Task linked: HF-28 Modern dynamic array functions |
marcin-kordas-hoc
force-pushed
the
feature/HF-69-sort
branch
from
July 13, 2026 18:48
5648f53 to
05389bf
Compare
7 tasks
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Performance comparison of head (2fe6a40) vs base (fd04f77) |
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
July 18, 2026 15:26
05389bf to
2fe6a40
Compare
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 2fe6a40. Configure here.
| {argumentType: FunctionArgumentType.BOOLEAN, defaultValue: false, emptyAsDefault: true}, | ||
| ], | ||
| vectorizationForbidden: true, | ||
| }, |
There was a problem hiding this comment.
Missing array arithmetic flag
Medium Severity
SORT omits enableArrayArithmeticForArguments: true, unlike sibling array functions FILTER, VSTACK, and HSTACK. With the default useArrayArithmetic: false, array expressions passed as the first argument are coerced as scalars and fail, so computed arrays cannot be sorted without a global config change or an ARRAYFORMULA wrapper.
Reviewed by Cursor Bugbot for commit 2fe6a40. Configure here.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## develop #1707 +/- ##
===========================================
- Coverage 97.17% 96.87% -0.30%
===========================================
Files 176 177 +1
Lines 15483 15539 +56
Branches 3429 3441 +12
===========================================
+ Hits 15045 15054 +9
- Misses 438 485 +47
🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
Note
Medium Risk
New formula surface in the interpreter with array spill sizing and comparison semantics; mistakes could affect many spreadsheets, but the change is isolated to a new plugin following established SEQUENCE/FILTER patterns.
Overview
Adds Excel-style SORT as a dynamic array function:
SORT(Array, [SortIndex], [SortOrder], [ByCol])returns a spilled range with the same shape as the input, sorting rows (default) or columns by a single 1-based key.Implementation is a new
SortPluginwired like other array functions (sizeOfResultArrayMethod,vectorizationForbidden), with parse-time size matching the input array (freshArraySizeso spills are not collapsed). Runtime sorting usesArithmeticHelperlt/gtfor stable ascending/descending order; invalidsort_order(only1/-1) orsort_index, non-finite numbers, and the first in-rangeCellErrorare handled per the ADR.Also updates CHANGELOG, built-in functions and known limitations (single-key only, strict sort order, HF comparison rules), registers the plugin in
plugin/index.ts, addsSORTto all 17 i18n packs, and documents SORT/UNIQUE decisions in a shared ADR (UNIQUE is out of scope for this PR).Reviewed by Cursor Bugbot for commit 2fe6a40. Bugbot is set up for automated code reviews on this repo. Configure here.