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]

@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]

@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 removed and reposted below)

[bartelink]

@T-Gro I believe I've addressed all open feedback and hence it's ready for another review at this point

Will attempt to be more responsive in addressing feedback quickly so we can get it into people's hands.

Checklist:

• Correct Cancellation handling re catch and catchWith inc xmldoc updates
  • xmldoc is complete but no longer terse
• Correct fast path exception handling re map and bind inc xmldoc updates
• Sync Task and ValueTask tests and impls
• Consider removing empty from the standard functions suite
  • we don't have clear evidence that it's high traffic
  • votes werent particularly conclusive for inclusion
  • it's not a container, so empty is confusing
  • idiomatic FP name is zero
  • workaround is pretty terse and intention revealing: result ()
• propagate all the above to module Async
  • xmldoc (map, bind, catch, catchWith docs need final edit in Task/ValueTask before doing busywork of syncing)
  • tests + impl (Tests will be cloned from Task+ValueTask, with any impl changes triggered by failing tests included)