Add AsyncSeq.isEmpty, tryHead, except

- isEmpty: checks if sequence has no elements; short-circuits after the first
- tryHead: returns first element as option (mirrors Seq.tryHead / alias for tryFirst)
- except: filters out elements present in a given collection (mirrors Seq.except)

All 276 tests pass (267 pre-existing + 9 new).

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

Author: github-actions[bot]

RELEASE_NOTES.md

@@ -1,3 +1,9 @@
+### 4.6.0
+
+* Added `AsyncSeq.isEmpty` — returns `true` if the sequence contains no elements; short-circuits after the first element, mirroring `Seq.isEmpty`.
+* Added `AsyncSeq.tryHead` — returns the first element as `option`, or `None` if the sequence is empty, mirroring `Seq.tryHead` (equivalent to the existing `AsyncSeq.tryFirst`).
+* Added `AsyncSeq.except` — returns a new sequence excluding all elements present in a given collection, mirroring `Seq.except`.
+
 ### 4.5.0
 
 * Added `AsyncSeq.last` — returns the last element of the sequence; raises `InvalidOperationException` if empty, mirroring `Seq.last`.

src/FSharp.Control.AsyncSeq/AsyncSeq.fs

@@ -1066,6 +1066,13 @@ module AsyncSeq =
       | None -> return raise (System.InvalidOperationException("The input sequence was empty."))
       | Some v -> return v }
 
+  let tryHead (source : AsyncSeq<'T>) = tryFirst source
+
+  let isEmpty (source : AsyncSeq<'T>) = async {
+      use ie = source.GetEnumerator()
+      let! v = ie.MoveNext()
+      return v.IsNone }
+
   let last (source : AsyncSeq<'T>) = async {
       let! result = tryLast source
       match result with
@@ -1381,6 +1388,10 @@ module AsyncSeq =
   let filter f (source : AsyncSeq<'T>) =
     filterAsync (f >> async.Return) source
 
+  let except (excluded : seq<'T>) (source : AsyncSeq<'T>) : AsyncSeq<'T> =
+    let s = System.Collections.Generic.HashSet(excluded)
+    source |> filter (fun x -> not (s.Contains(x)))
+
   #if !FABLE_COMPILER
   let iterAsyncParallel (f:'a -> Async<unit>) (s:AsyncSeq<'a>) : Async<unit> = async {
     use mb = MailboxProcessor.Start (ignore >> async.Return)

src/FSharp.Control.AsyncSeq/AsyncSeq.fsi

@@ -179,6 +179,14 @@ module AsyncSeq =
     /// Raises InvalidOperationException if the sequence is empty.
     val head : source:AsyncSeq<'T> -> Async<'T>
 
+    /// Asynchronously returns the first element of the asynchronous sequence as an option,
+    /// or None if the sequence is empty. Mirrors Seq.tryHead.
+    val tryHead : source:AsyncSeq<'T> -> Async<'T option>
+
+    /// Asynchronously returns true if the asynchronous sequence contains no elements, false otherwise.
+    /// Short-circuits after the first element. Mirrors Seq.isEmpty.
+    val isEmpty : source:AsyncSeq<'T> -> Async<bool>
+
     /// 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>
@@ -380,6 +388,10 @@ module AsyncSeq =
     /// and processes the input element immediately.
     val filter : predicate:('T -> bool) -> source:AsyncSeq<'T> -> AsyncSeq<'T>
 
+    /// Returns a new asynchronous sequence containing only elements that are not present
+    /// in the given excluded collection. Uses a HashSet for O(1) lookup. Mirrors Seq.except.
+    val except : excluded:seq<'T> -> source:AsyncSeq<'T> -> AsyncSeq<'T> when 'T : equality
+
     /// Creates an asynchronous sequence that lazily takes element from an
     /// input synchronous sequence and returns them one-by-one.
     val ofSeq : source:seq<'T> -> AsyncSeq<'T>

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

@@ -3274,3 +3274,59 @@ let ``AsyncSeq.tryItem returns None for negative index`` () =
 let ``AsyncSeq.tryItem returns None on empty sequence`` () =
   let result = AsyncSeq.tryItem 0 AsyncSeq.empty<int> |> Async.RunSynchronously
   Assert.AreEqual(None, result)
+
+// ===== isEmpty =====
+
+[<Test>]
+let ``AsyncSeq.isEmpty returns true for empty sequence`` () =
+  let result = AsyncSeq.isEmpty AsyncSeq.empty<int> |> Async.RunSynchronously
+  Assert.True(result)
+
+[<Test>]
+let ``AsyncSeq.isEmpty returns false for non-empty sequence`` () =
+  let source = asyncSeq { yield 1; yield 2 }
+  let result = AsyncSeq.isEmpty source |> Async.RunSynchronously
+  Assert.False(result)
+
+[<Test>]
+let ``AsyncSeq.isEmpty returns false for singleton`` () =
+  let result = AsyncSeq.isEmpty (AsyncSeq.singleton 42) |> Async.RunSynchronously
+  Assert.False(result)
+
+// ===== tryHead =====
+
+[<Test>]
+let ``AsyncSeq.tryHead returns Some for non-empty sequence`` () =
+  let source = asyncSeq { yield 42; yield 99 }
+  let result = AsyncSeq.tryHead source |> Async.RunSynchronously
+  Assert.AreEqual(Some 42, result)
+
+[<Test>]
+let ``AsyncSeq.tryHead returns None for empty sequence`` () =
+  let result = AsyncSeq.tryHead AsyncSeq.empty<int> |> Async.RunSynchronously
+  Assert.AreEqual(None, result)
+
+// ===== except =====
+
+[<Test>]
+let ``AsyncSeq.except removes excluded elements`` () =
+  let source = asyncSeq { yield 1; yield 2; yield 3; yield 4; yield 5 }
+  let result = AsyncSeq.except [2; 4] source |> AsyncSeq.toArrayAsync |> Async.RunSynchronously
+  Assert.AreEqual([| 1; 3; 5 |], result)
+
+[<Test>]
+let ``AsyncSeq.except with empty excluded returns all elements`` () =
+  let source = asyncSeq { yield 1; yield 2; yield 3 }
+  let result = AsyncSeq.except [] source |> AsyncSeq.toArrayAsync |> Async.RunSynchronously
+  Assert.AreEqual([| 1; 2; 3 |], result)
+
+[<Test>]
+let ``AsyncSeq.except with all excluded returns empty sequence`` () =
+  let source = asyncSeq { yield 1; yield 2; yield 3 }
+  let result = AsyncSeq.except [1; 2; 3] source |> AsyncSeq.toArrayAsync |> Async.RunSynchronously
+  Assert.AreEqual([||], result)
+
+[<Test>]
+let ``AsyncSeq.except on empty source returns empty`` () =
+  let result = AsyncSeq.except [1; 2] AsyncSeq.empty<int> |> AsyncSeq.toArrayAsync |> Async.RunSynchronously
+  Assert.AreEqual([||], result)