docs: update changelog and documentation for smart type inference in Either, Maybe, and Result utilities

Author: richecr

docs/changelog.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ---
 
+## [Unreleased]
+
+### Added
+- **Smart type inference for combinators**: `all`, `sequence`, and `partition` now return `T[]` for homogeneous arrays and preserve tuple types for mixed types.
+    - Before: `all([ok(1), ok(2), ok(3)])` returned `Result<[number, number, number], ...>` (tuple)
+    - After: `all([ok(1), ok(2), ok(3)])` returns `Result<number[], ...>` (array)
+    - Heterogeneous arrays still preserve tuple types: `all([ok(42), ok("hi")])` → `Result<[number, string], ...>`
+    - Applies to `all`, `sequence` (Result/Either), and `partition` (Result/Either)
+    - Makes `unwrapOr([])` work naturally without type errors
+
+### Changed
+- **Improved `unwrapOr` flexibility**: Now accepts default values of different (but compatible) types.
+    - Example: `all([ok(1), ok(2)]).unwrapOr([])` now works without type errors.
+    - Before: Required exact tuple type like `[0, 0]`.
+    - After: Accepts any compatible type like `[]` for arrays.
+
+---
+
 ## [1.2.0](https://github.com/richecr/holo-fn/releases/tag/v1.2.0) - 2025-12-08
 
 ### Added

docs/either/index.md

@@ -524,11 +524,13 @@ console.log(result); // true
 
 Combines an array of `Either` values into a single `Either`. Returns `Right` with all values if all are `Right`, or `Left` with all errors if any are `Left`.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `Either<L[], R[]>`. For mixed types, preserves tuple types.
+
 ```ts
 import { all, left, right, type Either } from 'holo-fn/either';
 
-const result1: Either<unknown, number[]> = all([right(1), right(2), right(3)]);
-console.log(result1.unwrapOr([])); // [1, 2, 3]
+const result1 = all([right(1), right(2), right(3)]);
+console.log(result1.unwrapOr([]));
 
 const result2 = all([left('Name required'), left('Email invalid'), right(25)]);
 console.log(
@@ -538,9 +540,10 @@ console.log(
   })
 ); // ['Name required', 'Email invalid']
 
-// Empty array
-const result3 = all([]);
-console.log(result3.unwrapOr([])); // []
+const result3 = all([right(42), right("hello"), right(true)]);
+
+const result4 = all([]);
+console.log(result4.unwrapOr([]));
 ```
 
 ---
@@ -551,11 +554,13 @@ Combines an array of `Either` values into a single `Either`, stopping at the fir
 
 Unlike `all` which collects all errors, `sequence` returns immediately when it finds the first `Left`.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `Either<L, R[]>`. For mixed types, preserves tuple types.
+
 ```ts
 import { left, right, sequence, type Either } from 'holo-fn/either';
 
-const result1: Either<unknown, number[]> = sequence([right(1), right(2), right(3)]);
-console.log(result1.unwrapOr([])); // [1, 2, 3]
+const result1 = sequence([right(1), right(2), right(3)]);
+console.log(result1.unwrapOr([]));
 
 const result2 = sequence([
   right(1),
@@ -565,7 +570,9 @@ const result2 = sequence([
 console.log(result2.match({
   left: (e) => e,
   right: (v) => v
-})); // 'First error' (not an array!)
+}));
+
+const result3 = sequence([right(42), right("hello")]);
 ```
 
 ---
@@ -576,6 +583,8 @@ Separates an array of `Either` values into two groups: `lefts` and `rights`. Alw
 
 Unlike `all` and `sequence` which return an `Either`, `partition` returns a plain object with two arrays.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `{ lefts: L[], rights: R[] }`. For mixed types, preserves tuple types.
+
 ```ts
 import { left, partition, right } from 'holo-fn/either';
 
@@ -588,8 +597,8 @@ const eithers = [
 ];
 
 const { lefts, rights } = partition(eithers);
-console.log(rights); // [1, 2, 3]
-console.log(lefts); // ['error1', 'error2']
+console.log(rights);
+console.log(lefts);
 
 const { lefts: errors, rights: values } = partition(eithers);
 console.log(`✓ ${values.length} succeeded`);

docs/maybe/index.md

@@ -320,20 +320,21 @@ console.log(result); // true
 
 Combines an array of `Maybe` values into a single `Maybe` containing an array. Returns `Just` with all values if all are `Just`, or `Nothing` if any is `Nothing`.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `Maybe<T[]>`. For mixed types, preserves tuple types like `Maybe<[number, string, boolean]>`.
+
 ```ts
 import { all, just, nothing, type Maybe } from 'holo-fn/maybe';
 
-// All success case
-const result1: Maybe<number[]> = all([just(1), just(2), just(3)]);
-console.log(result1.unwrapOr([])); // [1, 2, 3]
+const result1 = all([just(1), just(2), just(3)]);
+console.log(result1.unwrapOr([]));
 
