Add valueTaskValueOption CE for ValueTask<'T voption> computation expressions (#348)

* Initial plan

* Add valueTaskValueOption CE (ValueTask<'T voption> computation expression)

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

* Fix duplicate System import in ValueTaskValueOptionCE.fs

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

* Add gitbook documentation for valueTaskValueOption

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

@@ -176,6 +176,15 @@
     * [Other Functions](taskValueOption/others.md)
     * [zip](taskValueOption/zip.md)
 
+  * ValueTaskValueOption
+    * [apply](valueTaskValueOption/apply.md)
+    * [bind](valueTaskValueOption/bind.md)
+    * [Computation Expression](valueTaskValueOption/ce.md)
+    * [either](valueTaskValueOption/either.md)
+    * [map](valueTaskValueOption/map.md)
+    * [Other Functions](valueTaskValueOption/others.md)
+    * [zip](valueTaskValueOption/zip.md)
+
   * TaskResult
     * [apply](taskResult/apply.md)
     * [bind](taskResult/bind.md)

gitbook/valueTaskValueOption/apply.md

@@ -0,0 +1,48 @@
+# ValueTaskValueOption.apply
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Function Signature:
+
+```fsharp
+ValueTask<('a -> 'b) voption> -> ValueTask<'a voption> -> ValueTask<'b voption>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+// string -> int
+let characterCount (s: string) = s.Length
+```
+
+### Example 1
+
+```fsharp
+let result =
+    ValueTaskValueOption.valueSome "foo" // ValueTask<string voption>
+    |> ValueTaskValueOption.apply (ValueTaskValueOption.valueSome characterCount) // ValueTask<int voption>
+
+// valueTask { ValueSome 3 }
+```
+
+### Example 2
+
+```fsharp
+let result =
+    ValueTask<_>(ValueNone) // ValueTask<string voption>
+    |> ValueTaskValueOption.apply (ValueTaskValueOption.valueSome characterCount) // ValueTask<int voption>
+
+// valueTask { ValueNone }
+```
+
+### Example 3
+
+```fsharp
+let result : ValueTask<int voption> =
+    ValueTaskValueOption.valueSome "foo" // ValueTask<string voption>
+    |> ValueTaskValueOption.apply (ValueTask<_>(ValueNone)) // ValueTask<int voption>
+
+// valueTask { ValueNone }
+```

gitbook/valueTaskValueOption/bind.md

@@ -0,0 +1,68 @@
+# ValueTaskValueOption.bind
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+```fsharp
+('input -> ValueTask<'output voption>) -> ValueTask<'input voption> -> ValueTask<'output voption>
+```
+
+## Examples
+
+Take the following function for example
+
+```fsharp
+type Account =
+  { EmailAddress : string
+    Name : string }
+
+// string -> ValueTask<Account voption>
+let lookupAccountByEmail email = valueTask {
+  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" }
+  
+  // Just a map lookup, but imagine we look up an account in our database
+  let accounts = Map.ofList [
+      ("john@test.com", john)
+      ("jeff@test.com", jeff)
+      ("jack@test.com", jack)
+  ]
+  
+  return 
+    accounts
+    |> Map.tryFind email
+    |> Option.toValueOption
+}
+```
+
+### Example 1
+
+```fsharp
+let result : ValueTask<Account voption> =
+    ValueTaskValueOption.valueSome "john@test.com" // ValueTask<string voption>
+    |> ValueTaskValueOption.bind lookupAccountByEmail // ValueTask<Account voption>
+
+// valueTask { ValueSome { EmailAddress = "john@test.com"; Name = "John Johnson" } }
+```
+
+### Example 2
+
+```fsharp
+let result : ValueTask<Account voption> =
+    ValueTaskValueOption.valueSome "jerry@test.com" // ValueTask<string voption>
+    |> ValueTaskValueOption.bind lookupAccountByEmail // ValueTask<Account voption>
+
+// valueTask { ValueNone }
+```
+
+### Example 3
+
+```fsharp
+let result : ValueTask<Account voption> =
+    ValueTask<_>(ValueNone) // ValueTask<string voption>
+    |> ValueTaskValueOption.bind lookupAccountByEmail // ValueTask<Account voption>
+
+// valueTask { ValueNone }
+```

gitbook/valueTaskValueOption/ce.md

@@ -0,0 +1,26 @@
+## ValueTaskValueOption 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 voption
+tryFindPersonById : int -> ValueTask<Person voption>
+updatePerson : Person -> ValueTask<unit>
+```
+
+```fsharp
+// ValueTask<unit voption>
+let addResult = valueTaskValueOption {
+  let! personId = tryParseInt "3001"
+  let! age = tryParseInt "35"
+  let! person = tryFindPersonById personId
+  let person = { person with Age = age }
+  do! updatePerson person
+}
+```

gitbook/valueTaskValueOption/either.md

@@ -0,0 +1,32 @@
+# ValueTaskValueOption.either
+
+Namespace: `FsToolkit.ErrorHandling`
+
+## Function Signature
+
+Provide two functions to execute depending on the value of the voption. If the voption is `ValueSome`, the first function will be executed. If the voption is `ValueNone`, the second function will be executed.
+
+```fsharp
+(onValueSome : 'T -> ValueTask<'output>) 
+	-> (onValueNone : unit -> ValueTask<'output>) 
+	-> (input : ValueTask<'T voption>) 
+	-> ValueTask<'output>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+ValueTaskValueOption.either (fun x -> valueTask { return x * 2 }) (fun () -> valueTask { return 0 }) (ValueTaskValueOption.valueSome 5)
+
+// valueTask { 10 }
+```
+
+### Example 2
+
+```fsharp
+ValueTaskValueOption.either (fun x -> valueTask { return x * 2 }) (fun () -> valueTask { return 0 }) (ValueTask<_>(ValueNone))
+
+// valueTask { 0 }
+```

gitbook/valueTaskValueOption/map.md

@@ -0,0 +1,29 @@
+# ValueTaskValueOption.map
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Apply a function to the value of a value task voption if it is `ValueSome`. If the voption is `ValueNone`, return `ValueNone`.
+
+## Function Signature
+
+```fsharp
+('input -> 'output) -> ValueTask<'input voption> -> ValueTask<'output voption>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+ValueTaskValueOption.map (fun x -> x + 1) (ValueTaskValueOption.valueSome 1)
+
+// valueTask { ValueSome 2 }
+```
+
+### Example 2
+
+```fsharp
+ValueTaskValueOption.map (fun x -> x + 1) (ValueTask<_>(ValueNone))
+
+// valueTask { ValueNone }
+```

gitbook/valueTaskValueOption/others.md

@@ -0,0 +1,31 @@
+# Other ValueTaskValueOption Functions
+
+## defaultValue
+
+Returns the contained value if ValueSome, otherwise returns the provided value
+
+### Function Signature
+
+```fsharp
+'a -> ValueTask<'a voption> -> ValueTask<'a>
+```
+
+## defaultWith
+
+Returns the contained value if ValueSome, otherwise evaluates the given function and returns the result.
+
+### Function Signature
+
+```fsharp
+(unit -> 'a) -> ValueTask<'a voption> -> ValueTask<'a>
+```
+
+## valueSome
+
+Wraps the provided value in a `ValueTask<'a voption>`
+
+### Function Signature
+
+```fsharp
+'a -> ValueTask<'a voption>
+```

gitbook/valueTaskValueOption/zip.md

@@ -0,0 +1,33 @@
+# ValueTaskValueOption.zip
+
+Namespace: `FsToolkit.ErrorHandling`
+
+Takes two voptions and returns a tuple of the pair or ValueNone if either are ValueNone
+
+## Function Signature
+
+```fsharp
+ValueTask<'left voption> -> ValueTask<'right voption> -> ValueTask<('left * 'right) voption>
+```
+
+## Examples
+
+### Example 1
+
+```fsharp
+let left = ValueTaskValueOption.valueSome 123
+let right = ValueTaskValueOption.valueSome "abc"
+
+ValueTaskValueOption.zip left right
+// valueTask { ValueSome (123, "abc") }
+```
+
+### Example 2
+
+```fsharp
+let left = ValueTaskValueOption.valueSome 123
+let right = ValueTask<_>(ValueNone)
+
+ValueTaskValueOption.zip left right
+// valueTask { ValueNone }
+```

src/FsToolkit.ErrorHandling/FsToolkit.ErrorHandling.fsproj

@@ -41,10 +41,13 @@
     <Compile Include="AsyncOptionOp.fs" />
     <Compile Include="TaskOption.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="TaskValueOption.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
+    <Compile Include="ValueTaskValueOption.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="TaskOptionCE.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="TaskValueOptionCE.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
+    <Compile Include="ValueTaskValueOptionCE.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="TaskOptionOp.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="TaskValueOptionOp.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
+    <Compile Include="ValueTaskValueOptionOp.fs" Condition="'$(FABLE_COMPILER)' != 'true'" />
     <Compile Include="AsyncResultOption.fs" />
     <Compile Include="AsyncResultOptionCE.fs" />
     <Compile Include="AsyncResultOptionOp.fs" />