Rename returnError to error + documentation (#311)

tw0po1nt · web-flow · commit 26b9ed1ce979 · 2025-02-21T10:35:23.000-05:00
* Rename returnError to error; add documentation

* Fix mixup with docs + touchup some formatting
diff --git a/gitbook/SUMMARY.md b/gitbook/SUMMARY.md
@@ -87,7 +87,7 @@
     * [bind](asyncResult/bind.md)
     * [check](asyncResult/check.md)
     * [Computation Expression](asyncResult/ce.md)
-    * [error](pr.md)
+    * [error](asyncResult/error.md)
     * [foldResult](asyncResult/foldResult.md)
     * [ignore](asyncResult/ignore.md)
     * [map](asyncResult/map.md)
@@ -176,7 +176,7 @@
     * [mapError](taskResult/mapError.md)
     * [Operators](taskResult/operators.md)
     * [Other Functions](taskResult/others.md)
-    * [returnError](pr.md)
+    * [error](taskResult/error.md)
     * [zip](pr.md)
     * [zipError](pr.md)
     * Lists
@@ -202,14 +202,13 @@
   * [Validation](validation/index.md)
     * [apply](validation/apply.md)
     * [Computation Expression](validation/ce.md)
-    * [error](pr.md)
+    * [error](validation/error.md)
     * [map](pr.md)
     * [map2](validation/map2.md)
     * [map3](validation/map3.md)
     * [mapError](pr.md)
     * [mapErrors](pr.md)
     * [Operators](validation/operators.md)
-    * [returnError](pr.md)
     * [zip](pr.md)
     * Transforms
       * [ofChoice](validation/ofChoice.md)
@@ -218,14 +217,13 @@
   * [AsyncValidation](asyncValidation/index.md)
     * [apply](asyncValidation/apply.md)
     * [Computation Expression](asyncValidation/ce.md)
-    * [error](pr.md)
+    * [error](asyncValidation/error.md)
     * [map](pr.md)
     * [map2](asyncValidation/map2.md)
     * [map3](asyncValidation/map3.md)
     * [mapError](pr.md)
     * [mapErrors](pr.md)
     * [Operators](asyncValidation/operators.md)
-    * [returnError](pr.md)
     * [zip](pr.md)
     * Transforms
       * [ofChoice](asyncValidation/ofChoice.md)
@@ -251,7 +249,7 @@
     * [apply](cancellableTaskValidation/apply.md)
     * [bind](pr.md)
     * [Computation Expression](cancellableTaskValidation/ce.md)
-    * [error](pr.md)
+    * [error](cancellableTaskValidation/error.md)
     * [getCancellationToken](pr.md)
     * [map](pr.md)
     * [map2](cancellableTaskValidation/map2.md)
@@ -285,7 +283,7 @@
     * [bind](jobResult/bind.md)
     * [catch](pr.md)
     * [Computation Expression](jobResult/ce.md)
-    * [error](pr.md)
+    * [error](jobResult/error.md)
     * [fromTask](pr.md)
     * [fromUnitTask](pr.md)
     * [ignore](jobResult/ignore.md)
@@ -295,7 +293,6 @@
     * [mapError](jobResult/mapError.md)
     * [Operators](jobResult/operators.md)
     * [Other Functions](jobResult/others.md)
-    * [returnError](pr.md)
     * [zip](pr.md)
     * [zipError](pr.md)
     * Lists
diff --git a/gitbook/asyncResult/error.md b/gitbook/asyncResult/error.md
@@ -0,0 +1,22 @@
+## AsyncResult.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Async<Result<'ok, 'error>>`
+
+## Function Signature:
+
+```fsharp
+'error -> Async<Result<'ok, 'error>>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Async<Result<int, string>> =
+  AsyncResult.error "Something bad happened"
+```
+
diff --git a/gitbook/asyncValidation/error.md b/gitbook/asyncValidation/error.md
@@ -0,0 +1,22 @@
+## AsyncValidation.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Async<Validation<'ok, 'error>>`
+
+## Function Signature:
+
+```fsharp
+'error -> Async<Validation<'ok, 'error>>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Async<Validation<int, string>> =
+  AsyncValidation.error "Something bad happened"
+```
+
diff --git a/gitbook/cancellableTaskValidation/error.md b/gitbook/cancellableTaskValidation/error.md
@@ -0,0 +1,22 @@
+## CancellableTaskValidation
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `CancellableTaskValidation<'ok, 'error>`
+
+## Function Signature:
+
+```fsharp
+'error -> CancellableTaskValidation<'ok, 'error>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : CancellableTaskValidation<int, string> =
+  CancellableTaskValidation.error "Something bad happened"
+```
+
diff --git a/gitbook/jobResult/error.md b/gitbook/jobResult/error.md
@@ -0,0 +1,22 @@
+## JobResult.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Job<Result<'ok, 'error>>`
+
+## Function Signature:
+
+```fsharp
+'error -> Job<Result<'ok, 'error>>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Job<Result<int, string>> =
+  JobResult.error "Something bad happened"
+```
+
diff --git a/gitbook/taskResult/error.md b/gitbook/taskResult/error.md
@@ -0,0 +1,22 @@
+## TaskResult.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Task<Result<'ok, 'error>>`
+
+## Function Signature:
+
+```fsharp
+'error -> Task<Result<'ok, 'error>>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Task<Result<int, string>> =
+  TaskResult.error "Something bad happened"
+```
+
diff --git a/gitbook/validation/error.md b/gitbook/validation/error.md
@@ -0,0 +1,22 @@
+## Validation.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Validation<'ok, 'error>`
+
+## Function Signature:
+
+```fsharp
+'error -> Validation<'ok, 'error>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Validation<int, string> =
+  Validation.error "Something bad happened"
+```
+
diff --git a/src/FsToolkit.ErrorHandling.JobResult/JobResult.fs b/src/FsToolkit.ErrorHandling.JobResult/JobResult.fs
@@ -43,12 +43,10 @@ module JobResult =
         Ok x
         |> Job.result
 
-    let inline returnError x =
+    let inline error x =
         Error x
         |> Job.result
 
-    let inline error x = returnError x
-
     let inline map2 ([<InlineIfLambda>] f) xJR yJR = Job.map2 (Result.map2 f) xJR yJR
 
     let inline map3 ([<InlineIfLambda>] f) xJR yJR zJR = Job.map3 (Result.map3 f) xJR yJR zJR
diff --git a/src/FsToolkit.ErrorHandling.JobResult/List.fs b/src/FsToolkit.ErrorHandling.JobResult/List.fs
@@ -42,9 +42,9 @@ module List =
                 match s, fR with
                 | Ok ys, Ok y -> return! traverseJobResultA' (JobResult.singleton (y :: ys)) f xs
                 | Error errs, Error e ->
-                    return! traverseJobResultA' (JobResult.returnError (e :: errs)) f xs
-                | Ok _, Error e -> return! traverseJobResultA' (JobResult.returnError [ e ]) f xs
-                | Error e, Ok _ -> return! traverseJobResultA' (JobResult.returnError e) f xs
+                    return! traverseJobResultA' (JobResult.error (e :: errs)) f xs
+                | Ok _, Error e -> return! traverseJobResultA' (JobResult.error [ e ]) f xs
+                | Error e, Ok _ -> return! traverseJobResultA' (JobResult.error e) f xs
             }
 
 
