feat: add sequence function to combine Either and Result values with fail-fast behavior

Author: richecr

docs/either/index.md

@@ -527,11 +527,9 @@ Combines an array of `Either` values into a single `Either`. Returns `Right` wit
 ```ts
 import { all, right, left } from 'holo-fn/either';
 
-// All success case
 const result1 = all([right(1), right(2), right(3)]);
 console.log(result1.unwrapOr([])); // [1, 2, 3]
 
-// Collecting errors
 const result2 = all([left('Name required'), left('Email invalid'), right(25)]);
 console.log(
   result2.match({
@@ -547,3 +545,28 @@ console.log(result3.unwrapOr([])); // []
 
 ---
 
+### `sequence`
+
+Combines an array of `Either` values into a single `Either`, stopping at the first error (fail-fast). Returns `Right` with all values if all are `Right`, or `Left` with the first error encountered.
+
+Unlike `all` which collects all errors, `sequence` returns immediately when it finds the first `Left`.
+
+```ts
+import { sequence, right, left } from 'holo-fn/either';
+
+const result1 = sequence([right(1), right(2), right(3)]);
+console.log(result1.unwrapOr([])); // [1, 2, 3]
+
+const result2 = sequence([
+  right(1),
+  left('First error'),
+  left('Second error')
+]);
+console.log(result2.match({
+  left: (e) => e,
+  right: (v) => v
+})); // 'First error' (not an array!)
+```
+
+---
+

docs/result/index.md

@@ -424,11 +424,9 @@ Combines an array of `Result` values into a single `Result`. Returns `Ok` with a
 ```ts
 import { all, ok, err } from 'holo-fn/result';
 
-// All success case
 const result1 = all([ok(1), ok(2), ok(3)]);
 console.log(result1.unwrapOr([])); // [1, 2, 3]
 
-// Collecting errors
 const result2 = all([err('Name required'), err('Email invalid'), ok(25)]);
 console.log(
   result2.match({
@@ -437,10 +435,34 @@ console.log(
   })
 ); // ['Name required', 'Email invalid']
 
-// Empty array
 const result3 = all([]);
 console.log(result3.unwrapOr([])); // []
 ```
 
 ---
 
+### `sequence`
+
+Combines an array of `Result` values into a single `Result`, stopping at the first error (fail-fast). Returns `Ok` with all values if all are `Ok`, or `Err` with the first error encountered.
+
+Unlike `all` which collects all errors, `sequence` returns immediately when it finds the first `Err`.
+
+```ts
+import { sequence, ok, err } from 'holo-fn/result';
+
+const result1 = sequence([ok(1), ok(2), ok(3)]);
+console.log(result1.unwrapOr([])); // [1, 2, 3]
+
+const result2 = sequence([
+  ok(1),
+  err('First error'),
+  err('Second error')
+]);
+console.log(result2.match({
+  ok: (v) => v,
+  err: (e) => e
+})); // 'First error' (not an array!)
+```
+
+---
+

src/either/index.ts

@@ -188,5 +188,19 @@ export const all = <L, R>(eithers: Either<L, R>[]): Either<L[], R[]> => {
   return new Right<L[], R[]>(values);
 };
 
+export const sequence = <L, R>(eithers: Either<L, R>[]): Either<L, R[]> => {
+  const values: R[] = [];
+
+  for (const either of eithers) {
+    if (either.isLeft()) {
+      return new Left<L, R[]>(either.extract() as L);
+    }
+
+    values.push(either.extract() as R);
+  }
+
+  return new Right<L, R[]>(values);
+};
+
 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

@@ -194,5 +194,19 @@ export const all = <T, E>(results: Result<T, E>[]): Result<T[], E[]> => {
   return new Ok<T[], E[]>(values);
 };
 
+export const sequence = <T, E>(results: Result<T, E>[]): Result<T[], E> => {
+  const values: T[] = [];
+
+  for (const result of results) {
+    if (result.isErr()) {
+      return new Err<T[], E>(result.extract() as E);
+    }
+
+    values.push(result.extract() as T);
+  }
+
+  return new Ok<T[], E>(values);
+};
+
 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

@@ -13,6 +13,7 @@ import {
   match,
   Right,
   right,
+  sequence,
   tryCatch,
   unwrapOr,
   validate,
@@ -427,4 +428,34 @@ describe('Either - Curried Helpers', () => {
       'Age too low',
     ]);
   });
+
+  it('sequence should return Right with all values when all are Right', () => {
+    const eithers = [right<string, number>(1), right<string, number>(2), right<string, number>(3)];
+    const result = sequence(eithers);
+    expect(result.isRight()).toBe(true);
+    expect(result.unwrapOr([])).toEqual([1, 2, 3]);
+  });
+
+  it('sequence should return first Left when any is Left (fail-fast)', () => {
+    const eithers = [right<string, number>(1), left<string, number>('error1'), left<string, number>('error2')];
+    const result = sequence(eithers);
+    expect(result.isLeft()).toBe(true);
+    expect(result.match({ left: (e) => e, right: (_) => '' })).toBe('error1');
+  });
+
+  it('sequence should return Right with empty array for empty input', () => {
+    const result = sequence<string, number>([]);
+    expect(result.isRight()).toBe(true);
+    expect(result.unwrapOr([])).toEqual([]);
+  });
+
+  it('sequence should stop at first error unlike all', () => {
+    const eithers = [
+      left<string, number>('First error'),
+      left<string, number>('Second error'),
+      right<string, number>(1),
+    ];
+    const result = sequence(eithers);
+    expect(result.match({ left: (e) => e, right: (_) => '' })).toBe('First error');
+  });
 });

tests/result.test.ts

@@ -14,6 +14,7 @@ import {
   match,
   Ok,
   ok,
+  sequence,
   unwrapOr,
   validate,
 } from '../src/result';
@@ -392,4 +393,30 @@ describe('Result - Curried Helpers', () => {
     const result = all(results);
     expect(result.match({ ok: (_) => [], err: (e) => e })).toEqual(['Name required', 'Email invalid', 'Age too low']);
   });
+
+  it('sequence should return Ok with all values when all are Ok', () => {
+    const results = [ok<number, string>(1), ok<number, string>(2), ok<number, string>(3)];
+    const result = sequence(results);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrapOr([])).toEqual([1, 2, 3]);
+  });
+
+  it('sequence should return first Err when any is Err (fail-fast)', () => {
+    const results = [ok<number, string>(1), err<number, string>('error1'), err<number, string>('error2')];
+    const result = sequence(results);
+    expect(result.isErr()).toBe(true);
+    expect(result.match({ ok: (_) => '', err: (e) => e })).toBe('error1');
+  });
+
+  it('sequence should return Ok with empty array for empty input', () => {
+    const result = sequence<number, string>([]);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrapOr([])).toEqual([]);
+  });
+
+  it('sequence should stop at first error unlike all', () => {
+    const results = [err<number, string>('First error'), err<number, string>('Second error'), ok<number, string>(1)];
+    const result = sequence(results);
+    expect(result.match({ ok: (_) => '', err: (e) => e })).toBe('First error');
+  });
 });