feat: add partition static function

README.md

@@ -39,6 +39,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`Result.combine` (static class method)](#resultcombine-static-class-method)
     - [`Result.combineWithAllErrors` (static class method)](#resultcombinewithallerrors-static-class-method)
     - [`Result.safeUnwrap()`](#resultsafeunwrap)
+    - [`Result.partition (static class method)`](#resultpartition-static-class-method)
   + [Asynchronous API (`ResultAsync`)](#asynchronous-api-resultasync)
     - [`okAsync`](#okasync)
     - [`errAsync`](#errasync)
@@ -53,6 +54,7 @@ For asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a
     - [`ResultAsync.combine` (static class method)](#resultasynccombine-static-class-method)
     - [`ResultAsync.combineWithAllErrors` (static class method)](#resultasynccombinewithallerrors-static-class-method)
     - [`ResultAsync.safeUnwrap()`](#resultasyncsafeunwrap)
+    - [`ResultAsync.partition (static class method)`](#resultasyncpartition-static-class-method)
   + [Utilities](#utilities)
     - [`fromThrowable`](#fromthrowable)
     - [`fromPromise`](#frompromise)
@@ -669,6 +671,49 @@ const result = Result.combineWithAllErrors(resultList)
 Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate.
 
 
+[⬆️  Back to top](#toc)
+
+---
+
+#### `Result.partition` (static class method)
+
+> Although Result is not an actual JS class, the way that `partition` has been implemented requires that you call `partition` as though it were a static method on `Result`. See examples below.
+
+Partition lists of `Result`s.
+
+**`partition` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `Result`s and still be able to partition them. Note that you cannot partition lists that contain both `Result`s **and** `ResultAsync`s.
+
+The `partition` function takes a list of results and returns a tuple of all `Ok` results and `Err` errors.
+
+Function signature:
+
+```typescript
+// homogeneous lists
+function partition<T, E>(resultList: Result<T, E>[]): [T[], E[]]
+
+// heterogeneous lists
+function partition<T1, T2, E1, E2>(resultList: [ Result<T1, E1>, Result<T2, E2> ]): [(T1 | T2)[], (E1 | E2)[]]
+function partition<T1, T2, T3, E1, E2, E3> => [(T1 | T2 | T3) [], (E1 | E2 | E3)[]]
+function partition<T1, T2, T3, T4, E1, E2, E3, E4> => [(T1 | T2 | T3 | T4)[], (E1 | E2 | E3 | E4)[]]
+// ... etc etc ad infinitum
+```
+
+Example usage:
+
+```typescript
+const resultList: Result<number, string>[] = [
+  ok(123),
+  err('boooom!'),
+  ok(456),
+  err('ahhhhh!'),
+]
+
+const [results, errors] = Result.partition(resultList)
+
+// results is [123, 456]
+// errors is ['boooom!', 'ahhhhh!']
+```
+
 [⬆️  Back to top](#toc)
 
 ---
@@ -1148,6 +1193,47 @@ Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reduc
 
 ---
 
+#### `ResultAsync.partition` (static class method)
+
+Partition lists of `ResultAsync`s.
+
+**`partition` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `ResultAsync`s and still be able to partition them. Note that you cannot partition lists that contain both `Result`s **and** `ResultAsync`s.
+
+The `partition` function takes a list of async results and returns a `Promise` of a tuple of all Ok results and Err errors.
+
+Function signature:
+
+```typescript
+// homogeneous lists
+function partition<T, E>(resultList: ResultAsync<T, E>[]): Promise<[T[], E[]]>
+
+// heterogeneous lists
+function partition<T1, T2, E1, E2>(resultList: [ ResultAsync<T1, E1>, ResultAsync<T2, E2> ]): Promise<[(T1 | T2)[], (E1 | E2)[]]>
+function partition<T1, T2, T3, E1, E2, E3> => Promise<[(T1 | T2 | T3)[], (E1 | E2 | E3)[]]>
+function partition<T1, T2, T3, T4, E1, E2, E3, E4> => Promise<[(T1 | T2 | T3 | T4)[], (E1 | E2 | E3 | E4)[]]>
+// ... etc etc ad infinitum
+```
+
+Example usage:
+
+```typescript
+const resultList: ResultAsync<number, string>[] = [
+  okAsync(123),
+  errAsync('boooom!'),
+  okAsync(456),
+  errAsync('ahhhhh!'),
+]
+
+const [results, errors] = await ResultAsync.partition(resultList)
+
+// results is [123, 456]
+// errors is ['boooom!', 'ahhhhh!']
+```
+
+[⬆️  Back to top](#toc)
+
+---
+
 ### Utilities
 
 #### `fromThrowable`

src/_internals/utils.ts

@@ -81,3 +81,14 @@ export const combineResultAsyncListWithAllErrors = <T, E>(
   ResultAsync.fromSafePromise(Promise.all(asyncResultList)).andThen(
     combineResultListWithAllErrors,
   ) as ResultAsync<T[], E[]>
+
+export const partitionResultList = <T, E>(resultList: readonly Result<T, E>[]): [T[], E[]] =>
+  resultList.reduce(
+    ([oks, errors], result) =>
+      result.isErr() ? [oks, [...errors, result.error]] : [[...oks, result.value], errors],
+    [[], []] as [T[], E[]],
+  )
+
+export const partitionResultAsyncList = <T, E>(
+  asyncResultList: readonly ResultAsync<T, E>[],
+): Promise<[T[], E[]]> => Promise.all(asyncResultList).then(partitionResultList)

src/result-async.ts

@@ -17,6 +17,7 @@ import {
   InferAsyncOkTypes,
   InferErrTypes,
   InferOkTypes,
+  partitionResultAsyncList,
 } from './_internals/utils'
 
 export class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
@@ -68,6 +69,18 @@ export class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
     ) as CombineResultsWithAllErrorsArrayAsync<T>
   }
 
+  static partition<
+    T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]
+  >(asyncResultList: T): PartitionResultAsync<T>
+  static partition<T extends readonly ResultAsync<unknown, unknown>[]>(
+    asyncResultList: T,
+  ): PartitionResultAsync<T>
+  static partition<T extends readonly ResultAsync<unknown, unknown>[]>(
+    asyncResultList: T,
+  ): PartitionResultAsync<T> {
+    return partitionResultAsyncList(asyncResultList) as PartitionResultAsync<T>
+  }
+
   map<A>(f: (t: T) => A | Promise<A>): ResultAsync<A, E> {
     return new ResultAsync(
       this._promise.then(async (res: Result<T, E>) => {
@@ -176,6 +189,10 @@ export type CombineResultsWithAllErrorsArrayAsync<
   ? TraverseWithAllErrorsAsync<UnwrapAsync<T>>
   : ResultAsync<ExtractOkAsyncTypes<T>, ExtractErrAsyncTypes<T>[number][]>
 
+export type PartitionResultAsync<T extends readonly ResultAsync<unknown, unknown>[]> = Promise<
+  [ExtractOkAsyncTypes<T>[number][], ExtractErrAsyncTypes<T>[number][]]
+>
+
 // Unwraps the inner `Result` from a `ResultAsync` for all elements.
 type UnwrapAsync<T> = IsLiteralArray<T> extends 1
   ? Writable<T> extends [infer H, ...infer Rest]

src/result.ts

@@ -7,6 +7,7 @@ import {
   ExtractOkTypes,
   InferErrTypes,
   InferOkTypes,
+  partitionResultList,
 } from './_internals/utils'
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
@@ -56,6 +57,18 @@ export namespace Result {
   ): CombineResultsWithAllErrorsArray<T> {
     return combineResultListWithAllErrors(resultList) as CombineResultsWithAllErrorsArray<T>
   }
+
+  export function partition<
+    T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]
+  >(resultList: T): PartitionResult<T>
+  export function partition<T extends readonly Result<unknown, unknown>[]>(
+    resultList: T,
+  ): PartitionResult<T>
+  export function partition<T extends readonly Result<unknown, unknown>[]>(
+    resultList: T,
+  ): PartitionResult<T> {
+    return partitionResultList(resultList) as PartitionResult<T>
+  }
 }
 
 export type Result<T, E> = Ok<T, E> | Err<T, E>
@@ -583,4 +596,9 @@ export type CombineResultsWithAllErrorsArray<
   ? TraverseWithAllErrors<T>
   : Result<ExtractOkTypes<T>, ExtractErrTypes<T>[number][]>
 
+export type PartitionResult<T extends readonly Result<unknown, unknown>[]> = [
+  ExtractOkTypes<T>[number][],
+  ExtractErrTypes<T>[number][],
+]
+
 //#endregion