adds toTuple method and util infer getters

Author: everweij

package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "typescript-result",
-	"version": "3.0.0",
+	"version": "3.1.0",
 	"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

@@ -797,6 +797,27 @@ if (result.isError()) {
 }
 ```
 
+### toTuple()
+
+**returns** the result in a tuple format where the first element is the value and the second element is the error.
+
+If the result is successful, the error will be `null`. If the result is a failure, the value will be `null`.
+This method is especially useful when you want to destructure the result into a tuple and use TypeScript's narrowing capabilities.
+
+#### Example
+Narrowing down the type using destructuring
+```ts
+declare const result: Result<number, ErrorA>;
+
+const [value, error] = result.toTuple();
+
+if (error) {
+  // error is ErrorA
+} else {
+  // at this point the value must be a number
+}
+```
+
 ### errorOrNull()
 
 **returns** the encapsulated error if the result is a failure, otherwise `null`.
@@ -1316,6 +1337,27 @@ class AsyncResult<Value, Error> {}
 
 Utility getter that checks if the current instance is an `AsyncResult`.
 
+### toTuple()
+
+**returns** the result in a tuple format where the first element is the value and the second element is the error.
+
+If the result is successful, the error will be `null`. If the result is a failure, the value will be `null`.
+This method is especially useful when you want to destructure the result into a tuple and use TypeScript's narrowing capabilities.
+
+#### Example
+Narrowing down the type using destructuring
+```ts
+declare const result: AsyncResult<number, ErrorA>;
+
+const [value, error] = result.toTuple();
+
+if (error) {
+  // error is ErrorA
+} else {
+  // at this point the value must be a number
+}
+```
+
 ### errorOrNull()
 
 **returns** the encapsulated error if the result is a failure, otherwise `null`.

src/result.test.ts

@@ -611,6 +611,15 @@ describe("Result", () => {
 	});
 
 	describe("instance methods and getters", () => {
+		describe("$inferValue / $inferError", () => {
+			it("infers the value and error type of a result", () => {
+				const result: Result<number, ErrorA> = Result.ok(42);
+
+				expectTypeOf(result.$inferValue).toEqualTypeOf<number>();
+				expectTypeOf(result.$inferError).toEqualTypeOf<ErrorA>();
+			});
+		});
+
 		describe("value", () => {
 			it("returns the encapsulated value on success", () => {
 				const result: Result<number, ErrorA> = Result.ok(42);
@@ -723,6 +732,56 @@ describe("Result", () => {
 			});
 		});
 
+		describe("toTuple", () => {
+			it("returns a tuple on a successful result", () => {
+				const result: Result<number, ErrorA> = Result.ok(2);
+
+				const [value, error] = result.toTuple();
+				if (error) {
+					expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				} else {
+					expectTypeOf(value).toEqualTypeOf<number>();
+				}
+
+				expect(value).toBe(2);
+				expect(error).toBeNull();
+			});
+
+			it("returns a tuple on a failed result", () => {
+				const result: Result<number, ErrorA> = Result.error(errorA);
+
+				const [value, error] = result.toTuple();
+				if (error) {
+					expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				} else {
+					expectTypeOf(value).toEqualTypeOf<number>();
+				}
+
+				expect(value).toBeNull();
+				expect(error).toBe(errorA);
+			});
+
+			it("handles cases where the result can only be successful", () => {
+				const result = Result.ok(12);
+
+				const [value, error] = result.toTuple();
+				expectTypeOf(value).toEqualTypeOf<number>();
+				expectTypeOf(error).toEqualTypeOf<never>();
+				expect(value).toBe(12);
+				expect(error).toBe(null);
+			});
+
+			it("handles cases where the result can only be a failure", () => {
+				const result = Result.error(errorA);
+
+				const [value, error] = result.toTuple();
+				expectTypeOf(value).toEqualTypeOf<never>();
+				expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				expect(value).toBe(null);
+				expect(error).toBe(errorA);
+			});
+		});
+
 		describe("errorOrNull", () => {
 			it("returns the error on failure", () => {
 				const result: Result<number, CustomError> = Result.error(
@@ -1605,13 +1664,72 @@ describe("AsyncResult", () => {
 	});
 
 	describe("instance methods and getters", () => {
+		describe("$inferValue / $inferError", () => {
+			it("infers the value and error type of a result", () => {
+				const result: AsyncResult<number, ErrorA> = AsyncResult.ok(42);
+
+				expectTypeOf(result.$inferValue).toEqualTypeOf<number>();
+				expectTypeOf(result.$inferError).toEqualTypeOf<ErrorA>();
+			});
+		});
+
 		describe("isAsyncResult", () => {
 			it("tests whether a value is an async-result", () => {
 				const asyncResult = AsyncResult.ok(12);
 				expect(asyncResult.isAsyncResult).toBe(true);
 			});
 		});
 
+		describe("toTuple", () => {
+			it("returns a tuple on a successful result", async () => {
+				const result: AsyncResult<number, ErrorA> = AsyncResult.ok(2);
+
+				const [value, error] = await result.toTuple();
+				if (error) {
+					expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				} else {
+					expectTypeOf(value).toEqualTypeOf<number>();
+				}
+
+				expect(value).toBe(2);
+				expect(error).toBeNull();
+			});
+
+			it("returns a tuple on a failed result", async () => {
+				const result: AsyncResult<number, ErrorA> = AsyncResult.error(errorA);
+
+				const [value, error] = await result.toTuple();
+				if (error) {
+					expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				} else {
+					expectTypeOf(value).toEqualTypeOf<number>();
+				}
+
+				expect(value).toBeNull();
+				expect(error).toBe(errorA);
+			});
+
+			it("handles cases where the result can only be successful", async () => {
+				const result = AsyncResult.ok(12);
+
+				const [value, error] = await result.toTuple();
+				expectTypeOf(value).toEqualTypeOf<number>();
+				expectTypeOf(error).toEqualTypeOf<never>();
+				expect(value).toBe(12);
+				expect(error).toBe(null);
+			});
+
+			it("handles cases where the result can only be a failure", async () => {
+				const result = AsyncResult.error(errorA);
+
+				const [value, error] = await result.toTuple();
+				expectTypeOf(value).toEqualTypeOf<never>();
+				expectTypeOf(error).toEqualTypeOf<ErrorA>();
+				expect(value).toBe(null);
+				expect(error).toBe(errorA);
+			});
+		});
+
 		describe("errorOrNull", async () => {
 			it("returns the error on failure", async () => {
 				const asyncResult = AsyncResult.error(errorA) as AsyncResult<

src/result.ts

@@ -15,6 +15,8 @@ import type {
 } from "./helpers.js";
 import { isAsyncFn, isFunction, isPromise } from "./helpers.js";
 
+// TODO: also add transformError fn to regular map function??
+
 type InferError<T> = T extends Result<any, infer Error> ? Error : never;
 type InferValue<T> = T extends Result<infer Value, any> ? Value : T;
 
@@ -51,13 +53,56 @@ type AccountForFunctionThrowing<Items extends any[]> =
  * Represents the asynchronous outcome of an operation that can either succeed or fail.
  */
 export class AsyncResult<Value, Err> extends Promise<Result<Value, Err>> {
+	/**
+	 * Utiltity getter to infer the value type of the result.
+	 * Note: this getter does not hold any value, it's only used for type inference.
+	 */
+	declare $inferValue: Value;
+
+	/**
+	 * Utiltity getter to infer the error type of the result.
+	 * Note: this getter does not hold any value, it's only used for type inference.
+	 */
+	declare $inferError: Err;
+
 	/**
 	 * Utility getter to check if the current instance is an `AsyncResult`.
 	 */
 	get isAsyncResult(): true {
 		return true;
 	}
 
+	/**
+	 * @returns the result in a tuple format where the first element is the value and the second element is the error.
+	 * If the result is successful, the error will be `null`. If the result is a failure, the value will be `null`.
+	 *
+	 * This method is especially useful when you want to destructure the result into a tuple and use TypeScript's narrowing capabilities.
+	 *
+	 * @example Narrowing down the result type using destructuring
+	 * ```ts
+	 * declare const result: AsyncResult<number, ErrorA>;
+	 *
+	 * const [value, error] = await result.toTuple();
+	 *
+	 * if (error) {
+	 *   // error is ErrorA
+	 *   return;
+	 * }
+	 *
+	 * // value must be a number
+	 * ```
+	 */
+	async toTuple(): Promise<
+		[Err] extends [never]
+			? [value: Value, error: never]
+			: [Value] extends [never]
+				? [value: never, error: Err]
+				: [value: Value, error: null] | [value: null, error: Err]
+	> {
+		const result = await this;
+		return result.toTuple();
+	}
+
 	/**
 	 * @returns the encapsulated error if the result is a failure, otherwise `null`.
 	 */
@@ -549,6 +594,18 @@ export class Result<Value, Err> {
 		private readonly _error: Err,
 	) {}
 
+	/**
+	 * Utiltity getter to infer the value type of the result.
+	 * Note: this getter does not hold any value, it's only used for type inference.
+	 */
+	declare $inferValue: Value;
+
+	/**
+	 * Utiltity getter to infer the error type of the result.
+	 * Note: this getter does not hold any value, it's only used for type inference.
+	 */
+	declare $inferError: Err;
+
 	/**
 	 * Utility getter that checks if the current instance is a `Result`.
 	 */
@@ -661,6 +718,34 @@ export class Result<Value, Err> {
 		return this.failure;
 	}
 
+	/**
+	 * @returns the result in a tuple format where the first element is the value and the second element is the error.
+	 * If the result is successful, the error will be `null`. If the result is a failure, the value will be `null`.
+	 *
+	 * This method is especially useful when you want to destructure the result into a tuple and use TypeScript's narrowing capabilities.
+	 *
+	 * @example Narrowing down the result type using destructuring
+	 * ```ts
+	 * declare const result: Result<number, ErrorA>;
+	 *
+	 * const [value, error] = result.toTuple();
+	 *
+	 * if (error) {
+	 *   // error is ErrorA
+	 *   return;
+	 * }
+	 *
+	 * // value must be a number
+	 * ```
+	 */
+	toTuple() {
+		return [this._value ?? null, this._error ?? null] as [Err] extends [never]
+			? [value: Value, error: never]
+			: [Value] extends [never]
+				? [value: never, error: Err]
+				: [value: Value, error: null] | [value: null, error: Err];
+	}
+
 	/**
 	 * @returns the encapsulated error if the result is a failure, otherwise `null`.
 	 */