Add TaskResult.ofCatchTask (#353)

* Initial plan

* Add TaskResult.ofCatchTask with doc comments, tests, and gitbook docs

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

* Fix incorrect example code in doc comments and gitbook docs

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

* Fix ofTask.md Example 2 to correctly show exception propagation behavior

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

Author: Copilot

gitbook/SUMMARY.md

@@ -208,6 +208,7 @@
       * [sequenceTaskResultA](list/sequenceTaskResultA.md)
     * Transforms
       * [ofAsync](taskResult/ofAsync.md)
+      * [ofCatchTask](taskResult/ofCatchTask.md)
       * [ofResult](taskResult/ofResult.md)
       * [ofTask](taskResult/ofTask.md)
 

gitbook/taskResult/ofCatchTask.md

@@ -0,0 +1,29 @@
+# TaskResult.ofCatchTask
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Transforms a `Task<'T>` into a `Task<Result<'T, exn>>`, catching any exceptions thrown by the task and wrapping them in the `Error` case.
+
+Unlike [`ofTask`](ofTask.md), this function catches exceptions that escape from the task and maps them to `Error`. If the task completes successfully, the result is wrapped in `Ok`.
+
+## Function Signature
+
+```fsharp
+Task<'T> -> Task<Result<'T, exn>>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let result = TaskResult.ofCatchTask (task { return 42 })
+// task { return Ok 42 }
+```
+
+### Example 2
+
+```fsharp
+let result = TaskResult.ofCatchTask (task { failwith "something went wrong" })
+// task { return Error (System.Exception("something went wrong")) }
+```

gitbook/taskResult/ofTask.md

@@ -2,7 +2,9 @@
 
 Namespace: `FsToolkit.ErrorHandling`
 
-Transforms a `Task<'T>` into a `Task<Result<'T, exn>>`.
+Transforms a `Task<'T>` into a `Task<Result<'T, exn>>` by wrapping the value in `Ok`.
+
+> **Note:** This function does **not** catch exceptions thrown by the task. Any exceptions will propagate as-is. To catch exceptions and map them to the `Error` case, use [`ofCatchTask`](ofCatchTask.md).
 
 ## Function Signature
 
@@ -22,6 +24,8 @@ let result = TaskResult.ofTask (task { return 42 })
 ### Example 2
 
 ```fsharp
-let result = TaskResult.ofTask (task { return System.Exception("error") })
-// task { return Error (System.Exception("error")) }
+// Exceptions are NOT caught — they propagate out of the task
+let result = TaskResult.ofTask (task { return failwith "something went wrong" })
+// throws System.Exception("something went wrong")
 ```
+

src/FsToolkit.ErrorHandling/TaskResult.fs

@@ -244,11 +244,41 @@ module TaskResult =
             | Choice2Of2 ex -> Error(f ex)
         )
 
-    /// Lift Task to TaskResult
+    /// <summary>
+    /// Lifts a <c>Task&lt;'ok&gt;</c> into a <c>Task&lt;Result&lt;'ok, 'error&gt;&gt;</c> by wrapping the value in <c>Ok</c>.
+    /// Any exceptions thrown by the task will not be caught and will propagate as-is.
+    /// To catch exceptions and map them to the <c>Error</c> case, use <see cref="ofCatchTask"/>.
+    /// </summary>
+    /// <param name="x">The task to lift.</param>
+    /// <returns>A task containing <c>Ok</c> of the task's result value.</returns>
     let inline ofTask x =
         x
         |> Task.map Ok
 
+    /// <summary>
+    /// Lifts a <c>Task&lt;'ok&gt;</c> into a <c>Task&lt;Result&lt;'ok, exn&gt;&gt;</c>, catching any exceptions
+    /// thrown by the task and wrapping them in <c>Error</c>. If the task completes successfully,
+    /// the result is wrapped in <c>Ok</c>.
+    /// </summary>
+    /// <param name="x">The task to lift.</param>
+    /// <returns>
+    /// A task containing <c>Ok</c> of the result value if the task succeeds, or
+    /// <c>Error</c> of the exception if the task throws.
+    /// </returns>
+    /// <example>
+    /// <code>
+    ///     TaskResult.ofCatchTask (task { return 42 })
+    ///     // Returns: task { return Ok 42 }
+    ///
+    ///     TaskResult.ofCatchTask (task { failwith "something went wrong" })
+    ///     // Returns: task { return Error (System.Exception("something went wrong")) }
+    /// </code>
+    /// </example>
+    let inline ofCatchTask (x: Task<'ok>) : Task<Result<'ok, exn>> =
+        x
+        |> Task.catch
+        |> Task.map Result.ofChoice
+
     /// Lift Result to TaskResult
     let inline ofResult (x: Result<_, _>) =
         x

tests/FsToolkit.ErrorHandling.Tests/TaskResult.fs

@@ -730,6 +730,29 @@ let catchTests =
             Expect.hasTaskErrorValueSync "unmapped" (TaskResult.catch f (toTask (Error "unmapped")))
     ]
 
+let ofCatchTaskTests =
+    let taskThrow () =
+        task {
+            failwith err
+            return Unchecked.defaultof<int>
+        }
+
+    testList "TaskResult.ofCatchTask tests" [
+        testCase "ofCatchTask returns Ok for a successful task"
+        <| fun _ -> Expect.hasTaskOkValueSync 42 (TaskResult.ofCatchTask (task { return 42 }))
+
+        testCase "ofCatchTask returns Error for a throwing task"
+        <| fun _ ->
+            let result =
+                TaskResult.ofCatchTask (taskThrow ())
+                |> Async.AwaitTask
+                |> Async.RunSynchronously
+
+            match result with
+            | Error ex -> Expect.equal ex.Message err "Expected exception message to match"
+            | Ok _ -> Tests.failtestf "Expected Error, was Ok"
+    ]
+
 let zipTests =
     testList "TaskResult.zip tests" [
         testCase "Ok, Ok"
@@ -1077,6 +1100,7 @@ let allTests =
         teeErrorTests
         teeErrorIfTests
         catchTests
+        ofCatchTaskTests
         zipTests
         zipErrorTests
         TaskResultCETests