Merge pull request #296 from fsprojects/repo-assist/feat-scan-2026-03-8079b757d4337d53

[Repo Assist] feat: add TaskSeq.scan and TaskSeq.scanAsync (ref #289)

Author: dsyme

AGENTS.md

@@ -102,4 +102,12 @@ All workflows are in `.github/workflows/`:
 
 ## Release Notes
 
-When making changes, update the release notes and bump the version appropriately
+**Required**: Every PR that adds features, fixes bugs, or makes user-visible changes **must** include an update to `release-notes.txt`. Add a bullet under the appropriate version heading (currently `0.5.0`). The format is:
+
+```
+0.5.0
+    - adds TaskSeq.myFunction and TaskSeq.myFunctionAsync, #<issue>
+    - fixes <description>, #<issue>
+```
+
+If you are bumping to a new version, also update `Version.props`. PRs that touch library source (`src/FSharp.Control.TaskSeq/`) without updating `release-notes.txt` are incomplete.

release-notes.txt

@@ -3,6 +3,7 @@ Release notes:
 
 0.5.0
     - update engineering to .NET 9/10
+    - adds TaskSeq.scan and TaskSeq.scanAsync, #289
     - adds TaskSeq.pairwise, #289
 
 0.4.0

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

@@ -26,6 +26,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.Reduce.Tests.fs" />
     <Compile Include="TaskSeq.Forall.Tests.fs" />
     <Compile Include="TaskSeq.Head.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

@@ -410,5 +410,7 @@ 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
     static member reduce folder source = Internal.reduce (FolderAction folder) source
     static member reduceAsync folder source = Internal.reduce (AsyncFolderAction folder) source

src/FSharp.Control.TaskSeq/TaskSeq.fsi

@@ -1389,6 +1389,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>
     /// Applies the function <paramref name="folder" /> to each element of the task sequence, threading an accumulator
     /// argument through the computation. The first element is used as the initial state. If the input function is

src/FSharp.Control.TaskSeq/TaskSeqInternal.fs

@@ -397,6 +397,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 reduce folder (source: TaskSeq<_>) =
         checkNonNull (nameof source) source