From 2a7ebaf4cbde5892787a60f006b83d51131eb86b Mon Sep 17 00:00:00 2001
From: Brian Friesen <brian.friesen@gmail.com>
Date: Mon, 17 Apr 2023 14:29:31 -0400
Subject: [PATCH] Add Rescue methods

---
 CHANGELOG.md                                  |   1 +
 .../Rescue_methods.cs                         | 290 ++++++++++++++++++
 RandomSkunk.Results/Operations/Rescue.cs      | 243 +++++++++++++++
 3 files changed, 534 insertions(+)
 create mode 100644 RandomSkunk.Results.UnitTests/Rescue_methods.cs
 create mode 100644 RandomSkunk.Results/Operations/Rescue.cs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 46eb97a..60a4a2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning].
 
 - RandomSkunk.Results:
     - Add `Maybe<T>.ToFailIfNone` method.
+    - Add `Rescue` methods.
 
 ### Fixed
 - RandomSkunk.Results:
diff --git a/RandomSkunk.Results.UnitTests/Rescue_methods.cs b/RandomSkunk.Results.UnitTests/Rescue_methods.cs
new file mode 100644
index 0000000..7aca68c
--- /dev/null
+++ b/RandomSkunk.Results.UnitTests/Rescue_methods.cs
@@ -0,0 +1,290 @@
+namespace RandomSkunk.Results.UnitTests;
+
+public class Rescue_methods
+{
+    public class For_Result_sync
+    {
+        [Fact]
+        public void Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Result.Success();
+            var rescueResult = Result.Fail();
+
+            var actual = sourceResult.Rescue(error => rescueResult);
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public void Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Result.Fail();
+            var rescueResult = Result.Success();
+            Error? capturedError = null;
+
+            var actual = sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return rescueResult;
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public void Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Result.Fail();
+            var thrownException = new Exception();
+
+            var actual = sourceResult.Rescue((Func<Error, Result>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+
+    public class For_Result_async
+    {
+        [Fact]
+        public async Task Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Result.Success();
+            var rescueResult = Result.Fail();
+
+            var actual = await sourceResult.Rescue(error => Task.FromResult(rescueResult));
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Result.Fail();
+            var rescueResult = Result.Success();
+            Error? capturedError = null;
+
+            var actual = await sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return Task.FromResult(rescueResult);
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Result.Fail();
+            var thrownException = new Exception();
+
+            var actual = await sourceResult.Rescue((Func<Error, Task<Result>>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+
+    public class For_Result_of_T_sync
+    {
+        [Fact]
+        public void Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Result<int>.Success(123);
+            var rescueResult = Result<int>.Fail();
+
+            var actual = sourceResult.Rescue(error => rescueResult);
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public void Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Result<int>.Fail();
+            var rescueResult = Result<int>.Success(123);
+            Error? capturedError = null;
+
+            var actual = sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return rescueResult;
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public void Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Result<int>.Fail();
+            var thrownException = new Exception();
+
+            var actual = sourceResult.Rescue((Func<Error, Result<int>>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+
+    public class For_Result_of_T_async
+    {
+        [Fact]
+        public async Task Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Result<int>.Success(123);
+            var rescueResult = Result<int>.Fail();
+
+            var actual = await sourceResult.Rescue(error => Task.FromResult(rescueResult));
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Result<int>.Fail();
+            var rescueResult = Result<int>.Success(123);
+            Error? capturedError = null;
+
+            var actual = await sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return Task.FromResult(rescueResult);
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Result<int>.Fail();
+            var thrownException = new Exception();
+
+            var actual = await sourceResult.Rescue((Func<Error, Task<Result<int>>>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+
+    public class For_Maybe_of_T_sync
+    {
+        [Fact]
+        public void Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Maybe<int>.Success(123);
+            var rescueResult = Maybe<int>.Fail();
+
+            var actual = sourceResult.Rescue(error => rescueResult);
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public void Given_None_Returns_source()
+        {
+            var sourceResult = Maybe<int>.None;
+            var rescueResult = Maybe<int>.Fail();
+
+            var actual = sourceResult.Rescue(error => rescueResult);
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public void Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Maybe<int>.Fail();
+            var rescueResult = Maybe<int>.Success(123);
+            Error? capturedError = null;
+
+            var actual = sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return rescueResult;
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public void Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Maybe<int>.Fail();
+            var thrownException = new Exception();
+
+            var actual = sourceResult.Rescue((Func<Error, Maybe<int>>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+
+    public class For_Maybe_of_T_async
+    {
+        [Fact]
+        public async Task Given_IsSuccess_Returns_source()
+        {
+            var sourceResult = Maybe<int>.Success(123);
+            var rescueResult = Maybe<int>.Fail();
+
+            var actual = await sourceResult.Rescue(error => Task.FromResult(rescueResult));
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public async Task Given_IsNone_Returns_source()
+        {
+            var sourceResult = Maybe<int>.None;
+            var rescueResult = Maybe<int>.Fail();
+
+            var actual = await sourceResult.Rescue(error => Task.FromResult(rescueResult));
+
+            actual.Should().Be(sourceResult);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_Returns_result_from_rescue_function()
+        {
+            var sourceResult = Maybe<int>.Fail();
+            var rescueResult = Maybe<int>.Success(123);
+            Error? capturedError = null;
+
+            var actual = await sourceResult.Rescue(error =>
+            {
+                capturedError = error;
+                return Task.FromResult(rescueResult);
+            });
+
+            actual.Should().Be(rescueResult);
+            capturedError.Should().Be(sourceResult.Error);
+        }
+
+        [Fact]
+        public async Task Given_IsFail_When_rescue_function_throws_Returns_result_from_caught_exception()
+        {
+            var sourceResult = Maybe<int>.Fail();
+            var thrownException = new Exception();
+
+            var actual = await sourceResult.Rescue((Func<Error, Task<Maybe<int>>>)(error => throw thrownException));
+
+            actual.IsFail.Should().BeTrue();
+            actual.Error.ErrorCode.Should().Be(ErrorCodes.CaughtException);
+            actual.Error.InnerError!.Title.Should().Be(nameof(Exception));
+        }
+    }
+}
diff --git a/RandomSkunk.Results/Operations/Rescue.cs b/RandomSkunk.Results/Operations/Rescue.cs
new file mode 100644
index 0000000..f482b23
--- /dev/null
+++ b/RandomSkunk.Results/Operations/Rescue.cs
@@ -0,0 +1,243 @@
+namespace RandomSkunk.Results;
+
+/// <content> Defines the <c>Rescue</c> methods. </content>
+public partial struct Result
+{
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public Result Rescue(Func<Error, Result> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public async Task<Result> Rescue(Func<Error, Task<Result>> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return await onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+}
+
+/// <content> Defines the <c>Rescue</c> methods. </content>
+public partial struct Result<T>
+{
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public Result<T> Rescue(Func<Error, Result<T>> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public async Task<Result<T>> Rescue(Func<Error, Task<Result<T>>> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return await onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+}
+
+/// <content> Defines the <c>Rescue</c> methods. </content>
+public partial struct Maybe<T>
+{
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public Maybe<T> Rescue(Func<Error, Maybe<T>> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public async Task<Maybe<T>> Rescue(Func<Error, Task<Maybe<T>>> onFail)
+    {
+        if (onFail is null) throw new ArgumentNullException(nameof(onFail));
+
+        if (_outcome == Outcome.Fail)
+        {
+            try
+            {
+                return await onFail(GetError());
+            }
+            catch (Exception ex)
+            {
+                return Fail(ex, Error.GetMessageForExceptionThrownInCallback(nameof(onFail)));
+            }
+        }
+
+        return this;
+    }
+}
+
+/// <content> Defines the <c>Rescue</c> extension methods. </content>
+public static partial class ResultExtensions
+{
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Result> Rescue(this Task<Result> sourceResult, Func<Error, Result> onFail) =>
+        (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail);
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Result> Rescue(this Task<Result> sourceResult, Func<Error, Task<Result>> onFail) =>
+        await (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail).ConfigureAwait(ContinueOnCapturedContext);
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <typeparam name="T">The type of the source result value.</typeparam>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Result<T>> Rescue<T>(this Task<Result<T>> sourceResult, Func<Error, Result<T>> onFail) =>
+        (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail);
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <typeparam name="T">The type of the source result value.</typeparam>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Result<T>> Rescue<T>(this Task<Result<T>> sourceResult, Func<Error, Task<Result<T>>> onFail) =>
+        await (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail).ConfigureAwait(ContinueOnCapturedContext);
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <typeparam name="T">The type of the source result value.</typeparam>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Maybe<T>> Rescue<T>(this Task<Maybe<T>> sourceResult, Func<Error, Maybe<T>> onFail) =>
+        (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail);
+
+    /// <summary>
+    /// Rescues a <c>Fail</c> result by returning the output of the <paramref name="onFail"/> function. If the current result is
+    /// <c>Success</c>, nothing happens and the current result is returned.
+    /// </summary>
+    /// <typeparam name="T">The type of the source result value.</typeparam>
+    /// <param name="sourceResult">The source result.</param>
+    /// <param name="onFail">The function that rescues a failed operation.</param>
+    /// <returns>The output of the <paramref name="onFail"/> function if the current result is <c>Fail</c>, or the same result if
+    ///     it is <c>Success</c>.</returns>
+    public static async Task<Maybe<T>> Rescue<T>(this Task<Maybe<T>> sourceResult, Func<Error, Task<Maybe<T>>> onFail) =>
+        await (await sourceResult.ConfigureAwait(ContinueOnCapturedContext)).Rescue(onFail).ConfigureAwait(ContinueOnCapturedContext);
+}