-// Any failure case
 const result2 = all([just(1), nothing(), just(3)]);
-console.log(result2.isNothing()); // true
+console.log(result2.isNothing());
+
+const result3 = all([just(42), just("hello"), just(true)]);
 
-// Empty array
-const result3 = all([]);
-console.log(result3.unwrapOr([])); // []
+const result4 = all([]);
+console.log(result4.unwrapOr([]));
 ```
 
 ---

docs/result/index.md

@@ -425,23 +425,27 @@ console.log(result2); // false
 
 Combines an array of `Result` values into a single `Result`. Returns `Ok` with all values if all are `Ok`, or `Err` with all errors if any are `Err`.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `T[]`. For mixed types, preserves tuple types like `[number, string, boolean]`.
+
 ```ts
 import type { Result } from 'holo-fn';
 import { all, err, ok } from 'holo-fn/result';
 
-const result1: Result<number[], unknown[]> = all([ok(1), ok(2), ok(3)]);
-console.log(result1.unwrapOr([])); // [1, 2, 3]
+const result1 = all([ok(1), ok(2), ok(3)]);
+console.log(result1.unwrapOr([]));
 
 const result2 = all([err('Name required'), err('Email invalid'), ok(25)]);
 console.log(
   result2.match({
     ok: (v) => v,
     err: (e) => e,
   })
-); // ['Name required', 'Email invalid']
+);
+
+const result3 = all([ok(42), ok("hello"), ok(true)]);
 
-const result3 = all([]);
-console.log(result3.unwrapOr([])); // []
+const result4 = all([]);
+console.log(result4.unwrapOr([]));
 ```
 
 ---
@@ -452,12 +456,14 @@ Combines an array of `Result` values into a single `Result`, stopping at the fir
 
 Unlike `all` which collects all errors, `sequence` returns immediately when it finds the first `Err`.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `T[]`. For mixed types, preserves tuple types.
+
 ```ts
 import type { Result } from 'holo-fn';
 import { err, ok, sequence } from 'holo-fn/result';
 
