Add CancellableTaskOption module and CE + tests and documentation (#328)

Author: tw0po1nt

gitbook/SUMMARY.md

@@ -254,6 +254,15 @@
     * [Computation Expression](pr.md)
 
 * FsToolkit.ErrorHandling.IcedTasks
+  * CancellableTaskOption
+    * [apply](cancellableTaskOption/apply.md)
+    * [bind](cancellableTaskOption/bind.md)
+    * [Computation Expression](cancellableTaskOption/ce.md)
+    * [either](cancellableTaskOption/either.md)
+    * [map](cancellableTaskOption/map.md)
+    * [Other Functions](cancellableTaskOption/others.md)
+    * [zip](cancellableTaskOption/zip.md)
+
   * [CancellableTaskResult](cancellableTaskResult/index.md)
     * [apply](cancellableTaskResult/apply.md)
     * [bind](cancellableTaskResult/bind.md)

gitbook/cancellableTaskOption/apply.md

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

gitbook/cancellableTaskOption/bind.md

@@ -0,0 +1,65 @@
+# CancellableTaskOption.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('input -> CancellableTask<'output option>) -> CancellableTask<'input option> -> CancellableTask<'output option>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+type Account =
+  { EmailAddress : string
+    Name : string }
+
+// string -> CancellableTask<Account option>
+let lookupAccountByEmail email = cancellableTask {
+  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 taskOpt : CancellableTask<Account option> =
+    CancellableTaskOption.some "[email protected]" // CancellableTask<string option>
+    |> CancellableTaskOption.bind lookupAccountByEmail // CancellableTask<Account option>
+
+// cancellableTask { Some { EmailAddress = "[email protected]"; Name = "John Johnson" } }
+```
+
+### Example 2
+
+```fsharp
+let taskOpt : CancellableTask<Account option> =
+    CancellableTaskOption.some "[email protected]" // CancellableTask<string option>
+    |> CancellableTaskOption.bind lookupAccountByEmail // CancellableTask<Account option>
+
+// cancellableTask { None }
+```
+
+### Example 3
+
+```fsharp
+let taskOpt : CancellableTask<Account option> =
+    CancellableTask.singleton None // CancellableTask<string option>
+    |> CancellableTaskOption.bind lookupAccountByEmail // CancellableTask<Account option>
+
+// cancellableTask { None }
+```

gitbook/cancellableTaskOption/ce.md

@@ -0,0 +1,26 @@
+## CancellableTaskOption Computation Expression
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Examples:
+
+### Example 1
+
+Given a personId and an age, find a person and update their age.
+
+```fsharp
+tryParseInt : string -> Option<int>
+tryFindPersonById : int -> CancellableTask<Person option>
+updatePerson : Person -> CancellableTask<unit>
+```
+
+```fsharp
+// CancellableTask<unit option>
+let addResult = cancellableTaskOption {
+  let! personId = tryParseInt "3001"
+  let! age = tryParseInt "35"
+  let! person = tryFindPersonById personId
+  let person = { person with Age = age }
+  do! updatePerson person
+}
+```

gitbook/cancellableTaskOption/either.md

@@ -0,0 +1,33 @@
+# CancellableTaskOption.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 -> CancellableTask<'output>) 
+	-> (onNone : CancellableTask<'output>) 
+	-> (input : CancellableTask<'T option>) 
+	-> CancellableTask<'output>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+CancellableTaskOption.either (fun x -> cancellableTask { x * 2 }) (cancellableTask { 0 }) (CancellableTaskOption.some 5)
+
+// cancellableTask { 10 }
+```
+
+### Example 2
+
+```fsharp
+CancellableTaskOption.either (fun x -> x * 2) (cancellableTask { 0 }) None
+
+// cancellableTask { 0 }
+```
+

gitbook/cancellableTaskOption/map.md

@@ -0,0 +1,30 @@
+# CancellableTaskOption.map
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the value of a cancellable task option if it is `Some`. If the option is `None`, return `None`.
+
+## Function Signature
+
+```fsharp
+('input -> 'output) -> CancellableTask<'input option> -> CancellableTask<'output option>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+CancellableTaskOption.map (fun x -> x + 1) (CancellableTaskOption.some 1)
+
+// cancellableTask { Some 2 }
+```
+
+### Example 2
+
+```fsharp
+CancellableTaskOption.map (fun x -> x + 1) (CancellableTask.singleton None)
+
+// cancellableTask { None }
+```
+

gitbook/cancellableTaskOption/others.md

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

gitbook/cancellableTaskOption/zip.md

@@ -0,0 +1,33 @@
+# CancellableTaskOption.zip
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Takes two options and returns a tuple of the pair or None if either are None
+
+## Function Signature
+
+```fsharp
+CancellableTask<'left option> -> CancellableTask<'right option> -> CancellableTask<('left * 'right) option>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let left = CancellableTaskOption.some 123
+let right = CancellableTaskOption.some "abc"
+
+CancellableTaskOption.zip left right
+// cancellableTask { Some (123, "abc") }
+```
+
+### Example 2
+
+```fsharp
+let left = CancellableTaskOption.some 123
+let right = CancellableTaskOption.singleton None
+
+CancellableTaskOption.zip left right
+// cancellableTask { None }
+```

gitbook/taskOption/ce.md

@@ -19,8 +19,8 @@ updatePerson : Person -> Task<unit>
 let addResult = taskOption {
   let! personId = tryParseInt "3001"
   let! age = tryParseInt "35"
-  let! person = tryFindPersonById personId "US-OH"
+  let! person = tryFindPersonById personId
   let person = { person with Age = age }
   do! updatePerson person
 }
-```
+```