Add requireSomeWith and requireNoneWith for lazy error evaluation (#352)

* Initial plan

* Add requireSomeWith and requireNoneWith helpers to Result, AsyncResult, TaskResult, and JobResult

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

* Add gitbook documentation for requireSomeWith and requireNoneWith

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/asyncResult/others.md

@@ -20,6 +20,12 @@ Converts an async-wrapped Option to a Result, using the given error if None.
 ```fsharp
 'a -> Async<'b option> -> Async<Result<'b, 'a>>`
 ```
+### requireSomeWith
+
+Converts an async-wrapped Option to a Result, using the given error factory if None. The error factory is only called when the value is `None`.
+```fsharp
+(unit -> 'a) -> Async<'b option> -> Async<Result<'b, 'a>>
+```
 ### requireNone
 
 Converts an async-wrapped Option to a Result, using the given error if Some.
@@ -28,6 +34,14 @@ Converts an async-wrapped Option to a Result, using the given error if Some.
 'a -> Async<'b option> -> Async<Result<unit, 'a>>`
 ```
 
+### requireNoneWith
+
+Converts an async-wrapped Option to a Result, using the given error factory if Some. The error factory is only called when the value is `Some`.
+
+```fsharp
+(unit -> 'a) -> Async<'b option> -> Async<Result<unit, 'a>>
+```
+
 ### requireValueSome
 
 Converts an async-wrapped ValueOption to a Result, using the given error if ValueNone.

gitbook/jobResult/others.md

@@ -20,6 +20,12 @@ Converts an job-wrapped Option to a Result, using the given error if None.
 ```fsharp
 'a -> job<'b option> -> job<Result<'b, 'a>>`
 ```
+### requireSomeWith
+
+Converts an job-wrapped Option to a Result, using the given error factory if None. The error factory is only called when the value is `None`.
+```fsharp
+(unit -> 'a) -> job<'b option> -> job<Result<'b, 'a>>
+```
 ### requireNone
 
 Converts an job-wrapped Option to a Result, using the given error if Some.
@@ -28,6 +34,14 @@ Converts an job-wrapped Option to a Result, using the given error if Some.
 'a -> job<'b option> -> job<Result<unit, 'a>>`
 ```
 
+### requireNoneWith
+
+Converts an job-wrapped Option to a Result, using the given error factory if Some. The error factory is only called when the value is `Some`.
+
+```fsharp
+(unit -> 'a) -> job<'b option> -> job<Result<unit, 'a>>
+```
+
 ### requireValueSome
 
 Converts an job-wrapped ValueOption to a Result, using the given error if ValueNone.

gitbook/result/requireFunctions.md

@@ -96,6 +96,38 @@ let result : Result<unit, string> =
 // Error "Value must be Some"
 ```
 
+## requireSomeWith
+
+Converts an Option to a Result, using the given error factory if None. The error factory is only called when the value is `None`.
+
+### Function Signature
+
+```fsharp
+(unit -> 'a) -> 'b option -> Result<'b, 'a>
+```
+
+### Examples
+
+#### Example 1
+
+```fsharp
+let result : Result<int, string> =
+    Some 1
+    |> Result.requireSomeWith (fun () -> "Value must be Some")
+    
+// Ok 1
+```
+
+#### Example 2
+
+```fsharp
+let result : Result<int, string> =
+    None
+    |> Result.requireSomeWith (fun () -> "Value must be Some")
+    
+// Error "Value must be Some"
+```
+
 ## requireNone
 
 Converts an Option to a Result, using the given error if Some.
@@ -128,6 +160,38 @@ let result : Result<unit, string> =
 // Error "Value must be None"
 ```
 
+## requireNoneWith
+
+Converts an Option to a Result, using the given error factory if Some. The error factory is only called when the value is `Some`.
+
+### Function Signature
+
+```fsharp
+(unit -> 'a) -> 'b option -> Result<unit, 'a>
+```
+
+### Examples
+
+#### Example 1
+
+```fsharp
+let result : Result<unit, string> =
+    None
+    |> Result.requireNoneWith (fun () -> "Value must be None")
+    
+// Ok ()
+```
+
+#### Example 2
+
+```fsharp
+let result : Result<unit, string> =
+    Some 1
+    |> Result.requireNoneWith (fun () -> "Value must be None")
+    
+// Error "Value must be None"
+```
+
 ## requireValueSome
 
 Converts an ValueOption to a Result, using the given error if ValueNone.

gitbook/taskResult/others.md

@@ -20,6 +20,12 @@ Converts an task-wrapped Option to a Result, using the given error if None.
 ```fsharp
 'a -> Task<'b option> -> Task<Result<'b, 'a>>`
 ```
+### requireSomeWith
+
+Converts an task-wrapped Option to a Result, using the given error factory if None. The error factory is only called when the value is `None`.
+```fsharp
+(unit -> 'a) -> Task<'b option> -> Task<Result<'b, 'a>>
+```
 ### requireNone
 
 Converts an task-wrapped Option to a Result, using the given error if Some.
@@ -28,6 +34,14 @@ Converts an task-wrapped Option to a Result, using the given error if Some.
 'a -> Task<'b option> -> Task<Result<unit, 'a>>`
 ```
 
+### requireNoneWith
+
+Converts an task-wrapped Option to a Result, using the given error factory if Some. The error factory is only called when the value is `Some`.
+
+```fsharp
+(unit -> 'a) -> Task<'b option> -> Task<Result<unit, 'a>>
+```
+
 ### requireValueSome
 
 Converts an task-wrapped ValueOption to a Result, using the given error if ValueNone.

src/FsToolkit.ErrorHandling.JobResult/JobResult.fs

@@ -122,11 +122,21 @@ module JobResult =
         option
         |> Job.map (Result.requireSome error)
 
+    // Converts an job-wrapped Option to a Result, using the given error factory if None.
+    let inline requireSomeWith ([<InlineIfLambda>] errorFactory: unit -> 'error) option =
+        option
+        |> Job.map (Result.requireSomeWith errorFactory)
+
     // Converts an job-wrapped Option to a Result, using the given error if Some.
     let inline requireNone error option =
         option
         |> Job.map (Result.requireNone error)
 
+    // Converts an job-wrapped Option to a Result, using the given error factory if Some.
+    let inline requireNoneWith ([<InlineIfLambda>] errorFactory: unit -> 'error) option =
+        option
+        |> Job.map (Result.requireNoneWith errorFactory)
+
     // Converts an job-wrapped ValueOption to a Result, using the given error if ValueNone.
     let inline requireValueSome error voption =
         voption

src/FsToolkit.ErrorHandling/AsyncResult.fs

@@ -158,6 +158,14 @@ module AsyncResult =
         value
         |> Async.map (Result.requireSome error)
 
+    // Converts an async-wrapped Option to a Result, using the given error factory if None.
+    let inline requireSomeWith
+        ([<InlineIfLambda>] errorFactory: unit -> 'error)
+        (value: Async<'ok option>)
+        : Async<Result<'ok, 'error>> =
+        value
+        |> Async.map (Result.requireSomeWith errorFactory)
+
     // Converts an async-wrapped Option to a Result, using the given error if Some.
     let inline requireNone
         (error: 'error)
@@ -166,6 +174,14 @@ module AsyncResult =
         value
         |> Async.map (Result.requireNone error)
 
+    // Converts an async-wrapped Option to a Result, using the given error factory if Some.
+    let inline requireNoneWith
+        ([<InlineIfLambda>] errorFactory: unit -> 'error)
+        (value: Async<'ok option>)
+        : Async<Result<unit, 'error>> =
+        value
+        |> Async.map (Result.requireNoneWith errorFactory)
+
     // Converts an async-wrapped ValueOption to a Result, using the given error if ValueNone.
     let inline requireValueSome
         (error: 'error)

src/FsToolkit.ErrorHandling/Result.fs

@@ -307,6 +307,20 @@ module Result =
         | Some x -> Ok x
         | None -> Error error
 
+    /// <summary>
+    /// Requires a value to be <c>Some</c>, otherwise returns an error result using the given error factory.
+    /// </summary>
+    /// <param name="errorFactory">A function to produce the error value if the value is <c>None</c>.</param>
+    /// <param name="option">The <c>Option</c> value to check.</param>
+    /// <returns>An <c>Ok</c> result if the value is <c>Some</c>, otherwise an Error result with the value produced by <paramref name="errorFactory" />.</returns>
+    let inline requireSomeWith
+        ([<InlineIfLambda>] errorFactory: unit -> 'error)
+        (option: 'ok option)
+        : Result<'ok, 'error> =
+        match option with
+        | Some x -> Ok x
+        | None -> Error(errorFactory ())
+
     /// <summary>
     /// Requires a value to be <c>None</c>, otherwise returns an error result.
     ///
@@ -320,6 +334,20 @@ module Result =
         | Some _ -> Error error
         | None -> Ok()
 
+    /// <summary>
+    /// Requires a value to be <c>None</c>, otherwise returns an error result using the given error factory.
+    /// </summary>
+    /// <param name="errorFactory">A function to produce the error value if the value is <c>Some</c>.</param>
+    /// <param name="option">The <c>Option</c> value to check.</param>
+    /// <returns>An <c>Ok</c> result if the value is <c>None</c>, otherwise an Error result with the value produced by <paramref name="errorFactory" />.</returns>
+    let inline requireNoneWith
+        ([<InlineIfLambda>] errorFactory: unit -> 'error)
+        (option: 'value option)
+        : Result<unit, 'error> =
+        match option with
+        | Some _ -> Error(errorFactory ())
+        | None -> Ok()
+
     /// <summary>
     /// Requires a value to be <c>ValueSome</c>, otherwise returns an error result.
     ///

src/FsToolkit.ErrorHandling/TaskResult.fs

@@ -107,11 +107,21 @@ module TaskResult =
         option
         |> Task.map (Result.requireSome error)
 
+    // Converts an task-wrapped Option to a Result, using the given error factory if None.
+    let inline requireSomeWith ([<InlineIfLambda>] errorFactory: unit -> 'error) option =
+        option
+        |> Task.map (Result.requireSomeWith errorFactory)
+
     // Converts an task-wrapped Option to a Result, using the given error if Some.
     let inline requireNone error option =
         option
         |> Task.map (Result.requireNone error)
 
+    // Converts an task-wrapped Option to a Result, using the given error factory if Some.
+    let inline requireNoneWith ([<InlineIfLambda>] errorFactory: unit -> 'error) option =
+        option
+        |> Task.map (Result.requireNoneWith errorFactory)
+
     // Converts an task-wrapped ValueOption to a Result, using the given error if ValueNone.
     let inline requireValueSome error voption =
         voption

tests/FsToolkit.ErrorHandling.JobResult.Tests/JobResult.fs

@@ -284,6 +284,22 @@ let requireSomeTests =
             |> Expect.hasJobErrorValueSync err
     ]
 
+[<Tests>]
+let requireSomeWithTests =
+    testList "JobResult.requireSomeWith Tests" [
+        testCase "requireSomeWith happy path"
+        <| fun _ ->
+            toJob (Some 42)
+            |> JobResult.requireSomeWith (fun () -> err)
+            |> Expect.hasJobOkValueSync 42
+
+        testCase "requireSomeWith error path"
+        <| fun _ ->
+            toJob None
+            |> JobResult.requireSomeWith (fun () -> err)
+            |> Expect.hasJobErrorValueSync err
+    ]
+
 [<Tests>]
 let requireNoneTests =
     testList "JobResult.requireNone Tests" [
@@ -300,6 +316,22 @@ let requireNoneTests =
             |> Expect.hasJobErrorValueSync err
     ]
 
+[<Tests>]
+let requireNoneWithTests =
+    testList "JobResult.requireNoneWith Tests" [
+        testCase "requireNoneWith happy path"
+        <| fun _ ->
+            toJob None
+            |> JobResult.requireNoneWith (fun () -> err)
+            |> Expect.hasJobOkValueSync ()
+
+        testCase "requireNoneWith error path"
+        <| fun _ ->
+            toJob (Some 42)
+            |> JobResult.requireNoneWith (fun () -> err)
+            |> Expect.hasJobErrorValueSync err
+    ]
+
 [<Tests>]
 let requireValueSomeTests =
     testList "JobResult.requireValueSome Tests" [

tests/FsToolkit.ErrorHandling.Tests/AsyncResult.fs

@@ -296,6 +296,20 @@ let requireSomeTests =
     ]
 
 
+let requireSomeWithTests =
+    testList "AsyncResult.requireSomeWith Tests" [
+        testCaseAsync "requireSomeWith happy path"
+        <| (toAsync (Some 42)
+            |> AsyncResult.requireSomeWith (fun () -> err)
+            |> Expect.hasAsyncOkValue 42)
+
+        testCaseAsync "requireSomeWith error path"
+        <| (toAsync None
+            |> AsyncResult.requireSomeWith (fun () -> err)
+            |> Expect.hasAsyncErrorValue err)
+    ]
+
+
 let requireNoneTests =
     testList "AsyncResult.requireNone Tests" [
         testCaseAsync "requireNone happy path"
@@ -310,6 +324,20 @@ let requireNoneTests =
     ]
 
 
+let requireNoneWithTests =
+    testList "AsyncResult.requireNoneWith Tests" [
+        testCaseAsync "requireNoneWith happy path"
+        <| (toAsync None
+            |> AsyncResult.requireNoneWith (fun () -> err)
+            |> Expect.hasAsyncOkValue ())
+
+        testCaseAsync "requireNoneWith error path"
+        <| (toAsync (Some 42)
+            |> AsyncResult.requireNoneWith (fun () -> err)
+            |> Expect.hasAsyncErrorValue err)
+    ]
+
+
 let requireValueSomeTests =
     testList "AsyncResult.requireValueSome Tests" [
         testCaseAsync "requireValueSome happy path"
@@ -1034,7 +1062,9 @@ let allTests =
         requireTrueTests
         requireFalseTests
         requireSomeTests
+        requireSomeWithTests
         requireNoneTests
+        requireNoneWithTests
         requireValueSomeTests
         requireValueNoneTests
         requireEqualToTests