Add cancellableValueTaskOption and cancellableValueTaskResult CEs for IcedTasks (#349)

* Initial plan

* Add cancellableValueTaskOption and cancellableValueTaskResult CEs for IcedTasks

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

* Fix some function, add doc comments, and add gitbook documentation

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

* Avoid state machine creation in CancellableValueTaskOption.some

Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TheAngryByrd <1490044+TheAngryByrd@users.noreply.github.com>

Author: Copilot

gitbook/SUMMARY.md

@@ -310,6 +310,22 @@
       * [ofChoice](cancellableTaskValidation/ofChoice.md)
       * [ofResult](cancellableTaskValidation/ofResult.md)
 
+  * CancellableValueTaskOption
+    * [apply](cancellableValueTaskOption/apply.md)
+    * [bind](cancellableValueTaskOption/bind.md)
+    * [Computation Expression](cancellableValueTaskOption/ce.md)
+    * [either](cancellableValueTaskOption/either.md)
+    * [map](cancellableValueTaskOption/map.md)
+    * [Other Functions](cancellableValueTaskOption/others.md)
+    * [zip](cancellableValueTaskOption/zip.md)
+
+  * [CancellableValueTaskResult](cancellableValueTaskResult/index.md)
+    * [apply](cancellableValueTaskResult/apply.md)
+    * [bind](cancellableValueTaskResult/bind.md)
+    * [Computation Expression](cancellableValueTaskResult/ce.md)
+    * [map](cancellableValueTaskResult/map.md)
+    * [zip](cancellableValueTaskResult/zip.md)
+
 * FsToolkit.ErrorHandling.JobResult
   * Job
     * [apply](pr.md)

gitbook/cancellableValueTaskOption/apply.md

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

gitbook/cancellableValueTaskOption/bind.md

@@ -0,0 +1,64 @@
+# CancellableValueTaskOption.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('input -> CancellableValueTask<'output option>) -> CancellableValueTask<'input option> -> CancellableValueTask<'output option>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+type Account =
+  { EmailAddress : string
+    Name : string }
+
+// string -> CancellableValueTask<Account option>
+let lookupAccountByEmail email = cancellableValueTask {
+  let john = { EmailAddress = "john@test.com"; Name = "John Johnson" }
+  let jeff = { EmailAddress = "jeff@test.com"; Name = "Jeff Jefferson" }
+  let jack = { EmailAddress = "jack@test.com"; Name = "Jack Jackson" }
+  
+  let accounts = Map.ofList [
+      ("john@test.com", john)
+      ("jeff@test.com", jeff)
+      ("jack@test.com", jack)
+  ]
+  
+  return Map.tryFind email accounts
+}
+```
+
+### Example 1
+
+```fsharp
+let taskOpt : CancellableValueTask<Account option> =
+    CancellableValueTaskOption.some "john@test.com" // CancellableValueTask<string option>
+    |> CancellableValueTaskOption.bind lookupAccountByEmail // CancellableValueTask<Account option>
+
+// cancellableValueTask { Some { EmailAddress = "john@test.com"; Name = "John Johnson" } }
+```
+
+### Example 2
+
+```fsharp
+let taskOpt : CancellableValueTask<Account option> =
+    CancellableValueTaskOption.some "jerry@test.com" // CancellableValueTask<string option>
+    |> CancellableValueTaskOption.bind lookupAccountByEmail // CancellableValueTask<Account option>
+
+// cancellableValueTask { None }
+```
+
+### Example 3
+
+```fsharp
+let taskOpt : CancellableValueTask<Account option> =
+    CancellableValueTask.singleton None // CancellableValueTask<string option>
+    |> CancellableValueTaskOption.bind lookupAccountByEmail // CancellableValueTask<Account option>
+
+// cancellableValueTask { None }
+```

gitbook/cancellableValueTaskOption/ce.md

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

gitbook/cancellableValueTaskOption/either.md

@@ -0,0 +1,32 @@
+# CancellableValueTaskOption.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 -> CancellableValueTask<'output>) 
+	-> (onNone : unit -> CancellableValueTask<'output>) 
+	-> (input : CancellableValueTask<'T option>) 
+	-> CancellableValueTask<'output>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+CancellableValueTaskOption.either (fun x -> cancellableValueTask { return x * 2 }) (fun () -> cancellableValueTask { return 0 }) (CancellableValueTaskOption.some 5)
+
+// cancellableValueTask { 10 }
+```
+
+### Example 2
+
+```fsharp
+CancellableValueTaskOption.either (fun x -> cancellableValueTask { return x * 2 }) (fun () -> cancellableValueTask { return 0 }) (CancellableValueTask.singleton None)
+
+// cancellableValueTask { 0 }
+```

gitbook/cancellableValueTaskOption/map.md

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

gitbook/cancellableValueTaskOption/others.md

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

gitbook/cancellableValueTaskOption/zip.md

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

gitbook/cancellableValueTaskResult/apply.md

@@ -0,0 +1,32 @@
+# CancellableValueTaskResult.apply
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+CancellableValueTask<Result<('a -> 'b), 'c>> -> CancellableValueTask<Result<'a, 'c>> -> CancellableValueTask<Result<'b, 'c>>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let result =
+    CancellableValueTaskResult.singleton "foo"
+    |> CancellableValueTaskResult.apply (CancellableValueTaskResult.singleton String.length)
+
+// cancellableValueTask { Ok 3 }
+```
+
+### Example 2
+
+```fsharp
+let err : CancellableValueTask<Result<int, string>> = cancellableValueTask { return Error "some error" }
+let result =
+    err
+    |> CancellableValueTaskResult.apply (CancellableValueTaskResult.singleton String.length)
+
+// cancellableValueTask { Error "some error" }
+```

gitbook/cancellableValueTaskResult/bind.md

@@ -0,0 +1,29 @@
+# CancellableValueTaskResult.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+('a -> CancellableValueTask<Result<'b, 'c>>)
+  -> CancellableValueTask<Result<'a, 'c>>
+  -> CancellableValueTask<Result<'b, 'c>>
+```
+
+## Examples
+
+Note: Many use-cases requiring `bind` operations can also be solved using [the `cancellableValueTaskResult` computation expression](../cancellableValueTaskResult/ce.md).
+
+### Example 1
+
+Continuing from the CancellableValueTaskResult.map2 example and given the function
+
+```fsharp
+let notifyFollowers : NotifyNewPostRequest -> CancellableValueTask<Result<unit,exn>>
+```
+
+We can notify all followers using `CancellableValueTaskResult.bind` as below:
+
+```fsharp
+newPostRequestResult |> CancellableValueTaskResult.bind notifyFollowers
+```