feat: add partition function to separate Either and Result values into successes and failures

Author: richecr

docs/changelog.md

@@ -24,7 +24,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   - Example:
   ```ts
   sequence([ok(1), err('e1'), err('e2')]); // Err('e1') - stops at first!
-  // vs all: Err(['e1', 'e2']) - collects all
+  ```
+
+- **`partition` function for `Result` and `Either`**: Separates an array of monads into successes and failures.
+  - Returns a plain object with two arrays (not a monad).
+  - Always processes all items.
+  - Example:
+  ```ts
+  partition([ok(1), err('e1'), ok(2), err('e2')]);
+  // { oks: [1, 2], errs: ['e1', 'e2'] }
   ```
 
 ---

docs/either/index.md

@@ -570,3 +570,32 @@ console.log(result2.match({
 
 ---
 
+### `partition`
+
+Separates an array of `Either` values into two groups: `lefts` and `rights`. Always processes all items and returns both arrays.
+
+Unlike `all` and `sequence` which return an `Either`, `partition` returns a plain object with two arrays.
+
+```ts
+import { partition, left, right } from 'holo-fn/either';
+
+const eithers = [
+  right<string, number>(1),
+  left('error1'),
+  right<string, number>(2),
+  left('error2'),
+  right<string, number>(3),
+];
+
+const { lefts, rights } = partition(eithers);
+console.log(rights); // [1, 2, 3]
+console.log(lefts); // ['error1', 'error2']
+
+const { lefts: errors, rights: values } = partition(eithers);
+console.log(`✓ ${values.length} succeeded`);
+console.log(`✗ ${errors.length} failed`);
+errors.forEach((err) => console.error(err));
+```
+
+---
+

docs/result/index.md

@@ -466,3 +466,32 @@ console.log(result2.match({
 
 ---
 
+### `partition`
+
+Separates an array of `Result` values into two groups: successes (`oks`) and failures (`errs`). Always processes all items and returns both arrays.
+
+Unlike `all` and `sequence` which return a `Result`, `partition` returns a plain object with two arrays.
+
+```ts
+import { partition, ok, err } from 'holo-fn/result';
+
+const results = [
+  ok<number, string>(1),
+  err<number, string>('error1'),
+  ok<number, string>(2),
+  err<number, string>('error2'),
+  ok<number, string>(3),
+];
+
+const { oks, errs } = partition(results);
+console.log(oks); // [1, 2, 3]
+console.log(errs); // ['error1', 'error2']
+
+const { oks: succeeded, errs: failed } = partition(results);
+console.log(`✓ ${succeeded.length} succeeded`);
+console.log(`✗ ${failed.length} failed`);
+failed.forEach((err) => console.error(err));
+```
+
+---
+

src/either/index.ts

@@ -202,5 +202,19 @@ export const sequence = <L, R>(eithers: Either<L, R>[]): Either<L, R[]> => {
   return new Right<L, R[]>(values);
 };
 
+export const partition = <L, R>(eithers: Either<L, R>[]): { lefts: L[]; rights: R[] } => {
+  return eithers.reduce(
+    (acc, either) => {
+      if (either.isLeft()) {
+        acc.lefts.push(either.extract() as L);
+      } else {
+        acc.rights.push(either.extract() as R);
+      }
+      return acc;
+    },
+    { lefts: [] as L[], rights: [] as R[] }
+  );
+};
+
 export const left = <L, R = never>(value: L): Either<L, R> => new Left(value);
 export const right = <L, R>(value: R): Either<L, R> => new Right(value);

src/result/index.ts

@@ -208,5 +208,19 @@ export const sequence = <T, E>(results: Result<T, E>[]): Result<T[], E> => {
   return new Ok<T[], E>(values);
 };
 
+export const partition = <T, E>(results: Result<T, E>[]): { oks: T[]; errs: E[] } => {
+  return results.reduce(
+    (acc, result) => {
+      if (result.isErr()) {
+        acc.errs.push(result.extract() as E);
+      } else {
+        acc.oks.push(result.extract() as T);
+      }
+      return acc;
+    },
+    { oks: [] as T[], errs: [] as E[] }
+  );
+};
+
 export const ok = <T, E>(value: T): Result<T, E> => new Ok(value);
 export const err = <T, E>(error: E): Result<T, E> => new Err(error);

tests/either.test.ts

@@ -11,6 +11,7 @@ import {
   map,
   mapLeft,
   match,
+  partition,
   Right,
   right,
   sequence,
@@ -458,4 +459,37 @@ describe('Either - Curried Helpers', () => {
     const result = sequence(eithers);
     expect(result.match({ left: (e) => e, right: (_) => '' })).toBe('First error');
   });
+
+  it('partition should separate lefts and rights', () => {
+    const eithers = [
+      right<string, number>(1),
+      left<string, number>('error1'),
+      right<string, number>(2),
+      left<string, number>('error2'),
+      right<string, number>(3),
+    ];
+    const { lefts, rights } = partition(eithers);
+    expect(rights).toEqual([1, 2, 3]);
+    expect(lefts).toEqual(['error1', 'error2']);
+  });
+
+  it('partition should return all rights when no lefts', () => {
+    const eithers = [right<string, number>(1), right<string, number>(2), right<string, number>(3)];
+    const { lefts, rights } = partition(eithers);
+    expect(rights).toEqual([1, 2, 3]);
+    expect(lefts).toEqual([]);
+  });
+
+  it('partition should return all lefts when all fail', () => {
+    const eithers = [left<string, number>('e1'), left<string, number>('e2'), left<string, number>('e3')];
+    const { lefts, rights } = partition(eithers);
+    expect(lefts).toEqual(['e1', 'e2', 'e3']);
+    expect(rights).toEqual([]);
+  });
+
+  it('partition should return empty arrays for empty input', () => {
+    const { lefts, rights } = partition<string, number>([]);
+    expect(lefts).toEqual([]);
+    expect(rights).toEqual([]);
+  });
 });

tests/result.test.ts

@@ -14,6 +14,7 @@ import {
   match,
   Ok,
   ok,
+  partition,
   sequence,
   unwrapOr,
   validate,
@@ -419,4 +420,37 @@ describe('Result - Curried Helpers', () => {
     const result = sequence(results);
     expect(result.match({ ok: (_) => '', err: (e) => e })).toBe('First error');
   });
+
+  it('partition should separate oks and errs', () => {
+    const results = [
+      ok<number, string>(1),
+      err<number, string>('error1'),
+      ok<number, string>(2),
+      err<number, string>('error2'),
+      ok<number, string>(3),
+    ];
+    const { oks, errs } = partition(results);
+    expect(oks).toEqual([1, 2, 3]);
+    expect(errs).toEqual(['error1', 'error2']);
+  });
+
+  it('partition should return all oks when no errors', () => {
+    const results = [ok<number, string>(1), ok<number, string>(2), ok<number, string>(3)];
+    const { oks, errs } = partition(results);
+    expect(oks).toEqual([1, 2, 3]);
+    expect(errs).toEqual([]);
+  });
+
+  it('partition should return all errs when all fail', () => {
+    const results = [err<number, string>('e1'), err<number, string>('e2'), err<number, string>('e3')];
+    const { oks, errs } = partition(results);
+    expect(oks).toEqual([]);
+    expect(errs).toEqual(['e1', 'e2', 'e3']);
+  });
+
+  it('partition should return empty arrays for empty input', () => {
+    const { oks, errs } = partition<number, string>([]);
+    expect(oks).toEqual([]);
+    expect(errs).toEqual([]);
+  });
 });