Add overload of Catch that returns an IPromise or IPromise<PromisedT> to allow asynchronous continuation

These versions of Catch allow for recovery of a chain of promises by
handling an error from an earlier state, then getting back into the
"normal" flow of processing.

Rework of PR Real-Serious-Games#77.

Author: ReneB

Tests/PromiseTests.cs

@@ -202,7 +202,7 @@ public void error_handler_is_not_invoked_for_resolved_promised()
         {
             var promise = new Promise<int>();
 
-            promise.Catch(e => throw new Exception("This shouldn't happen"));
+            promise.Catch(onRejected: e => throw new Exception("This shouldn't happen"));
 
             promise.Resolve(5);
         }
@@ -1472,5 +1472,65 @@ public void rejected_reject_callback_is_caught_by_chained_catch()
 
             Assert.Equal(expectedException, actualException);
         }
+
+        [Fact]
+        public void rejected_catch_returning_resolved_promise_state_is_adopted()
+        {
+            var promise = new Promise<int>();
+            int expectedValue = 1;
+            int actualValue = 0;
+
+            promise.Catch(err => Promise<int>.Resolved(expectedValue))
+                   .Then(result => { actualValue = result; });
+
+            promise.Reject(new Exception());
+
+            Assert.Equal(expectedValue, actualValue);
+        }
+
+        [Fact]
+        public void rejected_catch_returning_rejected_promise_state_is_adopted()
+        {
+            var promise = new Promise<int>();
+            int expectedValue = 1;
+            int actualValue = 0;
+
+            promise.Catch(err => Promise<int>.Rejected(new Exception()))
+                   .Catch(err => actualValue = expectedValue);
+
+            promise.Reject(new Exception());
+
+            Assert.Equal(expectedValue, actualValue);
+        }
+
+        [Fact]
+        public void rejected_catch_returning_resolved_promise_state_is_adopted_nongeneric()
+        {
+            var promise = new Promise();
+            int expectedValue = 1;
+            int actualValue = 0;
+
+            promise.Catch(err => Promise.Resolved())
+                   .Then(() => { actualValue = expectedValue; });
+
+            promise.Reject(new Exception());
+
+            Assert.Equal(expectedValue, actualValue);
+        }
+
+        [Fact]
+        public void rejected_catch_returning_rejected_promise_state_is_adopted_nongeneric()
+        {
+            var promise = new Promise();
+            int expectedValue = 1;
+            int actualValue = 0;
+
+            promise.Catch(err => Promise.Rejected(new Exception()))
+                   .Catch(err => actualValue = expectedValue);
+
+            promise.Reject(new Exception());
+
+            Assert.Equal(expectedValue, actualValue);
+        }
     }
 }

src/Promise.cs

@@ -51,6 +51,11 @@ public interface IPromise<PromisedT>
         /// </summary>
         IPromise<PromisedT> Catch(Func<Exception, PromisedT> onRejected);
 
+        /// <summary>
+        /// Handle errors for the promise and adopt status of returned promise..
+        /// </summary>
+        IPromise<PromisedT> Catch(Func<Exception, IPromise<PromisedT>> rejectionHandler);
+
         /// <summary>
         /// Add a resolved callback that chains a value promise (optionally converting to a different value type).
         /// </summary>
@@ -602,6 +607,35 @@ public IPromise<PromisedT> Catch(Func<Exception, PromisedT> onRejected)
             return resultPromise;
         }
 
+        /// <summary>
+        /// Handle errors for the promise and adopt status of returned promise..
+        /// </summary>
+        public IPromise<PromisedT> Catch(Func<Exception, IPromise<PromisedT>> recoveryMethod) {
+            var resultPromise = new Promise<PromisedT>();
+            resultPromise.WithName(Name);
+
+            Action<PromisedT> resolveHandler = v => resultPromise.Resolve(v);
+
+            Action<Exception> rejectHandler = ex =>
+            {
+                try {
+                    recoveryMethod(ex)
+                        .Progress(progress => resultPromise.ReportProgress(progress))
+                        .Then(resolve => resultPromise.Resolve(resolve))
+                        .Catch(reject => resultPromise.Reject(ex));
+                }
+                catch (Exception cbEx)
+                {
+                    resultPromise.Reject(cbEx);
+                }
+            };
+
+            ActionHandlers(resultPromise, resolveHandler, rejectHandler);
+            ProgressHandlers(resultPromise, v => resultPromise.ReportProgress(v));
+
+            return resultPromise;
+        }
+
         /// <summary>
         /// Add a resolved callback that chains a value promise (optionally converting to a different value type).
         /// </summary>

src/Promise_NonGeneric.cs

@@ -46,6 +46,11 @@ public interface IPromise
         /// </summary>
         IPromise Catch(Action<Exception> onRejected);
 
+        /// <summary>
+        /// Handle errors for the promise and adopt status of returned promise..
+        /// </summary>
+        IPromise Catch(Func<Exception, IPromise> onRejected);
+
         /// <summary>
         /// Add a resolved callback that chains a value promise (optionally converting to a different value type).
         /// </summary>
@@ -689,6 +694,32 @@ public IPromise Catch(Action<Exception> onRejected)
             return resultPromise;
         }
 
+        public IPromise Catch(Func<Exception, IPromise> onRejected) {
+            var resultPromise = new Promise();
+            resultPromise.WithName(Name);
+
+            Action resolveHandler = () => resultPromise.Resolve();
+
+            Action<Exception> rejectHandler = ex =>
+            {
+                try {
+                    onRejected(ex)
+                        .Progress(progress => resultPromise.ReportProgress(progress))
+                        .Then(() => resultPromise.Resolve())
+                        .Catch(reject => resultPromise.Reject(ex));
+                }
+                catch (Exception cbEx)
+                {
+                    resultPromise.Reject(cbEx);
+                }
+            };
+
+            ActionHandlers(resultPromise, resolveHandler, rejectHandler);
+            ProgressHandlers(resultPromise, v => resultPromise.ReportProgress(v));
+
+            return resultPromise;
+        }
+
         /// <summary>
         /// Add a resolved callback that chains a value promise (optionally converting to a different value type).
         /// </summary>