Add TaskValidation module (#313)

* Implement TaskValidation module

* Implement TaskValidationOp functions

* Implement TaskValidation computation expression

* Add TaskValidation tests

* Finish TaskValidation tests; fix formatting

* Move TaskValidation tests to FsToolkit.ErrorHandling.TaskResult.Tests project

* Add gitbook documentation for TaskValidation

* Add overload for plain Result case; add test handling multiple errors case

Author: tw0po1nt

gitbook/SUMMARY.md

@@ -228,6 +228,21 @@
       * [ofChoice](asyncValidation/ofChoice.md)
       * [ofResult](asyncValidation/ofResult.md)
 
+  * [TaskValidation](taskValidation/index.md)
+    * [apply](taskValidation/apply.md)
+    * [Computation Expression](taskValidation/ce.md)
+    * [error](taskValidation/error.md)
+    * [map](taskValidation/map.md)
+    * [map2](taskValidation/map2.md)
+    * [map3](taskValidation/map3.md)
+    * [mapError](taskValidation/mapError.md)
+    * [mapErrors](taskValidation/mapErrors.md)
+    * [Operators](taskValidation/operators.md)
+    * [zip](taskValidation/zip.md)
+    * Transforms
+      * [ofChoice](taskValidation/ofChoice.md)
+      * [ofResult](taskValidation/ofResult.md)
+
 * FsToolkit.ErrorHandling.AsyncSeq
   * AsyncSeq
     * [Computation Expression](pr.md)

gitbook/taskValidation/apply.md

@@ -0,0 +1,13 @@
+## TaskValidation.apply
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+Task<Result<('a -> 'b), 'c list>>
+  -> Task<Result<'a, 'c list>>
+  -> Task<Result<'b, 'c list>>
+```
+
+## Examples

gitbook/taskValidation/ce.md

@@ -0,0 +1,41 @@
+## TaskValidation Computation Expression
+
+Namespace: `FsToolkit.ErrorHandling`
+
+The `TaskValidation` type is defined as:
+
+```fsharp
+type TaskValidation<'a,'err> = Task<Result<'a, 'err list>>
+```
+
+This CE can take advantage of the [and! operator](https://github.com/fsharp/fslang-suggestions/issues/579) to join multiple error results into a list.
+
+## Examples
+
+See [here](../validation/ce.md) for other validation-like examples
+
+```fsharp
+// Result<string, string> -> Task<Result<string, string>>
+let downloadTask stuff = task {
+    return stuff
+}
+
+// TaskValidation<string, string>
+let addResult = taskValidation {
+  let! x = downloadTask (Ok "I")
+  and! y = downloadTask (Ok "am")
+  and! z = downloadTask (Ok "async!")
+  return sprintf "%s %s %s" x y z
+}
+// task { return Ok "I am async!" }
+
+// TaskValidation<string, string>
+let addResult = taskValidation {
+  let! x = downloadTask (Error "Am")
+  and! y = downloadTask (Error "I")
+  and! z = downloadTask (Error "async?")
+  return sprintf "%s %s %s" x y z
+}
+
+// task { return Error [ "Am"; "I"; "async?" ] }
+```

gitbook/taskValidation/error.md

@@ -0,0 +1,22 @@
+## TaskValidation.error
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Lift an `'error` value into an `Task<Validation<'ok, 'error>>`
+
+## Function Signature:
+
+```fsharp
+'error -> Task<Validation<'ok, 'error>>
+```
+
+## Examples
+
+### Example 1
+
+
+```fsharp
+let result : Task<Validation<int, string>> =
+  TaskValidation.error "Something bad happened"
+```
+

gitbook/taskValidation/index.md

@@ -0,0 +1,5 @@
+# TaskValidation
+
+Namespace: `FsToolkit.ErrorHandling`
+
+This module provides utility functions and infix operators to work with `Task<Result<'a, 'b list>>`.

gitbook/taskValidation/map.md

@@ -0,0 +1,41 @@
+# TaskValidation.map
+
+Namespace: `FsToolkit.ErrorHandling`
+
+`map` applies a transformation to the value inside an `TaskValidation` if it represents a successful result (`Ok`). It allows you to perform a computation on the value while preserving the success/error status of the original `TaskValidation`. If the original `TaskValidation` is an `Error`, `map` does nothing and returns the same `Error` unchanged.
+
+## Function Signature
+
+```fsharp
+('okInput -> 'okOutput) -> TaskValidation<'okInput, 'error> -> TaskValidation<'okOutput, 'error>
+```
+
+## Examples
+
+Take the following functions for example
+
+```fsharp
+// string -> int
+let remainingCharacters (prompt: string) =
+    280 - prompt.Length
+```
+
+### Example 1
+
+```fsharp
+let validation =
+    TaskValidation.ok "foo" // TaskValidation<string, string>
+    |> TaskValidation.map remainingCharacters // TaskValidation<int, string>
+
+// task { Ok 277 }
+```
+
+### Example 2
+
+```fsharp
+let result =
+    TaskValidation.error "bad things happened" // TaskValidation<string, string>
+    |> TaskValidation.map remainingCharacters // TaskValidation<int, string>
+
+// task { Error ["bad things happened"] }
+```

gitbook/taskValidation/map2.md

@@ -0,0 +1,16 @@
+## TaskValidation.map2
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+('a -> 'b -> 'c)
+  -> Task<Result<'a, 'd list>>
+  -> Task<Result<'b, 'd list>>
+  -> Task<Result<'c, 'd list>>
+```
+
+Like [Result.map2](../result/map2.md), but collects the errors from both arguments.
+
+## Examples

gitbook/taskValidation/map3.md

@@ -0,0 +1,17 @@
+## TaskValidation.map3
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```
+('a -> 'b -> 'c -> 'd)
+  -> Task<Result<'a, 'e list>>
+  -> Task<Result<'b, 'e list>>
+  -> Task<Result<'c, 'e list>>
+  -> Task<Result<'d, 'e list>>
+```
+
+Like [Result.map3](../result/map3.md), but collects the errors from all arguments.
+
+## Examples

gitbook/taskValidation/mapError.md

@@ -0,0 +1,44 @@
+# TaskValidation.mapError
+
+Namespace: `FsToolkit.ErrorHandling`
+
+`mapError` takes an task validation and a normal function and returns a new task validation value based on the input error value and the function
+
+## Function Signature
+
+```fsharp
+('errorInput -> 'errorOutput) -> TaskValidation<'ok, 'errorInput> 
+    -> TaskValidation<'ok, 'errorOutput>
+```
+
+## Examples
+
+Take the following functions for example
+
+```fsharp
+// string -> int
+let getErrorCode (message: string) =
+    match message with
+    | "bad things happened" -> 1
+    | _ -> 0
+```
+
+### Example 1
+
+```fsharp
+let result =
+    TaskValidation.ok "all good" // TaskValidation<string, string>
+    |> TaskValidation.mapError getErrorCode // TaskValidation<string, int>
+
+// task { Ok "all good" }
+```
+
+### Example 2
+
+```fsharp
+let result =
+    TaskValidation.error "bad things happened" // TaskValidation<string, string>
+    |> TaskValidation.mapError getErrorCode // TaskValidation<string, int>
+
+// task { Error [1] }
+```

gitbook/taskValidation/mapErrors.md

@@ -0,0 +1,44 @@
+# TaskValidation.mapErrors
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Similar to [TaskValidation.mapError](../taskValidation/mapError.md), except that the mapping function is passed the full list of errors, rather than each one individually.
+
+## Function Signature
+
+```fsharp
+('errorInput list -> 'errorOutput list) -> TaskValidation<'ok, 'errorInput> 
+    -> TaskValidation<'ok, 'errorOutput>
+```
+
+## Examples
+
+Take the following functions for example
+
+```fsharp
+// string -> int
+let getErrorCode (messages: string list) =
+    match messages |> List.tryFind ((=) "bad things happened") with
+    | Some _ -> [1]
+    | _ -> [0]
+```
+
+### Example 1
+
+```fsharp
+let result =
+    TaskValidation.ok "all good" // TaskValidation<string, string>
+    |> TaskValidation.mapErrors getErrorCode // TaskValidation<string, int>
+
+// task { Ok "all good" }
+```
+
+### Example 2
+
+```fsharp
+let result : TaskValidation<string, int> =
+    TaskValidation.error "bad things happened" // TaskValidation<string, string>
+    |> TaskValidation.mapErrors getErrorCode // TaskValidation<string, int>
+
+// task { Error [1] }
+```

gitbook/taskValidation/ofChoice.md

@@ -0,0 +1,27 @@
+# TaskValidation.ofChoice
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Transforms a `Choice<'T, 'Error>` into a `Task<Result<'T, 'Error list>>`
+
+## Function Signature
+
+```fsharp
+Choice<'T, 'Error> -> Task<Result<'T, 'Error list>>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let result = TaskValidation.ofChoice (Choice1Of2 42)
+// task { return Ok 42 }
+```
+
+### Example 2
+
+```fsharp
+let result = TaskValidation.ofChoice (Choice2Of2 "error")
+// task { return Error ["error"] }
+```

gitbook/taskValidation/ofResult.md

@@ -0,0 +1,27 @@
+# TaskValidation.ofResult
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Transforms a `Result<'T, 'Error>` into a `Task<Result<'T, 'Error list>>`
+
+## Function Signature
+
+```fsharp
+Result<'T, 'Error> -> Task<Result<'T, 'Error list>>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let result = TaskValidation.ofResult (Ok 42)
+// task { return Ok 42 }
+```
+
+### Example 2
+
+```fsharp
+let result = TaskValidation.ofResult (Error "error")
+// task { return Error ["error"] }
+```