[v5] API Consolidation Around retn/singleton/ok/some (#287)

* Removed Async.retn since it duplicates Async.singleton

* Converted all uses of retn, ok, and some into singleton

* Reverted some instances of singleton back to ok/some

Author: 1eyewonder

src/FsToolkit.ErrorHandling.IcedTasks/CancellableTaskValidationCE.fs

@@ -323,12 +323,6 @@ module CancellableTaskValidation =
         let x = Result.mapError List.singleton result
         fun _ -> Task.FromResult(x)
 
-    /// <summary>Lifts an item to a CancellableTaskValidation.</summary>
-    /// <param name="item">The item to be the ok result of the CancellableTaskValidation.</param>
-    /// <returns>A CancellableTaskValidation with the item as the result.</returns>
-    let inline ok (item: 'ok) : CancellableTaskValidation<'ok, 'error> =
-        fun _ -> Task.FromResult(Ok item)
-
     /// <summary>Lifts an item to a CancellableTaskValidation.</summary>
     /// <param name="error">The item to be the error result of the CancellableTaskValidation.</param>
     /// <returns>A CancellableTaskValidation with the item as the result.</returns>
@@ -338,11 +332,9 @@ module CancellableTaskValidation =
 
     let inline ofChoice (choice: Choice<'ok, 'error>) : CancellableTaskValidation<'ok, 'error> =
         match choice with
-        | Choice1Of2 x -> ok x
+        | Choice1Of2 x -> singleton x
         | Choice2Of2 x -> error x
 
-    let inline retn (value: 'ok) : CancellableTaskValidation<'ok, 'error> = ok value
-
 
     let inline mapError
         ([<InlineIfLambda>] errorMapper: 'errorInput -> 'errorOutput)
@@ -480,7 +472,7 @@ module CancellableTaskValidation =
 
             return!
                 result
-                |> Result.either ok (fun _ -> ifError)
+                |> Result.either singleton (fun _ -> ifError)
         }
 
     let inline orElseWith
@@ -493,7 +485,7 @@ module CancellableTaskValidation =
 
             return!
                 match result with
-                | Ok x -> ok x
+                | Ok x -> singleton x
                 | Error err -> ifErrorFunc err
         }
 
@@ -928,7 +920,7 @@ module CTVMergeSourcesExtensionsTV1CV2 =
             (
                 left: 'Awaiter1,
                 [<InlineIfLambda>] right: CancellationToken -> 'Awaiter2
-            )  =
+            ) =
             this.Source(
                 // cancellableTask.Run(
                 //     cancellableTask.Bind(
@@ -950,17 +942,17 @@ module CTVMergeSourcesExtensionsTV1CV2 =
                     let! struct (l1, r1) = cancellableTask.MergeSources(left, right)
                     return Validation.zip l1 r1
                 }
-                // fun ct -> Awaitable.GetTaskAwaiter(IcedTasks.Polyfill.Task.Tasks.TaskBuilder.task {
-                //     let r1 = right ct
-                //     let l1 = left
-                //     let! struct (l1, r1) = IcedTasks.Polyfill.Task.Tasks.TaskBuilder.task.MergeSources(l1, r1)
+            // fun ct -> Awaitable.GetTaskAwaiter(IcedTasks.Polyfill.Task.Tasks.TaskBuilder.task {
+            //     let r1 = right ct
+            //     let l1 = left
+            //     let! struct (l1, r1) = IcedTasks.Polyfill.Task.Tasks.TaskBuilder.task.MergeSources(l1, r1)
 
-                //     // let foo  = cancellableTask.MergeSources(left, right) ct
-                //     return Validation.zip l1 r1
-                // })
-                // |> ignore
+            //     // let foo  = cancellableTask.MergeSources(left, right) ct
+            //     return Validation.zip l1 r1
+            // })
+            // |> ignore
 
-                // Unchecked.defaultof<_>
+            // Unchecked.defaultof<_>
             )
 
 

src/FsToolkit.ErrorHandling.JobResult/JobOption.fs

@@ -20,10 +20,10 @@ module JobOption =
             return! t
         }
 
-    let inline retn x = job { return Some x }
+    let inline singleton x = job { return Some x }
 
     let inline apply f x =
-        bind (fun f' -> bind (fun x' -> retn (f' x')) x) f
+        bind (fun f' -> bind (fun x' -> singleton (f' x')) x) f
 
 
     /// <summary>

src/FsToolkit.ErrorHandling.JobResult/JobResult.fs

