unthrown 3.0.0 → 3.1.0

package/README.md

@@ -11,7 +11,10 @@ pnpm add unthrown
 ```
 
 ```ts
-import { Ok, Err, fromPromise, type Result } from "unthrown";
+import { fromPromise, TaggedError } from "unthrown";
+
+class NotFound extends TaggedError("NotFound") {} // our modeled domain failure
+class NotFoundError extends Error {} // what `fetchUser` rejects with on a 404
 
 const user = fromPromise(fetchUser(id), (cause, defect) =>
   cause instanceof NotFoundError ? new NotFound() : defect(cause),
@@ -37,4 +40,4 @@ and complete API.
 
 ## License
 
-[MIT](../../LICENSE) © Benoit TRAVERS
+[MIT](https://github.com/btravstack/unthrown/blob/main/LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -15,6 +15,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * re-thrown (with its original stack) instead.
 *
 * @typeParam E - the type of the {@link UnwrapError.error} it carries.
+*
+* @category Errors
 */
 var UnwrapError = class extends Error {
 	/**
@@ -129,7 +131,7 @@ var Res = class {
 			f(this.error);
 			return this;
 		} catch (cause) {
-			return defectRes(cause);
+			return observerThrowToDefect(cause, this.error);
 		}
 	}
 	flatTapErr(f) {
@@ -138,7 +140,7 @@ var Res = class {
 			const r = f(this.error);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
-			return defectRes(cause);
+			return observerThrowToDefect(cause, this.error);
 		}
 	}
 	recoverDefect(f) {
@@ -155,7 +157,7 @@ var Res = class {
 			f(this.cause);
 			return this;
 		} catch (cause) {
-			return defectRes(cause);
+			return observerThrowToDefect(cause, this.cause);
 		}
 	}
 	match(cases) {
@@ -218,10 +220,10 @@ const RESULT_PROTO = Res.prototype;
 * @internal
 */
 function okRes(value) {
-	return Object.assign(Object.create(RESULT_PROTO), {
+	return Object.freeze(Object.assign(Object.create(RESULT_PROTO), {
 		tag: "Ok",
 		value
-	});
+	}));
 }
 /**
 * Construct an `Err` result.
@@ -229,10 +231,10 @@ function okRes(value) {
 * @internal
 */
 function errRes(error) {
-	return Object.assign(Object.create(RESULT_PROTO), {
+	return Object.freeze(Object.assign(Object.create(RESULT_PROTO), {
 		tag: "Err",
 		error
-	});
+	}));
 }
 /**
 * Construct a `Defect` result.
@@ -240,10 +242,10 @@ function errRes(error) {
 * @internal
 */
 function defectRes(cause) {
-	return Object.assign(Object.create(RESULT_PROTO), {
+	return Object.freeze(Object.assign(Object.create(RESULT_PROTO), {
 		tag: "Defect",
 		cause
-	});
+	}));
 }
 /**
 * Type guard: is `x` a {@link Result} (any of `Ok` / `Err` / `Defect`)?
@@ -256,6 +258,20 @@ function defectRes(cause) {
 * is not a `Result` and returns `false`.
 *
 * @returns `true` when `x` is a `Result` produced by this library.
+*
+* @example
+* ```ts
+* import { isResult, Ok } from "unthrown";
+*
+* isResult(Ok(1)); // => true
+* isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
+* isResult(Ok(1).toAsync()); // => false (an AsyncResult is not a Result)
+*
+* const x: unknown = Ok(1);
+* if (isResult(x)) x.match({ ok: () => 1, err: () => 0, defect: () => -1 });
+* ```
+*
+* @category Guards
 */
 function isResult(x) {
 	return x instanceof Res;
@@ -274,6 +290,18 @@ function passThrough(self) {
 	return self;
 }
 /**
+* A throw inside a *failure observer* (`tapErr` / `tapDefect` / `flatTapErr`)
+* must not destroy the failure being observed — that is the exact place (e.g. a
+* failing error-logger) where losing the underlying failure hurts most. The
+* resulting Defect aggregates both: `errors[0]` is the observer's throw,
+* `errors[1]` the original failure.
+*
+* @internal
+*/
+function observerThrowToDefect(thrown, original) {
+	return defectRes(new AggregateError([thrown, original], "unthrown: a failure-observer callback threw; errors[0] is the callback's throw, errors[1] the original failure"));
+}
+/**
 * Validate that a `bind`/`let` scope is a real (non-null) object before merging a
 * key into it.
 *
@@ -292,7 +320,7 @@ function passThrough(self) {
 * @internal
 */
 function scopeOf(value) {
-	if (typeof value !== "object" || value === null) throw new TypeError("bind/let requires an object scope — start a do-chain with Do()");
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("bind/let requires an object scope — start a do-chain with Do()");
 	return value;
 }
 /**
@@ -420,7 +448,7 @@ var AsyncRes = class AsyncRes {
 				f(r.error);
 				return r;
 			} catch (cause) {
-				return defectRes(cause);
+				return observerThrowToDefect(cause, r.error);
 			}
 		}));
 	}
@@ -431,7 +459,7 @@ var AsyncRes = class AsyncRes {
 				const inner = await f(r.error);
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
-				return defectRes(cause);
+				return observerThrowToDefect(cause, r.error);
 			}
 		}));
 	}
@@ -452,7 +480,7 @@ var AsyncRes = class AsyncRes {
 				f(r.cause);
 				return r;
 			} catch (cause) {
-				return defectRes(cause);
+				return observerThrowToDefect(cause, r.cause);
 			}
 		}));
 	}
@@ -469,11 +497,7 @@ var AsyncRes = class AsyncRes {
 		return this.promise.then((r) => r.unwrapOr(fallback));
 	}
 	unwrapOrElse(f) {
-		return this.promise.then((r) => {
-			if (r.tag === "Ok") return r.value;
-			if (r.tag === "Defect") throw r.cause;
-			return f(r.error);
-		});
+		return this.promise.then((r) => r.unwrapOrElse(f));
 	}
 	getOrNull() {
 		return this.promise.then((r) => r.getOrNull());
@@ -493,8 +517,12 @@ var AsyncRes = class AsyncRes {
 * @example
 * ```ts
 * import { Ok } from "unthrown";
-* Ok(42).unwrap(); // 42
+*
+* Ok(2).map((n) => n + 1); // => Ok(3)
+* Ok(42).unwrap(); // => 42
 * ```
+*
+* @category Constructors
 */
 function Ok(value) {
 	return okRes(value);
@@ -508,8 +536,12 @@ function Ok(value) {
 * @example
 * ```ts
 * import { Err } from "unthrown";
-* Err("not_found").unwrapErr(); // "not_found"
+*
+* Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
+* Err("not_found").unwrapErr(); // => "not_found"
 * ```
+*
+* @category Constructors
 */
 function Err(error) {
 	return errRes(error);
@@ -521,10 +553,16 @@ function Err(error) {
 *
 * @example
 * ```ts
-* import { isOk, type Result } from "unthrown";
+* import { isOk, Ok, Err, type Result } from "unthrown";
+*
+* isOk(Ok(1)); // => true
+* isOk(Err("boom")); // => false
+*
 * declare const r: Result<number, string>;
 * if (isOk(r)) r.value; // number, narrowed
 * ```
+*
+* @category Guards
 */
 function isOk(r) {
 	return r.tag === "Ok";
@@ -533,6 +571,19 @@ function isOk(r) {
 * Type guard: narrow a {@link Result} to its `Err` variant, exposing `.error`.
 *
 * @returns `true` when `r` is `Err`.
+*
+* @example
+* ```ts
+* import { isErr, Ok, Err, type Result } from "unthrown";
+*
+* isErr(Err("boom")); // => true
+* isErr(Ok(1)); // => false
+*
+* declare const r: Result<number, string>;
+* if (isErr(r)) r.error; // string, narrowed
+* ```
+*
+* @category Guards
 */
 function isErr(r) {
 	return r.tag === "Err";
@@ -540,7 +591,27 @@ function isErr(r) {
 /**
 * Type guard: narrow a {@link Result} to its `Defect` variant, exposing `.cause`.
 *
+* @remarks
+* A `Defect` has no public constructor — it only arises at a boundary (e.g. a
+* callback throwing inside a combinator). This guard is how you detect one.
+*
 * @returns `true` when `r` is a `Defect`.
+*
+* @example
+* ```ts
+* import { isDefect, Ok } from "unthrown";
+*
+* // A throw inside a combinator is captured as a Defect:
+* const r = Ok(1).map(() => {
+*   throw new Error("boom");
+* });
+* isDefect(r); // => true
+* isDefect(Ok(1)); // => false
+*
+* if (isDefect(r)) r.cause; // unknown, narrowed
+* ```
+*
+* @category Guards
 */
 function isDefect(r) {
 	return r.tag === "Defect";
@@ -568,6 +639,24 @@ function isDefect(r) {
 *   .map(({ user, org, label }) => render(user, org, label));
 * // Result<View, NotFound>
 * ```
+*
+* @example
+* ```ts
+* import { Do, Ok, Err } from "unthrown";
+*
+* // Ok path — the scope accumulates:
+* Do()
+*   .bind("a", () => Ok(2))
+*   .let("b", ({ a }) => a * 10)
+*   .map(({ a, b }) => a + b); // => Ok(22)
+*
+* // Err path — the first Err short-circuits the rest:
+* Do()
+*   .bind("a", () => Err("boom"))
+*   .let("b", ({ a }) => a); // => Err("boom")
+* ```
+*
+* @category Do-notation
 */
 function Do() {
 	return Ok({});
@@ -617,10 +706,16 @@ function isDefectMarker(x) {
 * @param value - the possibly-absent value.
 * @param onAbsent - lazily produces the error for the absent case.
 *
+* @category Interop
+*
 * @example
 * ```ts
 * import { fromNullable } from "unthrown";
-* fromNullable(map.get(key), () => "missing").unwrap();
+*
+* const map = new Map([["a", 1]]);
+* fromNullable(map.get("a"), () => "absent").unwrap(); // => 1
+* fromNullable(map.get("z"), () => "absent"); // => Err("absent")
+* fromNullable(0, () => "absent").unwrap(); // => 0 (falsy but present)
 * ```
 */
 function fromNullable(value, onAbsent) {
@@ -651,11 +746,21 @@ function fromNullable(value, onAbsent) {
 * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
 * @returns a function with the same arguments returning `Result<T, E>`.
 *
+* @category Interop
+*
 * @example
 * ```ts
 * import { fromThrowable } from "unthrown";
-* const parse = fromThrowable(JSON.parse, (cause, defect) => defect(cause));
-* parse("{}").unwrap();
+*
+* // Model the parse failure as an `Err`, everything unexpected as a `Defect`.
+* const parse = fromThrowable(
+*   (text: string) => JSON.parse(text) as unknown,
+*   (cause, defect) =>
+*     cause instanceof SyntaxError ? ("invalid_json" as const) : defect(cause),
+* );
+*
+* parse('{"ok":true}').unwrap(); // => { ok: true }
+* parse("nope"); // => Err("invalid_json")
 * ```
 */
 function fromThrowable(fn, qualify) {
@@ -690,17 +795,24 @@ function fromThrowable(fn, qualify) {
 * @param qualify - triages a rejection `cause` into a modeled `E`, or marks it
 * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
 *
+* @category Interop
+*
 * @example
 * ```ts
 * import { fromPromise } from "unthrown";
+*
+* // A rejection with a NotFoundError becomes a modeled `Err`; anything else a Defect.
 * const user = await fromPromise(fetchUser(id), (cause, defect) =>
 *   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
 * );
+*
+* user.unwrap(); // => the fetched user (on success)
+* // when fetchUser rejects with NotFoundError: => Err("not_found")
 * ```
 */
 function fromPromise(promise, qualify) {
 	const triage = qualify;
-	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : promise).then((value) => okRes(value), (cause) => qualifyToResult(cause, triage)));
+	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : Promise.resolve(promise)).then((value) => okRes(value), (cause) => qualifyToResult(cause, triage)));
 }
 /**
 * Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
@@ -713,9 +825,20 @@ function fromPromise(promise, qualify) {
 *
 * @typeParam T - the resolved value type.
 * @param promise - the promise, or a thunk returning one.
+*
+* @category Interop
+*
+* @example
+* ```ts
+* import { fromSafePromise } from "unthrown";
+*
+* (await fromSafePromise(Promise.resolve(3))).unwrap(); // => 3
+* // a rejection becomes a Defect (never a modeled Err):
+* await fromSafePromise(Promise.reject(new Error("boom"))); // => Defect(Error("boom"))
+* ```
 */
 function fromSafePromise(promise) {
-	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : promise).then((value) => okRes(value), (cause) => defectRes(cause)));
+	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : Promise.resolve(promise)).then((value) => okRes(value), (cause) => defectRes(cause)));
 }
 function qualifyToResult(cause, qualify) {
 	try {
@@ -735,8 +858,10 @@ function foldArray(results) {
 	let firstErr;
 	let firstDefect;
 	const values = [];
-	for (const r of results) if (r.tag === "Defect") firstDefect ??= r;
-	else if (r.tag === "Err") firstErr ??= r;
+	for (const r of results) if (r.tag === "Defect") {
+		firstDefect ??= r;
+		break;
+	} else if (r.tag === "Err") firstErr ??= r;
 	else values.push(r.value);
 	return firstDefect ?? firstErr ?? Ok(values);
 }
@@ -751,8 +876,10 @@ function foldRecord(results) {
 	let firstErr;
 	let firstDefect;
 	const values = {};
-	for (const [key, r] of Object.entries(results)) if (r.tag === "Defect") firstDefect ??= r;
-	else if (r.tag === "Err") firstErr ??= r;
+	for (const [key, r] of Object.entries(results)) if (r.tag === "Defect") {
+		firstDefect ??= r;
+		break;
+	} else if (r.tag === "Err") firstErr ??= r;
 	else Object.defineProperty(values, key, {
 		value: r.value,
 		enumerable: true,
@@ -773,11 +900,14 @@ function foldRecord(results) {
 * collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
 * use {@link allFromDict}.
 *
+* @category Aggregate
+*
 * @example
 * ```ts
-* import { all, Ok } from "unthrown";
-* all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
-* all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
+* import { all, Ok, Err } from "unthrown";
+*
+* all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // => [1, "a", true] (typed [number, string, boolean])
+* all([Ok(1), Err("e"), Ok(3)]); // => Err("e") (short-circuits on the first Err)
 * ```
 */
 function all(results) {
@@ -793,10 +923,14 @@ function all(results) {
 * Same folding rules as {@link all}: first `Err` short-circuits, any `Defect`
 * dominates. This is **not** error accumulation.
 *
+* @category Aggregate
+*
 * @example
 * ```ts
-* import { allFromDict, Ok } from "unthrown";
-* allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
+* import { allFromDict, Ok, Err } from "unthrown";
+*
+* allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // => { id: 1, name: "ada" }
+* allFromDict({ id: Ok(1), name: Err("missing") }); // => Err("missing")
 * ```
 */
 function allFromDict(results) {
@@ -812,10 +946,14 @@ function allFromDict(results) {
 * short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
 * internal promise never rejects. For a **record**, use {@link allFromDictAsync}.
 *
+* @category Aggregate
+*
 * @example
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
-* await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
+*
+* const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+* (await both).unwrap(); // => [1, 2]
 * ```
 */
 function allAsync(results) {
@@ -829,10 +967,17 @@ function allAsync(results) {
 * Resolved concurrently (order preserved), folded with the {@link all} rules,
 * and the internal promise never rejects.
 *
+* @category Aggregate
+*
 * @example
 * ```ts
 * import { allFromDictAsync, fromSafePromise } from "unthrown";
-* await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
+*
+* const both = allFromDictAsync({
+*   a: fromSafePromise(Promise.resolve(1)),
+*   b: fromSafePromise(Promise.resolve("x")),
+* });
+* (await both).unwrap(); // => { a: 1, b: "x" }
 * ```
 */
 function allFromDictAsync(results) {
@@ -864,10 +1009,12 @@ function allFromDictAsync(results) {
 * (`AsyncResult.fromPromise`, `AsyncResult.all`, …), grouped by what they
 * return — a static lives in exactly one namespace.
 *
+* @category Facade
+*
 * @example
 * ```ts
 * import { Result } from "unthrown";
-* Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
+* Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // => 2
 * ```
 */
 const Result = {
@@ -898,10 +1045,13 @@ const Result = {
 * {@link Result}, the free functions remain the primary, tree-shakeable API; the
 * value `AsyncResult` and the type {@link AsyncResult} share one name.
 *
+* @category Facade
+*
 * @example
 * ```ts
 * import { AsyncResult } from "unthrown";
 * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* user.unwrap(); // => the fetched user (on success)
 * ```
 */
 const AsyncResult = {
@@ -920,7 +1070,10 @@ const AsyncResult = {
 * Extend the returned class to declare a concrete error. Supply the payload with
 * an instantiation expression; omit it for a payload-less error. A `message`
 * field in the payload is forwarded to `Error`. The `_tag` always reflects
-* `tag` and cannot be overridden by the payload.
+* `tag` and cannot be overridden by the payload. `name` is likewise reserved —
+* it is the display label (set it with `options.name`); a payload `name` is
+* rejected at compile time (and excluded from the instance type), so it can't
+* shadow `Error.name`.
 *
 * `_tag` is the discriminant used by {@link matchTags}; `Error.name` is the
 * human-facing label in stack traces and logs. By default they coincide, but
@@ -943,13 +1096,15 @@ const AsyncResult = {
 * @param options - optional overrides. `options.name` sets `Error.name`
 * independently of `tag` (defaults to `tag`).
 *
+* @category Tagged errors
+*
 * @example
 * ```ts
 * class NotFound extends TaggedError("NotFound") {}
 * class HttpError extends TaggedError("HttpError")<{ status: number }> {}
 *
-* new NotFound()._tag; // "NotFound"
-* new HttpError({ status: 500 }).status; // 500
+* new NotFound()._tag; // => "NotFound"
+* new HttpError({ status: 500 }).status; // => 500
 * ```
 */
 function TaggedError(tag, options) {
@@ -968,8 +1123,9 @@ function TaggedError(tag, options) {
 }
 function matchTags(result, handlers) {
 	const onErr = (error) => {
-		const handler = handlers[error._tag];
-		return handler(error);
+		const tag = error._tag;
+		const handler = tag === "Ok" || tag === "Defect" || !Object.hasOwn(handlers, tag) ? void 0 : handlers[tag];
+		return handler ? handler(error) : handlers.Defect(error);
 	};
 	return result.match({
 		ok: handlers.Ok,