Add async sort variants: sortAsync, sortByAsync, sortDescendingAsync, sortByDescendingAsync, sortWithAsync

The existing sort functions (sort, sortBy, sortDescending, sortByDescending,
sortWith) use Async.RunSynchronously internally, which blocks a thread and
cannot be composed in async workflows without escaping to a thread-pool.

This PR adds five Async<'T[]>-returning counterparts for composing sort
operations inside async { ... } blocks:

  AsyncSeq.sortAsync            : AsyncSeq<'T> -> Async<'T[]>
  AsyncSeq.sortByAsync          : ('T -> 'Key) -> AsyncSeq<'T> -> Async<'T[]>
  AsyncSeq.sortDescendingAsync  : AsyncSeq<'T> -> Async<'T[]>
  AsyncSeq.sortByDescendingAsync: ('T -> 'Key) -> AsyncSeq<'T> -> Async<'T[]>
  AsyncSeq.sortWithAsync        : ('T -> 'T -> int) -> AsyncSeq<'T> -> Async<'T[]>

Each is a thin wrapper over toArrayAsync + Async.map, identical semantics to
the sync counterparts but composable without blocking. 6 new tests added;
all 378 existing tests continue to pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: github-actions[bot]

RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+### 4.12.0
+
+* Added `AsyncSeq.sortAsync` — asynchronous variant of `sort` returning `Async<'T[]>`, avoiding `Async.RunSynchronously` in async workflows.
+* Added `AsyncSeq.sortByAsync` — asynchronous variant of `sortBy` returning `Async<'T[]>`.
+* Added `AsyncSeq.sortDescendingAsync` — asynchronous variant of `sortDescending` returning `Async<'T[]>`.
+* Added `AsyncSeq.sortByDescendingAsync` — asynchronous variant of `sortByDescending` returning `Async<'T[]>`.
+* Added `AsyncSeq.sortWithAsync` — asynchronous variant of `sortWith` returning `Async<'T[]>`.
+
 ### 4.11.0
 
 * Code/Performance: Modernised ~30 API functions to use `mutable` local variables instead of `ref` cells (`!`/`:=` operators). Affected: `tryLast`, `tryFirst`, `tryItem`, `compareWithAsync`, `reduceAsync`, `scanAsync`, `pairwise`, `windowed`, `pickAsync`, `tryPickAsync`, `tryFindIndex`, `tryFindIndexAsync`, `threadStateAsync`, `zipWithAsync`, `zipWithAsyncParallel`, `zipWithAsync3`, `allPairs`, `takeWhileAsync`, `takeUntilSignal`, `skipWhileAsync`, `skipWhileInclusiveAsync`, `skipUntilSignal`, `tryTail`, `splitAt`, `toArrayAsync`, `concatSeq`, `interleaveChoice`, `chunkBySize`, `chunkByAsync`, `mergeChoiceEnum`, `distinctUntilChangedWithAsync`, `emitEnumerator`, `removeAt`, `updateAt`, `insertAt`. This eliminates heap-allocated `ref`-cell objects for these variables, reducing GC pressure in hot paths, and modernises the code style to idiomatic F#.

src/FSharp.Control.AsyncSeq/AsyncSeq.fs