@@ -39,12 +39,10 @@ module JobResult =
         |> Job.catch
         |> Job.map Result.ofChoice
 
-    let inline retn x =
+    let inline singleton x =
         Ok x
         |> Job.result
 
-    let inline ok x = retn x
-
     let inline returnError x =
         Error x
         |> Job.result
@@ -68,17 +66,17 @@ module JobResult =
     /// <example>
     /// <code>
     ///     JobResult.error "First" |> JobResult.orElse (JobResult.error "Second") // evaluates to Error ("Second")
-    ///     JobResult.error "First" |> JobResult.orElse (JobResult.ok "Second") // evaluates to Ok ("Second")
-    ///     JobResult.ok "First" |> JobResult.orElse (JobResult.error "Second") // evaluates to Ok ("First")
-    ///     JobResult.ok "First" |> JobResult.orElse (JobResult.ok "Second") // evaluates to Ok ("First")
+    ///     JobResult.error "First" |> JobResult.orElse (JobResult.singleton "Second") // evaluates to Ok ("Second")
+    ///     JobResult.singleton "First" |> JobResult.orElse (JobResult.error "Second") // evaluates to Ok ("First")
+    ///     JobResult.singleton "First" |> JobResult.orElse (JobResult.singleton "Second") // evaluates to Ok ("First")
     /// </code>
     /// </example>
     /// <returns>
     /// The result if the result is Ok, else returns <paramref name="ifError"/>.
     /// </returns>
     let inline orElse (ifError: Job<Result<'ok, 'error2>>) (result: Job<Result<'ok, 'error>>) =
         result
-        |> Job.bind (Result.either ok (fun _ -> ifError))
+        |> Job.bind (Result.either singleton (fun _ -> ifError))
 
     /// <summary>
     /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
@@ -91,9 +89,9 @@ module JobResult =
     /// <example>
     /// <code>
     ///     JobResult.error "First" |> JobResult.orElseWith (fun _ -> JobResult.error "Second") // evaluates to Error ("Second")
-    ///     JobResult.error "First" |> JobResult.orElseWith (fun _ -> JobResult.ok "Second") // evaluates to Ok ("Second")
-    ///     JobResult.ok "First" |> JobResult.orElseWith (fun _ -> JobResult.error "Second") // evaluates to Ok ("First")
-    ///     JobResult.ok "First" |> JobResult.orElseWith (fun _ -> JobResult.ok "Second") // evaluates to Ok ("First")
+    ///     JobResult.error "First" |> JobResult.orElseWith (fun _ -> JobResult.singleton "Second") // evaluates to Ok ("Second")
+    ///     JobResult.singleton "First" |> JobResult.orElseWith (fun _ -> JobResult.error "Second") // evaluates to Ok ("First")
+    ///     JobResult.singleton "First" |> JobResult.orElseWith (fun _ -> JobResult.singleton "Second") // evaluates to Ok ("First")
     /// </code>
     /// </example>
     /// <returns>
@@ -104,7 +102,7 @@ module JobResult =
         (result: Job<Result<'ok, 'error>>)
         =
         result
-        |> Job.bind (Result.either ok ifErrorFunc)
+        |> Job.bind (Result.either singleton ifErrorFunc)
 
     /// Replaces the wrapped value with unit
     let inline ignore<'ok, 'error> (jr: Job<Result<'ok, 'error>>) =

src/FsToolkit.ErrorHandling.JobResult/JobResultOption.fs

@@ -9,7 +9,7 @@ module JobResultOption =
         let binder opt =
             match opt with
             | Some x -> f x
-            | None -> JobResult.retn None
+            | None -> JobResult.singleton None
 
         JobResult.bind binder jro
 
@@ -19,7 +19,7 @@ module JobResultOption =
     let inline map3 ([<InlineIfLambda>] f) xJRO yJRO zJRO =
         JobResult.map3 (Option.map3 f) xJRO yJRO zJRO
 
-    let inline retn value =
+    let inline singleton value =
         Some value
         |> Ok
         |> Job.result

src/FsToolkit.ErrorHandling.JobResult/JobResultOptionCE.fs

@@ -5,7 +5,7 @@ module JobResultOptionCE =
     open Hopac
 
     type JobResultOptionBuilder() =
-        member inline _.Return value = JobResultOption.retn value
+        member inline _.Return value = JobResultOption.singleton value
         member inline _.ReturnFrom value = value
         member inline _.Bind(result, [<InlineIfLambda>] binder) = JobResultOption.bind binder result
 

