feat(Async+Task+ValueTask): consistent helper modules

[bartelink]

Adds consistent helper modules for Async, Task and ValueTask.

Resolves fsharp/fslang-suggestions#1466

Checklist

• Test cases added
• Release notes entry updated
• await conclusions on whether to include debatable ones
• consider a Task.wait helper not now anyway

[github-actions]

✅ No release notes required

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds new camelCase helpers for Async, Task, and ValueTask in FSharp.Core, along with unit tests and surface area/release note updates.

Changes:

• Introduced result, map, bind, ignore, catchWith, catch, empty for Async, Task, ValueTask (+ Task.ofValueTask, ValueTask.ofTask where available).
• Added unit tests covering success/failure flows for the new helpers.
• Updated netstandard surface area baselines and release notes.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/TaskModuleFunctions.fs	New tests for Task/ValueTask camelCase helpers.
tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/AsyncModuleFunctions.fs	New tests for Async camelCase helpers.
tests/FSharp.Core.UnitTests/FSharp.Core.UnitTests.fsproj	Includes the new test files in the test project.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.release.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard21.debug.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.release.bsl	Surface area baseline updated for new APIs.
tests/FSharp.Core.UnitTests/FSharp.Core.SurfaceArea.netstandard20.debug.bsl	Surface area baseline updated for new APIs.
src/FSharp.Core/tasks.fsi	Public signatures/docs for new Task/ValueTask modules.
src/FSharp.Core/tasks.fs	Implementation of new Task/ValueTask helpers.
src/FSharp.Core/async.fsi	Public signatures/docs for new Async camelCase helpers.
src/FSharp.Core/async.fs	Implementation of new Async camelCase helpers.
docs/release-notes/.FSharp.Core/11.0.100.md	Release notes entry for the new APIs.

[T-Gro]

Still open: `module`s → modules, plus comma-space → modules Async, Task, ValueTask``.

[bartelink]

reworded in 6708b8f to make format more consistent if there's any other functions added any time soon.

[T-Gro]

@bartelink :

Hi Ruben, just to let you know - I am waiting for when we stop flowing into .NET 10 releases (10.0.400).
Once we branch off to do NET11 only from main, I will have another look (but looks ready) at all your PRs and merge if no objections 👍 .

[bartelink]

Thanks @T-Gro; will be ready when the times come.

Some open questions for when you have a minute to scan:

• Any thoughts on whether other more fringe things can/should make it in e.g. Task.parallelLimit feat(Task, Async): parallelLimit, parallelDoLimit bartelink/fsharp#2 - if the answer is >= maybe then we should discuss things like e.g. extending the base impl to e.g. avoid generating any redundant Task instances and/or canceling in flight work once an exception is raised (there doesn't seem to be any easy/solid BCL idiomatic ways to accomplish this beyond that simple impl AFAICT)
• Wondering if you see the value/point in including a [Task|Async|ValueTask].wait/runSync Add Async.RunImmediate fsharp/fslang-suggestions#1042 (comment) function - probably confirmation bias, but I keep seeing places this would clean things up ever since I wrote that (will rely on Async.Await)
• ICYMI I have a StartTaskImmediate stacked in the wings, awaiting Async.Await feat(Async): StartTaskImmediate bartelink/fsharp#1

[bartelink]

@T-Gro Two more notes

• The Async+Task.wait I proposed/mused about also addresses the ask for a syncTask or similar for top level and/or interactive task running
• you added a 👍 on my tangential comment re pickV and friends but on closer inspection a module ValueOption is already in place and pretty complete. Can you clarify here which aspect, if any of my proposals you felt merited expansion into a suggestion and/or considering doing please?

[T-Gro]

Focused on the consistency premise across Async/Task/ValueTask. Two decisions already settled: module suffix (compiled TaskModule/ValueTaskModule) and cancellation propagates everywhere (first-class, not caught like a normal exception — applies to both catch and catchWith). Inline comments have repros + proposed fixes.

[T-Gro]

catch demotes cancellation to Error — also ValueTask.catch (:860). Reverses the shipped Error(cancelled) test; decision is to treat cancellation as first-class, consistent with Async.

Task.FromCanceled<int>(CancellationToken true) |> Task.catch

