Result.safe() supports an Error-class and unwraps nested Results. Result.map() now also allows callbacks that return a value directly.

Author: Erik

README.md

@@ -131,7 +131,7 @@ function doStuff(value: number): Result<Error, number> {
 
 #### Result.safe
 
-Functions as a try-catch, returning the return-value of the callback on success, or the predefined error or caught error on failure:
+Functions as a try-catch, returning the return-value of the callback on success, or the predefined error(-class) or caught error on failure:
 
 ```ts
 // with caught error...
@@ -153,6 +153,17 @@ const result = Result.safe(new CustomError("Custom error!"), () => {
 
   return value;
 }); // Result<CustomError, number>
+
+// with predefined error-class...
+class CustomError extends Error {}
+
+const result = Result.safe(CustomError, () => {
+  let value = 2;
+
+  // code that might throw...
+
+  return value;
+}); // Result<CustomError, number>
 ```
 
 #### Result.combine
@@ -292,7 +303,7 @@ const value = result.getOrThrow();
 #### Result.map()
 
 Maps a result to another result.
-If the result is success, it will call the callback-function with the encapsulated value, which must return another Result.
+If the result is success, it will call the callback-function with the encapsulated value, which returnr another Result.
 If the result is failure, it will ignore the callback-function, and will return the initial Result (error)
 
 ```ts
@@ -302,7 +313,13 @@ class ErrorB extends Error {}
 function doA(): Result<ErrorA, number> {}
 function doB(value: number): Result<ErrorB, string> {}
 
-const result = doA().map(value => doB(value)); // Result<ErrorA | ErrorB, string>
+// nested results will flat-map to a single Result...
+const result1 = doA().map(value => doB(value)); // Result<ErrorA | ErrorB, string>
+
+// ...or transform the successful value right away
+// note: underneath, the callback is wrapped inside Result.safe() in case the callback
+// might throw
+const result2 = doA().map(value => value * 2); // Result<ErrorA | Error, number>
 ```
 
 #### Result.forward()

src/index.ts

@@ -6,6 +6,10 @@ function isAsyncFn(fn: Function) {
   return fn.constructor.name === "AsyncFunction";
 }
 
+function isResult(value: unknown): value is Result<any, any, any> {
+  return value instanceof Ok || value instanceof Err;
+}
+
 interface SyncThenable {
   isSync: true;
   then<Fn extends () => Promise<any>>(cb: Fn): ReturnType<Fn>;
@@ -228,7 +232,8 @@ interface IResult<ErrorType, OkType> {
 
   /**
    * **Maps a result to another result**
-   * If the result is success, it will call the callback-function with the encapsulated value, which must return another Result.
+   * If the result is success, it will call the callback-function with the encapsulated value, which returns another Result.
+   * Nested Results are supported, which will basically act as a flat-map.
    * If the result is failure, it will ignore the callback-function.
    *
    * Example:
@@ -245,15 +250,29 @@ interface IResult<ErrorType, OkType> {
    *  // ...
    * }
    *
-   * const result = doA().map(value => doB(value)); // Result<ErrorA | ErrorB, string>
+   * // nested results will flat-map to a single Result...
+   * const result1 = doA().map(value => doB(value)); // Result<ErrorA | ErrorB, string>
+   *
+   * // ...or transform the successful value right away
+   * // note: underneath, the callback is wrapped inside Result.safe() in case the callback
+   * // might throw
+   * const result2 = doA().map(value => value * 2); // Result<ErrorA | Error, number>
    * ```
    */
-  map<T extends Result<any, any, any>>(
-    fn: (value: OkType) => T
-  ): JoinErrorTypes<ErrorType, T>;
-  map<T extends Result<any, any, any>>(
+  map<T>(
     fn: (value: OkType) => Promise<T>
-  ): Promise<JoinErrorTypes<ErrorType, T>>;
+  ): Promise<
+    JoinErrorTypes<
+      ErrorType,
+      T extends Result<any, any, any> ? T : Result<Error, T, any>
+    >
+  >;
+  map<T>(
+    fn: (value: OkType) => T
+  ): JoinErrorTypes<
+    ErrorType,
+    T extends Result<any, any, any> ? T : Result<Error, T, any>
+  >;
 
   /**
    * **Rolls back things that were successful**
@@ -380,6 +399,10 @@ export namespace Result {
     return new Err<ErrorType, OkType, RollbackFn>(error, rollbackFn);
   }
 
+  type SafeReturnType<E, T> = T extends Result<any, any, any>
+    ? Result<E | InferErrorType<T>, InferOkType<T>, never>
+    : Result<E, T, never>;
+
   /**
    * **Functions as a try-catch, returning the return-value of the callback on success, or the predefined error or caught error on failure **
    *
@@ -404,39 +427,65 @@ export namespace Result {
    *
    *   return value;
    * }); // Result<CustomError, number>
+   *
+   * // with predefined error Class...
+   * const result = Result.safe(CustomError, () => {
+   *   let value = 2;
+   *
+   *   // code that might throw...
+   *
+   *   return value;
+   * }); // Result<CustomError, number>
    * ```
    */
-  export function safe<ErrorType, OkType>(
-    fn: () => Promise<OkType>
-  ): Promise<Result<Error, OkType, never>>;
-  export function safe<ErrorType, OkType>(
-    fn: () => OkType
-  ): Result<Error, OkType, never>;
-  export function safe<ErrorType, OkType>(
-    err: ErrorType,
-    fn: () => Promise<OkType>
-  ): Promise<Result<ErrorType, OkType, never>>;
-  export function safe<ErrorType, OkType>(
-    err: ErrorType,
-    fn: () => OkType
-  ): Result<ErrorType, OkType, never>;
+  export function safe<T>(
+    fn: () => Promise<T>
+  ): Promise<SafeReturnType<Error, T>>;
+  export function safe<T>(fn: () => T): SafeReturnType<Error, T>;
+  export function safe<ErrorType, T>(
+    err: ErrorType | (new (...args: any[]) => ErrorType),
+    fn: () => Promise<T>
+  ): Promise<SafeReturnType<ErrorType, T>>;
+  export function safe<ErrorType, T>(
+    err: ErrorType | (new (...args: any[]) => ErrorType),
+    fn: () => T
+  ): SafeReturnType<ErrorType, T>;
   export function safe(errOrFn: any, fn?: any) {
     const hasCustomError = fn !== undefined;
 
     const execute = hasCustomError ? fn : errOrFn;
 
+    function getError(caughtError: Error) {
+      if (!hasCustomError) {
+        // just forward the original Error
+        return caughtError;
+      }
+
+      // pass the caught error to the specified constructor
+      if (typeof errOrFn === "function") {
+        return new errOrFn(caughtError);
+      }
+
+      // return predefined error
+      return errOrFn;
+    }
+
     try {
       const resultOrPromise = execute();
 
       if (resultOrPromise instanceof Promise) {
         return resultOrPromise
-          .then(okValue => Result.ok(okValue))
-          .catch(caughtError => error(hasCustomError ? errOrFn : caughtError));
+          .then(okValue => {
+            return isResult(okValue) ? okValue : Result.ok(okValue);
+          })
+          .catch(caughtError => error(getError(caughtError)));
       }
 
-      return ok(resultOrPromise);
+      return isResult(resultOrPromise)
+        ? resultOrPromise
+        : Result.ok(resultOrPromise);
     } catch (caughtError) {
-      return error(hasCustomError ? errOrFn : caughtError);
+      return error(getError(caughtError));
     }
   }
 
@@ -650,20 +699,28 @@ abstract class Base<
     throw new Error("Method not implemented.");
   }
 
-  map<T extends Result<any, any, any>>(
-    fn: (value: OkType) => T
-  ): JoinErrorTypes<ErrorType, T>;
-  map<T extends Result<any, any, any>>(
+  map<T>(
     fn: (value: OkType) => Promise<T>
-  ): Promise<JoinErrorTypes<ErrorType, T>>;
+  ): Promise<
+    JoinErrorTypes<
+      ErrorType,
+      T extends Result<any, any, any> ? T : Result<Error, T, any>
+    >
+  >;
+  map<T>(
+    fn: (value: OkType) => T
+  ): JoinErrorTypes<
+    ErrorType,
+    T extends Result<any, any, any> ? T : Result<Error, T, any>
+  >;
   map(fn: any) {
     if (this.isFailure()) {
       return isAsyncFn(fn) ? Promise.resolve(this) : this;
     }
 
-    const result = fn((this as any).value) as any;
+    const result = Result.safe(() => fn((this as any).value) as any);
 
-    return result;
+    return result as any;
   }
 
   rollback(): RollbackFn extends RollbackFunction

src/test/index.test.ts

@@ -65,25 +65,57 @@ describe("Result", () => {
         expect((result as any).value).toBe(123);
       });
 
-      it("returns an Result.Error when the callbacks throws", () => {
-        const result = Result.safe(ERROR, () => {
-          throw new Error("This should fail");
-          // @ts-ignore
+      it("allows you to pass in a Error constructor", () => {
+        class CustomError extends Error {
+          isCustom = true;
+        }
+        const result = Result.safe(CustomError, () => {
+          throw new Error("random error");
           return 1;
         });
 
-        expect(result.isFailure()).toBe(true);
-        expect((result as any).error).toBe(ERROR);
+        expect((result as any).error.isCustom).toBe(true);
       });
 
-      it("returns an Result.Error when the callbacks throws", async () => {
-        const result = await Result.safe(ERROR, async () => {
-          throw new Error("This should fail");
-          // @ts-ignore
+      it("allows you to pass in a Error constructor ASYNC", async () => {
+        class CustomError extends Error {
+          isCustom = true;
+        }
+        const result = await Result.safe(CustomError, async () => {
+          throw new Error("random error");
           return 1;
         });
 
-        expect(result.isFailure()).toBe(true);
+        expect((result as any).error.isCustom).toBe(true);
+      });
+
+      it("merges a returned Result when callback is successful", () => {
+        class CustomError {}
+        const result = Result.safe(
+          (): Result<CustomError, number> => {
+            return Result.ok(1);
+          }
+        );
+
+        expect((result as any).value).toBe(1);
+      });
+
+      it("merges a returned Result when callback is successful ASYNC", async () => {
+        const result = await Result.safe(async () => {
+          return Result.ok(1);
+        });
+
+        expect((result as any).value).toBe(1);
+      });
+
+      it("merges a returned Result when callback is failure", () => {
+        class CustomError {}
+        const result = Result.safe(
+          (): Result<CustomError, number> => {
+            return Result.error(ERROR);
+          }
+        );
+
         expect((result as any).error).toBe(ERROR);
       });
     });
@@ -429,26 +461,34 @@ describe("Result", () => {
 
     describe("Result#map()", () => {
       it("maps the value to another Result on success, returns Result.Error on failure", () => {
-        const resultOk = Result.ok<Error, number>(1).map(val =>
+        const resultOk = Result.ok<Error, number>(1).map(val => val * 2);
+        expect((resultOk as any).value).toBe(2);
+
+        const resultNestedOk = Result.ok<Error, number>(1).map(val =>
           Result.ok(val * 2)
         );
-        expect((resultOk as any).value).toBe(2);
+        expect((resultNestedOk as any).value).toBe(2);
 
         const resultError = Result.error<Error, number>(ERROR).map(val =>
-          Result.ok(val * 2)
+          Result.ok<Error, number>(val * 2)
         );
         expect((resultError as any).error).toBe(ERROR);
       });
 
       it("maps the value to another Result on success, returns Result.Error on failure ASYNC", async () => {
+        const resultNestedOk = await Result.ok<Error, number>(1).map(
+          async val => val * 2
+        );
+        expect((resultNestedOk as any).value).toBe(2);
+
         const resultOk = await Result.ok<Error, number>(1).map(async val =>
-          Result.ok(val * 2)
+          Result.ok<Error, number>(val * 2)
         );
         expect((resultOk as any).value).toBe(2);
 
         const resultError = await Result.error<Error, number>(
           ERROR
-        ).map(async val => Result.ok(val * 2));
+        ).map(async val => Result.ok<Error, number>(val * 2));
         expect((resultError as any).error).toBe(ERROR);
       });
     });