Add AsyncSeq.head, iteri, find, tryFindAsync, tail

Five new combinators mirroring standard F# module functions:
- head: returns first element; raises InvalidOperationException on empty (mirrors Seq.head)
- iteri: sync iteration with element index exposed in .fsi (was already implemented but not exported)
- find: returns first matching element; raises KeyNotFoundException if no match (mirrors Seq.find)
- tryFindAsync: async-predicate variant of tryFind, returning option
- tail: returns sequence without first element (mirrors Seq.tail / List.tail)

11 new tests added; all 248 tests pass.

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

Author: 2 people

RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+### 4.3.0
+
+* Added `AsyncSeq.head` — returns the first element of the sequence; raises `InvalidOperationException` if empty, mirroring `Seq.head`.
+* Added `AsyncSeq.iteri` — iterates the sequence calling a synchronous action with each element's index, mirroring `Seq.iteri`.
+* Added `AsyncSeq.find` — returns the first element satisfying a predicate; raises `KeyNotFoundException` if no match, mirroring `Seq.find`.
+* Added `AsyncSeq.tryFindAsync` — async-predicate variant of `AsyncSeq.tryFind`, returning the first matching element as `option`.
+* Added `AsyncSeq.tail` — returns the sequence without its first element, mirroring `Seq.tail`.
+
 ### 4.2.0
 
 * Added `AsyncSeq.zip3`, `AsyncSeq.zipWith3`, and `AsyncSeq.zipWithAsync3` — combinators for zipping three async sequences, mirroring `Seq.zip3` ([PR #254](https://github.com/fsprojects/FSharp.Control.AsyncSeq/pull/254)).

src/FSharp.Control.AsyncSeq/AsyncSeq.fs

@@ -1060,6 +1060,12 @@ module AsyncSeq =
       | None -> return def
       | Some v -> return v }
 
+  let head (source : AsyncSeq<'T>) = async {
+      let! result = tryFirst source
+      match result with
+      | None -> return raise (System.InvalidOperationException("The input sequence was empty."))
+      | Some v -> return v }
+
   let exactlyOne (source : AsyncSeq<'T>) = async {
       use ie = source.GetEnumerator()
       let! first = ie.MoveNext()
@@ -1168,6 +1174,12 @@ module AsyncSeq =
   let tryFind f (source : AsyncSeq<'T>) =
     source |> tryPick (fun v -> if f v then Some v else None)
 
+  let tryFindAsync f (source : AsyncSeq<'T>) =
+    source |> tryPickAsync (fun v -> async { let! b = f v in return if b then Some v else None })
+
+  let find f (source : AsyncSeq<'T>) =
+    source |> pick (fun v -> if f v then Some v else None)
+
   let exists f (source : AsyncSeq<'T>) =
     source |> tryFind f |> Async.map Option.isSome
 
@@ -1715,6 +1727,8 @@ module AsyncSeq =
           let! moven = ie.MoveNext()
           b := moven }
 
+  let tail (source : AsyncSeq<'T>) : AsyncSeq<'T> = skip 1 source
+
   let toArrayAsync (source : AsyncSeq<'T>) : Async<'T[]> = async {
       let ra = (new ResizeArray<_>())
       use ie = source.GetEnumerator()

src/FSharp.Control.AsyncSeq/AsyncSeq.fsi

@@ -163,6 +163,10 @@ module AsyncSeq =
     /// given asynchronous sequence (or None if the sequence is empty).
     val tryFirst : source:AsyncSeq<'T> -> Async<'T option>
 
+    /// Asynchronously returns the first element of the asynchronous sequence.
+    /// Raises InvalidOperationException if the sequence is empty.
+    val head : source:AsyncSeq<'T> -> Async<'T>
+
     /// Asynchronously returns the only element of the asynchronous sequence.
     /// Raises InvalidOperationException if the sequence is empty or contains more than one element.
     val exactlyOne : source:AsyncSeq<'T> -> Async<'T>
@@ -189,6 +193,10 @@ module AsyncSeq =
     /// The input sequence will be asked for the next element after the processing of an element completes.
     val iteriAsync : action:(int -> 'T -> Async<unit>) -> source:AsyncSeq<'T> -> Async<unit>
 
+    /// Iterates over the input sequence and calls the specified function for
+    /// every value, passing along the index of that element.
+    val iteri : action:(int -> 'T -> unit) -> source:AsyncSeq<'T> -> Async<unit>
+
     #if !FABLE_COMPILER
     /// Iterates over the input sequence and calls the specified asynchronous function for
     /// every value. Each action computation is started but not awaited before consuming
@@ -312,6 +320,13 @@ module AsyncSeq =
     /// Asynchronously find the first value in a sequence for which the predicate returns true
     val tryFind : predicate:('T -> bool) -> source:AsyncSeq<'T> -> Async<'T option>
 
+    /// Asynchronously find the first value in a sequence for which the async predicate returns true
+    val tryFindAsync : predicate:('T -> Async<bool>) -> source:AsyncSeq<'T> -> Async<'T option>
+
+    /// Asynchronously find the first value in a sequence for which the predicate returns true.
+    /// Raises KeyNotFoundException if no matching element is found.
+    val find : predicate:('T -> bool) -> source:AsyncSeq<'T> -> Async<'T>
+
     /// Asynchronously determine if there is a value in the sequence for which the predicate returns true
     val exists : predicate:('T -> bool) -> source:AsyncSeq<'T> -> Async<bool>
 
@@ -517,6 +532,10 @@ module AsyncSeq =
     /// then returns the rest of the sequence unmodified.
     val skip : count:int -> source:AsyncSeq<'T> -> AsyncSeq<'T>
 
+    /// Returns an asynchronous sequence that skips the first element of the input sequence.
+    /// Returns an empty sequence if the source is empty.
+    val tail : source:AsyncSeq<'T> -> AsyncSeq<'T>
+
     /// Creates an async computation which iterates the AsyncSeq and collects the output into an array.
     val toArrayAsync : source:AsyncSeq<'T> -> Async<'T []>
 

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

@@ -3046,3 +3046,98 @@ let ``AsyncSeq.tryExactlyOne returns None for sequence with more than one elemen
     let result = AsyncSeq.tryExactlyOne source |> Async.RunSynchronously
     Assert.AreEqual(None, result)
   } |> Async.RunSynchronously
+
+// ===== head =====
+
+[<Test>]
+let ``AsyncSeq.head returns first element`` () =
+  let source = asyncSeq { yield 42; yield 99 }
+  let result = AsyncSeq.head source |> Async.RunSynchronously
+  Assert.AreEqual(42, result)
+
+[<Test>]
+let ``AsyncSeq.head raises on empty sequence`` () =
+  Assert.Throws<InvalidOperationException>(fun () ->
+    AsyncSeq.head AsyncSeq.empty<int> |> Async.RunSynchronously |> ignore) |> ignore
+
+// ===== iteri =====
+
+[<Test>]
+let ``AsyncSeq.iteri calls action with correct indices`` () =
+  let indices = System.Collections.Generic.List<int>()
+  let values  = System.Collections.Generic.List<int>()
+  asyncSeq { yield 10; yield 20; yield 30 }
+  |> AsyncSeq.iteri (fun i v -> indices.Add(i); values.Add(v))
+  |> Async.RunSynchronously
+  Assert.AreEqual([| 0; 1; 2 |], indices |> Seq.toArray)
+  Assert.AreEqual([| 10; 20; 30 |], values |> Seq.toArray)
+
+[<Test>]
+let ``AsyncSeq.iteri on empty sequence does nothing`` () =
+  let mutable count = 0
+  AsyncSeq.empty<int>
+  |> AsyncSeq.iteri (fun _ _ -> count <- count + 1)
+  |> Async.RunSynchronously
+  Assert.AreEqual(0, count)
+
+// ===== find / tryFindAsync =====
+
+[<Test>]
+let ``AsyncSeq.find returns matching element`` () =
+  for i in 0 .. 10 do
+    let ls = [ 1 .. i + 1 ]
+    let result = AsyncSeq.ofSeq ls |> AsyncSeq.find (fun x -> x = i + 1) |> Async.RunSynchronously
+    Assert.AreEqual(i + 1, result)
+
+[<Test>]
+let ``AsyncSeq.find raises KeyNotFoundException when no match`` () =
+  Assert.Throws<System.Collections.Generic.KeyNotFoundException>(fun () ->
+    AsyncSeq.ofSeq [ 1; 2; 3 ] |> AsyncSeq.find (fun x -> x = 99) |> Async.RunSynchronously |> ignore)
+  |> ignore
+
+[<Test>]
+let ``AsyncSeq.tryFindAsync returns Some when found`` () =
+  for i in 0 .. 10 do
+    let ls = [ 1 .. i + 1 ]
+    let result =
+      AsyncSeq.ofSeq ls
+      |> AsyncSeq.tryFindAsync (fun x -> async { return x = i + 1 })
+      |> Async.RunSynchronously
+    Assert.AreEqual(Some (i + 1), result)
+
+[<Test>]
+let ``AsyncSeq.tryFindAsync returns None when not found`` () =
+  let result =
+    AsyncSeq.ofSeq [ 1; 2; 3 ]
+    |> AsyncSeq.tryFindAsync (fun x -> async { return x = 99 })
+    |> Async.RunSynchronously
+  Assert.AreEqual(None, result)
+
+// ===== tail =====
+
+[<Test>]
+let ``AsyncSeq.tail skips first element`` () =
+  let result =
+    asyncSeq { yield 1; yield 2; yield 3 }
+    |> AsyncSeq.tail
+    |> AsyncSeq.toListAsync
+    |> Async.RunSynchronously
+  Assert.AreEqual([ 2; 3 ], result)
+
+[<Test>]
+let ``AsyncSeq.tail on singleton returns empty`` () =
+  let result =
+    asyncSeq { yield 42 }
+    |> AsyncSeq.tail
+    |> AsyncSeq.toListAsync
+    |> Async.RunSynchronously
+  Assert.AreEqual([], result)
+
+[<Test>]
+let ``AsyncSeq.tail on empty returns empty`` () =
+  let result =
+    AsyncSeq.empty<int>
+    |> AsyncSeq.tail
+    |> AsyncSeq.toListAsync
+    |> Async.RunSynchronously
+  Assert.AreEqual([], result)