• result is Error (TaskCanceledException)
• Async.catch propagates; Error should be reserved for genuine faults

Proposed fix:

TaskBuilder.task {
    try
        let! v = task
        return Ok v
    with
    | :? OperationCanceledException as e -> return raise e   // stays Canceled
    | e -> return Error e
}

[bartelink]

(corrected; pushed for Task, but not yet for ValueTask)
Thanks for the catch, the proposed fix works (though I wonder if the stack trace is optimal and/or whether that's the canonical way to bail on cancellation)

@T-Gro I guess map, bind, catch, catchWith should each have xmldoc covering the pinned behavior? i.e. I'm thinking that it should allude to the fact that catch will let a TaskCanceledException escape so it's not 100% 1:1 equivalent to task { try let! r = task in Ok r with e -> Error e }

[T-Gro]

map/bind throw synchronously on already-completed input — also bind (:751) and the ValueTask equivalents (:809/:822).

let boom (_: int) : int = failwith "boom"
tcs.Task       |> Task.map boom     // pending
Task.result 21 |> Task.map boom     // completed

• pending input → faulted Task
• completed input → raises at the call site, no Task returned
• same call, exception delivered two different ways depending on timing

Proposed fix:

if task.Status = TaskStatus.RanToCompletion then
    try result (mapping task.Result)
    with e -> Task.FromException<'U> e

[bartelink]

@T-Gro I get the point/concern on the catch variants - easy to test etc and will fix.

same call, exception delivered two different ways depending on timing

But can you clarify the exact desire re cancellation handling please?

This code will use the task { leg in the canceled or faulted case and passes my tests:

if task.Status = TaskStatus.RanToCompletion then
    result (mapping task.Result)
else
    task {
        let! v = task
        return mapping v
    }

Recall task.Status = TaskStatus.RanToCompletion is a ns2.0 compatible equivalent of .IsCompletedSuccessfully, so AIUI there can't be a throw from that leg, so the proposed fix would never hit its catch?

Changing Status = TaskStatus.RanToCompletion fast path check to to instead use IsCompleted to force a given handling would entail switching to:

if task.IsCompleted then // includes Canceled or Faulted states
     try result (task.GetAwaiter().GetResult() |> mapping) // Result would surface AggregateException
     with e -> Task.FromException<'U>(e)
else
    TaskBuilder.task {
            let! v = task
            return mapping v
        }

Current (passing with above impls) test semantics:

[<Fact>]
let ``Task.map flows Cancellation (sync)`` () =
    use cts = new CancellationTokenSource()
    cts.Cancel()
    let t = Task.FromCanceled<int>(cts.Token) |> Task.map (fun x -> x * 2)
    task {
        let! e = Assert.ThrowsAsync<TaskCanceledException>(fun () -> t)
        Assert.Equal(cts.Token, e.CancellationToken)
    }
    
[<Fact>]
let ``Task.map flows Cancellation (async)`` () =
    let tcs = TaskCompletionSource<int>()
    let t = tcs.Task |> Task.map (fun x -> x * 2)
    use cts = new CancellationTokenSource()
    tcs.SetCanceled cts.Token
    task {
        let! e = Assert.ThrowsAsync<TaskCanceledException>(fun () -> t)
        Assert.Equal(cts.Token, e.CancellationToken)
    }
    
[<Fact>]
let ``Task.map propagates exception (sync)`` () =
    let t = Task.FromException<int>(Exception "boom") |> Task.map (fun x -> x * 2)
    task {
        let! e = Assert.ThrowsAnyAsync<exn>(fun () -> t)
        Assert.Equal("boom", e.Message)
    }

[<Fact>]
let ``Task.map propagates exception (async)`` () =
    let tcs = TaskCompletionSource<int>()
    let t = tcs.Task |> Task.map (fun x -> x * 2)
    tcs.SetException(exn "boom")
    task {
        let! e = Assert.ThrowsAnyAsync<exn>(fun () -> t)
        Assert.Equal("boom", e.Message)
    }

How would one specify/validate the precise semantics you seek? Is it about being able to set a breakpoint?

Anything worth borrowing from prior art?:

https://github.com/fsprojects/FSharpPlus/blob/master/src/FSharpPlus/Extensions/Task.fs#L15-L28
https://github.com/fsprojects/FSharpPlus/blob/master/src/FSharpPlus/Extensions/Task.fs#L85-L96
https://github.com/demystifyfp/FsToolkit.ErrorHandling/blob/master/src/FsToolkit.ErrorHandling/Task.fs#L8-L36

[bartelink]

cc @TheAngryByrd @gusty If either of you have time to throw a set of eyes over the impl and the test suite to see if there are any gaps that FsToolkit and/or FSharpPlus cover which should be considered?

https://github.com/bartelink/fsharp/blob/atvt/src/FSharp.Core/tasks.fs#L729-L804
https://github.com/bartelink/fsharp/blob/atvt/tests/FSharp.Core.UnitTests/FSharp.Core/Microsoft.FSharp.Control/TaskModuleFunctions.fs#L11-L274

The aim is for a balance of:

• idiomatic / terse impl (optimization can come later (though each function has a sync/completed fast path)
• thorough test suite that provides coverage of all intended behaviors, no matter how esoteric (i.e. if this provides bad stack traces and/or usage of return raise e throws away stack traces and the test suite should call that out, I'm interested!

Bottom line it would be good to rule out footguns like egregious AggregateException wrapping or catch/catchWith trapping cancellation from the off

[bartelink]

@T-Gro Task test suite reviewed, expanded and polished
catch/catchWith Cancellation handling is corrected

NOTE ValueTask impl and tests are still unchanged - I'll port those when we're happy with Task.

[T-Gro]

"(async)" tests run the sync path — also bind (:203).

ValueTask<int>(Task.FromResult 21).IsCompletedSuccessfully   // true

• input already completed → fast path; the slow (Task-allocating) branch is untested
• also why the map/bind timing issue has no failing test

Proposed fix:

let tcs = TaskCompletionSource<int>()
let vt = ValueTask<int>(tcs.Task) |> ValueTask.map (fun x -> x * 2)
Assert.False vt.IsCompletedSuccessfully
tcs.SetResult 21
Assert.Equal(42, vt.Result)

[bartelink]

Apologies for the lack of quality control - will review the suite and make Task vs ValueTask more consistent before forcing it on human eyes again ☹️
(ignore has the same issue, IsCompletedSuccessfully should be IsCompleted etc etc)

[bartelink]

(corrected; pushed for Task, but not yet for ValueTask)

[T-Gro]

Doc example doesn't type-check.

file.AsyncRead(numBytes) |> Async.ignore<int>

• AsyncRead : int -> Async<byte[]>, so ignore<int> → FS0001

Proposed fix:

file.AsyncRead(numBytes) |> Async.ignore<byte array>

[bartelink]

fixed (but using byte[])

[T-Gro]

@bartelink I noticed I was owing a few replies here, I apologize for taking a longer time.

Any thoughts on whether other more fringe things can/should make it in e.g. Task.parallelLimit … extending the base impl to avoid redundant Task instances and/or canceling in-flight work once an exception is raised

Let's keep it out of this PR. It adds throttling + cancel-on-first-exception + aggregation and overlaps Parallel.ForEachAsync. The cancel-in-flight story (no clean BCL-idiomatic path, as you note) is exactly why it deserves its own treatment.

Wondering if you see the value/point in including a [Task|Async|ValueTask].wait/runSync … also addresses the ask for a syncTask … (#1459)

The ergonomics are real, but a blessed runSync/wait is a policy call (sync-over-async, deadlock footguns) that these pure combinators don't carry. Let's not fold it in here.

ICYMI I have a StartTaskImmediate stacked in the wings, awaiting Async.Await

Noted — happy to review once that lands.

---

I believe that clears everything I had outstanding — if I've missed a question anywhere in the thread, or any of the above needs more detail, flag it and I'll follow up.

[bartelink]

Thanks for catches - this is ready for re-review from my perspective

Checklist:

• port final Task impl and test suite to ValueTask
• xmldoc re Cancellation semantics for map, bind, catch, catchWith ?
• any follow-ups from @TheAngryByrd @gusty
• followups from anyone else - please feel free to refer anyone with relevant expertise (and time!) by atting them in...
• remove empty ?