-const result1: Result<number[], unknown> = sequence([ok(1), ok(2), ok(3)]);
-console.log(result1.unwrapOr([])); // [1, 2, 3]
+const result1 = sequence([ok(1), ok(2), ok(3)]);
+console.log(result1.unwrapOr([]));
 
 const result2 = sequence([
   ok(1),
@@ -467,7 +473,9 @@ const result2 = sequence([
 console.log(result2.match({
   ok: (v) => v,
   err: (e) => e
-})); // 'First error'
+}));
+
+const result3 = sequence([ok(42), ok("hello")]);
 ```
 
 ---
@@ -478,6 +486,8 @@ Separates an array of `Result` values into two groups: successes (`oks`) and fai
 
 Unlike `all` and `sequence` which return a `Result`, `partition` returns a plain object with two arrays.
 
+**Smart Type Inference**: For homogeneous arrays (same type), returns `{ oks: T[], errs: E[] }`. For mixed types, preserves tuple types.
+
 ```ts
 import { err, ok, partition } from 'holo-fn/result';
 
@@ -490,8 +500,8 @@ const results = [
 ];
 
 const { oks, errs } = partition(results);
-console.log(oks); // [1, 2, 3]
-console.log(errs); // ['error1', 'error2']
+console.log(oks);
+console.log(errs);
 
 const { oks: succeeded, errs: failed } = partition(results);
 console.log(`✓ ${succeeded.length} succeeded`);

src/either/index.ts

@@ -428,99 +428,119 @@ type UnwrapLeftArray<T extends Either<unknown, unknown>[]> = {
 	[K in keyof T]: T[K] extends Either<infer L, unknown> ? L : never;
 }[number];
 
+type ExtractEitherRight<T> = T extends Either<unknown, infer R> ? R : never;
+type ExtractEitherLeft<T> = T extends Either<infer L, unknown> ? L : never;
+
 /**
  * Combines multiple Either values, collecting all Left values.
- * Supports heterogeneous tuple types.
+ * For homogeneous arrays, returns R[] instead of tuples. For mixed types, preserves tuple types.
  *
  * @example
  * ```ts
- * all([right(1), right(2), right(3)]); // Right([1, 2, 3])
+ * all([right(1), right(2), right(3)]); // Right<number[]>
  * all([right(1), left("e1"), left("e2")]); // Left(["e1", "e2"])
+ * all([right(42), right("hello")]); // Right<[number, string]>
  * ```
  */
+export function all<
+	T extends Either<L, R>,
+	L = ExtractEitherLeft<T>,
+	R = ExtractEitherRight<T>,
+>(eithers: T[]): Either<L[], R[]>;
 export function all<T extends Either<unknown, unknown>[]>(
 	eithers: [...T],
-): Either<UnwrapLeftArray<T>[], UnwrapEitherArray<T>> {
-	const values: UnwrapEitherArray<T>[number][] = [];
-	const errors: UnwrapLeftArray<T>[] = [];
+): Either<UnwrapLeftArray<T>[], UnwrapEitherArray<T>>;
+export function all<T extends Either<unknown, unknown>[]>(
+	eithers: T,
+): Either<unknown, unknown> {
+	const values: unknown[] = [];
+	const errors: unknown[] = [];
 
 	for (const either of eithers) {
 		if (either.isLeft()) {
-			errors.push(either.extract() as UnwrapLeftArray<T>);
+			errors.push(either.extract());
 		} else {
-			values.push(either.extract() as UnwrapEitherArray<T>[number]);
+			values.push(either.extract());
 		}
 	}
 
 	if (errors.length > 0) {
-		return new Left(errors) as Either<
-			UnwrapLeftArray<T>[],
-			UnwrapEitherArray<T>
-		>;
+		return new Left(errors);
 	}
 
-	return new Right(values) as Either<
-		UnwrapLeftArray<T>[],
-		UnwrapEitherArray<T>
-	>;
+	return new Right(values);
 }
 
 /**
  * Combines multiple Either values with fail-fast behavior.
- * Supports heterogeneous tuple types.
+ * For homogeneous arrays, returns R[] instead of tuples. For mixed types, preserves tuple types.
  *
  * @example
  * ```ts
- * sequence([right(1), right(2), right(3)]); // Right([1, 2, 3])
+ * sequence([right(1), right(2), right(3)]); // Right<number[]>
  * sequence([right(1), left("e1"), left("e2")]); // Left("e1") - stops at first
+ * sequence([right(42), right("hello")]); // Right<[number, string]>
  * ```
  */
+export function sequence<
+	T extends Either<L, R>,
+	L = ExtractEitherLeft<T>,
+	R = ExtractEitherRight<T>,
+>(eithers: T[]): Either<L, R[]>;
 export function sequence<T extends Either<unknown, unknown>[]>(
 	eithers: [...T],
-): Either<UnwrapLeftArray<T>, UnwrapEitherArray<T>> {
-	const values: UnwrapEitherArray<T>[number][] = [];
+): Either<UnwrapLeftArray<T>, UnwrapEitherArray<T>>;
+export function sequence<T extends Either<unknown, unknown>[]>(
+	eithers: T,
+): Either<unknown, unknown> {
+	const values: unknown[] = [];
 
 	for (const either of eithers) {
 		if (either.isLeft()) {
-			return new Left(either.extract() as UnwrapLeftArray<T>) as Either<
-				UnwrapLeftArray<T>,
-				UnwrapEitherArray<T>
-			>;
+			return new Left(either.extract());
 		}
 
-		values.push(either.extract() as UnwrapEitherArray<T>[number]);
+		values.push(either.extract());
 	}
 
-	return new Right(values) as Either<UnwrapLeftArray<T>, UnwrapEitherArray<T>>;
+	return new Right(values);
 }
 
 /**
  * Separates an array of Eithers into Left and Right values.
- * Supports heterogeneous tuple types.
+ * For homogeneous arrays, returns R[] instead of tuples. For mixed types, preserves tuple types.
  *
  * @example
  * ```ts
  * partition([right(1), left("e1"), right(2)]);
- * // { lefts: ["e1"], rights: [1, 2] }
+ * // { lefts: string[], rights: number[] } (not tuples!)
  * ```
  */
+export function partition<
+	T extends Either<L, R>,
+	L = ExtractEitherLeft<T>,
+	R = ExtractEitherRight<T>,
+>(eithers: T[]): { lefts: L[]; rights: R[] };
 export function partition<T extends Either<unknown, unknown>[]>(
 	eithers: [...T],
-): { lefts: UnwrapLeftArray<T>[]; rights: UnwrapEitherArray<T> } {
+): { lefts: UnwrapLeftArray<T>[]; rights: UnwrapEitherArray<T> };
+export function partition<T extends Either<unknown, unknown>[]>(
+	eithers: T,
+): { lefts: unknown[]; rights: unknown[] } {
 	return eithers.reduce(
 		(acc, either) => {
 			if (either.isLeft()) {
-				acc.lefts.push(either.extract() as UnwrapLeftArray<T>);
+				acc.lefts.push(either.extract());
 			} else {
-				acc.rights.push(either.extract() as UnwrapEitherArray<T>[number]);
+				acc.rights.push(either.extract());
 			}
 			return acc;
 		},
 		{
-			lefts: [] as UnwrapLeftArray<T>[],
-			rights: [] as UnwrapEitherArray<T>[number][],
+			lefts: [] as unknown[],
+			rights: [] as unknown[],
 		},
-	) as { lefts: UnwrapLeftArray<T>[]; rights: UnwrapEitherArray<T> };
+	);
 }
 
 /**