adds overload to Result.fromAsync to create an async-result using an async callback fn

Author: everweij

readme.md

@@ -685,16 +685,76 @@ See [Async support](#async-support) for more context.
 
 Because it can be quite cumbersome to work with results that are wrapped in a promise, we provide an `AsyncResult` type that is essentially a regular promise that contains a `Result` type, along with most of the methods that are available on the regular `Result` type. This makes it easier to chain operations without having to assign the intermediate results to a variable or having to use `await` for each async operation.
 
-There are of course plenty of scenarios where an async function returns a `Result` (`Promise<Result<*, *>>`). In these cases, you can use the `fromAsync` and `fromAsyncCatching` methods to convert the promise to an `AsyncResult`, and continue chaining operations:
+There are of course plenty of scenarios where an async function (or method) returns a `Result` (`Promise<Result<*, *>>`). Although there nothing wrong with this per se, it can become a bit cumbersome to await each function call before you can perform any operations. You can use the `fromAsync` and `fromAsyncCatching` utility methods to make working with results in an async context more ergonomic and developer-friendly.
+
+There are two approaches you can choose from: transform to an `AsyncResult` _directly at the source_, or let the _consuming code_ handle the conversion. Let's look at both approaches in more detail.
+
+#### Transforming to an `AsyncResult` directly at the source
+
+Before:
+```ts
+// Note the `async` keyword and that we return a `Promise` holding a `Result`
+async function findUserById(id: string): Promise<Result<User, NotFoundError>> {
+  const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
+
+  if (!user) {
+    return Result.error(new NotFoundError("User not found"));
+  }
+
+  return Result.ok(user);
+}
+
+async function getDisplayName(userId: string): Promise<string> {
+  return (await findUserById(userId))
+    .map((user) => user.name)
+    .getOrElse(() => "Unknown User");
+}
+```
+
+After:
+```ts
+// Note that we no longer use the `async` keyword and that we return an `AsyncResult`
+// instead of a `Promise`
+function findUserById(id: string): AsyncResult<User, NotFoundError> {
+  return Result.fromAsync(async () => {
+    const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
+
+    if (!user) {
+      return Result.error(new NotFoundError("User not found"));
+    }
+    return Result.ok(user);
+  });
+}
+
+function getDisplayName(userId: string): Promise<string> {
+  return findUserById(userId)
+    .map((user) => user.name)
+    .getOrElse(() => "Unknown User");
+}
+```
+
+The difference might be subtle, but if your codebase has a lot of async operations it might be worth considering this approach.
+
+#### Let the consuming code handle the conversion
+
+You can also choose to do the conversion from the consuming code. The previous example with this approach would translate to this:
 
 ```ts
-async function someAsyncOperation(): Promise<Result<number, Error>> {
-  return Result.ok(42);
+async function findUserById(id: string): Promise<Result<User, NotFoundError>> {
+  const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
+
+  if (!user) {
+    return Result.error(new NotFoundError("User not found"));
+  }
+
+  return Result.ok(user);
 }
 
-const result = await Result.fromAsync(someAsyncOperation())
-  .map((value) => value * 2)
-  // etc...
+async function getDisplayName(userId: string): Promise<string> {
+  return Result.fromAsync(findUserById(userId))
+    .map((user) => user.name)
+    .getOrElse(() => "Unknown User");
+}
 ```
 
 ### Merging or combining results
@@ -743,8 +803,8 @@ const result = Result.all(...tasks.map(createTask)); // Result<Task[], IOError>
     - [Result.allCatching(items)](#resultallcatchingitems)
     - [Result.wrap(fn)](#resultwrapfn)
     - [Result.try(fn, [transform])](#resulttryfn-transform)
-    - [Result.fromAsync(promise)](#resultfromasyncpromise)
-    - [Result.fromAsyncCatching(promise)](#resultfromasynccatchingpromise)
+    - [Result.fromAsync()](#resultfromasync)
+    - [Result.fromAsyncCatching()](#resultfromasynccatching)
     - [Result.assertOk(result)](#resultassertokresult)
     - [Result.assertError(result)](#resultasserterrorresult)
 - [AsyncResult](#asyncresult)
@@ -1336,15 +1396,19 @@ const result = Result.try(
 ); // Result<void, IOError>
 ```
 
-### Result.fromAsync(promise)
+### Result.fromAsync()
 
-Utility method to transform a Promise, that holds a literal value or
-a [`Result`](#result) or [`AsyncResult`](#asyncresult) instance, into an [`AsyncResult`](#asyncresult) instance. Useful when you want to immediately chain operations
+Utility method to:
+- transform a Promise, that holds a literal value or
+a [`Result`](#result) or [`AsyncResult`](#asyncresult) instance; or,
+- transform an async function
+into an [`AsyncResult`](#asyncresult) instance. Useful when you want to immediately chain operations
 after calling an async function.
 
 #### Parameters
 
-- `promise` a Promise that holds a literal value or a [`Result`](#result) or [`AsyncResult`](#asyncresult) instance.
+- `promise` a Promise that holds a literal value or a [`Result`](#result) or [`AsyncResult`](#asyncresult) instance. or,
+- `fn` an async callback funtion returning a literal value or a [`Result`](#result) or [`AsyncResult`](#asyncresult) instance.
 
 **returns** a new [`AsyncResult`](#asyncresult) instance.
 
@@ -1366,9 +1430,9 @@ const result = (await someAsyncOperation()).map((value) => value 2); // Result<n
 const asyncResult = Result.fromAsync(someAsyncOperation()).map((value) => value 2); // AsyncResult<number, Error>
 ```
 
-### Result.fromAsyncCatching(promise)
+### Result.fromAsyncCatching()
 
-Similar to [`Result.fromAsync`](#resultfromasyncpromise) this method transforms a Promise into an [`AsyncResult`](#asyncresult) instance.
+Similar to [`Result.fromAsync`](#resultfromasync) this method transforms a Promise or async callback function into an [`AsyncResult`](#asyncresult) instance.
 In addition, it catches any exceptions that might be thrown during the operation and encapsulates them in a failed result.
 
 ### Result.assertOk(result)

src/integration.test.ts

@@ -82,15 +82,17 @@ describe("User management app", () => {
 			this.users[user.id] = user;
 		}
 
-		async findById(id: number) {
-			const possibleUser = this.users[id];
-			if (!possibleUser) {
-				return Result.error(
-					new NotFoundError(`Cannot find user with id ${id}`),
-				);
-			}
-
-			return Result.ok(possibleUser);
+		findById(id: number) {
+			return Result.fromAsync(async () => {
+				const possibleUser = this.users[id];
+				if (!possibleUser) {
+					return Result.error(
+						new NotFoundError(`Cannot find user with id ${id}`),
+					);
+				}
+
+				return Result.ok(possibleUser);
+			});
 		}
 
 		async existsByEmail(email: string) {
@@ -112,7 +114,8 @@ describe("User management app", () => {
 		}
 
 		updateUserEmail(id: number, email: string) {
-			return Result.fromAsync(this.userRepository.findById(id))
+			return this.userRepository
+				.findById(id)
 				.map((user) => user.updateEmail(email))
 				.onSuccess((user) => this.userRepository.save(user))
 				.map(UserDto.fromUser);

src/result.test.ts

@@ -592,6 +592,55 @@ describe("Result", () => {
 				Result.fromAsync(myFunction()).map(() => 12),
 			).rejects.toThrow(CustomError);
 		});
+
+		it("takes an async function and turns it into an async-result", async () => {
+			const result = Result.fromAsync(async () => {
+				await sleep();
+				return Result.ok(12);
+			});
+
+			expect(result).toBeInstanceOf(AsyncResult);
+			expectTypeOf(result).toEqualTypeOf<AsyncResult<number, never>>();
+			expect(await result).toEqual(Result.ok(12));
+		});
+
+		it("takes an async function that possibly returns multiple types", async () => {
+			const exec = (value: number) =>
+				Result.fromAsync(async () => {
+					if (value === 1) {
+						return "one" as const;
+					}
+
+					if (value === 2) {
+						return Result.ok("two" as const);
+					}
+
+					if (value === 3) {
+						return AsyncResult.ok("three" as const);
+					}
+
+					if (value === 4) {
+						return Promise.resolve("four" as const);
+					}
+
+					if (value === 5) {
+						return Result.error(new ErrorA("five"));
+					}
+
+					return Promise.resolve(Result.error(new ErrorB()));
+				});
+
+			expectTypeOf(exec).returns.toEqualTypeOf<
+				AsyncResult<"one" | "two" | "three" | "four", ErrorA | ErrorB>
+			>();
+
+			expect(await exec(1)).toEqual(Result.ok("one"));
+			expect(await exec(2)).toEqual(Result.ok("two"));
+			expect(await exec(3)).toEqual(Result.ok("three"));
+			expect(await exec(4)).toEqual(Result.ok("four"));
+			expect(await exec(5)).toEqual(Result.error(new ErrorA("five")));
+			expect(await exec(6)).toEqual(Result.error(new ErrorB()));
+		});
 	});
 
 	describe("Result.fromAsyncCatching", () => {
@@ -618,6 +667,57 @@ describe("Result", () => {
 			Result.assertError(resolvedAsyncResult);
 			expect(resolvedAsyncResult.error).toBeInstanceOf(CustomError);
 		});
+
+		it("takes an async function that possibly returns multiple types", async () => {
+			const exec = (value: number) =>
+				Result.fromAsyncCatching(async () => {
+					if (value === 1) {
+						return "one" as const;
+					}
+
+					if (value === 2) {
+						return Result.ok("two" as const);
+					}
+
+					if (value === 3) {
+						return AsyncResult.ok("three" as const);
+					}
+
+					if (value === 4) {
+						return Promise.resolve("four" as const);
+					}
+
+					if (value === 5) {
+						return Result.error(new ErrorA("five"));
+					}
+
+					return Promise.resolve(Result.error(new ErrorB()));
+				});
+
+			expectTypeOf(exec).returns.toEqualTypeOf<
+				AsyncResult<"one" | "two" | "three" | "four", ErrorA | ErrorB | Error>
+			>();
+
+			expect(await exec(1)).toEqual(Result.ok("one"));
+			expect(await exec(2)).toEqual(Result.ok("two"));
+			expect(await exec(3)).toEqual(Result.ok("three"));
+			expect(await exec(4)).toEqual(Result.ok("four"));
+			expect(await exec(5)).toEqual(Result.error(new ErrorA("five")));
+			expect(await exec(6)).toEqual(Result.error(new ErrorB()));
+		});
+
+		it("catches thrown exceptions inside the callback correctly", async () => {
+			const asyncResult = Result.fromAsyncCatching(async () => {
+				throw new CustomError("Boom!");
+			});
+
+			expectTypeOf(asyncResult).toEqualTypeOf<AsyncResult<never, Error>>();
+			expect(asyncResult).toBeInstanceOf(AsyncResult);
+
+			const result = await asyncResult;
+			Result.assertError(result);
+			expect(result.error).toBeInstanceOf(CustomError);
+		});
 	});
 
 	describe("instance methods and getters", () => {

src/result.ts

@@ -1665,6 +1665,41 @@ export class Result<Value, Err> {
 		}
 	}
 
+	/**
+	 * Utility method to transform an async function to an {@linkcode AsyncResult} instance. Useful when you want to
+	 * immediately chain operations after calling an async function/method that returns a Result.
+	 *
+	 * @param fn the async callback function that returns a literal value or a {@linkcode Result} or {@linkcode AsyncResult} instance.
+	 *
+	 * @returns a new {@linkcode AsyncResult} instance.
+	 *
+	 * > [!NOTE]
+	 * > Any exceptions that might be thrown are not caught, so it is your responsibility
+	 * > to handle these exceptions. Please refer to {@linkcode Result.fromAsyncCatching} for a version that catches exceptions
+	 * > and encapsulates them in a failed result.
+	 *
+	 * @example
+	 * basic usage
+	 *
+	 * ```ts
+	 * function findUserById(id: string) {
+	 *   return Result.fromAsync(async () => {
+	 *     const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
+	 *
+	 *     if (!user) {
+	 *       return Result.error(new NotFoundError("User not found"));
+	 *     }
+	 *
+	 *     return Result.ok(user);
+	 *   });
+	 * }
+	 *
+	 * const displayName = await findUserById("123").fold((user) => user.name, () => "Unknown User");
+	 * ```
+	 */
+	static fromAsync<T>(
+		fn: () => Promise<T>,
+	): AsyncResult<ExtractValue<T>, ExtractError<T>>;
 	/**
 	 * Utility method to transform a Promise, that holds a literal value or
 	 * a {@linkcode Result} or {@linkcode AsyncResult} instance, into an {@linkcode AsyncResult} instance. Useful when you want to immediately chain operations
@@ -1692,40 +1727,33 @@ export class Result<Value, Err> {
 	 * const asyncResult = Result.fromAsync(someAsyncOperation()).map((value) => value * 2); // AsyncResult<number, Error>
 	 * ```
 	 */
-	static fromAsync<T extends Promise<AnyAsyncResult>>(
-		value: T,
-	): T extends Promise<AsyncResult<infer V, infer E>>
-		? AsyncResult<V, E>
-		: never;
-	static fromAsync<T extends Promise<AnyResult>>(
-		value: T,
-	): T extends Promise<Result<infer V, infer E>> ? AsyncResult<V, E> : never;
-	static fromAsync<T extends AnyPromise>(
-		value: T,
-	): T extends Promise<infer V> ? AsyncResult<V, never> : never;
-	static fromAsync(value: unknown): unknown {
-		return Result.run(() => value);
+	static fromAsync<T>(
+		value: Promise<T>,
+	): AsyncResult<ExtractValue<T>, ExtractError<T>>;
+	static fromAsync(valueOrFn: AnyPromise | AnyAsyncFunction) {
+		return Result.run(
+			typeof valueOrFn === "function" ? valueOrFn : () => valueOrFn,
+		);
 	}
 
+	/**
+	 * 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>(
+		fn: () => Promise<T>,
+	): AsyncResult<ExtractValue<T>, ExtractError<T> | NativeError>;
 	/**
 	 * 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 extends Promise<AnyAsyncResult>>(
-		value: T,
-	): T extends Promise<AsyncResult<infer V, infer E>>
-		? AsyncResult<V, E | NativeError>
-		: never;
-	static fromAsyncCatching<T extends Promise<AnyResult>>(
-		value: T,
-	): T extends Promise<Result<infer V, infer E>>
-		? AsyncResult<V, E | NativeError>
-		: never;
-	static fromAsyncCatching<T extends AnyPromise>(
-		value: T,
-	): T extends Promise<infer V> ? AsyncResult<V, NativeError> : never;
-	static fromAsyncCatching(value: unknown): unknown {
-		return Result.try(() => value);
+	static fromAsyncCatching<T>(
+		value: Promise<T>,
+	): AsyncResult<ExtractValue<T>, ExtractError<T> | NativeError>;
+	static fromAsyncCatching(valueOrFn: AnyPromise | AnyAsyncFunction) {
+		return Result.try(
+			typeof valueOrFn === "function" ? valueOrFn : () => valueOrFn,
+		);
 	}
 
 	/**