From 99d46183c58d91555d126f68d8a11c02d3e844eb Mon Sep 17 00:00:00 2001 From: Nick Potts Date: Fri, 16 Aug 2024 16:27:53 +0800 Subject: [PATCH] remove async methods, change safeUnwrap to unsafeUnwrap. --- README.md | 34 --- src/index.spec.ts | 15 +- src/index.ts | 595 ++++++++++++++++++++++++---------------------- 3 files changed, 314 insertions(+), 330 deletions(-) diff --git a/README.md b/README.md index 6c6657b..7413537 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,8 @@ import { ok, err, Result, ... } from 'resultwire' - [mapErr](#maperr) - [unwrapOr](#unwrapor) - [andThen](#andthen) - - [asyncAndThen](#asyncandthen) - [orElse](#orelse) - [match](#match) - - [asyncMatch](#asyncmatch) - - [asyncMap](#asyncmap) - [fromThrowable](#fromthrowable) - [fromPromise](#frompromise) - [combine](#combine) @@ -143,16 +140,6 @@ const result = ok(42); const chainedResult = andThen(result, (value) => ok(value * 2)); ``` -### asyncAndThen - -Asynchronously chains a function that returns a ```Promise``` to the value of an ```Ok``` result. - -**Example:** -```typescript -const result = ok(42); -const chainedResult = await asyncAndThen(result, async (value) => ok(value * 2)); -``` - ### orElse Chains a function that returns a ```Result``` to the error of an ```Err``` result. @@ -172,27 +159,6 @@ Matches a ```Result``` against two functions, one for ```Ok``` and one for ```Er const result = ok(42); const matchedResult = match(result, (value) => value * 2, (error) => 0); // 84 ``` - -### asyncMatch - -Asynchronously matches a ```Result``` against two functions, one for ```Ok``` and one for ```Err```. - -**Example:** -```typescript -const result = ok(42); -const matchedResult = await asyncMatch(result, async (value) => value * 2, async (error) => 0); // 84 -``` - -### asyncMap - -Asynchronously maps a function over the value of an ```Ok``` result. - -**Example:** -```typescript -const result = ok(42); -const mappedResult = await asyncMap(result, async (value) => value * 2); -``` - ### fromThrowable Executes a function that may throw an error and returns the result as a ```Result```. diff --git a/src/index.spec.ts b/src/index.spec.ts index 047b0a5..0f7597e 100644 --- a/src/index.spec.ts +++ b/src/index.spec.ts @@ -9,9 +9,6 @@ import { andThen, orElse, match, - asyncAndThen, - asyncMatch, - asyncMap, fromThrowable, combine, combineWithAllErrors, @@ -138,7 +135,7 @@ describe('Result', () => { it('should async chain a function that returns a Promise to the value of an Ok result', async () => { const result = ok(42); - const chainedResult = await asyncAndThen(result, async (value) => + const chainedResult = await andThen(result, async (value) => Promise.resolve(ok(value * 2)), ); expect(chainedResult).toEqual({ kind: 'ok', value: 84 }); @@ -146,7 +143,7 @@ describe('Result', () => { it('should not async chain a function to the value of an Err result', async () => { const result = err('Something went wrong'); - const chainedResult = await asyncAndThen(result, async () => { + const chainedResult = await andThen(result, async () => { return Promise.reject('Should not be called'); } ); @@ -155,7 +152,7 @@ describe('Result', () => { it('should async match the Ok variant of a Result', async () => { const result = ok(42); - const matchedValue = await asyncMatch( + const matchedValue = await match( result, async (value) => Promise.resolve(value * 2), async () => Promise.resolve(0), @@ -165,7 +162,7 @@ describe('Result', () => { it('should async match the Err variant of a Result', async () => { const result = err('Something went wrong'); - const matchedValue = await asyncMatch( + const matchedValue = await match( result, async () => { return Promise.reject('Should not be called'); @@ -177,7 +174,7 @@ describe('Result', () => { it('should async map a function over the value of an Ok result', async () => { const result = ok(42); - const mappedResult = await asyncMap(result, async (value) => + const mappedResult = await map(result, async (value) => Promise.resolve(value * 2), ); expect(mappedResult).toEqual({ kind: 'ok', value: 84 }); @@ -185,7 +182,7 @@ describe('Result', () => { it('should not async map a function over the value of an Err result', async () => { const result = err('Something went wrong'); - const mappedResult = await asyncMap(result, async () => { + const mappedResult = await map(result, async () => { throw new Error('Should not be called'); }, ); diff --git a/src/index.ts b/src/index.ts index e67455a..4d800fa 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,322 +1,330 @@ +/** + * Represents a successful result containing a value. + * @template T The type of the successful value. + */ export type Ok = { kind: 'ok'; value: T; }; +/** + * Represents an error result containing an error. + * @template E The type of the error. + */ export type Err = { kind: 'err'; error: E; }; +/** + * Represents a result that can be either successful (Ok) or an error (Err). + * @template T The type of the successful value. + * @template E The type of the error. + */ export type Result = Ok | Err; /** - * Creates a new `Ok` result. + * Creates a successful result. + * @template T The type of the successful value. + * @param value The value to wrap in a successful result. + * @returns An Ok result containing the value. * - * @param value - The value to wrap in an `Ok` result. - * @returns An `Ok` result containing the provided value. - * - * The `ok` function is used to create a new `Result` instance representing a successful operation. - * It takes a value of type `T` and returns an `Ok` result wrapping that value. - * - * Example usage: - * ```typescript + * @example * const result = ok(42); - * ``` + * // result is now a successful Result containing 42 */ export function ok(value: T): Ok { return {kind: 'ok', value}; } /** - * Creates a new `Err` result. - * - * @param error - The error to wrap in an `Err` result. - * @returns An `Err` result containing the provided error. - * - * The `err` function is used to create a new `Result` instance representing an error or failure. - * It takes an error value of type `E` and returns an `Err` result wrapping that error. - * - * Example usage: - * ```typescript - * const result = err('Something went wrong'); - * ``` + * Creates an error result. + * @template E The type of the error. + * @param error The error to wrap in an error result. + * @returns An Err result containing the error. + * + * @example + * const result = err(new Error("Something went wrong")); + * // result is now an error Result containing the error */ export function err(error: E): Err { return {kind: 'err', error}; } /** - * Checks if a `Result` is `Ok`. - * - * @param result - The `Result` to check. - * @returns `true` if the `Result` is `Ok`, `false` otherwise. + * Checks if a result is successful. + * @template T The type of the successful value. + * @template E The type of the error. + * @param result The result to check. + * @returns True if the result is Ok, false otherwise. * - * The `isOk` function is a type guard that checks if a given `Result` is an `Ok` instance. - * It takes a `Result` and returns `true` if the `Result` is an `Ok`, and `false` otherwise. - * - * Example usage: - * ```typescript + * @example * const result = ok(42); * if (isOk(result)) { - * console.log(result.value); + * console.log("The result is successful"); * } - * ``` */ export function isOk(result: Result): result is Ok { return result.kind === 'ok'; } /** - * Checks if a `Result` is `Err`. - * - * @param result - The `Result` to check. - * @returns `true` if the `Result` is `Err`, `false` otherwise. - * - * The `isErr` function is a type guard that checks if a given `Result` is an `Err` instance. - * It takes a `Result` and returns `true` if the `Result` is an `Err`, and `false` otherwise. - * - * Example usage: - * ```typescript - * const result = err('Something went wrong'); + * Checks if a result is an error. + * @template T The type of the successful value. + * @template E The type of the error. + * @param result The result to check. + * @returns True if the result is Err, false otherwise. + * + * @example + * const result = err(new Error("Something went wrong")); * if (isErr(result)) { - * console.error(result.error); + * console.log("The result is an error"); * } - * ``` */ export function isErr(result: Result): result is Err { return result.kind === 'err'; } /** - * Maps a function over the value of an `Ok` result. - * - * @param result - The `Result` to map over. - * @param f - The function to apply to the value of the `Ok` result. - * @returns A new `Result` with the mapped value if the input is `Ok`, or the original `Err` result. - * - * The `map` function allows you to transform the value inside an `Ok` result by applying a given function to it. - * If the input `Result` is an `Ok`, it applies the provided function to the wrapped value and returns a new `Ok` result with the mapped value. - * If the input `Result` is an `Err`, it returns the `Err` result unchanged. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const mappedResult = map(result, value => value * 2); - * ``` + * Maps a Result to Result by applying a function to a contained Ok value, + * leaving an Err value untouched. + * @template T The type of the original successful value. + * @template U The type of the new successful value. + * @template E The type of the error. + * @param result The result to map. + * @param f The function to apply to the successful value. + * @returns A new Result with the mapped value if Ok, or the original error if Err. + * + * @example + * const result = ok(5); + * const mappedResult = map(result, x => x * 2); + * // mappedResult is now ok(10) + * + * @example + * const result = err("error"); + * const mappedResult = map(result, x => x * 2); + * // mappedResult is still err("error") */ -export function map(result: Result, f: (value: T) => U): Result { - return isOk(result) ? ok(f(result.value)) : result; +export function map( + result: Result, + f: (value: T) => U +): Result; + +export function map( + result: Result, + f: (value: T) => Promise +): Promise>; + +export function map( + result: Result, + f: (value: T) => U | Promise +): Result | Promise> { + if (isOk(result)) { + const res = f(result.value); + if (res instanceof Promise) { + return res.then(ok); + } else { + return ok(res); + } + } else { + return result; + } } /** - * Maps a function over the error of an `Err` result. - * - * @param result - The `Result` to map over. - * @param f - The function to apply to the error of the `Err` result. - * @returns A new `Result` with the mapped error if the input is `Err`, or the original `Ok` result. - * - * The `mapErr` function allows you to transform the error inside an `Err` result by applying a given function to it. - * If the input `Result` is an `Err`, it applies the provided function to the wrapped error and returns a new `Err` result with the mapped error. - * If the input `Result` is an `Ok`, it returns the `Ok` result unchanged. - * - * Example usage: - * ```typescript - * const result = err('Something went wrong'); - * const mappedResult = mapErr(result, error => new Error(error)); - * ``` + * Maps a Result to Result by applying a function to a contained Err value, + * leaving an Ok value untouched. + * @template T The type of the successful value. + * @template E The type of the original error. + * @template F The type of the new error. + * @param result The result to map. + * @param f The function to apply to the error value. + * @returns A new Result with the mapped error if Err, or the original value if Ok. + * + * @example + * const result = err("error"); + * const mappedResult = mapErr(result, e => new Error(e)); + * // mappedResult is now err(new Error("error")) + * + * @example + * const result = ok(5); + * const mappedResult = mapErr(result, e => new Error(e)); + * // mappedResult is still ok(5) */ export function mapErr(result: Result, f: (error: E) => F): Result { return isErr(result) ? err(f(result.error)) : result; } /** - * Unwraps a `Result`, returning the value if it's `Ok`, or a default value if it's `Err`. - * - * @param result - The `Result` to unwrap. - * @param defaultValue - The default value to return if the `Result` is `Err`. - * @returns The value of the `Ok` result, or the provided default value if the `Result` is `Err`. - * - * The `unwrapOr` function allows you to extract the value from an `Ok` result, or return a default value if the `Result` is an `Err`. - * If the input `Result` is an `Ok`, it returns the wrapped value. - * If the input `Result` is an `Err`, it returns the provided default value. + * Unwraps a result, yielding the content of an Ok. Else, it returns the provided default value. + * @template T The type of the successful value. + * @template E The type of the error. + * @param result The result to unwrap. + * @param defaultValue The default value to return if the result is an error. + * @returns The value if Ok, or the default value if Err. + * + * @example + * const result = ok(5); + * const value = unwrapOr(result, 0); + * // value is 5 * - * Example usage: - * ```typescript - * const result = ok(42); + * @example + * const result = err("error"); * const value = unwrapOr(result, 0); - * ``` + * // value is 0 */ export function unwrapOr(result: Result, defaultValue: T): T { return isOk(result) ? result.value : defaultValue; } /** - * Chains a function that returns a `Result` to the value of an `Ok` result. - * - * @param result - The `Result` to chain from. - * @param f - The function to chain, which takes the value of the `Ok` result and returns a new `Result`. - * @returns The `Result` returned by the chained function if the input is `Ok`, or the original `Err` result. - * - * The `andThen` function allows you to chain multiple operations that return `Result`s. - * If the input `Result` is an `Ok`, it applies the provided function to the wrapped value, which should return another `Result`. - * If the input `Result` is an `Err`, it returns the `Err` result unchanged. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const chainedResult = andThen(result, value => ok(value * 2)); - * ``` + * Calls the provided function with the contained value (if Ok), + * or returns the error (if Err). + * @template T The type of the original successful value. + * @template U The type of the new successful value. + * @template E The type of the error. + * @param result The result to chain. + * @param f The function to apply to the successful value. + * @returns A new Result from the applied function if Ok, or the original error if Err. + * + * @example + * const divide = (x: number): Result => + * x === 0 ? err("Division by zero") : ok(10 / x); + * + * const result = ok(2); + * const chainedResult = andThen(result, divide); + * // chainedResult is ok(5) + * + * const result2 = ok(0); + * const chainedResult2 = andThen(result2, divide); + * // chainedResult2 is err("Division by zero") */ -export function andThen(result: Result, f: (value: T) => Result): Result { - return isOk(result) ? f(result.value) : result; -} +export function andThen( + result: Result, + f: (value: T) => Result +): Result; -/** - * Asynchronously chains a function that returns a `Promise` to the value of an `Ok` result. - * - * @param result - The `Result` to chain from. - * @param f - The asynchronous function to chain, which takes the value of the `Ok` result and returns a new `Promise`. - * @returns A `Promise` that resolves to the `Result` returned by the chained function if the input is `Ok`, or the original `Err` result. - * - * The `asyncAndThen` function is similar to `andThen`, but it allows you to chain asynchronous operations that return `Promise`s. - * If the input `Result` is an `Ok`, it applies the provided asynchronous function to the wrapped value, which should return a `Promise`. - * If the input `Result` is an `Err`, it returns a `Promise` that resolves to the `Err` result. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const chainedResult = await asyncAndThen(result, async value => ok(value * 2)); - * ``` - */ -export async function asyncAndThen( +export function andThen( result: Result, f: (value: T) => Promise> -): Promise> { - return isOk(result) ? await f(result.value) : result; +): Promise>; + +export function andThen( + result: Result, + f: (value: T) => Result | Promise> +): Result | Promise> { + if (isOk(result)) { + const res = f(result.value); + if (res instanceof Promise) { + return res; + } else { + return res; + } + } else { + return result; + } } /** - * Chains a function that returns a `Result` to the error of an `Err` result. - * - * @param result - The `Result` to chain from. - * @param f - The function to chain, which takes the error of the `Err` result and returns a new `Result`. - * @returns The `Result` returned by the chained function if the input is `Err`, or the original `Ok` result. - * - * The `orElse` function allows you to chain a fallback operation to an `Err` result. - * If the input `Result` is an `Err`, it applies the provided function to the wrapped error, which should return another `Result`. - * If the input `Result` is an `Ok`, it returns the `Ok` result unchanged. - * - * Example usage: - * ```typescript - * const result = err('Something went wrong'); - * const chainedResult = orElse(result, error => ok('Fallback value')); - * ``` + * Calls the provided function with the contained error (if Err), + * or returns the success value (if Ok). + * @template T The type of the successful value. + * @template E The type of the original error. + * @template F The type of the new error. + * @param result The result to transform. + * @param f The function to apply to the error value. + * @returns A new Result from the applied function if Err, or the original value if Ok. + * + * @example + * const result = err("error"); + * const transformedResult = orElse(result, e => ok(e.length)); + * // transformedResult is ok(5) + * + * const result2 = ok(10); + * const transformedResult2 = orElse(result2, e => ok(e.length)); + * // transformedResult2 is still ok(10) */ export function orElse(result: Result, f: (error: E) => Result): Result { return isErr(result) ? f(result.error) : result; } /** - * Matches a `Result` against two functions, one for `Ok` and one for `Err`. - * - * @param result - The `Result` to match. - * @param okFn - The function to apply if the `Result` is `Ok`. - * @param errFn - The function to apply if the `Result` is `Err`. - * @returns The value returned by the matched function. - * - * The `match` function allows you to handle both the `Ok` and `Err` cases of a `Result` separately. - * It takes two functions as arguments: one for handling the `Ok` case and one for handling the `Err` case. - * If the input `Result` is an `Ok`, it applies the `okFn` to the wrapped value and returns the result. - * If the input `Result` is an `Err`, it applies the `errFn` to the wrapped error and returns the result. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const value = match( + * Applies the provided function to the contained value (if Ok) or the contained error (if Err). + * @template T The type of the successful value. + * @template E The type of the error. + * @template U The type of the result of both functions. + * @param result The result to match against. + * @param okFn The function to apply if the result is Ok. + * @param errFn The function to apply if the result is Err. + * @returns The result of applying the appropriate function. + * + * @example + * const result = ok(5); + * const matched = match( * result, - * value => value * 2, - * error => 0 + * value => `Success: ${value}`, + * error => `Error: ${error}` * ); - * ``` - */ -export function match(result: Result, okFn: (value: T) => U, errFn: (error: E) => U): U { - return isOk(result) ? okFn(result.value) : errFn(result.error); -} - -/** - * Asynchronously matches a `Result` against two functions, one for `Ok` and one for `Err`. - * - * @param result - The `Result` to match. - * @param okFn - The asynchronous function to apply if the `Result` is `Ok`. - * @param errFn - The asynchronous function to apply if the `Result` is `Err`. - * @returns A `Promise` that resolves to the value returned by the matched function. + * // matched is "Success: 5" * - * The `asyncMatch` function is similar to `match`, but it allows you to handle both the `Ok` and `Err` cases asynchronously. - * It takes two asynchronous functions as arguments: one for handling the `Ok` case and one for handling the `Err` case. - * If the input `Result` is an `Ok`, it applies the `okFn` to the wrapped value and returns a `Promise` that resolves to the result. - * If the input `Result` is an `Err`, it applies the `errFn` to the wrapped error and returns a `Promise` that resolves to the result. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const value = await asyncMatch( + * @example + * const result = err("Something went wrong"); + * const matched = match( * result, - * async value => value * 2, - * async error => 0 + * value => `Success: ${value}`, + * error => `Error: ${error}` * ); - * ``` + * // matched is "Error: Something went wrong" */ -export async function asyncMatch( +export function match( + result: Result, + okFn: (value: T) => U, + errFn: (error: E) => U +): U; + +export function match( result: Result, okFn: (value: T) => Promise, errFn: (error: E) => Promise -): Promise { - return isOk(result) ? await okFn(result.value) : await errFn(result.error); -} +): Promise; -/** - * Asynchronously maps a function over the value of an `Ok` result. - * - * @param result - The `Result` to map over. - * @param f - The asynchronous function to apply to the value of the `Ok` result. - * @returns A `Promise` that resolves to a new `Result` with the mapped value if the input is `Ok`, or the original `Err` result. - * - * The `asyncMap` function is similar to `map`, but it allows you to apply an asynchronous function to the value of an `Ok` result. - * If the input `Result` is an `Ok`, it applies the provided asynchronous function to the wrapped value and returns a `Promise` that resolves to a new `Ok` result with the mapped value. - * If the input `Result` is an `Err`, it returns a `Promise` that resolves to the `Err` result unchanged. - * - * Example usage: - * ```typescript - * const result = ok(42); - * const mappedResult = await asyncMap(result, async value => value * 2); - * ``` - */ -export async function asyncMap( +export function match( result: Result, - f: (value: T) => Promise -): Promise> { - return isOk(result) ? ok(await f(result.value)) : result; + okFn: (value: T) => U | Promise, + errFn: (error: E) => U | Promise +): U | Promise { + if (isOk(result)) { + const res = okFn(result.value); + if (res instanceof Promise) { + return res; + } else { + return res; + } + } else { + const res = errFn(result.error); + if (res instanceof Promise) { + return res; + } else { + return res; + } + } } /** - * Executes a function that may throw an error and returns the result as a `Result`. - * - * @param f - The function to execute. - * @returns An `Ok` result containing the return value of the function if it succeeds, or an `Err` result containing the thrown error. - * - * The `fromThrowable` function allows you to execute a function that may throw an error and convert the result into a `Result`. - * It takes a function `f` as an argument, which can be either synchronous or asynchronous. - * If the function `f` executes successfully without throwing an error, it returns an `Ok` result containing the return value of the function. - * If the function `f` throws an error, it returns an `Err` result containing the thrown error. - * - * Example usage: - * ```typescript - * const result = fromThrowable(() => { - * // Code that may throw an error - * return 42; - * }); - * ``` + * Wraps a function that might throw an error in a Result. + * @template T The return type of the function. + * @template R The type of the error. + * @param f The function to wrap. + * @returns A Result containing either the function's return value or the caught error. + * + * @example + * const dangerousFunction = () => { + * if (Math.random() < 0.5) throw new Error("Bad luck"); + * return "Success!"; + * }; + * + * const result = fromThrowable(dangerousFunction); + * // result is either ok("Success!") or err(Error("Bad luck")) */ export function fromThrowable(f: () => T): Result; export function fromThrowable(f: () => Promise): Promise>; @@ -333,38 +341,45 @@ export function fromThrowable(f: () => T | Promise): Result | Pro } } -/* -* Converts a Promise into a Promise. -* -* @param promise - The Promise to convert. -* @returns A Promise that resolves to an Ok result containing the resolved value of the input Promise, or an Err result containing the rejection reason. -* -* The fromPromise function allows you to convert a Promise into a Promise. -* It takes a Promise as an argument and returns a new Promise that resolves to a Result. -* If the input Promise resolves successfully, the returned Promise resolves to an Ok result containing the resolved value. -* If the input Promise rejects, the returned Promise resolves to an Err result containing the rejection reason. -* -* Example usage: -* typescript * const promise = Promise.resolve(42); * const resultPromise = fromPromise(promise); * -*/ +/** + * Converts a Promise into a Result. + * @template T The type of the successful value. + * @template E The type of the error. + * @param promise The promise to convert. + * @returns A Promise that resolves to a Result. + * + * @example + * const asyncOperation = () => Promise.resolve(42); + * const result = await fromPromise(asyncOperation()); + * // result is ok(42) + * + * @example + * const failingAsyncOperation = () => Promise.reject(new Error("Failed")); + * const result = await fromPromise(failingAsyncOperation()); + * // result is err(Error("Failed")) + */ export function fromPromise(promise: Promise): Promise> { return promise.then(ok).catch((error) => err(error)); } -/* -* Combines an array of Results into a single Result. -* -* @param results - The array of Results to combine. -* @returns An Ok result containing an array of the values from the input Results if they are all Ok, or the first Err result encountered. -* -* The combine function allows you to combine multiple Results into a single Result. -* It takes an array of Results as an argument and returns a new Result. -* If all the input Results are Ok, it returns an Ok result containing an array of the values from the input Results. -* If any of the input Results is an Err, it returns the first Err result encountered. -* -* Example usage: -* typescript * const results = [ok(1), ok(2), ok(3)]; * const combinedResult = combine(results); * -*/ +/** + * Combines an array of Results into a single Result containing an array of values. + * If any Result is an Err, the first Err encountered is returned. + * @template T The type of the successful values. + * @template E The type of the errors. + * @param results An array of Results to combine. + * @returns A Result containing either an array of all successful values or the first error encountered. + * + * @example + * const results = [ok(1), ok(2), ok(3)]; + * const combined = combine(results); + * // combined is ok([1, 2, 3]) + * + * @example + * const results = [ok(1), err("error"), ok(3)]; + * const combined = combine(results); + * // combined is err("error") + */ export function combine(results: Result[]): Result { const values: T[] = []; for (const result of results) { @@ -376,20 +391,24 @@ export function combine(results: Result[]): Result { return ok(values); } -/* -* Combines an array of Results into a single Result, collecting all errors. -* -* @param results - The array of Results to combine. -* @returns An Ok result containing an array of the values from the input Results if they are all Ok, or an Err result containing an array of all the errors. -* -* The combineWithAllErrors function is similar to combine, but it collects all the errors from the input Results instead of returning the first Err encountered. -* It takes an array of Results as an argument and returns a new Result. -* If all the input Results are Ok, it returns an Ok result containing an array of the values from the input Results. -* If any of the input Results is an Err, it returns an Err result containing an array of all the errors from the input Results. -* -* Example usage: -* typescript * const results = [ok(1), err('Error 1'), ok(3), err('Error 2')]; * const combinedResult = combineWithAllErrors(results); * -*/ +/** + * Combines an array of Results into a single Result containing an array of values. + * If any Results are Err, all errors are collected into an array. + * @template T The type of the successful values. + * @template E The type of the errors. + * @param results An array of Results to combine. + * @returns A Result containing either an array of all successful values or an array of all errors. + * + * @example + * const results = [ok(1), ok(2), ok(3)]; + * const combined = combineWithAllErrors(results); + * // combined is ok([1, 2, 3]) + * + * @example + * const results = [ok(1), err("error1"), ok(3), err("error2")]; + * const combined = combineWithAllErrors(results); + * // combined is err(["error1", "error2"]) + */ export function combineWithAllErrors(results: Result[]): Result { const values: T[] = []; const errors: E[] = []; @@ -403,22 +422,24 @@ export function combineWithAllErrors(results: Result[]): Result(result: Result): T { if (isErr(result)) { throw new Error('Attempted to unwrap an Err value');