Implements orElse/orElseWith

Closes #119

Author: TheAngryByrd

build.fsx

@@ -216,4 +216,4 @@ Target.create "UpdateDocs" (fun _ ->
   ==> "Release"
 
 // *** Start Build ***
-Target.runOrDefaultWithArguments "Build"
+Target.runOrDefaultWithArguments "NuGet"

src/FsToolkit.ErrorHandling.JobResult/JobResult.fs

@@ -40,10 +40,14 @@ module JobResult =
     Ok x
     |> Job.result
 
+  let ok = retn
+
   let returnError x =
     Error x
     |> Job.result
 
+  let error = returnError
+
   let map2 f xJR yJR =
     Job.map2 (Result.map2 f) xJR yJR
 
@@ -53,6 +57,58 @@ module JobResult =
   let apply fJR xJR =
     map2 (fun f x -> f x) fJR xJR
 
+
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/> 
+  /// </summary>
+  /// <param name="ifError">The value to use if <paramref name="result"/> is <c>Error</c></param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// </remarks>
+  /// <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")
+  /// </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>>)  = 
+    job {
+      match! result with
+      | Ok r -> return Ok r
+      | Error _ -> return! ifError
+    }
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
+  /// </summary>
+  /// <param name="ifErrorFunc">A function that provides an alternate result when evaluated.</param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// <paramref name="ifErrorFunc"/>  is not executed unless <paramref name="result"/> is an <c>Error</c>.
+  /// </remarks>
+  /// <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")
+  /// </code>
+  /// </example>
+  /// <returns>
+  /// The result if the result is Ok, else the result of executing <paramref name="ifErrorFunc"/>.
+  /// </returns>
+  let inline orElseWith (ifErrorFunc : 'error -> Job<Result<'ok,'error2>>) (result : Job<Result<'ok,'error>>) =
+    job {
+      match! result with
+      | Ok r -> return Ok r
+      | Error e -> return! ifErrorFunc e
+    }
+
   /// Replaces the wrapped value with unit
   let ignore jr =
       jr |> map ignore

src/FsToolkit.ErrorHandling.TaskResult/TaskResult.fs

@@ -34,9 +34,13 @@ module TaskResult =
     Ok x
     |> Task.singleton
 
+  let ok = retn
+
   let returnError x =
     Error x
     |> Task.singleton
+   
+  let error = returnError
 
   let map2 f xTR yTR =
     Task.map2 (Result.map2 f) xTR yTR
@@ -47,6 +51,58 @@ module TaskResult =
   let apply fTR xTR =
     map2 (fun f x -> f x) fTR xTR
 
+
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/> 
+  /// </summary>
+  /// <param name="ifError">The value to use if <paramref name="result"/> is <c>Error</c></param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     TaskResult.error "First" |> TaskResult.orElse (TaskResult.error "Second") // evaluates to Error ("Second")
+  ///     TaskResult.error "First" |> TaskResult.orElse (TaskResult.ok "Second") // evaluates to Ok ("Second")
+  ///     TaskResult.ok "First" |> TaskResult.orElse (TaskResult.error "Second") // evaluates to Ok ("First")
+  ///     TaskResult.ok "First" |> TaskResult.orElse (TaskResult.ok "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 : Task<Result<'ok,'error2>>) (result : Task<Result<'ok,'error>>)  = 
+    task {
+      match! result with
+      | Ok r -> return Ok r
+      | Error _ -> return! ifError
+    }
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
+  /// </summary>
+  /// <param name="ifErrorFunc">A function that provides an alternate result when evaluated.</param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// <paramref name="ifErrorFunc"/> is not executed unless <paramref name="result"/> is an <c>Error</c>.
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     TaskResult.error "First" |> TaskResult.orElseWith (fun _ -> TaskResult.error "Second") // evaluates to Error ("Second")
+  ///     TaskResult.error "First" |> TaskResult.orElseWith (fun _ -> TaskResult.ok "Second") // evaluates to Ok ("Second")
+  ///     TaskResult.ok "First" |> TaskResult.orElseWith (fun _ -> TaskResult.error "Second") // evaluates to Ok ("First")
+  ///     TaskResult.ok "First" |> TaskResult.orElseWith (fun _ -> TaskResult.ok "Second") // evaluates to Ok ("First")
+  /// </code>
+  /// </example>
+  /// <returns>
+  /// The result if the result is Ok, else the result of executing <paramref name="ifErrorFunc"/>.
+  /// </returns>
+  let inline orElseWith (ifErrorFunc : 'error -> Task<Result<'ok,'error2>>) (result : Task<Result<'ok,'error>>) =
+    task {
+      match! result with
+      | Ok r -> return Ok r
+      | Error e -> return! ifErrorFunc e
+    }
+
   /// Replaces the wrapped value with unit
   let ignore tr =
       tr |> map ignore

src/FsToolkit.ErrorHandling/AsyncResult.fs

@@ -42,11 +42,15 @@ module AsyncResult =
   let retn x =
     Ok x
     |> Async.singleton
+
+  let ok = retn
 
   let returnError x =
     Error x
     |> Async.singleton
 
+  let error = returnError
+
   let map2 f xR yR =
     Async.map2 (Result.map2 f) xR yR
 
@@ -56,6 +60,58 @@ module AsyncResult =
   let apply fAR xAR =
     map2 (fun f x -> f x) fAR xAR
 
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/> 
+  /// </summary>
+  /// <param name="ifError">The value to use if <paramref name="result"/> is <c>Error</c></param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     AsyncResult.error "First" |> AsyncResult.orElse (AsyncResult.error "Second") // evaluates to Error ("Second")
+  ///     AsyncResult.error "First" |> AsyncResult.orElse (AsyncResult.ok "Second") // evaluates to Ok ("Second")
+  ///     AsyncResult.ok "First" |> AsyncResult.orElse (AsyncResult.error "Second") // evaluates to Ok ("First")
+  ///     AsyncResult.ok "First" |> AsyncResult.orElse (AsyncResult.ok "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 : Async<Result<'ok,'error2>>) (result : Async<Result<'ok,'error>>)  = 
+    async {
+      match! result with
+      | Ok r -> return Ok r
+      | Error _ -> return! ifError
+    }
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
+  /// </summary>
+  /// <param name="ifErrorFunc">A function that provides an alternate result when evaluated.</param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// <paramref name="ifErrorFunc"/>  is not executed unless <paramref name="result"/> is an <c>Error</c>.
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     AsyncResult.error "First" |> AsyncResult.orElseWith (fun _ -> AsyncResult.error "Second") // evaluates to Error ("Second")
+  ///     AsyncResult.error "First" |> AsyncResult.orElseWith (fun _ -> AsyncResult.ok "Second") // evaluates to Ok ("Second")
+  ///     AsyncResult.ok "First" |> AsyncResult.orElseWith (fun _ -> AsyncResult.error "Second") // evaluates to Ok ("First")
+  ///     AsyncResult.ok "First" |> AsyncResult.orElseWith (fun _ -> AsyncResult.ok "Second") // evaluates to Ok ("First")
+  /// </code>
+  /// </example>
+  /// <returns>
+  /// The result if the result is Ok, else the result of executing <paramref name="ifErrorFunc"/>.
+  /// </returns>
+  let inline orElseWith (ifErrorFunc : 'error -> Async<Result<'ok,'error2>>) (result : Async<Result<'ok,'error>>) =
+    async {
+      match! result with
+      | Ok r -> return Ok r
+      | Error e -> return! ifErrorFunc e
+    }
+
   /// Replaces the wrapped value with unit
   let ignore ar =
     ar |> map ignore

src/FsToolkit.ErrorHandling/Result.fs

@@ -45,6 +45,55 @@ module Result =
     tryCreate' x
     |> Result.mapError (fun z -> (fieldName, z))
 
+
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/> 
+  /// </summary>
+  /// <param name="ifError">The value to use if <paramref name="result"/> is <c>Error</c></param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     Error ("First") |> Result.orElse (Error ("Second")) // evaluates to Error ("Second")
+  ///     Error ("First") |> Result.orElseWith (Ok ("Second")) // evaluates to Ok ("Second")
+  ///     Ok ("First") |> Result.orElseWith (Error ("Second")) // evaluates to Ok ("First")
+  ///     Ok ("First") |> Result.orElseWith (Ok ("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 : Result<'ok,'error2>) (result : Result<'ok,'error>)  = 
+    match result with
+    | Ok r -> Ok r
+    | Error _ -> ifError
+
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
+  /// </summary>
+  /// <param name="ifErrorFunc">A function that provides an alternate result when evaluated.</param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// <paramref name="ifErrorFunc"/>  is not executed unless <paramref name="result"/> is an <c>Error</c>.
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     Error ("First") |> Result.orElseWith (fun _ -> Error ("Second")) // evaluates to Error ("Second")
+  ///     Error ("First") |> Result.orElseWith (fun _ -> Ok ("Second")) // evaluates to Ok ("Second")
+  ///     Ok ("First") |> Result.orElseWith (fun _ -> Error ("Second")) // evaluates to Ok ("First")
+  ///     Ok ("First") |> Result.orElseWith (fun _ -> Ok ("Second")) // evaluates to Ok ("First")
+  /// </code>
+  /// </example>
+  /// <returns>
+  /// The result if the result is Ok, else the result of executing <paramref name="ifErrorFunc"/>.
+  /// </returns>
+  let inline orElseWith (ifErrorFunc : 'error -> Result<'ok,'error2>) (result : Result<'ok,'error>) =
+    match result with
+    | Ok r -> Ok r
+    | Error e -> ifErrorFunc e
+
   /// Replaces the wrapped value with unit
   let ignore result =
     result |> Result.map ignore

src/FsToolkit.ErrorHandling/Validation.fs

@@ -23,6 +23,57 @@ module Validation =
 
   let retn x = ok x
 
+  let returnError e = error 
+
+  
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise returns <paramref name="ifError"/> 
+  /// </summary>
+  /// <param name="ifError">The value to use if <paramref name="result"/> is <c>Error</c></param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     Error (["First"]) |> Validation.orElse (Error (["Second"])) // evaluates to Error (["Second"])
+  ///     Error (["First"]) |> Validation.orElseWith (Ok ("Second")) // evaluates to Ok ("Second")
+  ///     Ok ("First") |> Validation.orElseWith (Error (["Second"])) // evaluates to Ok ("First")
+  ///     Ok ("First") |> Validation.orElseWith (Ok ("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 : Validation<'ok,'error2>) (result : Validation<'ok,'error>) : Validation<'ok,'error2> = 
+    match result with
+    | Ok r -> Ok r
+    | Error _ -> ifError
+
+    
+  /// <summary>
+  /// Returns <paramref name="result"/> if it is <c>Ok</c>, otherwise executes <paramref name="ifErrorFunc"/> and returns the result.
+  /// </summary>
+  /// <param name="ifErrorFunc">A function that provides an alternate result when evaluated.</param>
+  /// <param name="result">The input result.</param>
+  /// <remarks>
+  /// <paramref name="ifErrorFunc"/>  is not executed unless <paramref name="result"/> is an <c>Error</c>.
+  /// </remarks>
+  /// <example>
+  /// <code>
+  ///     Error (["First"]) |> Validation.orElseWith (fun _ -> Error (["Second"])) // evaluates to Error (["Second"])
+  ///     Error (["First"]) |> Validation.orElseWith (fun _ -> Ok ("Second")) // evaluates to Ok ("Second")
+  ///     Ok ("First") |> Validation.orElseWith (fun _ -> Error (["Second"])) // evaluates to Ok ("First")
+  ///     Ok ("First") |> Validation.orElseWith (fun _ -> Ok ("Second")) // evaluates to Ok ("First")
+  /// </code>
+  /// </example>
+  /// <returns>
+  /// The result if the result is Ok, else the result of executing <paramref name="ifErrorFunc"/>.
+  /// </returns>
+  let inline orElseWith (ifErrorFunc : 'error list -> Validation<'ok,'error2>) (result : Validation<'ok,'error>) : Validation<'ok,'error2> =
+    match result with
+    | Ok r -> Ok r
+    | Error e -> ifErrorFunc e
+
   let map f (x : Validation<_,_>) : Validation<_,_>= Result.map f x
 
   let map2 f (x : Validation<_,_>) (y : Validation<_,_>) : Validation<_,_> =

tests/FsToolkit.ErrorHandling.JobResult.Tests/Expect.JobResult.fs

@@ -10,12 +10,20 @@ module Expect =
       ()
     else Tests.failtestf "Expected %A, was %A." v x
 
+  let hasJobOkValue v (jobX : Job<_>) = job {
+    let! x = jobX
+    TestHelpers.Expect.hasOkValue v x
+  }
 
-  let hasJobOkValue v jobX = 
+  let hasJobOkValueSync v jobX = 
     let x = run jobX
     TestHelpers.Expect.hasOkValue v x
 
+  let hasJobErrorValue v (jobX : Job<_>) = job {
+    let! x = jobX
+    TestHelpers.Expect.hasErrorValue v x
+  }
 
-  let hasJobErrorValue v jobX = 
+  let hasJobErrorValueSync v jobX = 
     let x = run jobX
     TestHelpers.Expect.hasErrorValue v x