unthrown 5.8.0 → 5.9.0

package/dist/index.cjs

@@ -1126,7 +1126,7 @@ function fromThrowable(fn, qualify) {
 	return (...args) => {
 		try {
 			const value = fn(...args);
-			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
+			return isThenable(value) ? thenableReturnDefect(value, SYNC_FN_THENABLE) : Ok(value);
 		} catch (cause) {
 			return qualifyToResult(cause, triage);
 		}
@@ -1169,7 +1169,7 @@ function fromSafeThrowable(fn) {
 	return (...args) => {
 		try {
 			const value = fn(...args);
-			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
+			return isThenable(value) ? thenableReturnDefect(value, SYNC_FN_THENABLE) : Ok(value);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -1331,30 +1331,46 @@ function qualifyToResult(cause, qualify) {
 	}
 }
 /**
-* The Defect minted when a **synchronous** boundary's `fn` returns a thenable —
-* i.e. an `async` function was handed to {@link fromThrowable} /
-* {@link fromSafeThrowable}.
+* The message for {@link thenableReturnDefect} at a **synchronous boundary** —
+* an `async` function handed to {@link fromThrowable} / {@link fromSafeThrowable}.
+*
+* @internal
+*/
+const SYNC_FN_THENABLE = "unthrown: fromThrowable/fromSafeThrowable wrap a SYNCHRONOUS function, but `fn` returned a thenable — its rejection would escape qualification. Use fromPromise/fromSafePromise instead.";
+/**
+* The message for {@link thenableReturnDefect} in an **accumulating aggregate** —
+* an `async` `merge` handed to {@link validateAll} and friends.
+*
+* @internal
+*/
+const MERGE_THENABLE = "unthrown: an accumulating aggregate's `merge` must be SYNCHRONOUS, but it returned a thenable — its rejection would escape qualification.";
+/**
+* The Defect minted where a callback that must be **synchronous** returned a
+* thenable: a `fn` handed to {@link fromThrowable} / {@link fromSafeThrowable},
+* or a `merge` handed to an accumulating aggregate.
 *
 * @remarks
 * This is the sibling of the thenable-`qualify` net in {@link qualifyToResult},
 * and it closes a strictly worse hole. A synchronous boundary only ever sees a
 * synchronous `throw`, so an async `fn`'s rejection never reaches `qualify` at
 * all: it would sit inside `Ok(<Promise>)`, un-triaged, and then float as an
-* unhandled rejection — which terminates the process on Node by default.
-*
-* Unlike the combinator callbacks, this cannot be banned at compile time
-* without collateral damage: `T & NotThenable<T>` on `fn`'s return makes a
-* **generic** function unassignable, so `fromSafeThrowable(structuredClone)`
-* stops compiling and `T` collapses to `unknown`. (The phantom rest-tuple guard
-* `fromPromise` uses fares worse.) So the ban is enforced here, at runtime,
-* where it costs nothing: a Defect, plus adopt-and-silence so the orphaned
-* rejection cannot float.
+* unhandled rejection — which terminates the process on Node by default. An
+* async `merge` is the same hole one channel over: `Err(<Promise>)`.
+*
+* The `fn` case cannot be banned at compile time without collateral damage:
+* `T & NotThenable<T>` on `fn`'s return makes a **generic** function
+* unassignable, so `fromSafeThrowable(structuredClone)` stops compiling and `T`
+* collapses to `unknown`. (The phantom rest-tuple guard `fromPromise` uses fares
+* worse.) `merge` *is* `NotThenable`-constrained, but a cast or an untyped
+* caller still reaches here. Either way the runtime answer is the same, and it
+* costs nothing: a Defect, plus adopt-and-silence so the orphaned rejection
+* cannot float.
 *
 * @internal
 */
-function thenableReturnDefect(value) {
-	Promise.resolve(value).then(void 0, () => void 0);
-	return defectRes(/* @__PURE__ */ new TypeError("unthrown: fromThrowable/fromSafeThrowable wrap a SYNCHRONOUS function, but `fn` returned a thenable — its rejection would escape qualification. Use fromPromise/fromSafePromise instead."));
+function thenableReturnDefect(value, message) {
+	silenceIfThenable(value);
+	return defectRes(new TypeError(message));
 }
 /**
 * Fold an array of settled `Result`s: first `Err` wins, any `Defect` dominates,
@@ -1366,11 +1382,23 @@ function thenableReturnDefect(value) {
 function nonResultDefect() {
 	return defectRes(/* @__PURE__ */ new TypeError("unthrown: aggregate received a non-Result element"));
 }
-function foldArray(results) {
+/**
+* Resolve every input concurrently (order preserved), adopting each one
+* defensively: a cast/untyped rejecting thenable becomes a `Defect` rather than
+* rejecting the internal promise, so the "an `AsyncResult`'s internal promise
+* never rejects" invariant holds even for out-of-contract input.
+*
+* @internal
+*/
+function settleAll(results) {
+	return Promise.all(results.map((r) => Promise.resolve(r).then((x) => x, (cause) => defectRes(cause))));
+}
+function foldArray(results, merge) {
 	let firstErr;
 	let firstDefect;
 	const values = [];
-	for (const r of results) {
+	const errors = [];
+	for (const [i, r] of results.entries()) {
 		if (!isResult(r)) {
 			firstDefect ??= nonResultDefect();
 			break;
@@ -1378,10 +1406,19 @@ function foldArray(results) {
 		if (r.tag === "Defect") {
 			firstDefect ??= r;
 			break;
-		} else if (r.tag === "Err") firstErr ??= r;
+		} else if (r.tag === "Err") if (merge) errors.push([i, r.error]);
+		else firstErr ??= r;
 		else values.push(r.value);
 	}
-	return firstDefect ?? firstErr ?? Ok(values);
+	if (firstDefect) return firstDefect;
+	if (merge && errors.length > 0) try {
+		const merged = merge(errors);
+		if (isThenable(merged)) return thenableReturnDefect(merged, MERGE_THENABLE);
+		return Err(merged);
+	} catch (cause) {
+		return defectRes(cause);
+	}
+	return firstErr ?? Ok(values);
 }
 /**
 * Fold a record of settled `Result`s with the same rules, else `Ok` of the
@@ -1399,9 +1436,17 @@ function foldArray(results) {
 *
 * @internal
 */
-function foldRecord(results) {
+function foldRecord(results, merge) {
 	const keys = Object.keys(results);
-	return foldArray(Object.values(results)).map((values) => Object.fromEntries(keys.map((key, i) => [key, values[i]])));
+	return foldArray(Object.values(results), merge && ((errors) => merge(nameErrors(errors, keys)))).map((values) => Object.fromEntries(keys.map((key, i) => [key, values[i]])));
+}
+/** Drop the accumulated indices — the positional forms merge errors alone. @internal */
+function stripIndices(errors) {
+	return errors.map(([, e]) => e);
+}
+/** Pair each accumulated index back onto its key. @internal */
+function nameErrors(errors, keys) {
+	return errors.map(([i, e]) => [keys[i], e]);
 }
 /**
 * Collect a tuple/array of {@link Result}s into a single `Result` of all their
@@ -1413,7 +1458,8 @@ function foldRecord(results) {
 * `Err`. A **fixed tuple** keeps its positional types — `all([Ok(1), Ok("a")])`
 * is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
 * collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
-* use {@link allFromDict}.
+* use {@link allFromDict}. To report **every** `Err` instead of only the first,
+* use {@link validateAll}.
 *
 * @category Aggregate
 *
@@ -1436,7 +1482,9 @@ function all(results) {
 *
 * @remarks
 * Same folding rules as {@link all}: first `Err` short-circuits, any `Defect`
-* dominates. This is **not** error accumulation.
+* dominates. This is **not** error accumulation — for that, reach for
+* {@link validateAllFromDict}, which accumulates every `Err` and folds them into
+* one modeled error.
 *
 * @category Aggregate
 *
@@ -1459,7 +1507,8 @@ function allFromDict(results) {
 * The inputs are resolved **concurrently** (order preserved); the resolved
 * `Result`s are then folded with the same rules as {@link all} — first `Err`
 * short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
-* internal promise never rejects. For a **record**, use {@link allFromDictAsync}.
+* internal promise never rejects. For a **record**, use {@link allFromDictAsync};
+* to report **every** `Err`, use {@link validateAllAsync}.
 *
 * @category Aggregate
 *
@@ -1475,7 +1524,7 @@ function allFromDict(results) {
 * ```
 */
 function allAsync(results) {
-	return new AsyncRes(Promise.all(results.map((r) => Promise.resolve(r).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => foldArray(resolved)));
+	return new AsyncRes(settleAll(results).then((resolved) => foldArray(resolved)));
 }
 /**
 * The asynchronous counterpart of {@link allFromDict}: combine a record of
@@ -1483,7 +1532,8 @@ function allAsync(results) {
 *
 * @remarks
 * Resolved concurrently (order preserved), folded with the {@link all} rules,
-* and the internal promise never rejects.
+* and the internal promise never rejects. To report **every** `Err`, use
+* {@link validateAllFromDictAsync}.
 *
 * @category Aggregate
 *
@@ -1500,7 +1550,163 @@ function allAsync(results) {
 */
 function allFromDictAsync(results) {
 	const keys = Object.keys(results);
-	return new AsyncRes(Promise.all(Object.values(results).map((ar) => Promise.resolve(ar).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => foldArray(resolved).map((values) => Object.fromEntries(keys.map((key, i) => [key, values[i]])))));
+	return new AsyncRes(settleAll(Object.values(results)).then((resolved) => foldRecord(Object.fromEntries(keys.map((key, i) => [key, resolved[i]])))));
+}
+/**
+* Collect a tuple/array of {@link Result}s, **accumulating every** `Err` and
+* merging them into a single modeled error — the accumulating counterpart of
+* {@link all}.
+*
+* @remarks
+* Same success channel as {@link all}: a **fixed tuple** keeps its positional
+* types, a **dynamic array** collapses to `Result<T[], E2>`. The difference is
+* the error channel — instead of the first `Err` winning, every `Err` is
+* collected in input order and handed to `merge`, whose return becomes the
+* modeled error.
+*
+* `merge` receives a **non-empty** list, so it is total: it is called only when
+* at least one `Err` was collected. It is **not** called when every element is
+* `Ok`, nor when a `Defect` is present.
+*
+* Any `Defect` still **dominates** — it wins over the accumulated errors, which
+* are discarded and never reach `merge`. A defect means something in this batch
+* failed in a way nobody modeled, so the violations computed alongside it are
+* not trustworthy. An out-of-contract non-`Result` element becomes a
+* `TypeError`-caused `Defect` the same way, and a throw inside `merge` becomes
+* a `Defect` too.
+*
+* `merge` must be **synchronous** — an `async` one is a compile error
+* ({@link NotThenable}), since a `Promise` in `E` is an unqualified rejection.
+*
+* For **schema-shaped** input (a request body, a form), reach for
+* `@unthrown/standard-schema`'s `fromSchema` instead — a validator already
+* hands you every issue as the modeled error. `validateAll` is for independent
+* checks you wrote yourself. For a **record** keyed by name, use
+* {@link validateAllFromDict}.
+*
+* @typeParam Rs - the tuple/array of input `Result` types.
+* @typeParam E2 - the merged error type.
+* @param results - the results to collect.
+* @param merge - folds the collected errors into one modeled error.
+*
+* @category Aggregate
+*
+* @example
+* ```ts
+* import { validateAll, Ok, Err } from "unthrown";
+*
+* // every Err is collected, not just the first
+* validateAll([Ok(1), Err("stock"), Err("credit")], (errors) => errors.join(" and "));
+* // => Err("stock and credit")
+*
+* // all-Ok keeps the positional tuple; `merge` never runs
+* validateAll([Ok(1), Ok("a")], (errors) => errors.join());
+* // => Ok([1, "a"]) typed Result<[number, string], string>
+* ```
+*/
+function validateAll(results, merge) {
+	return foldArray(results, (errors) => merge(stripIndices(errors)));
+}
+/**
+* Collect a **record** of {@link Result}s, accumulating every `Err` — the
+* accumulating counterpart of {@link allFromDict}, and the named counterpart of
+* {@link validateAll}.
+*
+* @remarks
+* `merge` receives a non-empty list of **`[key, error]` entries**, correlated
+* per key: `{ a: Result<A, E1>; b: Result<B, E2> }` yields
+* `["a", E1] | ["b", E2]`, so a `switch` on the key narrows the error and an
+* impossible pairing does not typecheck. That is what keeps two checks sharing
+* one error type distinguishable. Entries come in `Object.keys` order.
+*
+* Every other rule matches {@link validateAll}: any `Defect` dominates and
+* discards the accumulated errors, a throw in `merge` becomes a `Defect`, and
+* `merge` must be synchronous.
+*
+* @typeParam R - the record of input `Result` types.
+* @typeParam E2 - the merged error type.
+* @param results - the results to collect, keyed by name.
+* @param merge - folds the collected `[key, error]` entries into one error.
+*
+* @category Aggregate
+*
+* @example
+* ```ts
+* import { validateAllFromDict, Ok, Err } from "unthrown";
+*
+* validateAllFromDict(
+*   { vatRate: Err("out of range"), currency: Ok("EUR"), dueDate: Err("past") },
+*   (entries) => entries.map(([key, error]) => `${key}: ${error}`).join("; "),
+* );
+* // => Err("vatRate: out of range; dueDate: past")
+* ```
+*/
+function validateAllFromDict(results, merge) {
+	return foldRecord(results, (entries) => merge(entries));
+}
+/**
+* The asynchronous counterpart of {@link validateAll}: collect a tuple/array of
+* {@link AsyncResult}s, accumulating every `Err` into one merged error.
+*
+* @remarks
+* Every {@link validateAll} rule holds, with the inputs resolved
+* **concurrently** (order preserved) — as with {@link allAsync}, no work is
+* short-circuited either way; the fail-fast/accumulating split is purely which
+* errors get reported. The internal promise never rejects: an out-of-contract
+* rejecting thenable becomes a dominating `Defect`. `merge` stays synchronous
+* here too — this is exactly where its rejection would land unqualified in `E`.
+* For a **record**, use {@link validateAllFromDictAsync}.
+*
+* @typeParam Rs - the tuple/array of input `AsyncResult` types.
+* @typeParam E2 - the merged error type.
+* @param results - the async results to collect.
+* @param merge - folds the collected errors into one modeled error.
+*
+* @category Aggregate
+*
+* @example
+* ```ts
+* import { validateAllAsync, OkAsync, ErrAsync } from "unthrown";
+*
+* const checked = validateAllAsync(
+*   [OkAsync(1), ErrAsync("stock"), ErrAsync("credit")],
+*   (errors) => errors.join(" and "),
+* );
+* // (await checked) => Err("stock and credit")
+* ```
+*/
+function validateAllAsync(results, merge) {
+	return new AsyncRes(settleAll(results).then((resolved) => foldArray(resolved, (errors) => merge(stripIndices(errors)))));
+}
+/**
+* The asynchronous counterpart of {@link validateAllFromDict}: collect a record
+* of {@link AsyncResult}s, accumulating every `Err` into one merged error.
+*
+* @remarks
+* The {@link validateAllFromDict} rules, over inputs resolved concurrently as
+* in {@link validateAllAsync}.
+*
+* @typeParam R - the record of input `AsyncResult` types.
+* @typeParam E2 - the merged error type.
+* @param results - the async results to collect, keyed by name.
+* @param merge - folds the collected `[key, error]` entries into one error.
+*
+* @category Aggregate
+*
+* @example
+* ```ts
+* import { validateAllFromDictAsync, OkAsync, ErrAsync } from "unthrown";
+*
+* const checked = validateAllFromDictAsync(
+*   { stock: ErrAsync("none left"), credit: OkAsync(500) },
+*   (entries) => entries.map(([key, error]) => `${key}: ${error}`).join("; "),
+* );
+* // (await checked) => Err("stock: none left")
+* ```
+*/
+function validateAllFromDictAsync(results, merge) {
+	const keys = Object.keys(results);
+	return new AsyncRes(settleAll(Object.values(results)).then((resolved) => foldRecord(Object.fromEntries(keys.map((key, i) => [key, resolved[i]])), (entries) => merge(entries))));
 }
 //#endregion
 //#region src/facade.ts
@@ -1509,7 +1715,8 @@ function allFromDictAsync(results) {
 * single, discoverable namespace: {@link Result.Ok}, {@link Result.Err},
 * {@link Result.Do}, {@link Result.fromNullable}, {@link Result.fromThrowable},
 * {@link Result.fromSafeThrowable}, {@link Result.all},
-* {@link Result.allFromDict}, {@link Result.isOk}, {@link Result.isErr},
+* {@link Result.allFromDict}, {@link Result.validateAll},
+* {@link Result.validateAllFromDict}, {@link Result.isOk}, {@link Result.isErr},
 * {@link Result.isDefect}, {@link Result.isResult}.
 *
 * @remarks
@@ -1539,6 +1746,8 @@ const Result = {
 	fromSafeThrowable,
 	all,
 	allFromDict,
+	validateAll,
+	validateAllFromDict,
 	isOk,
 	isErr,
 	isDefect,
@@ -1549,7 +1758,8 @@ const Result = {
 * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
 * {@link AsyncResult.Do}, {@link AsyncResult.fromExecutor},
 * {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
-* {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
+* {@link AsyncResult.all}, {@link AsyncResult.allFromDict},
+* {@link AsyncResult.validateAll}, {@link AsyncResult.validateAllFromDict}.
 *
 * @remarks
 * The async sibling of {@link Result}. Statics are grouped by what they
@@ -1560,7 +1770,8 @@ const Result = {
 * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
 * `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
 * `AsyncResult.allFromDict` is
-* `allFromDictAsync`). Like {@link Result}, the free functions remain the
+* `allFromDictAsync`; `AsyncResult.validateAll` is `validateAllAsync`). Like
+* {@link Result}, the free functions remain the
 * primary, tree-shakeable API; the value `AsyncResult` and the type
 * {@link AsyncResult} share one name.
 *
@@ -1584,7 +1795,9 @@ const AsyncResult = {
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
-	allFromDict: allFromDictAsync
+	allFromDict: allFromDictAsync,
+	validateAll: validateAllAsync,
+	validateAllFromDict: validateAllFromDictAsync
 };
 //#endregion
 //#region src/tagged.ts
@@ -1704,3 +1917,7 @@ exports.isErr = isErr;
 exports.isOk = isOk;
 exports.isResult = isResult;
 exports.match = match;
+exports.validateAll = validateAll;
+exports.validateAllAsync = validateAllAsync;
+exports.validateAllFromDict = validateAllFromDict;
+exports.validateAllFromDictAsync = validateAllFromDictAsync;