adds optional transform-error callback to recoverCatching to transform caught errors

Author: everweij

package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "typescript-result",
-	"version": "3.2.0-beta.5",
+	"version": "3.2.0-beta.6",
 	"description": "A Result type inspired by Rust and Kotlin that leverages TypeScript's powerful type system to simplify error handling and make your code more readable and maintainable.",
 	"keywords": [
 		"result",

readme.md

@@ -793,7 +793,7 @@ const result = Result.all(...tasks.map(createTask)); // Result<Task[], IOError>
     - [mapCatching(transformFn, transformErrorFn?)](#mapcatchingtransformfn-transformerrorfn)
     - [mapError(transformFn)](#maperrortransformfn)
     - [recover(onFailure)](#recoveronfailure)
-    - [recoverCatching(onFailure)](#recovercatchingonfailure)
+    - [recoverCatching(onFailure, transformErrorFn?)](#recovercatchingonfailure-transformerrorfn)
   - Static methods
     - [Result.ok(value)](#resultokvalue)
     - [Result.error(error)](#resulterrorerror)
@@ -824,7 +824,7 @@ const result = Result.all(...tasks.map(createTask)); // Result<Task[], IOError>
     - [mapCatching(transformFn, transfornErrorFn?)](#mapcatchingtransformfn-transformerrorfn-1)
     - [mapError(transformFn)](#maperrortransformfn-1)
     - [recover(onFailure)](#recoveronfailure-1)
-    - [recoverCatching(onFailure)](#recovercatchingonfailure-1)
+    - [recoverCatching(onFailure, transformErrorFn?)](#recovercatchingonfailure-transformerrorfn-1)
 
 ## Result
 
@@ -1229,7 +1229,7 @@ declare function persistLocally(item: Item): Result<Item, IOError>;
 persistInDB(item).recover(() => persistLocally(item)); // Result<Item, IOError>
 ```
 
-### recoverCatching(onFailure)
+### recoverCatching(onFailure, transformErrorFn?)
 
 Like [`Result.recover`](#recoveronfailure) it transforms a failed result using the `onFailure` callback into a successful result.
 In addition, it catches any exceptions that might be thrown inside the `onFailure` callback and encapsulates them
@@ -1238,6 +1238,7 @@ in a failed result.
 #### Parameters
 
 - `onFailure` callback function to transform the error of the result. The callback can be async as well.
+- `transformError` callback function to transform any potential caught error while recovering the result.`
 
 **returns** a new successful [`Result`](#result) instance or a new successful [`AsyncResult`](#asyncresult) instance when the result represents a failure, or the original instance if it represents a success.
 
@@ -1775,7 +1776,7 @@ declare function persistLocally(item: Item): AsyncResult<Item, IOError>;
 persistInDB(item).recover(() => persistLocally(item)); // AsyncResult<Item, IOError>
 ```
 
-### recoverCatching(onFailure)
+### recoverCatching(onFailure, transformErrorFn?)
 
 Like [`AsyncResult.recover`](#recoveronfailure-1) it transforms a failed result using the `onFailure` callback into a successful result.
 In addition, it catches any exceptions that might be thrown inside the `onFailure` callback and encapsulates them
@@ -1784,6 +1785,7 @@ in a failed result.
 #### Parameters
 
 - `onFailure` callback function to transform the error of the result. The callback can be async as well.
+- `transformError` callback function to transform any potential caught error while recovering the result.`
 
 **returns** a new successful [`AsyncResult`](#asyncresult) instance when the result represents a failure, or the original instance
 if it represents a success.

src/result.test.ts

@@ -718,6 +718,26 @@ describe("Result", () => {
 			Result.assertError(result);
 			expect(result.error).toBeInstanceOf(CustomError);
 		});
+
+		it("allows you to transform the error that was thrown inside the callback into a new error", async () => {
+			const asyncResult = Result.fromAsyncCatching(
+				async (): Promise<number> => {
+					throw new CustomError("Boom!");
+				},
+				(error) => {
+					expect(error).toBeInstanceOf(CustomError);
+					return new ErrorA("my message", { cause: error });
+				},
+			);
+
+			expectTypeOf(asyncResult).toEqualTypeOf<AsyncResult<number, ErrorA>>();
+
+			const result = await asyncResult;
+
+			Result.assertError(result);
+
+			expect(result.error).toBeInstanceOf(ErrorA);
+		});
 	});
 
 	describe("instance methods and getters", () => {
@@ -1728,6 +1748,27 @@ describe("Result", () => {
 				Result.assertOk(await recoveredResult);
 				expect(spy).not.toHaveBeenCalled();
 			});
+
+			it("allows you to transform the error that was thrown inside the callback into a new error", () => {
+				const result = Result.error(new ErrorA()) as Result<number, ErrorA>;
+
+				const nextResult = result.recoverCatching(
+					(error): number => {
+						expectTypeOf(error).toEqualTypeOf<ErrorA>();
+						throw new CustomError();
+					},
+					(error) => {
+						expect(error).toBeInstanceOf(CustomError);
+						return new ErrorB();
+					},
+				);
+
+				expectTypeOf(nextResult).toEqualTypeOf<Result<number, ErrorB>>();
+
+				Result.assertError(nextResult);
+
+				expect(nextResult.error).toBeInstanceOf(ErrorB);
+			});
 		});
 	});
 

src/result.ts

@@ -591,29 +591,35 @@ export class AsyncResult<Value, Err> extends Promise<Result<Value, Err>> {
 	 * in a failed result.
 	 *
 	 * @param onFailure callback function to transform the error of the result. The callback can be async as well.
+	 * @param transformError callback function to transform any potential caught error while recovering the result.
 	 * @returns a new successful {@linkcode AsyncResult} instance when the result represents a failure, or the original instance
 	 * if it represents a success.
 	 */
 	recoverCatching<
 		This extends AnyAsyncResult,
 		ReturnType,
+		ErrorType = NativeError,
 		U = Awaited<ReturnType>,
-	>(this: This, onFailure: (error: InferError<This>) => ReturnType) {
+	>(
+		this: This,
+		onFailure: (error: InferError<This>) => ReturnType,
+		transformError?: (error: unknown) => ErrorType,
+	) {
 		return new AsyncResult<any, any>((resolve, reject) =>
 			this.then((result) => {
-				resolve(result.recoverCatching(onFailure));
+				resolve(result.recoverCatching(onFailure, transformError));
 			}).catch(reject),
 		) as [ReturnType] extends [Promise<infer PValue>]
 			? PValue extends U
 				? AsyncResult<
 						InferValue<This> | ExtractValue<U>,
-						ExtractError<U> | NativeError
+						ExtractError<U> | ErrorType
 					>
 				: never
 			: ReturnType extends U
 				? AsyncResult<
 						InferValue<This> | ExtractValue<U>,
-						ExtractError<U> | NativeError
+						ExtractError<U> | ErrorType
 					>
 				: never;
 	}
@@ -1287,38 +1293,48 @@ export class Result<Value, Err> {
 	 * in a failed result.
 	 *
 	 * @param onFailure callback function to transform the error of the result. The callback can be async as well.
+	 * @param transformError callback function to transform any potential caught error while recovering the result.
 	 * @returns a new successful {@linkcode Result} instance or a new successful {@linkcode AsyncResult} instance
 	 * when the result represents a failure, or the original instance if it represents a success.
 	 */
-	recoverCatching<This extends AnyResult, ReturnType, U = Awaited<ReturnType>>(
+	recoverCatching<
+		This extends AnyResult,
+		ReturnType,
+		ErrorType = NativeError,
+		U = Awaited<ReturnType>,
+	>(
 		this: This,
 		onFailure: (error: InferError<This>) => ReturnType,
+		transformError?: (err: unknown) => ErrorType,
 	) {
 		return (
 			this.success
 				? isAsyncFn(onFailure)
 					? AsyncResult.ok(this._value)
 					: this
-				: Result.try(() => onFailure(this._error))
+				: Result.try(
+						() => onFailure(this._error),
+						transformError as AnyFunction,
+					)
 		) as [ReturnType] extends [Promise<infer PValue>]
 			? PValue extends U
 				? AsyncResult<
 						InferValue<This> | ExtractValue<U>,
-						ExtractError<U> | NativeError
+						ExtractError<U> | ErrorType
 					>
 				: never
 			: IfReturnsAsync<
 					ReturnType,
 					ReturnType extends U
 						? AsyncResult<
 								InferValue<This> | ExtractValue<U>,
-								ExtractError<U> | NativeError
+								ExtractError<U> | ErrorType
 							>
 						: never,
 					ReturnType extends U
 						? Result<
 								InferValue<This> | ExtractValue<U>,
-								ExtractError<U> | NativeError
+								ExtractError<U> | ErrorType
 							>
 						: never
 				>;
@@ -1740,19 +1756,25 @@ export class Result<Value, Err> {
 	 * Similar to {@linkcode Result.fromAsync} this method transforms an async callback function into an {@linkcode AsyncResult} instance.
 	 * In addition, it catches any exceptions that might be thrown during the operation and encapsulates them in a failed result.
 	 */
-	static fromAsyncCatching<T>(
+	static fromAsyncCatching<T, ErrorType = NativeError>(
 		fn: () => Promise<T>,
-	): AsyncResult<ExtractValue<T>, ExtractError<T> | NativeError>;
+		transformError?: (err: unknown) => ErrorType,
+	): AsyncResult<ExtractValue<T>, ExtractError<T> | ErrorType>;
 	/**
 	 * Similar to {@linkcode Result.fromAsync} this method transforms a Promise into an {@linkcode AsyncResult} instance.
 	 * In addition, it catches any exceptions that might be thrown during the operation and encapsulates them in a failed result.
 	 */
-	static fromAsyncCatching<T>(
+	static fromAsyncCatching<T, ErrorType = NativeError>(
 		value: Promise<T>,
-	): AsyncResult<ExtractValue<T>, ExtractError<T> | NativeError>;
-	static fromAsyncCatching(valueOrFn: AnyPromise | AnyAsyncFunction) {
+		transformError?: (err: unknown) => ErrorType,
+	): AsyncResult<ExtractValue<T>, ExtractError<T> | ErrorType>;
+	static fromAsyncCatching(
+		valueOrFn: AnyPromise | AnyAsyncFunction,
+		transformError?: (err: unknown) => any,
+	) {
 		return Result.try(
 			typeof valueOrFn === "function" ? valueOrFn : () => valueOrFn,
+			transformError as AnyFunction,
 		);
 	}