diff --git a/src/FsToolkit.ErrorHandling/Array.fs b/src/FsToolkit.ErrorHandling/Array.fs
@@ -91,13 +91,9 @@ module Array =
                     return! traverseAsyncResultA' (AsyncResult.ok (Array.append [| y |] ys)) f xs
                 | Error errs, Error e ->
                     return!
-                        traverseAsyncResultA'
-                            (AsyncResult.returnError (Array.append [| e |] errs))
-                            f
-                            xs
-                | Ok _, Error e ->
-                    return! traverseAsyncResultA' (AsyncResult.returnError [| e |]) f xs
-                | Error e, Ok _ -> return! traverseAsyncResultA' (AsyncResult.returnError e) f xs
+                        traverseAsyncResultA' (AsyncResult.error (Array.append [| e |] errs)) f xs
+                | Ok _, Error e -> return! traverseAsyncResultA' (AsyncResult.error [| e |]) f xs
+                | Error e, Ok _ -> return! traverseAsyncResultA' (AsyncResult.error e) f xs
             }
 
     let traverseResultA f xs = traverseResultA' (Ok [||]) f xs
diff --git a/src/FsToolkit.ErrorHandling/AsyncResult.fs b/src/FsToolkit.ErrorHandling/AsyncResult.fs
@@ -9,12 +9,10 @@ module AsyncResult =
         Ok value
         |> Async.singleton
 
