added Result.forward()

Author: Erik

README.md

@@ -38,7 +38,7 @@ The problem with this 'usual' try-catch approach is that:
 - it makes our code harder to reason about. We need to look at implementation details to discover what might go wrong.
 - it makes the control flow of our code harder to reason about, especially with multiple (nested) try-catch statements
 
-Instead, we could express the outcome of code to be executed in the form of a Return-type. People using your code will be explicitly confronted with the fact that code potentially might fail, and will know upfront what kind of errors they can expect.
+Instead, we could express the outcome of code to be executed in the form of a Result-type. People using your code will be explicitly confronted with the fact that code potentially might fail, and will know upfront what kind of errors they can expect.
 
 ## Installation
 
@@ -305,6 +305,36 @@ function doB(value: number): Result<ErrorB, string> {}
 const result = doA().map(value => doB(value)); // Result<ErrorA | ErrorB, string>
 ```
 
+#### Result.forward()
+
+Creates and forwards a brand new Result out of the current error or value.
+This is useful if you want to return early after failure.
+
+```ts
+class ErrorA extends Error {}
+class ErrorB extends Error {}
+
+function doA(): Result<ErrorA, number> {}
+function doB(): Result<ErrorB, number> {}
+
+function performAction(): Result<ErrorA | ErrorB, number> {
+  const resultA = doA();
+  if (resultA.isFailure()) {
+    return resultA.forward();
+  }
+
+  const resultB = doA();
+  if (resultB.isFailure()) {
+    return resultB.forward();
+  }
+
+  // from here both 'a' and 'b' are valid values
+  const [a, b] = [resultA.value, resultB.value];
+
+  return a + b;
+}
+```
+
 ## Rollbacks
 
 There are cases where a series of operations are performed that need to be treated as a 'unit of work'. In other words: if the last operation fails, de preceding operations should also fail, despite the fact that those preceding operations succeeded on their own. In such cases you probably want some kind of recovering a.k.a. a rollback.

src/index.ts

@@ -702,6 +702,13 @@ class Ok<
   toString(): string {
     return `Result.Ok(${this.value})`;
   }
+
+  /**
+   * **Creates and forwards a brand new Result out of the current error or value **
+   */
+  forward(): Result<unknown, OkType, RollbackFn> {
+    return Result.ok(this.value);
+  }
 }
 
 class Err<
@@ -727,4 +734,11 @@ class Err<
   toString(): string {
     return `Result.Error(${this.error})`;
   }
+
+  /**
+   * **Creates and forwards a brand new Result out of the current error or value **
+   */
+  forward(): Result<ErrorType, unknown, RollbackFn> {
+    return Result.error(this.error);
+  }
 }

src/test/index.test.ts

@@ -452,5 +452,15 @@ describe("Result", () => {
         expect((resultError as any).error).toBe(ERROR);
       });
     });
+
+    describe("Result#forward", () => {
+      it("forwards a error or value into a new Result", () => {
+        const error = Result.error(ERROR);
+        expect(error.forward().errorOrNull()).toBe(ERROR);
+
+        const success = Result.ok("success");
+        expect(success.forward().getOrNull()).toBe("success");
+      });
+    });
   });
 });