unthrown 3.0.1 → 4.0.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

@@ -14,7 +14,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * A `Defect` is never wrapped in an `UnwrapError`: its original cause is
 * re-thrown (with its original stack) instead.
 *
+* `unwrap()` and `unwrapErr()` are type-gated (`this: Result<T, never>` /
+* `Result<never, E>`), so the wrong-variant branch that throws this is
+* unreachable through well-typed code — it remains only as a defensive guard
+* against unsound runtime misuse (e.g. an `as` cast past the gate).
+*
 * @typeParam E - the type of the {@link UnwrapError.error} it carries.
+*
+* @category Errors
 */
 var UnwrapError = class extends Error {
 	/**
@@ -129,7 +136,7 @@ var Res = class {
 			f(this.error);
 			return this;
 		} catch (cause) {
-			return defectRes(cause);
+			return observerThrowToDefect(cause, this.error);
 		}
 	}
 	flatTapErr(f) {
@@ -138,7 +145,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 +162,7 @@ var Res = class {
 			f(this.cause);
 			return this;
 		} catch (cause) {
-			return defectRes(cause);
+			return observerThrowToDefect(cause, this.cause);
 		}
 	}
 	match(cases) {
@@ -218,10 +225,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 +236,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 +247,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 +263,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 +295,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 +325,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 +453,7 @@ var AsyncRes = class AsyncRes {
 				f(r.error);
 				return r;
 			} catch (cause) {
-				return defectRes(cause);
+				return observerThrowToDefect(cause, r.error);
 			}
 		}));
 	}
@@ -431,7 +464,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 +485,7 @@ var AsyncRes = class AsyncRes {
 				f(r.cause);
 				return r;
 			} catch (cause) {
-				return defectRes(cause);
+				return observerThrowToDefect(cause, r.cause);
 			}
 		}));
 	}
@@ -489,8 +522,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);
@@ -504,8 +541,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);
@@ -517,10 +558,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";
@@ -529,6 +576,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";
@@ -536,7 +596,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";
@@ -564,6 +644,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({});
@@ -613,10 +711,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").unwrapOr(0); // => 1
+* fromNullable(map.get("z"), () => "absent"); // => Err("absent")
+* fromNullable(0, () => "absent").unwrapOr(-1); // => 0 (falsy but present)
 * ```
 */
 function fromNullable(value, onAbsent) {
@@ -647,11 +751,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}').unwrapOr(null); // => { ok: true }
+* parse("nope"); // => Err("invalid_json")
 * ```
 */
 function fromThrowable(fn, qualify) {
@@ -686,17 +800,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),
 * );
+*
+* if (user.isOk()) user.value; // => the fetched user
+* // when fetchUser rejects with NotFoundError: user is 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
@@ -709,9 +830,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 {
@@ -749,8 +881,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,
@@ -771,11 +905,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) {
@@ -791,10 +928,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) {
@@ -810,10 +951,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) {
@@ -827,10 +972,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) {
@@ -862,10 +1014,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 = {
@@ -896,10 +1050,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 = {
@@ -916,9 +1073,17 @@ const AsyncResult = {
 *
 * @remarks
 * 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.
+* an instantiation expression; omit it for a payload-less error. The `message`
+* is **not** a payload field — it is the human string owned by `Error`, not
+* structured data, so it is reserved. Define it once per subclass the standard
+* way, `override message = "…"` (it may interpolate the payload via `this`,
+* which the base populates before the subclass field initialiser runs); a
+* payload `message` is rejected at compile time, so contextual detail lives in
+* typed fields, never baked into per-call prose. The `_tag` always reflects
+* `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
@@ -929,11 +1094,14 @@ const AsyncResult = {
 * ```ts
 * class RetryableError extends TaggedError("@my-lib/RetryableError", {
 *   name: "RetryableError",
-* })<{ message: string }> {}
+* }) {
+*   override message = "operation failed; safe to retry";
+* }
 *
-* const e = new RetryableError({ message: "boom" });
-* e._tag; // "@my-lib/RetryableError" — namespaced discriminant
-* e.name; // "RetryableError"          — clean display name
+* const e = new RetryableError();
+* e._tag;    // "@my-lib/RetryableError" — namespaced discriminant
+* e.name;    // "RetryableError"          — clean display name
+* e.message; // "operation failed; safe to retry" — the standard Error.message
 * ```
 *
 * @typeParam Tag - the string literal discriminant.
@@ -941,13 +1109,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) {
@@ -955,10 +1125,11 @@ function TaggedError(tag, options) {
 	class TaggedErrorBase extends Error {
 		_tag;
 		constructor(props) {
-			super(typeof props?.["message"] === "string" ? props["message"] : void 0);
+			super();
 			if (props) Object.assign(this, props);
 			this._tag = tag;
 			this.name = displayName;
+			delete this.message;
 			Object.setPrototypeOf(this, new.target.prototype);
 		}
 	}
@@ -966,8 +1137,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,