Add parallelAsyncResult docs

Author: njlr

gitbook/parallelAsyncResult/ce.md

@@ -0,0 +1,51 @@
+## ParallelAsyncResult Computation Expression
+
+Namespace: `FsToolkit.ErrorHandling`
+
+This CE operates on the same type as `asyncResult`, but it adds the `and!` operator for running workflows in parallel.
+
+Concurrent workflows are run with the same semantics as [`Async.Parallel`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html#Parallel), so only the first exception is returned.
+
+
+## Examples
+
+### Example 1
+
+Suppose we want to download 3 files.
+
+Here is our simulated download function:
+
+```fsharp
+// string -> Async<Result<string, string>>
+let downloadAsync stuff : Async<Result<string, string>> = async {
+    do! Async.Sleep 3_000
+    return Ok stuff
+}
+```
+
+This workflow will download each item in sequence:
+
+```fsharp
+let downloadAllSequential = ayncResult {
+  let! x = downloadAsync (Ok "We")
+  let! y = downloadAsync (Ok "run")
+  let! z = downloadAsync (Ok "sequentially :(")
+  return sprintf "%s %s %s" x y z
+}
+```
+
+It takes 9 seconds to complete.
+
+However, using `parallelAsyncResult`, we can download all 3 concurrently:
+
+```fsharp
+// Async<Result<string, string>>
+let downloadAll = parallelAsyncResult {
+  let! x = downloadAsync (Ok "We")
+  and! y = downloadAsync (Ok "run")
+  and! z = downloadAsync (Ok "concurrently!")
+  return sprintf "%s %s %s" x y z
+}
+```
+
+This takes just 3 seconds.

gitbook/parallelAsyncResult/map2.md

@@ -0,0 +1,53 @@
+## ParallelAsyncResult.map2
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+('a -> 'b -> 'c) -> Async<Result<'a, 'd>> -> Async<Result<'b, 'd>>
+  -> Async<Result<'c, 'd>>
+```
+
+## Examples
+
+Note: Many use-cases requiring `map2` operations can also be solved using [the `parallelAsyncResult` computation expression](../parallelAsyncResult/ce.md).
+
+### Example 1
+
+Given the functions
+
+```fsharp
+getFollowerIds : UserId -> Async<Result<UserId list, exn>>
+createPost : CreatePostRequest -> Async<Result<PostId, exn>>
+```
+
+And the type
+
+```fsharp
+type NotifyNewPostRequest =
+  { UserIds : UserId list
+    NewPostId : PostId }
+  static member Create userIds newPostsId =
+    {UserIds = userIds; NewPostId = newPostsId}
+```
+
+We can create a `NotifyNewPostRequest` using `ParallelAsyncResult.map2` as below:
+
+```fsharp
+let createPostAndGetNotifyRequest (req : CreatePostRequest) =
+  //  Async<Result<UserId list, exn>>
+  let getFollowersResult = getFollowerIds req.UserId
+
+  // Async<Result<PostId, exn>>
+  let createPostResult = createPost req
+
+  // Async<Result<NotifyNewPostRequest, exn>>
+  let newPostRequestResult =
+    ParallelAsyncResult.map2
+      NotifyNewPostRequest.Create getFollowersResult createPostResult
+
+  // ...
+```
+
+This workflow will run the sub-tasks `getFollowersResult` and `createPostResult` concurrently, which can increase throughput.

gitbook/parallelAsyncResult/map3.md

@@ -0,0 +1,17 @@
+## ParallelAsyncResult.map3
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+('a -> 'b -> 'c -> 'd)
+  -> Async<Result<'a, 'e>>
+  -> Async<Result<'b, 'e>>
+  -> Async<Result<'c, 'e>>
+  -> Async<Result<'d, 'e>>
+```
+
+## Examples
+
+Note: Many use-cases requiring `map3` operations can also be solved using [the `parallelAsyncResult` computation expression](../parallelAsyncResult/ce.md).