unthrown 5.9.0 → 5.10.0

package/README.md

@@ -45,9 +45,6 @@ const status = await user.match({
 See the [full documentation](https://btravstack.github.io/unthrown/) for the guide
 and complete API.
 
-**Upgrading from 4.x?** See
-[Upgrade from 4.x to 5.0](https://btravstack.github.io/unthrown/how-to/upgrade-to-v5).
-
 ## License
 
 [MIT](https://github.com/btravstack/unthrown/blob/main/LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -18,24 +18,63 @@ const PATTERN_BRAND = Symbol.for("unthrown.matcher.pattern");
 * is a bug).
 *
 * @category Errors
+*
+* @example
+* ```ts
+* import { match, NonExhaustiveError } from "unthrown";
+*
+* // A value typed "a" | "b" that is really "c" (a cast, a raw-JS caller):
+* const rogue = "c" as "a" | "b";
+* try {
+*   match(rogue)
+*     .with("a", () => 1)
+*     .with("b", () => 2)
+*     .exhaustive();
+* } catch (error) {
+*   error instanceof NonExhaustiveError; // => true
+*   (error as NonExhaustiveError).input; // => "c"
+* }
+* ```
 */
 var NonExhaustiveError = class extends Error {
 	/** The value no arm matched. */
 	input;
 	constructor(input) {
-		let printed;
-		try {
-			printed = JSON.stringify(input) ?? String(input);
-		} catch {
-			printed = String(input);
-		}
-		super(`unthrown: no pattern matched the value ${printed}`);
+		super(`unthrown: no pattern matched the value ${printValue(input)}`);
 		this.name = "NonExhaustiveError";
 		this.input = input;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 };
 /**
+* Render a rogue value for {@link NonExhaustiveError}'s message — **total**,
+* because the error is constructed inside the throw → defect net and a throw
+* here would replace the diagnostic with an unrelated one (or escape `match`).
+*
+* @remarks
+* Each step can fail for a different input, so each is guarded: `JSON.stringify`
+* RETURNS undefined for a function, a symbol or `undefined` and throws for a
+* bigint or a circular object; `String()` throws for a null-prototype object or
+* a hostile `toString` / `Symbol.toPrimitive`; `Object.prototype.toString`
+* throws only for a Proxy whose `get` trap does. The last resort is a constant.
+*
+* @internal
+*/
+function printValue(input) {
+	try {
+		const json = JSON.stringify(input);
+		if (json !== void 0) return json;
+	} catch {}
+	try {
+		return String(input);
+	} catch {}
+	try {
+		return Object.prototype.toString.call(input);
+	} catch {
+		return "<unprintable value>";
+	}
+}
+/**
 * Is `x` a *plain* object (prototype `Object.prototype` or `null`) — an object
 * literal, the only object shape that acts as a structural pattern?
 *
@@ -123,6 +162,24 @@ Object.freeze(MatcherImpl.prototype);
 * {@link P}).
 *
 * @category Constructors
+*
+* @example
+* ```ts
+* import { match, type Result } from "unthrown";
+*
+* // Matching a whole Result natively — every variant named, `.exhaustive()` last:
+* declare const r: Result<number, "odd" | "negative">;
+* const label = match(r)
+*   .with({ tag: "Ok" }, (ok) => `got ${ok.value}`)
+*   .with({ tag: "Err" }, (err) => `failed: ${err.error}`)
+*   .with({ tag: "Defect" }, () => "bug")
+*   .exhaustive();
+*
+* // Inside a combinator, return the un-terminated builder — it runs `.exhaustive()`:
+* const reason = r.mapErrCases((matcher) =>
+*   matcher.with("odd", () => "not even" as const).with("negative", () => "below zero" as const),
+* ); // Result<number, "not even" | "below zero">
+* ```
 */
 function match(value) {
 	return new MatcherImpl(value);
@@ -156,17 +213,49 @@ const universal = pattern(() => true);
 *   (`.with(P.tag("A"), P.tag("B"), handler)`).
 * - `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
 *   instance type (for union members that are not tagged, e.g. a third-party
-*   error class).
+*   error class). **Exhaustiveness here is structural, the check is not:**
+*   two classes with the same shape (`class A extends Error {}`,
+*   `class B extends Error {}`) are one type to the compiler, so a match
+*   naming only `A` compiles as exhaustive while a `B` fails `instanceof A`
+*   at runtime and becomes a `Defect`. Give each class a distinguishing field
+*   (a `readonly kind = "A"` literal) or use `TaggedError`, and the missing
+*   arm is a compile error again.
 * - `P.when(guard)` — an arbitrary type-guard predicate. Also the way to match
 *   a primitive shape (`P.when((v): v is string => typeof v === "string")`),
 *   and grouping patterns under one handler is what a `.with(a, b, handler)`
 *   arm already does.
 *
 * @category Constructors
+*
+* @example
+* ```ts
+* import { P, TaggedError, type Result } from "unthrown";
+*
+* class NotFound extends TaggedError("NotFound")<{ id: string }> {}
+* class Conflict extends TaggedError("Conflict") {}
+* class VendorTimeout extends Error {
+*   readonly afterMs = 30_000;
+* }
+*
+* declare const r: Result<string, NotFound | Conflict | VendorTimeout | "rate_limited">;
+* const status = r.match({
+*   ok: () => 200,
+*   errCases: (matcher) =>
+*     matcher
+*       .with(P.tag("NotFound"), () => 404) // a TaggedError, narrowed with its payload
+*       .with(P.tag("Conflict"), () => 409)
+*       .with(P.instanceOf(VendorTimeout), (e) => (e.afterMs > 10_000 ? 504 : 503))
+*       .with(
+*         P.when((v): v is "rate_limited" => v === "rate_limited"),
+*         () => 429,
+*       ),
+*   defect: () => 500,
+* });
+* ```
 */
 const P = Object.freeze({
 	_: universal,
-	tag: (value) => ({ _tag: value }),
+	tag: (value) => Object.freeze({ _tag: value }),
 	instanceOf: (cls) => pattern((value) => value instanceof cls),
 	when: (guard) => pattern(guard)
 });
@@ -328,6 +417,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return defectRes(out.cause);
+			if (isThenable(out)) return asyncBranchDefect(out);
 			return errRes(out);
 		} catch (cause) {
 			return defectRes(cause);
@@ -349,6 +439,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return defectRes(out.cause);
+			if (isThenable(out)) return asyncBranchDefect(out);
 			return okRes(out);
 		} catch (cause) {
 			return defectRes(cause);
@@ -518,7 +609,8 @@ function defectRes(cause) {
 * brand the prototype carries — so a `Result` built by **another copy** of
 * unthrown, e.g. the CJS and ESM builds loaded side by side, is still
 * recognised). A look-alike plain object (`{ tag: "Ok" }`) carries neither and
-* is **not** matched. An `AsyncResult` is not a `Result` and returns `false`.
+* is **not** matched; nor is a forgery built on the real prototype whose `tag` or
+* payload is a getter (both must be own data properties). An `AsyncResult` is not a `Result` and returns `false`.
 *
 * @returns `true` when `x` is a `Result` produced by this library.
 *
@@ -545,13 +637,42 @@ function defectRes(cause) {
 * @category Guards
 */
 function isResult(x) {
-	if (x instanceof Res) return true;
 	try {
-		return (typeof x === "object" || typeof x === "function") && x !== null && Reflect.get(x, RESULT_BRAND) === true;
+		return (x instanceof Res || (typeof x === "object" || typeof x === "function") && x !== null && Reflect.get(x, RESULT_BRAND) === true) && hasOwnVariantShape(x);
 	} catch {
 		return false;
 	}
 }
+/** Each variant's payload key. @internal */
+const PAYLOAD_KEY = {
+	Ok: "value",
+	Err: "error",
+	Defect: "cause"
+};
+/**
+* Does `x` carry a variant's shape as own **data** properties — `tag` one of
+* the three variants, plus that variant's payload key?
+*
+* @remarks
+* A brand is not enough: the prototype (and so the brand) is reachable from any
+* genuine `Result`, so `Object.create(protoOf(Ok(1)))` with a throwing `tag` or
+* payload getter passed the guard and then threw — raw out of `all`, or as a
+* rejection out of an `AsyncResult` that must never reject. Every genuine
+* `Result`, from any copy of the library, is a frozen object literal whose `tag`
+* and payload are own data properties, so reading their descriptors (which
+* never runs a getter) accepts all of them and no getter-bearing forgery.
+*
+* @internal
+*/
+function hasOwnVariantShape(x) {
+	const tag = Object.getOwnPropertyDescriptor(x, "tag");
+	if (tag === void 0 || !("value" in tag)) return false;
+	const variant = tag.value;
+	if (variant !== "Ok" && variant !== "Err" && variant !== "Defect") return false;
+	const key = PAYLOAD_KEY[variant];
+	const payload = Object.getOwnPropertyDescriptor(x, key);
+	return payload !== void 0 && "value" in payload;
+}
 /**
 * Reuse a non-matching variant (an `Err` or `Defect`) as a differently-typed
 * `Result`, with no runtime work. Sound because the passed-through variant
@@ -577,9 +698,9 @@ function passThrough(self) {
 * - inside a `try` that routes the throw to a `Defect` (the boundaries in
 *   `interop.ts`, where a hostile value arriving at a triage point *is* an
 *   unmodeled failure and should surface as one); or
-* - through {@link silenceIfThenable}, for a value being **discarded**, where
-*   there is no Defect channel to route to and the only correct answer is to
-*   drop it without throwing.
+* - to classify a value that is then **discarded** (a `Defect` minted, the
+*   value handed to {@link silenceIfThenable}), where the only correct answer
+*   is to drop it without throwing — and without starting a lazy thenable.
 *
 * Calling it bare, outside both, is a bug: the throw escapes into whatever
 * context invoked it.
@@ -590,27 +711,37 @@ function isThenable(x) {
 	return (typeof x === "object" || typeof x === "function") && x !== null && typeof x.then === "function";
 }
 /**
-* Adopt-and-silence a thenable a combinator is about to **discard**.
+* Silence a **genuine `Promise`** a combinator or boundary is about to
+* **discard** — and leave every other thenable untouched.
 *
 * @remarks
 * The observers (`tap`, `tapErrCases`, `tapDefect`, `tapFailure`) throw their
 * callback's return value away, and the `Result`-returning combinators reject a
-* non-`Result` one. Either way, a thenable that slipped past `NotThenable` (a
+* non-`Result` one. Either way, a promise that slipped past `NotThenable` (a
 * cast, a raw-JS caller) is dropped while still in flight — and if it later
 * rejects, nothing is holding it, so the rejection floats unhandled and takes
 * the process down on Node by default. Worse for an observer: its whole job is
 * to make a failure visible, and this is the one path where the failure is
-* invisible.
+* invisible. Attaching a no-op rejection handler costs nothing and changes no
+* outcome.
 *
-* Adopting it costs one microtask and makes the rejection a no-op. The
-* boundaries already do exactly this for a thenable `qualify` and a thenable
-* `fn` (see `interop.ts`); this is the same net on the combinator side.
+* Only a `Promise` **instance** is touched. A promise is already running, so
+* handling its rejection starts nothing; a non-`Promise` thenable may be
+* **lazy** — a `PrismaPromise`, a query builder — whose work begins only when
+* `then` is called. Adopting one (`Promise.resolve(x)` calls `x.then`) would
+* *run* the effect the caller is being told was refused: `fromSafeThrowable(()
+* => prisma.user.deleteMany())` returned a `Defect` and deleted the rows
+* anyway. A lazy thenable that is never started cannot reject, so there is
+* nothing to silence. Callers still *classify* any thenable (a `Defect` where
+* the spec says so) via {@link isThenable}; this only decides what to adopt.
+*
+* Total: a hostile `then` getter or `Symbol.hasInstance` path is swallowed.
 *
 * @internal
 */
 function silenceIfThenable(value) {
 	try {
-		if (isThenable(value)) Promise.resolve(value).then(void 0, () => void 0);
+		if (value instanceof Promise) value.then(void 0, () => void 0);
 	} catch {}
 }
 /**
@@ -628,6 +759,19 @@ function nonResultCallbackDefect(returned) {
 	return defectRes(/* @__PURE__ */ new TypeError("unthrown: a combinator callback returned a non-Result value"));
 }
 /**
+* The Defect minted when a non-awaiting error transformer (`mapErrCases` /
+* `recoverErrCases`) gets a thenable branch output past the compile-time ban
+* (a cast, an untyped caller): never `Err(<Promise>)` / `Ok(<Promise>)` — a
+* Promise in the channel is un-triaged — and a genuine Promise is silenced so
+* its rejection cannot float. The sibling of the aggregates' async-`merge` net.
+*
+* @internal
+*/
+function asyncBranchDefect(out) {
+	silenceIfThenable(out);
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: mapErrCases/recoverErrCases branches must be SYNCHRONOUS, but one returned a thenable — lift async work with fromPromise and use flatMapErrCases"));
+}
+/**
 * Drive an error-combinator callback: build `match(error)`, hand it (plus the
 * injected `defect`) to the callback, and `.run()` the returned exhaustive
 * builder to its output. `.run()` executes `.exhaustive()` — type-forced
@@ -676,10 +820,23 @@ function observerThrowToDefect(thrown, original) {
 * @internal
 */
 function scopeOf(value) {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("bind/let requires an object scope — start a do-chain with Do()");
+	if (typeof value !== "object" || value === null || !isPlainScope(value)) throw new TypeError("bind/let requires a plain object scope — start a do-chain with Do()");
 	return value;
 }
 /**
+* A *plain* object: its prototype is `null` or an `Object.prototype` (any
+* realm's — recognised by having no prototype of its own). The spread that
+* merges a `bind`/`let` key copies only own enumerable data, so a class
+* instance's getters and prototype methods — and an array's identity — would
+* silently vanish while the type still claimed them.
+*
+* @internal
+*/
+function isPlainScope(value) {
+	const proto = Object.getPrototypeOf(value);
+	return proto === null || Object.getPrototypeOf(proto) === null;
+}
+/**
 * The sole runtime implementation of {@link AsyncResult}: wraps a
 * `Promise<Result>` constructed never to reject. Operates on the public `Result`
 * union (via `tag`), never on `Res` internals. Never re-exported from `index.ts`.
@@ -769,7 +926,7 @@ var AsyncRes = class AsyncRes {
 	ensure(predicate, onFail) {
 		return this.#lift((r) => r.ensure(predicate, onFail));
 	}
-	mapErrCases(f) {
+	mapErrCases(f, ..._guard) {
 		return this.#lift((r) => r.mapErrCases(f));
 	}
 	flatMapErrCases(f) {
@@ -786,7 +943,7 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	recoverErrCases(f) {
+	recoverErrCases(f, ..._guard) {
 		return this.#lift((r) => r.recoverErrCases(f));
 	}
 	tapErrCases(f) {
@@ -1124,12 +1281,17 @@ function fromNullable(value, onAbsent) {
 function fromThrowable(fn, qualify) {
 	const triage = qualify;
 	return (...args) => {
+		let value;
 		try {
-			const value = fn(...args);
-			return isThenable(value) ? thenableReturnDefect(value, SYNC_FN_THENABLE) : Ok(value);
+			value = fn(...args);
 		} catch (cause) {
 			return qualifyToResult(cause, triage);
 		}
+		try {
+			return isThenable(value) ? thenableReturnDefect(value, SYNC_FN_THENABLE) : Ok(value);
+		} catch (cause) {
+			return defectRes(cause);
+		}
 	};
 }
 /**
@@ -1311,7 +1473,7 @@ function fromExecutor(executor) {
 	};
 	try {
 		const returned = executor(settle, defect);
-		if (isThenable(returned)) Promise.resolve(returned).then(void 0, (cause) => settle(defect(cause)));
+		if (returned instanceof Promise) returned.then(void 0, (cause) => settle(defect(cause)));
 	} catch (cause) {
 		settle(defect(cause));
 	}
@@ -1322,7 +1484,7 @@ function qualifyToResult(cause, qualify) {
 		const q = qualify(cause, defect);
 		if (isDefectMarker(q)) return defectRes(q.cause);
 		if (isThenable(q)) {
-			Promise.resolve(q).then(void 0, () => void 0);
+			silenceIfThenable(q);
 			return defectRes(/* @__PURE__ */ new TypeError("unthrown: qualify must be synchronous — it returned a thenable; triage the cause without awaiting"));
 		}
 		return errRes(q);
@@ -1363,7 +1525,7 @@ const MERGE_THENABLE = "unthrown: an accumulating aggregate's `merge` must be SY
 * 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
+* costs nothing: a Defect, plus a no-op rejection handler so an orphaned Promise
 * cannot float.
 *
 * @internal
@@ -1373,6 +1535,38 @@ function thenableReturnDefect(value, message) {
 	return defectRes(new TypeError(message));
 }
 /**
+* A record's own **enumerable** keys — strings and symbols — with their values.
+*
+* @remarks
+* `Object.keys` / `Object.values` skip symbol keys, so a symbol-keyed `Err`
+* silently vanished from the fold while the types (`keyof R` includes it)
+* promised otherwise. `Reflect.ownKeys` filtered to the enumerable ones is
+* `Object.keys` plus symbols, in the same order (strings first, then symbols).
+* May throw on an out-of-contract container (`null`, a throwing getter) — every
+* caller routes that to a `Defect`.
+*
+* @internal
+*/
+function ownEntries(record) {
+	const keys = Reflect.ownKeys(record).filter((key) => Object.prototype.propertyIsEnumerable.call(record, key));
+	return [keys, keys.map((key) => record[key])];
+}
+/**
+* Build an async aggregate's settled promise, turning a synchronous throw while
+* reading an out-of-contract container (`allAsync(undefined)`, a throwing
+* getter) into a `Defect` — the returned `AsyncResult` still never rejects and
+* the call never throws.
+*
+* @internal
+*/
+function settleOrDefect(build) {
+	try {
+		return new AsyncRes(build());
+	} catch (cause) {
+		return new AsyncRes(Promise.resolve(defectRes(cause)));
+	}
+}
+/**
 * Fold an array of settled `Result`s: first `Err` wins, any `Defect` dominates,
 * else `Ok` of the values array.
 *
@@ -1394,31 +1588,34 @@ 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 = [];
-	const errors = [];
-	for (const [i, r] of results.entries()) {
-		if (!isResult(r)) {
-			firstDefect ??= nonResultDefect();
-			break;
+	try {
+		let firstErr;
+		let firstDefect;
+		const values = [];
+		const errors = [];
+		for (const [i, r] of results.entries()) {
+			if (!isResult(r)) {
+				firstDefect ??= nonResultDefect();
+				break;
+			}
+			if (r.tag === "Defect") {
+				firstDefect ??= r;
+				break;
+			} else if (r.tag === "Err") {
+				if (merge) errors.push([i, r.error]);
+				else firstErr ??= r;
+			} else values.push(r.value);
 		}
-		if (r.tag === "Defect") {
-			firstDefect ??= r;
-			break;
-		} else if (r.tag === "Err") if (merge) errors.push([i, r.error]);
-		else firstErr ??= r;
-		else values.push(r.value);
-	}
-	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);
+		if (firstDefect) return firstDefect;
+		if (merge && errors.length > 0) {
+			const merged = merge(errors);
+			if (isThenable(merged)) return thenableReturnDefect(merged, MERGE_THENABLE);
+			return Err(merged);
+		}
+		return firstErr ?? Ok(values);
 	} catch (cause) {
 		return defectRes(cause);
 	}
-	return firstErr ?? Ok(values);
 }
 /**
 * Fold a record of settled `Result`s with the same rules, else `Ok` of the
@@ -1437,8 +1634,14 @@ function foldArray(results, merge) {
 * @internal
 */
 function foldRecord(results, merge) {
-	const keys = Object.keys(results);
-	return foldArray(Object.values(results), merge && ((errors) => merge(nameErrors(errors, keys)))).map((values) => Object.fromEntries(keys.map((key, i) => [key, values[i]])));
+	let keys;
+	let values;
+	try {
+		[keys, values] = ownEntries(results);
+	} catch (cause) {
+		return defectRes(cause);
+	}
+	return foldArray(values, 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) {
@@ -1524,7 +1727,7 @@ function allFromDict(results) {
 * ```
 */
 function allAsync(results) {
-	return new AsyncRes(settleAll(results).then((resolved) => foldArray(resolved)));
+	return settleOrDefect(() => settleAll(results).then((resolved) => foldArray(resolved)));
 }
 /**
 * The asynchronous counterpart of {@link allFromDict}: combine a record of
@@ -1549,8 +1752,10 @@ function allAsync(results) {
 * ```
 */
 function allFromDictAsync(results) {
-	const keys = Object.keys(results);
-	return new AsyncRes(settleAll(Object.values(results)).then((resolved) => foldRecord(Object.fromEntries(keys.map((key, i) => [key, resolved[i]])))));
+	return settleOrDefect(() => {
+		const [keys, values] = ownEntries(results);
+		return settleAll(values).then((resolved) => foldRecord(Object.fromEntries(keys.map((key, i) => [key, resolved[i]]))));
+	});
 }
 /**
 * Collect a tuple/array of {@link Result}s, **accumulating every** `Err` and
@@ -1617,7 +1822,8 @@ function validateAll(results, merge) {
 * 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.
+* one error type distinguishable. Entries come in key order — `Object.keys`
+* order, then enumerable symbol keys (a symbol key is folded like any other).
 *
 * Every other rule matches {@link validateAll}: any `Defect` dominates and
 * discards the accumulated errors, a throw in `merge` becomes a `Defect`, and
@@ -1676,7 +1882,7 @@ function validateAllFromDict(results, merge) {
 * ```
 */
 function validateAllAsync(results, merge) {
-	return new AsyncRes(settleAll(results).then((resolved) => foldArray(resolved, (errors) => merge(stripIndices(errors)))));
+	return settleOrDefect(() => settleAll(results).then((resolved) => foldArray(resolved, (errors) => merge(stripIndices(errors)))));
 }
 /**
 * The asynchronous counterpart of {@link validateAllFromDict}: collect a record
@@ -1705,8 +1911,10 @@ function validateAllAsync(results, merge) {
 * ```
 */
 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))));
+	return settleOrDefect(() => {
+		const [keys, values] = ownEntries(results);
+		return settleAll(values).then((resolved) => foldRecord(Object.fromEntries(keys.map((key, i) => [key, resolved[i]])), (entries) => merge(entries)));
+	});
 }
 //#endregion
 //#region src/facade.ts