feat: add TaskSeq.scan and TaskSeq.scanAsync

Implements scan/scanAsync (issue #289 — align with AsyncSeq).

scan: like fold but yields the initial state and each intermediate
accumulator state. Output has N+1 elements for N-element input.
scanAsync: async variant.

- TaskSeqInternal.fs: scan using FolderAction DU (matches fold pattern)
- TaskSeq.fsi: signatures with XML doc for scan/scanAsync
- TaskSeq.fs: static member dispatch (scan/scanAsync → Internal.scan)
- TaskSeq.Scan.Tests.fs: 54 tests (empty, single, multi, side-effects)

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

Author: 2 people

src/FSharp.Control.TaskSeq.Test/FSharp.Control.TaskSeq.Test.fsproj

@@ -25,6 +25,7 @@
     <Compile Include="TaskSeq.FindIndex.Tests.fs" />
     <Compile Include="TaskSeq.Find.Tests.fs" />
     <Compile Include="TaskSeq.Fold.Tests.fs" />
+    <Compile Include="TaskSeq.Scan.Tests.fs" />
     <Compile Include="TaskSeq.Forall.Tests.fs" />
     <Compile Include="TaskSeq.Head.Tests.fs" />
     <Compile Include="TaskSeq.Indexed.Tests.fs" />

src/FSharp.Control.TaskSeq.Test/TaskSeq.Scan.Tests.fs

@@ -0,0 +1,163 @@
+module TaskSeq.Tests.Scan
+
+open Xunit
+open FsUnit.Xunit
+
+open FSharp.Control
+
+//
+// TaskSeq.scan
+// TaskSeq.scanAsync
+//
+
+module EmptySeq =
+    [<Fact>]
+    let ``Null source is invalid`` () =
+        assertNullArg
+        <| fun () -> TaskSeq.scan (fun _ _ -> 42) 0 null
+
+        assertNullArg
+        <| fun () -> TaskSeq.scanAsync (fun _ _ -> Task.fromResult 42) 0 null
+
+    [<Theory; ClassData(typeof<TestEmptyVariants>)>]
+    let ``TaskSeq-scan on empty returns singleton initial state`` variant = task {
+        let! result =
+            Gen.getEmptyVariant variant
+            |> TaskSeq.scan (fun acc _ -> acc + 1) 0
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ 0 ]
+    }
+
+    [<Theory; ClassData(typeof<TestEmptyVariants>)>]
+    let ``TaskSeq-scanAsync on empty returns singleton initial state`` variant = task {
+        let! result =
+            Gen.getEmptyVariant variant
+            |> TaskSeq.scanAsync (fun acc _ -> task { return acc + 1 }) 0
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ 0 ]
+    }
+
+module Functionality =
+    [<Fact>]
+    let ``TaskSeq-scan yields initial state then each intermediate state`` () = task {
+        let! result =
+            TaskSeq.ofList [ 1; 2; 3; 4; 5 ]
+            |> TaskSeq.scan (fun acc item -> acc + item) 0
+            |> TaskSeq.toListAsync
+
+        // N=5 elements → N+1=6 output elements
+        result |> should equal [ 0; 1; 3; 6; 10; 15 ]
+    }
+
+    [<Fact>]
+    let ``TaskSeq-scanAsync yields initial state then each intermediate state`` () = task {
+        let! result =
+            TaskSeq.ofList [ 1; 2; 3; 4; 5 ]
+            |> TaskSeq.scanAsync (fun acc item -> task { return acc + item }) 0
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ 0; 1; 3; 6; 10; 15 ]
+    }
+
+    [<Fact>]
+    let ``TaskSeq-scan output length is input length plus one`` () = task {
+        let input = TaskSeq.ofList [ 'a'; 'b'; 'c' ]
+
+        let! result =
+            input
+            |> TaskSeq.scan (fun acc c -> acc + string c) ""
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ ""; "a"; "ab"; "abc" ]
+    }
+
+    [<Fact>]
+    let ``TaskSeq-scanAsync output length is input length plus one`` () = task {
+        let input = TaskSeq.ofList [ 'a'; 'b'; 'c' ]
+
+        let! result =
+            input
+            |> TaskSeq.scanAsync (fun acc c -> task { return acc + string c }) ""
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ ""; "a"; "ab"; "abc" ]
+    }
+
+    [<Fact>]
+    let ``TaskSeq-scan with single element returns two-element result`` () = task {
+        let! result =
+            TaskSeq.singleton 42
+            |> TaskSeq.scan (fun acc item -> acc + item) 10
+            |> TaskSeq.toListAsync
+
+        result |> should equal [ 10; 52 ]
+    }
+
+    [<Theory; ClassData(typeof<TestImmTaskSeq>)>]
+    let ``TaskSeq-scan accumulates correctly across variants`` variant = task {
+        // Input is 1..10; cumulative sums: 0, 1, 3, 6, 10, 15, 21, 28, 36, 45, 55
+        let! result =
+            Gen.getSeqImmutable variant
+            |> TaskSeq.scan (fun acc item -> acc + item) 0
+            |> TaskSeq.toListAsync
+
+        result
+        |> should equal [ 0; 1; 3; 6; 10; 15; 21; 28; 36; 45; 55 ]
+    }
+
+    [<Theory; ClassData(typeof<TestImmTaskSeq>)>]
+    let ``TaskSeq-scanAsync accumulates correctly across variants`` variant = task {
+        let! result =
+            Gen.getSeqImmutable variant
+            |> TaskSeq.scanAsync (fun acc item -> task { return acc + item }) 0
+            |> TaskSeq.toListAsync
+
+        result
+        |> should equal [ 0; 1; 3; 6; 10; 15; 21; 28; 36; 45; 55 ]
+    }
+
+module SideEffects =
+    [<Theory; ClassData(typeof<TestSideEffectTaskSeq>)>]
+    let ``TaskSeq-scan second iteration accumulates from fresh start`` variant = task {
+        let ts = Gen.getSeqWithSideEffect variant
+
+        let! first =
+            ts
+            |> TaskSeq.scan (fun acc item -> acc + item) 0
+            |> TaskSeq.toListAsync
+
+        first
+        |> should equal [ 0; 1; 3; 6; 10; 15; 21; 28; 36; 45; 55 ]
+
+        let! second =
+            ts
+            |> TaskSeq.scan (fun acc item -> acc + item) 0
+            |> TaskSeq.toListAsync
+
+        // side-effect sequences yield next 10 items (11..20)
+        second
+        |> should equal [ 0; 11; 23; 36; 50; 65; 81; 98; 116; 135; 155 ]
+    }
+
+    [<Theory; ClassData(typeof<TestSideEffectTaskSeq>)>]
+    let ``TaskSeq-scanAsync second iteration accumulates from fresh start`` variant = task {
+        let ts = Gen.getSeqWithSideEffect variant
+
+        let! first =
+            ts
+            |> TaskSeq.scanAsync (fun acc item -> task { return acc + item }) 0
+            |> TaskSeq.toListAsync
+
+        first
+        |> should equal [ 0; 1; 3; 6; 10; 15; 21; 28; 36; 45; 55 ]
+
+        let! second =
+            ts
+            |> TaskSeq.scanAsync (fun acc item -> task { return acc + item }) 0
+            |> TaskSeq.toListAsync
+
+        second
+        |> should equal [ 0; 11; 23; 36; 50; 65; 81; 98; 116; 135; 155 ]
+    }