src/FsToolkit.ErrorHandling.JobResult/List.fs

@@ -24,7 +24,7 @@ module List =
             }
 
     let traverseJobResultM f xs =
-        traverseJobResultM' (JobResult.retn []) f xs
+        traverseJobResultM' (JobResult.singleton []) f xs
 
     let sequenceJobResultM xs = traverseJobResultM id xs
 
@@ -40,7 +40,7 @@ module List =
                 let! fR = f x
 
                 match s, fR with
-                | Ok ys, Ok y -> return! traverseJobResultA' (JobResult.retn (y :: ys)) f xs
+                | 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
@@ -49,6 +49,6 @@ module List =
 
 
     let traverseJobResultA f xs =
-        traverseJobResultA' (JobResult.retn []) f xs
+        traverseJobResultA' (JobResult.singleton []) f xs
 
     let sequenceJobResultA xs = traverseJobResultA id xs

src/FsToolkit.ErrorHandling/Array.fs

@@ -53,7 +53,7 @@ module Array =
     let sequenceResultM xs = traverseResultM id xs
 
     let traverseAsyncResultM f xs =
-        traverseAsyncResultM' (AsyncResult.retn [||]) f xs
+        traverseAsyncResultM' (AsyncResult.ok [||]) f xs
 
     let sequenceAsyncResultM xs = traverseAsyncResultM id xs
 
@@ -88,7 +88,7 @@ module Array =
 
                 match s, fR with
                 | Ok ys, Ok y ->
-                    return! traverseAsyncResultA' (AsyncResult.retn (Array.append [| y |] ys)) f xs
+                    return! traverseAsyncResultA' (AsyncResult.ok (Array.append [| y |] ys)) f xs
                 | Error errs, Error e ->
                     return!
                         traverseAsyncResultA'
@@ -127,7 +127,7 @@ module Array =
     let sequenceValidationA xs = traverseValidationA id xs
 
     let traverseAsyncResultA f xs =
-        traverseAsyncResultA' (AsyncResult.retn [||]) f xs
+        traverseAsyncResultA' (AsyncResult.ok [||]) f xs
 
     let sequenceAsyncResultA xs = traverseAsyncResultA id xs
 
@@ -193,7 +193,7 @@ module Array =
     let sequenceOptionM xs = traverseOptionM id xs
 
     let traverseAsyncOptionM f xs =
-        traverseAsyncOptionM' (AsyncOption.retn [||]) f xs
+        traverseAsyncOptionM' (AsyncOption.some [||]) f xs
 
     let sequenceAsyncOptionM xs = traverseAsyncOptionM id xs
 

src/FsToolkit.ErrorHandling/Async.fs

@@ -15,15 +15,6 @@ module Async =
         value
         |> async.Return
 
-    /// <summary>
-    /// Converts a value to an <c>Async</c> value
-    /// </summary>
-    /// <param name="value">The value to convert to an <c>Async</c> value.</param>
-    /// <returns>The <c>Async</c> value.</returns>
-    let inline retn (value: 'value) : Async<'value> =
-        value
-        |> async.Return
-
     /// <summary>
     /// Takes a transformation function and applies it to the value of an <c>Async</c> value.
     /// </summary>

src/FsToolkit.ErrorHandling/AsyncOption.fs

@@ -21,16 +21,13 @@ module AsyncOption =
             )
             input
 
-    let inline retn (value: 'value) : Async<'value option> = Async.singleton (Some value)
-
-
     let inline some (value: 'value) : Async<'value option> = Async.singleton (Some value)
 
     let inline apply
         (applier: Async<('input -> 'output) option>)
         (input: Async<'input option>)
         : Async<'output option> =
-        bind (fun f' -> bind (fun x' -> retn (f' x')) input) applier
+        bind (fun f' -> bind (fun x' -> some (f' x')) input) applier
 
     /// <summary>
     /// Returns result of running <paramref name="onSome"/> if it is <c>Some</c>, otherwise returns result of running <paramref name="onNone"/>

src/FsToolkit.ErrorHandling/AsyncOptionCE.fs

@@ -7,7 +7,7 @@ open System
 module AsyncOptionCE =
     type AsyncOptionBuilder() =
 
-        member inline _.Return(value: 'value) : Async<'value option> = AsyncOption.retn value
+        member inline _.Return(value: 'value) : Async<'value option> = AsyncOption.some value
 
         member inline _.ReturnFrom(value: Async<'value option>) : Async<'value option> = value