-    let inline returnError (error: 'error) : Async<Result<'ok, 'error>> =
+    let inline error (error: 'error) : Async<Result<'ok, 'error>> =
         Error error
         |> Async.singleton
 
-    let inline error (error: 'error) : Async<Result<'ok, 'error>> = returnError error
-
     let inline map
         ([<InlineIfLambda>] mapper: 'input -> 'output)
         (input: Async<Result<'input, 'error>>)
@@ -31,7 +29,7 @@ module AsyncResult =
         ([<InlineIfLambda>] binder: 'input -> Async<Result<'output, 'error>>)
         (input: Async<Result<'input, 'error>>)
         : Async<Result<'output, 'error>> =
-        Async.bind (Result.either binder returnError) input
+        Async.bind (Result.either binder error) input
 
     let inline foldResult
         ([<InlineIfLambda>] onSuccess: 'input -> 'output)
diff --git a/src/FsToolkit.ErrorHandling/AsyncValidation.fs b/src/FsToolkit.ErrorHandling/AsyncValidation.fs
@@ -43,10 +43,6 @@ module AsyncValidation =
                     )
         }
 
-    let inline returnError (error: 'error) : AsyncValidation<'ok, 'error> =
-        Error [ error ]
-        |> async.Return
-
     let inline orElse
         (ifError: AsyncValidation<'ok, 'errorOutput>)
         (result: AsyncValidation<'ok, 'errorInput>)
diff --git a/src/FsToolkit.ErrorHandling/List.fs b/src/FsToolkit.ErrorHandling/List.fs
@@ -79,10 +79,9 @@ module List =
                 match s, fR with
                 | Ok ys, Ok y -> return! traverseAsyncResultA' (AsyncResult.ok (y :: ys)) f xs
                 | Error errs, Error e ->
-                    return! traverseAsyncResultA' (AsyncResult.returnError (e :: errs)) f xs
-                | Ok _, Error e ->
-                    return! traverseAsyncResultA' (AsyncResult.returnError [ e ]) f xs
-                | Error e, Ok _ -> return! traverseAsyncResultA' (AsyncResult.returnError e) f xs
+                    return! traverseAsyncResultA' (AsyncResult.error (e :: errs)) f xs
+                | Ok _, Error e -> return! traverseAsyncResultA' (AsyncResult.error [ e ]) f xs
+                | Error e, Ok _ -> return! traverseAsyncResultA' (AsyncResult.error e) f xs
             }
 
     let traverseResultA f xs = traverseResultA' (Ok []) f xs
diff --git a/src/FsToolkit.ErrorHandling/TaskResult.fs b/src/FsToolkit.ErrorHandling/TaskResult.fs
@@ -28,12 +28,10 @@ module TaskResult =
         Ok x
         |> Task.singleton
 
-    let inline returnError x =
+    let inline error x =
         Error x
         |> Task.singleton
 
-    let inline error x = returnError x
-
     let inline map2 ([<InlineIfLambda>] f) xTR yTR = Task.map2 (Result.map2 f) xTR yTR
 
     let inline map3 ([<InlineIfLambda>] f) xTR yTR zTR = Task.map3 (Result.map3 f) xTR yTR zTR
diff --git a/src/FsToolkit.ErrorHandling/Validation.fs b/src/FsToolkit.ErrorHandling/Validation.fs
@@ -31,9 +31,6 @@ module Validation =
                 @ errs2
             )
 
-    let inline returnError (error: 'error) : Validation<'ok, 'error> = Error [ error ]
-
-
     /// <summary>
     /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/>
     /// </summary>
diff --git a/tests/FsToolkit.ErrorHandling.JobResult.Tests/JobResult.fs b/tests/FsToolkit.ErrorHandling.JobResult.Tests/JobResult.fs
@@ -795,43 +795,3 @@ let bindRequireValueOptionTests =
 type CreatePostResult =
     | PostSuccess of NotifyNewPostRequest
     | NotAllowedToPost
-
-// [<Tests>]
-// let JobResultCETests =
-//   let createPost userId = taskResult {
-//     let! isAllowed = allowedToPost userId
-//     if isAllowed then
-//       let! postId = createPostSuccess validCreatePostRequest
-//       let! followerIds = getFollowersSuccess sampleUserId
-//       return PostSuccess {NewPostId = postId; UserIds = followerIds}
-//     else
-//       return NotAllowedToPost
-//   }
-//   testList "JobResult Computation Expression tests" [
-//     testCase "bind with all Ok" <| fun _ ->
-//       createPost sampleUserId
-//       |> Expect.hasJobOkValueSync (PostSuccess {NewPostId = PostId newPostId; UserIds = followerIds})
-
-//     testCase "bind with an Error" <| fun _ ->
-//       createPost (UserId (System.Guid.NewGuid()))
-//       |> Expect.hasJobErrorValueSync commonEx
-//   ]
-
-// [<Tests>]
-// let JobResultOperatorTests =
-//   testList "JobResult Operators Tests" [
-//     testCase "map & apply operators" <| fun _ ->
-//       let getFollowersResult = getFollowersSuccess sampleUserId
-//       let createPostResult = createPostSuccess validCreatePostRequest
-//       newPostRequest <!> getFollowersResult <*> createPostResult
-//       |> Expect.hasJobOkValueSync {NewPostId = PostId newPostId; UserIds = followerIds}
-
-//     testCase "bind operator" <| fun _ ->
-//       allowedToPost sampleUserId
-//       >>= (fun isAllowed ->
-//             if isAllowed then
-//               createPostSuccess validCreatePostRequest
-//             else
-//               JobResult.returnError (Exception ""))
-//       |> Expect.hasJobOkValueSync (PostId newPostId)
-//   ]
diff --git a/tests/FsToolkit.ErrorHandling.TaskResult.Tests/TaskResult.fs b/tests/FsToolkit.ErrorHandling.TaskResult.Tests/TaskResult.fs
@@ -851,7 +851,7 @@ let TaskResultOperatorTests =
                 if isAllowed then
                     createPostSuccess validCreatePostRequest
                 else
-                    TaskResult.returnError (Exception "")
+                    TaskResult.error (Exception "")
             )
             |> Expect.hasTaskOkValueSync (PostId newPostId)
     ]
diff --git a/tests/FsToolkit.ErrorHandling.Tests/AsyncResult.fs b/tests/FsToolkit.ErrorHandling.Tests/AsyncResult.fs
@@ -781,7 +781,7 @@ let asyncResultOperatorTests =
                     if isAllowed then
                         createPostSuccess validCreatePostRequest
                     else
-                        AsyncResult.returnError (Exception "")
+                        AsyncResult.error (Exception "")
                 )
                 |> Expect.hasAsyncOkValue (PostId newPostId)
         }