src/FSharp.Control.TaskSeq/TaskSeq.fs

@@ -406,3 +406,5 @@ type TaskSeq private () =
     static member zip source1 source2 = Internal.zip source1 source2
     static member fold folder state source = Internal.fold (FolderAction folder) state source
     static member foldAsync folder state source = Internal.fold (AsyncFolderAction folder) state source
+    static member scan folder state source = Internal.scan (FolderAction folder) state source
+    static member scanAsync folder state source = Internal.scan (AsyncFolderAction folder) state source

src/FSharp.Control.TaskSeq/TaskSeq.fsi

@@ -1350,6 +1350,35 @@ type TaskSeq =
     static member foldAsync:
         folder: ('State -> 'T -> #Task<'State>) -> state: 'State -> source: TaskSeq<'T> -> Task<'State>
 
+    /// <summary>
+    /// Like <see cref="TaskSeq.fold" />, but returns the sequence of intermediate results and the final result.
+    /// The first element of the output sequence is always the initial state. If the input task sequence
+    /// has <c>N</c> elements, the output task sequence has <c>N + 1</c> elements.
+    /// If the folder function <paramref name="folder" /> is asynchronous, consider using <see cref="TaskSeq.scanAsync" />.
+    /// </summary>
+    ///
+    /// <param name="folder">A function that updates the state with each element from the sequence.</param>
+    /// <param name="state">The initial state.</param>
+    /// <param name="source">The input sequence.</param>
+    /// <returns>A task sequence of states, starting with the initial state and applying the folder to each element.</returns>
+    /// <exception cref="T:ArgumentNullException">Thrown when the input task sequence is null.</exception>
+    static member scan: folder: ('State -> 'T -> 'State) -> state: 'State -> source: TaskSeq<'T> -> TaskSeq<'State>
+
+    /// <summary>
+    /// Like <see cref="TaskSeq.foldAsync" />, but returns the sequence of intermediate results and the final result.
+    /// The first element of the output sequence is always the initial state. If the input task sequence
+    /// has <c>N</c> elements, the output task sequence has <c>N + 1</c> elements.
+    /// If the folder function <paramref name="folder" /> is synchronous, consider using <see cref="TaskSeq.scan" />.
+    /// </summary>
+    ///
+    /// <param name="folder">A function that updates the state with each element from the sequence.</param>
+    /// <param name="state">The initial state.</param>
+    /// <param name="source">The input sequence.</param>
+    /// <returns>A task sequence of states, starting with the initial state and applying the folder to each element.</returns>
+    /// <exception cref="T:ArgumentNullException">Thrown when the input task sequence is null.</exception>
+    static member scanAsync:
+        folder: ('State -> 'T -> #Task<'State>) -> state: 'State -> source: TaskSeq<'T> -> TaskSeq<'State>
+
     /// <summary>
     /// Return a new task sequence with a new item inserted before the given index.
     /// </summary>

src/FSharp.Control.TaskSeq/TaskSeqInternal.fs

@@ -371,6 +371,29 @@ module internal TaskSeqInternal =
             return result
         }
 
+    let scan folder initial (source: TaskSeq<_>) =
+        checkNonNull (nameof source) source
+
+        match folder with
+        | FolderAction folder -> taskSeq {
+            let mutable state = initial
+            yield state
+
+            for item in source do
+                state <- folder state item
+                yield state
+          }
+
+        | AsyncFolderAction folder -> taskSeq {
+            let mutable state = initial
+            yield state
+
+            for item in source do
+                let! newState = folder state item
+                state <- newState
+                yield state
+          }
+
     let toResizeArrayAsync source =
         checkNonNull (nameof source) source