Add new AsyncOption APIs and document all its other functions; minor fixes to documentation for Option module (#307)

* Add AsyncOption.orElse and orElseWith; add entries for Option.traverseAsync and sequenceAsync to SUMMARY.md; add documentation for the rest of the functions in  module

* Cleanup typos in type signatures in documentation

Author: tw0po1nt

gitbook/SUMMARY.md

@@ -42,8 +42,10 @@
     * [map](option/map.md)
     * [map2](option/map2.md)
     * [map3](option/map3.md)
+    * [sequenceAsync](option/sequenceAsync.md)
     * [sequenceResult](option/sequenceResult.md)
     * [tee Functions](option/teeFunctions.md)
+    * [traverseAsync](option/traverseAsync.md)
     * [traverseResult](option/traverseResult.md)
     * [zip](option/zip.md)
     * Lists
@@ -112,6 +114,15 @@
       * [ofTask](asyncResult/ofTask.md)
       * [ofTaskAction](asyncResult/ofTaskAction.md)
 
+  * AsyncOption
+    * [apply](asyncOption/apply.md)
+    * [bind](asyncOption/bind.md)
+    * [Computation Expression](asyncOption/ce.md)
+    * [either](asyncOption/either.md)
+    * [map](asyncOption/map.md)
+    * [orElse Functions](asyncOption/orElseFunctions.md)
+    * [Other Functions](asyncOption/others.md)
+
   * AsyncResultOption
     * [apply](asyncResultOption/apply.md)
     * [bind](asyncResultOption/bind.md)

gitbook/asyncOption/apply.md

@@ -0,0 +1,49 @@
+# AsyncOption.apply
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+Async<('a -> 'b) option> -> Async<'a option> 
+  -> Async<'b option>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+// string -> int
+let characterCount (s: string) = s.Length
+```
+
+### Example 1
+
+```fsharp
+let result =
+    AsyncOption.some "foo" // Async<string option>
+    |> AsyncOption.apply (AsyncOption.some characterCount) // Async<int option>
+
+// async { Some 3 }
+```
+
+### Example 2
+
+```fsharp
+let result =
+    Async.singleton None // Async<string option>
+    |> AsyncOption.apply (AsyncOption.some characterCount) // Async<int option>
+
+// async { None }
+```
+
+### Example 3
+
+```fsharp
+let result : Async<int option> =
+    AsyncOption.some "foo" // Async<string option>
+    |> AsyncOption.apply (Async.singleton None) // Async<int option>
+
+// async { None }
+```

gitbook/asyncOption/bind.md

@@ -0,0 +1,65 @@
+# AsyncOption.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('TInput -> Async<'TOutput option>) -> Async<'TInput option> -> Async<'TOutput option>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+type Account =
+  { EmailAddress : string
+    Name : string }
+
+// string -> Async<Account option>
+let lookupAccountByEmail email = async {
+  let john = { EmailAddress = "[email protected]"; Name = "John Johnson" }
+  let jeff = { EmailAddress = "[email protected]"; Name = "Jeff Jefferson" }
+  let jack = { EmailAddress = "[email protected]"; Name = "Jack Jackson" }
+  
+  // Just a map lookup, but imagine we look up an account in our database
+  let accounts = Map.ofList [
+      ("[email protected]", john)
+      ("[email protected]", jeff)
+      ("[email protected]", jack)
+  ]
+  
+  return Map.tryFind email accounts
+}
+```
+
+### Example 1
+
+```fsharp
+let asyncOpt : Async<Account option> =
+    AsyncOption.some "[email protected]" // Async<string option>
+    |> AsyncOption.bind lookupAccountByEmail // Async<Account option>
+
+// async { Some { EmailAddress = "[email protected]"; Name = "John Johnson" } }
+```
+
+### Example 2
+
+```fsharp
+let asyncOpt : Async<Account option> =
+    AsyncOption.some "[email protected]" // Async<string option>
+    |> AsyncOption.bind lookupAccountByEmail // Async<Account option>
+
+// async { None }
+```
+
+### Example 3
+
+```fsharp
+let asyncOpt : Async<Account option> =
+    Async.singleton None // Async<string option>
+    |> AsyncOption.bind lookupAccountByEmail // Async<Account option>
+
+// async { None }
+```

gitbook/asyncOption/either.md

@@ -0,0 +1,30 @@
+# AsyncOption.either
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+Provide two functions to execute depending on the value of the option. If the option is `Some`, the first function will be executed. If the option is `None`, the second function will be executed.
+
+```fsharp
+(onSome : 'T -> Async<'output>) -> (onNone : Async<'output>) -> (input : Async<'T option>) -> Async<'output>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+AsyncOption.either (fun x -> async { x * 2 }) (async { 0 }) (AsyncOption.some 5)
+
+// async { 10 }
+```
+
+### Example 2
+
+```fsharp
+AsyncOption.either (fun x -> x * 2) (async { 0 }) None
+
+// async { 0 }
+```
+

gitbook/asyncOption/map.md

@@ -0,0 +1,30 @@
+# AsyncOption.map
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the value of an async option if it is `Some`. If the option is `None`, return `None`.
+
+## Function Signature
+
+```fsharp
+('TInput -> 'TOutput) -> Async<'TInput option> -> Async<'TOutput option>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+AsyncOption.map (fun x -> x + 1) (AsyncOption.some 1)
+
+// async { Some 2 }
+```
+
+### Example 2
+
+```fsharp
+AsyncOption.map (fun x -> x + 1) (Async.singleton None)
+
+// async { None }
+```
+

gitbook/asyncOption/orElseFunctions.md

@@ -0,0 +1,111 @@
+# OrElse Functions
+
+## AsyncOption.orElse
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Returns the option if the option is Some, otherwise returns the given option
+
+### Function Signature
+
+```fsharp
+(ifNone : Async<'value option>) -> (input : Async<'value option>) 
+    -> Async<'value option>
+```
+
+### Examples
+
+#### Example 1
+
+```fsharp
+let asyncOption : Async<int option> =
+    AsyncOption.some 1
+    |> AsyncOption.orElse (AsyncOption.some 2)
+    
+// async { Some 1 }
+```
+
+#### Example 2
+
+```fsharp
+let asyncOption : Async<int option> =
+    AsyncOption.some 1
+    |> AsyncOption.orElse (Async.singleton None)
+    
+// async { Some 1 }
+```
+
+#### Example 3
+
+```fsharp
+let asyncOption : Async<int option> =
+    Async.singleton None
+    |> AsyncOption.orElse (Some 2)
+    
+// async { Some 2 }
+```
+
+#### Example 4
+
+```fsharp
+let asyncOption : Async<int option> =
+    Async.singleton None
+    |> AsyncOption.orElse (Async.singleton None)
+
+// async { None }
+```
+
+## AsyncOption.orElseWith
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Returns the option if the option is Some, otherwise evaluates the given function and returns the result.
+
+### Function Signature
+
+```fsharp
+(ifNoneFunc : unit -> Async<'value option>) -> (input : Async<'value option>)
+    -> Async<'value option>
+```
+
+### Examples
+
+#### Example 1
+
+```fsharp
+let asyncOption : Async<int option> =
+    AsyncOption.some 1
+    |> AsyncOption.orElseWith (fun () -> AsyncOption.some 2)
+
+// async { Some 1 }
+```
+
+#### Example 2
+
+```fsharp
+let asyncOption : Async<int option> =
+    AsyncOption.some 1
+    |> AsyncOption.orElseWith (fun () -> None)
+
+// async { Some 1 }
+```
+
+#### Example 3
+
+```fsharp
+let asyncOption : Async<int option> =
+    Async.singleton None
+    |> AsyncOption.orElseWith (fun () -> AsyncOption.some 2)
+
+// async { Some 2 }
+```
+
+#### Example 4
+
+```fsharp
+let asyncOption : Async<int option> =
+    Async.singleton None
+    |> AsyncOption.orElseWith (fun () -> Async.singleton None)
+
+// async { None }
+```

gitbook/asyncOption/others.md

@@ -0,0 +1,33 @@
+# Other AsyncOption Functions
+
+## defaultValue
+
+Returns the contained value if Some, otherwise returns the provided value
+
+### Function Signature
+
+```fsharp
+'a -> Async<'a option> -> Async<'a>
+```
+
+## defaultWith
+
+Returns the contained value if Some, otherwise evaluates the given function and returns the result.
+
+### Function Signature
+
+```fsharp
+(unit -> 'a) -> Async<'a option> -> Async<'a>
+```
+
+## some
+
+Wraps the provided value in an Async<value option>
+
+### Function Signature
+
+```fsharp
+'a -> Async<'a option>
+```
+
+