feat: add TaskSeq.foldWhile and foldWhileAsync

[OnurGumus]

Summary

Adds TaskSeq.foldWhile and TaskSeq.foldWhileAsync — a fold variant with early termination. A boolean predicate decides, against the current state and next element, whether that element should be folded in. Once the predicate returns false, iteration halts without folding that element and no further elements are pulled from the input (matches takeWhile semantics exactly).

TaskSeq.foldWhile      : ('State -> 'T ->       bool) -> ('State -> 'T ->       'State) -> 'State -> TaskSeq<'T> -> Task<'State>
TaskSeq.foldWhileAsync : ('State -> 'T -> #Task<bool>) -> ('State -> 'T -> #Task<'State>) -> 'State -> TaskSeq<'T> -> Task<'State>

Motivation

Reaching for fold / foldAsync often ends with a mutable flag or a match state with Decided -> state | _ -> ... guard at the top of the folder when the caller wants to short-circuit on some condition discovered mid-stream. tryPickAsync handles the "find and halt" subcase but cannot also thread an accumulator. foldWhile fills the gap.

// Sum elements while the running total stays within a budget.
[ 1; 2; 3; 4; 5 ]
|> TaskSeq.ofList
|> TaskSeq.foldWhile
    (fun acc x -> acc + x <= 5)
    (+)
    0
// result: 3  (1+2, then 3 would overshoot — halt without folding it)

Why not existing operators

• tryPickAsync — short-circuits but returns 'U option, no accumulator.
• fold + mutable flag — works but requires mutation at the call site and drains the whole sequence even after deciding.
• takeWhileInclusive + toListAsync — nice shape but allocates a list and requires a second pass to inspect.
• scan + tryFind — loses the final state when no element halts.

foldWhile is the shape the language naturally wants for stateful early-exit folds, and matches the existing takeWhile / skipWhile / tryFind convention: plain bool predicate separated from the data function, no new public types.

What's in the PR

• TaskSeq.foldWhile and TaskSeq.foldWhileAsync in TaskSeq.fs + signatures and XML docs in TaskSeq.fsi
• Release-notes entry under Unreleased
• 22 tests in TaskSeq.FoldWhile.Tests.fs:
  • Null source raises ArgumentNullException
  • Empty sequence → initial state returned, predicate and folder never called (all variants from TestEmptyVariants)
  • Always-true predicate behaves identically to fold (including left-associativity)
  • Predicate false on first element → predicate called once, folder never called, initial state returned
  • Halt mid-sequence → correct halt state preserved, source not pulled past the halting element, predicate/folder call counts verified
  • Non-halting traversal equivalent to fold

Test plan

• dotnet test ... — full suite: 5277 passed, 0 failed, 2 skipped
• Filtered foldWhile suite: 44 passed, 0 failed
• dotnet fantomas . --check — clean
• Library builds on netstandard2.1

---

Originally proposed as foldUntil with a FoldStep<'State> DU (Continue / Halt). Per @dsyme's review, refactored to the bool-predicate form above to match the library's existing early-termination API style.

[dsyme]

@OnurGumus I'm wondering about the new type. Why not a boolean flag to indicate when to stop?

TaskSeq.foldUntil      : ('State -> 'T ->   'State * bool) -> 'State -> TaskSeq<'T> -> Task<'State>

[OnurGumus]

@OnurGumus I'm wondering about the new type. Why not a boolean flag to indicate when to stop?

TaskSeq.foldUntil      : ('State -> 'T ->   'State * bool) -> 'State -> TaskSeq<'T> -> Task<'State>

Hi @dsyme , I kinda favor types over bools, but you are right. Looking at other signatures using bool would be more consistent. I refactored accordingly:

foldWhile : ('State -> 'T -> bool) -> ('State -> 'T -> 'State) -> 'State -> TaskSeq<'T> -> Task<'State> 

[github-actions]

🤖 This is an automated response from Repo Assist.

Nice implementation — the semantics are correct and the test suite is thorough. One small code-quality note:

In both foldWhile and foldWhileAsync, e.Current is accessed twice on the element that passes the predicate — once for the predicate call and once for the folder call:

// foldWhile
if predicate result e.Current then
    result <- folder result e.Current   // e.Current accessed again

// foldWhileAsync
let! keepGoing = predicate result e.Current
if keepGoing then
    let! newState = folder result e.Current  // e.Current accessed again

While IAsyncEnumerator<T>.Current is always a simple property getter with no side effects, capturing to a local is the convention used throughout the rest of the library's early-exit functions (e.g. tryFind does let current = e.Current before the predicate match). It also makes the intent clearer — the predicate and folder act on the same element:

// suggested
let item = e.Current
if predicate result item then
    result <- folder result item

This is minor and does not affect correctness. Everything else looks clean.

Generated by 🤖 Repo Assist, see workflow run.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a