Add AsyncSeq.sortByAsync and sortByDescendingAsync

Adds two new async sorting functions that mirror the existing 'Async' variants
pattern of minByAsync, maxByAsync, and countByAsync:

- sortByAsync: sorts by an async key projection, returning Async<array<'T>>
- sortByDescendingAsync: same but in descending order

Both functions compute each key exactly once per element, then sort.
5 new tests added; all 326 tests pass.

Co-authored-by: Copilot <[email protected]>

Author: github-actions[bot]

RELEASE_NOTES.md

@@ -1,3 +1,8 @@
+### 4.10.1
+
+* Added `AsyncSeq.sortByAsync` — sorts an async sequence by an asynchronous key-generating function, computing each key exactly once and returning a sorted array. Mirrors the `*Async` pattern of `minByAsync`, `maxByAsync`, and `countByAsync`.
+* Added `AsyncSeq.sortByDescendingAsync` — same as `sortByAsync` but orders descending.
+
 ### 4.10.0
 
 * Added `AsyncSeq.withCancellation` — returns a new `AsyncSeq` that passes the given `CancellationToken` to `GetAsyncEnumerator`, overriding whatever token would otherwise be supplied. Mirrors `TaskSeq.withCancellation` and is useful when consuming sequences from libraries (e.g. Entity Framework) that accept a cancellation token through `GetAsyncEnumerator`. Part of ongoing design-parity work with FSharp.Control.TaskSeq (see #277).

src/FSharp.Control.AsyncSeq/AsyncSeq.fs

@@ -2084,6 +2084,20 @@ module AsyncSeq =
   let sortWith (comparer:'T -> 'T -> int) (source:AsyncSeq<'T>) : array<'T> =
     toSortedSeq (Array.sortWith comparer) source
 
+  let sortByAsync (projection:'T -> Async<'Key>) (source:AsyncSeq<'T>) : Async<array<'T>> when 'Key : comparison = async {
+    let! pairs =
+        source
+        |> mapAsync (fun x -> async { let! k = projection x in return (k, x) })
+        |> toArrayAsync
+    return pairs |> Array.sortBy fst |> Array.map snd }
+
+  let sortByDescendingAsync (projection:'T -> Async<'Key>) (source:AsyncSeq<'T>) : Async<array<'T>> when 'Key : comparison = async {
+    let! pairs =
+        source
+        |> mapAsync (fun x -> async { let! k = projection x in return (k, x) })
+        |> toArrayAsync
+    return pairs |> Array.sortByDescending fst |> Array.map snd }
+
   let rev (source: AsyncSeq<'T>) : AsyncSeq<'T> = asyncSeq {
       let! arr = toArrayAsync source
       for i in arr.Length - 1 .. -1 .. 0 do

src/FSharp.Control.AsyncSeq/AsyncSeq.fsi

@@ -663,6 +663,18 @@ module AsyncSeq =
     /// large or infinite sequences.
     val sortByDescending : projection:('T -> 'Key) -> source:AsyncSeq<'T> -> array<'T> when 'Key : comparison
 
+    /// Applies an asynchronous key-generating function to each element of an AsyncSeq and returns
+    /// an array ordered by the computed keys. Each key is computed exactly once per element.
+    /// This function digests the whole initial sequence before returning. As a result this
+    /// function should not be used with large or infinite sequences.
+    val sortByAsync : projection:('T -> Async<'Key>) -> source:AsyncSeq<'T> -> Async<array<'T>> when 'Key : comparison
+
+    /// Applies an asynchronous key-generating function to each element of an AsyncSeq and returns
+    /// an array ordered descending by the computed keys. Each key is computed exactly once per element.
+    /// This function digests the whole initial sequence before returning. As a result this
+    /// function should not be used with large or infinite sequences.
+    val sortByDescendingAsync : projection:('T -> Async<'Key>) -> source:AsyncSeq<'T> -> Async<array<'T>> when 'Key : comparison
+
     /// Sorts the given async sequence using the given comparison function and returns an array.
     /// This function returns an array that digests the whole initial sequence as soon as
     /// that sequence is iterated. As a result this function should not be used with

tests/FSharp.Control.AsyncSeq.Tests/AsyncSeqTests.fs

@@ -3409,8 +3409,56 @@ let ``AsyncSeq.sortWith returns empty array for empty sequence`` () =
   let result = AsyncSeq.sortWith compare AsyncSeq.empty<int>
   Assert.AreEqual([||], result)
 
+// ── AsyncSeq.sortByAsync / sortByDescendingAsync ──────────────────────────────
+
+[<Test>]
+let ``AsyncSeq.sortByAsync sorts ascending by async projection`` () =
+  let source = asyncSeq { yield "banana"; yield "apple"; yield "cherry" }
+  let result =
+    source
+    |> AsyncSeq.sortByAsync (fun s -> async { return s.Length })
+    |> Async.RunSynchronously
+  Assert.AreEqual([| "apple"; "banana"; "cherry" |], result)
+
+[<Test>]
+let ``AsyncSeq.sortByAsync returns empty array for empty sequence`` () =
+  let result =
+    AsyncSeq.empty<int>
+    |> AsyncSeq.sortByAsync (fun x -> async { return x })
+    |> Async.RunSynchronously
+  Assert.AreEqual([||], result)
+
+[<Test>]
+let ``AsyncSeq.sortByAsync computes projection exactly once per element`` () =
+  let callCount = ref 0
+  let source = asyncSeq { yield 3; yield 1; yield 2 }
+  let result =
+    source
+    |> AsyncSeq.sortByAsync (fun x -> async { incr callCount; return x })
+    |> Async.RunSynchronously
+  Assert.AreEqual([| 1; 2; 3 |], result)
+  Assert.AreEqual(3, !callCount)
+
+[<Test>]
+let ``AsyncSeq.sortByDescendingAsync sorts descending by async projection`` () =
+  let source = asyncSeq { yield "hi"; yield "apple"; yield "cherry" }
+  let result =
+    source
+    |> AsyncSeq.sortByDescendingAsync (fun s -> async { return s.Length })
+    |> Async.RunSynchronously
+  Assert.AreEqual([| "cherry"; "apple"; "hi" |], result)
+
+[<Test>]
+let ``AsyncSeq.sortByDescendingAsync returns empty array for empty sequence`` () =
+  let result =
+    AsyncSeq.empty<int>
+    |> AsyncSeq.sortByDescendingAsync (fun x -> async { return x })
+    |> Async.RunSynchronously
+  Assert.AreEqual([||], result)
+
 // ── AsyncSeq.mapFold ──────────────────────────────────────────────────────────
 
+
 [<Test>]
 let ``AsyncSeq.mapFold maps elements and accumulates state`` () =
   let source = asyncSeq { yield 1; yield 2; yield 3 }