@@ -2244,6 +2244,21 @@ module AsyncSeq =
   let sortWith (comparer:'T -> 'T -> int) (source:AsyncSeq<'T>) : array<'T> =
     toSortedSeq (Array.sortWith comparer) source
 
+  let sortAsync (source:AsyncSeq<'T>) : Async<array<'T>> when 'T : comparison =
+    toArrayAsync source |> Async.map Array.sort
+
+  let sortByAsync (projection:'T -> 'Key) (source:AsyncSeq<'T>) : Async<array<'T>> when 'Key : comparison =
+    toArrayAsync source |> Async.map (Array.sortBy projection)
+
+  let sortDescendingAsync (source:AsyncSeq<'T>) : Async<array<'T>> when 'T : comparison =
+    toArrayAsync source |> Async.map Array.sortDescending
+
+  let sortByDescendingAsync (projection:'T -> 'Key) (source:AsyncSeq<'T>) : Async<array<'T>> when 'Key : comparison =
+    toArrayAsync source |> Async.map (Array.sortByDescending projection)
+
+  let sortWithAsync (comparer:'T -> 'T -> int) (source:AsyncSeq<'T>) : Async<array<'T>> =
+    toArrayAsync source |> Async.map (Array.sortWith comparer)
+
   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

@@ -730,6 +730,26 @@ module AsyncSeq =
     /// large or infinite sequences.
     val sortWith : comparer:('T -> 'T -> int) -> source:AsyncSeq<'T> -> array<'T>
 
+    /// Asynchronously sorts the given async sequence and returns an Async<array<'T>>.
+    /// Prefer this over sortAsync when composing async workflows.
+    val sortAsync : source:AsyncSeq<'T> -> Async<array<'T>> when 'T : comparison
+
+    /// Asynchronously applies a key-generating function to each element of an AsyncSeq and returns
+    /// an Async<array<'T>> ordered by keys. Prefer this over sortBy when composing async workflows.
+    val sortByAsync : projection:('T -> 'Key) -> source:AsyncSeq<'T> -> Async<array<'T>> when 'Key : comparison
+
+    /// Asynchronously sorts the given async sequence in descending order and returns an Async<array<'T>>.
+    /// Prefer this over sortDescending when composing async workflows.
+    val sortDescendingAsync : source:AsyncSeq<'T> -> Async<array<'T>> when 'T : comparison
+
+    /// Asynchronously applies a key-generating function to each element of an AsyncSeq and returns
+    /// an Async<array<'T>> ordered descending by keys. Prefer this over sortByDescending when composing async workflows.
+    val sortByDescendingAsync : projection:('T -> 'Key) -> source:AsyncSeq<'T> -> Async<array<'T>> when 'Key : comparison
+
+    /// Asynchronously sorts the given async sequence using the given comparison function and returns
+    /// an Async<array<'T>>. Prefer this over sortWith when composing async workflows.
+    val sortWithAsync : comparer:('T -> 'T -> int) -> source:AsyncSeq<'T> -> Async<array<'T>>
+
     /// Returns a new async sequence with the elements in reverse order. The entire source
     /// sequence is buffered before yielding any elements, mirroring Seq.rev.
     /// This function should not be used with large or infinite sequences.

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

@@ -3456,6 +3456,47 @@ let ``AsyncSeq.sortWith returns empty array for empty sequence`` () =
   let result = AsyncSeq.sortWith compare AsyncSeq.empty<int>
   Assert.AreEqual([||], result)
 
+// ===== sortAsync / sortByAsync / sortDescendingAsync / sortByDescendingAsync / sortWithAsync =====
+
+[<Test>]
+let ``AsyncSeq.sortAsync sorts in ascending order`` () =
+  let result = AsyncSeq.ofSeq [ 3; 1; 4; 1; 5; 9 ] |> AsyncSeq.sortAsync |> Async.RunSynchronously
+  Assert.AreEqual([| 1; 1; 3; 4; 5; 9 |], result)
+
+[<Test>]
+let ``AsyncSeq.sortAsync returns empty array for empty sequence`` () =
+  let result = AsyncSeq.empty<int> |> AsyncSeq.sortAsync |> Async.RunSynchronously
+  Assert.AreEqual([||], result)
+
+[<Test>]
+let ``AsyncSeq.sortByAsync sorts by projected key`` () =
+  let result =
+    AsyncSeq.ofSeq [ "banana"; "apple"; "cherry" ]
+    |> AsyncSeq.sortByAsync (fun s -> s.Length)
+    |> Async.RunSynchronously
+  Assert.AreEqual([| "apple"; "banana"; "cherry" |], result)
+
+[<Test>]
+let ``AsyncSeq.sortDescendingAsync sorts in descending order`` () =
+  let result = AsyncSeq.ofSeq [ 3; 1; 4; 1; 5 ] |> AsyncSeq.sortDescendingAsync |> Async.RunSynchronously
+  Assert.AreEqual([| 5; 4; 3; 1; 1 |], result)
+
+[<Test>]
+let ``AsyncSeq.sortByDescendingAsync sorts by projected key descending`` () =
+  let result =
+    AsyncSeq.ofSeq [ "apple"; "banana"; "fig" ]
+    |> AsyncSeq.sortByDescendingAsync (fun s -> s.Length)
+    |> Async.RunSynchronously
+  Assert.AreEqual([| "banana"; "apple"; "fig" |], result)
+
+[<Test>]
+let ``AsyncSeq.sortWithAsync sorts using custom comparer`` () =
+  let result =
+    AsyncSeq.ofSeq [ 3; 1; 4; 1; 5 ]
+    |> AsyncSeq.sortWithAsync (fun a b -> compare b a)
+    |> Async.RunSynchronously
+  Assert.AreEqual([| 5; 4; 3; 1; 1 |], result)
+
 // ── AsyncSeq.mapFold ──────────────────────────────────────────────────────────
 
 [<Test>]