unthrown 4.3.0 → 5.0.0-beta.1

package/dist/index.cjs

@@ -1,4 +1,35 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let ts_pattern = require("ts-pattern");
+//#region src/defect.ts
+const DEFECT = Symbol("unthrown/Defect");
+/**
+* Wrap a cause as a `Defect` marker — the value returned from a `qualify`
+* function when a failure is **not** a modeled domain error. The boundary
+* (`fromPromise` / `fromThrowable`) passes this in as `qualify`'s second
+* argument, so domain code never imports it.
+*
+* @param cause - the original thrown/rejected value.
+* @returns an opaque Defect marker carrying `cause`.
+*
+* @internal
+*/
+function defect(cause) {
+	return Object.freeze({
+		[DEFECT]: true,
+		cause
+	});
+}
+/**
+* Internal guard for the qualify-time marker. Distinct from the public
+* {@link isDefect} state guard — this one narrows the `E | Defect` union a
+* `qualify` function returns, not a `Result`.
+*
+* @internal
+*/
+function isDefectMarker(x) {
+	return typeof x === "object" && x !== null && x[DEFECT] === true;
+}
+//#endregion
 //#region src/core.ts
 /**
 * Thrown by a {@link Result}'s `get` / `getErr` when the assertion is
@@ -6,12 +37,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * `Ok`.
 *
 * @remarks
-* The offending value is exposed two ways: the typed {@link UnwrapError.error}
+* The offending value is exposed two ways: the typed {@link GetError.error}
 * property for programmatic access, and the standard `Error.cause` for the
 * runtime and devtools to chain — when `E` is an `Error` (e.g. a `TaggedError`)
 * its original stack is printed under "caused by".
 *
-* A `Defect` is never wrapped in an `UnwrapError`: its original cause is
+* A `Defect` is never wrapped in a `GetError`: its original cause is
 * re-thrown (with its original stack) instead.
 *
 * `get()` and `getErr()` are type-gated (`this: Result<T, never>` /
@@ -19,19 +50,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * 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.
+* @typeParam E - the type of the {@link GetError.error} it carries.
 *
 * @category Errors
 */
-var UnwrapError = class extends Error {
+var GetError = class extends Error {
 	/**
 	* The offending value: the `Err` error for `get()`, or the `Ok` value for
 	* `getErr()`.
 	*/
 	error;
 	constructor(error) {
-		super("unthrown: called unwrap on a non-matching Result", { cause: error });
-		this.name = "UnwrapError";
+		super("unthrown: get() / getErr() called on a non-matching Result variant", { cause: error });
+		this.name = "GetError";
 		this.error = error;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
@@ -55,7 +86,8 @@ var Res = class {
 	flatMap(f) {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
-			return f(this.value);
+			const r = f(this.value);
+			return isResult(r) ? r : nonResultCallbackDefect();
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -73,6 +105,7 @@ var Res = class {
 		if (this.tag !== "Ok") return this;
 		try {
 			const r = f(this.value);
+			if (!isResult(r)) return nonResultCallbackDefect();
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return defectRes(cause);
@@ -82,6 +115,7 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			const r = f(this.value);
+			if (!isResult(r)) return nonResultCallbackDefect();
 			if (r.tag !== "Ok") return passThrough(r);
 			return okRes({
 				...scopeOf(this.value),
@@ -110,10 +144,20 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		return okRes(void 0);
 	}
+	ensure(predicate, onFail) {
+		if (this.tag !== "Ok") return passThrough(this);
+		try {
+			return predicate(this.value) ? this : errRes(onFail(this.value));
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
 	mapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return errRes(f(this.error));
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			return errRes(out);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -121,31 +165,28 @@ var Res = class {
 	flatMapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return f(this.error);
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			if (!isResult(out)) return nonResultCallbackDefect();
+			return out;
 		} catch (cause) {
 			return defectRes(cause);
 		}
 	}
-	/** @deprecated Use {@link Res.flatMapErr}. */
-	orElse(f) {
-		return this.flatMapErr(f);
-	}
 	recoverErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return okRes(f(this.error));
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			return okRes(out);
 		} catch (cause) {
 			return defectRes(cause);
 		}
 	}
-	/** @deprecated Use {@link Res.recoverErr}. */
-	recover(f) {
-		return this.recoverErr(f);
-	}
 	tapErr(f) {
 		if (this.tag !== "Err") return this;
 		try {
-			f(this.error);
+			runMatch(f, this.error);
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -154,7 +195,8 @@ var Res = class {
 	flatTapErr(f) {
 		if (this.tag !== "Err") return this;
 		try {
-			const r = f(this.error);
+			const r = runMatch(f, this.error);
+			if (!isResult(r)) return nonResultCallbackDefect();
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -163,7 +205,8 @@ var Res = class {
 	recoverDefect(f) {
 		if (this.tag !== "Defect") return this;
 		try {
-			return f(this.cause);
+			const r = f(this.cause);
+			return isResult(r) ? r : nonResultCallbackDefect();
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -189,50 +232,34 @@ var Res = class {
 	match(cases) {
 		switch (this.tag) {
 			case "Ok": return cases.ok(this.value);
-			case "Err": return cases.err(this.error);
+			case "Err": return cases.err((0, ts_pattern.match)(this.error)).run();
 			case "Defect": return cases.defect(this.cause);
 		}
 	}
 	get() {
 		switch (this.tag) {
 			case "Ok": return this.value;
-			case "Err": throw new UnwrapError(this.error);
+			case "Err": throw new GetError(this.error);
 			case "Defect": throw this.cause;
 		}
 	}
-	/** @deprecated Use {@link Res.get}. */
-	unwrap() {
-		return this.get();
-	}
 	getErr() {
 		switch (this.tag) {
 			case "Err": return this.error;
-			case "Ok": throw new UnwrapError(this.value);
+			case "Ok": throw new GetError(this.value);
 			case "Defect": throw this.cause;
 		}
 	}
-	/** @deprecated Use {@link Res.getErr}. */
-	unwrapErr() {
-		return this.getErr();
-	}
 	getOr(fallback) {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
 		return fallback;
 	}
-	/** @deprecated Use {@link Res.getOr}. */
-	unwrapOr(fallback) {
-		return this.getOr(fallback);
-	}
 	getOrElse(f) {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
 		return f(this.error);
 	}
-	/** @deprecated Use {@link Res.getOrElse}. */
-	unwrapOrElse(f) {
-		return this.getOrElse(f);
-	}
 	getOrNull() {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
@@ -260,7 +287,19 @@ var Res = class {
 		return new AsyncRes(Promise.resolve(this));
 	}
 };
+/**
+* Cross-copy brand: `Symbol.for` yields the same symbol in every copy of the
+* library (the dual CJS/ESM build, a duplicated install, another realm), so
+* {@link isResult} can recognise a `Result` built by another copy whose `Res`
+* class fails the `instanceof` check. Defined non-enumerably on the prototype,
+* before it is frozen.
+*
+* @internal
+*/
+const RESULT_BRAND = Symbol.for("unthrown.Result");
 const RESULT_PROTO = Res.prototype;
+Object.defineProperty(RESULT_PROTO, RESULT_BRAND, { value: true });
+Object.freeze(RESULT_PROTO);
 /**
 * Construct an `Ok` result — a plain object on the {@link Res} prototype.
 *
@@ -300,9 +339,12 @@ function defectRes(cause) {
 * @remarks
 * Unlike {@link isOk} / {@link isErr} / {@link isDefect}, which narrow a value
 * already known to be a `Result`, this narrows from `unknown` — useful at an
-* untyped boundary. It checks the value carries the `Result` prototype, so a
-* look-alike plain object (`{ tag: "Ok" }`) is **not** matched. An `AsyncResult`
-* is not a `Result` and returns `false`.
+* untyped boundary. It checks the value carries the `Result` prototype
+* (`instanceof` first, falling back to the `Symbol.for("unthrown.Result")`
+* 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`.
 *
 * @returns `true` when `x` is a `Result` produced by this library.
 *
@@ -321,7 +363,12 @@ function defectRes(cause) {
 * @category Guards
 */
 function isResult(x) {
-	return x instanceof Res;
+	if (x instanceof Res) return true;
+	try {
+		return (typeof x === "object" || typeof x === "function") && x !== null && Reflect.get(x, RESULT_BRAND) === true;
+	} catch {
+		return false;
+	}
 }
 /**
 * Reuse a non-matching variant (an `Err` or `Defect`) as a differently-typed
@@ -337,6 +384,32 @@ function passThrough(self) {
 	return self;
 }
 /**
+* The Defect minted when a callback constrained to return a `Result` returns
+* something else — reachable only from untyped/cast callers (in typed code the
+* constraint is a compile error). The combinator-side sibling of the
+* aggregates' non-`Result`-element guard: surface the out-of-contract value as
+* a `Defect` here rather than letting a poison value throw a raw `TypeError`
+* further down the pipeline.
+*
+* @internal
+*/
+function nonResultCallbackDefect() {
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: a combinator callback returned a non-Result value"));
+}
+/**
+* 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
+* exhaustive, so it always matches for well-typed callers; a value that slips
+* through the types (a widened cast, a JS caller) throws `NonExhaustiveError`,
+* which the caller's `try/catch` turns into a `Defect` — an unmodeled failure.
+*
+* @internal
+*/
+function runMatch(f, error) {
+	return f((0, ts_pattern.match)(error), defect).run();
+}
+/**
 * 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
@@ -378,15 +451,15 @@ function scopeOf(value) {
 * @internal
 */
 var AsyncRes = class AsyncRes {
-	promise;
+	#promise;
 	constructor(promise) {
-		this.promise = promise;
+		this.#promise = promise;
 	}
 	then(onfulfilled, onrejected) {
-		return this.promise.then(onfulfilled, onrejected);
+		return this.#promise.then(onfulfilled, onrejected);
 	}
 	map(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				return okRes(f(r.value));
@@ -396,17 +469,18 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	flatMap(f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
-				return await f(r.value);
+				const inner = await f(r.value);
+				return isResult(inner) ? inner : nonResultCallbackDefect();
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
 	tap(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Ok") return r;
 			try {
 				f(r.value);
@@ -417,10 +491,11 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	flatTap(f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
+				if (!isResult(inner)) return nonResultCallbackDefect();
 				return inner.tag === "Ok" ? r : passThrough(inner);
 			} catch (cause) {
 				return defectRes(cause);
@@ -428,10 +503,11 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	bind(name, f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
+				if (!isResult(inner)) return nonResultCallbackDefect();
 				if (inner.tag !== "Ok") return passThrough(inner);
 				return okRes({
 					...scopeOf(r.value),
@@ -443,7 +519,7 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	let(name, f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				return okRes({
@@ -456,54 +532,64 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	as(value) {
-		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(value) : passThrough(r)));
+		return new AsyncRes(this.#promise.then((r) => r.tag === "Ok" ? okRes(value) : passThrough(r)));
 	}
 	discard() {
-		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(void 0) : passThrough(r)));
+		return new AsyncRes(this.#promise.then((r) => r.tag === "Ok" ? okRes(void 0) : passThrough(r)));
+	}
+	ensure(predicate, onFail) {
+		return new AsyncRes(this.#promise.then((r) => {
+			if (r.tag !== "Ok") return passThrough(r);
+			try {
+				return predicate(r.value) ? r : errRes(onFail(r.value));
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
 	}
 	mapErr(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return errRes(f(r.error));
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				return errRes(out);
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
 	flatMapErr(f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return await f(r.error);
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				const inner = await out;
+				if (!isResult(inner)) return nonResultCallbackDefect();
+				return inner;
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
-	/** @deprecated Use {@link AsyncRes.flatMapErr}. */
-	orElse(f) {
-		return this.flatMapErr(f);
-	}
 	recoverErr(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return okRes(f(r.error));
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				return okRes(out);
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
-	/** @deprecated Use {@link AsyncRes.recoverErr}. */
-	recover(f) {
-		return this.recoverErr(f);
-	}
 	tapErr(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return r;
 			try {
-				f(r.error);
+				runMatch(f, r.error);
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -511,10 +597,11 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	flatTapErr(f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				const inner = await f(r.error);
+				const inner = await runMatch(f, r.error);
+				if (!isResult(inner)) return nonResultCallbackDefect();
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -522,17 +609,18 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	recoverDefect(f) {
-		return new AsyncRes(this.promise.then(async (r) => {
+		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Defect") return r;
 			try {
-				return await f(r.cause);
+				const inner = await f(r.cause);
+				return isResult(inner) ? inner : nonResultCallbackDefect();
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
 	tapDefect(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Defect") return r;
 			try {
 				f(r.cause);
@@ -543,7 +631,7 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	tapFailure(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag === "Ok") return r;
 			try {
 				f(r);
@@ -554,46 +642,31 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	match(cases) {
-		return this.promise.then((r) => r.match(cases));
+		return this.#promise.then((r) => r.match(cases));
 	}
 	get() {
-		return this.promise.then((r) => r.get());
-	}
-	/** @deprecated Use {@link AsyncRes.get}. */
-	unwrap() {
-		return this.get();
+		return this.#promise.then((r) => r.get());
 	}
 	getErr() {
-		return this.promise.then((r) => r.getErr());
-	}
-	/** @deprecated Use {@link AsyncRes.getErr}. */
-	unwrapErr() {
-		return this.getErr();
+		return this.#promise.then((r) => r.getErr());
 	}
 	getOr(fallback) {
-		return this.promise.then((r) => r.getOr(fallback));
-	}
-	/** @deprecated Use {@link AsyncRes.getOr}. */
-	unwrapOr(fallback) {
-		return this.getOr(fallback);
+		return this.#promise.then((r) => r.getOr(fallback));
 	}
 	getOrElse(f) {
-		return this.promise.then((r) => r.getOrElse(f));
-	}
-	/** @deprecated Use {@link AsyncRes.getOrElse}. */
-	unwrapOrElse(f) {
-		return this.getOrElse(f);
+		return this.#promise.then((r) => r.getOrElse(f));
 	}
 	getOrNull() {
-		return this.promise.then((r) => r.getOrNull());
+		return this.#promise.then((r) => r.getOrNull());
 	}
 	getOrUndefined() {
-		return this.promise.then((r) => r.getOrUndefined());
+		return this.#promise.then((r) => r.getOrUndefined());
 	}
 	getOrThrow() {
-		return this.promise.then((r) => r.getOrThrow());
+		return this.#promise.then((r) => r.getOrThrow());
 	}
 };
+Object.freeze(AsyncRes.prototype);
 //#endregion
 //#region src/constructors.ts
 function Ok(value) {
@@ -759,35 +832,32 @@ function isDefect(r) {
 function Do() {
 	return Ok({});
 }
-//#endregion
-//#region src/defect.ts
-const DEFECT = Symbol("unthrown/Defect");
 /**
-* Wrap a cause as a `Defect` marker — the value returned from a `qualify`
-* function when a failure is **not** a modeled domain error. The boundary
-* (`fromPromise` / `fromThrowable`) passes this in as `qualify`'s second
-* argument, so domain code never imports it.
+* Start an **asynchronous** do-notation chain with an empty object scope — the
+* pre-lifted form of {@link Do}, sparing you `Do().toAsync()`.
 *
-* @param cause - the original thrown/rejected value.
-* @returns an opaque Defect marker carrying `cause`.
+* @remarks
+* From here a `bind` may return a `Result` **or** an `AsyncResult`; the scope
+* accumulates exactly as in a sync {@link Do} chain, and a throw in any step
+* becomes a `Defect`. Named with the `Async` suffix the async free functions
+* carry (`OkAsync`, `allAsync`); the {@link AsyncResult} companion aliases it as
+* `AsyncResult.Do` (the namespace already says "async", so the suffix drops).
 *
-* @internal
-*/
-function defect(cause) {
-	return {
-		[DEFECT]: true,
-		cause
-	};
-}
-/**
-* Internal guard for the qualify-time marker. Distinct from the public
-* {@link isDefect} state guard — this one narrows the `E | Defect` union a
-* `qualify` function returns, not a `Result`.
+* @example
+* ```ts
+* import { DoAsync, Ok } from "unthrown";
 *
-* @internal
+* const result = await DoAsync()
+*   .bind("user", () => findUser(id)) // AsyncResult<User, NotFound>
+*   .bind("plan", ({ user }) => Ok(user.plan)) // a sync Result is accepted too
+*   .let("label", ({ user, plan }) => `${user.name} on ${plan}`);
+* // Result<{ user: User; plan: Plan; label: string }, NotFound>
+* ```
+*
+* @category Do-notation
 */
-function isDefectMarker(x) {
-	return typeof x === "object" && x !== null && x[DEFECT] === true;
+function DoAsync() {
+	return Do().toAsync();
 }
 //#endregion
 //#region src/interop.ts
@@ -827,7 +897,10 @@ function fromNullable(value, onAbsent) {
 * `qualify` **must** triage every thrown cause into a modeled error `E` or a
 * `Defect` (via the injected `defect` helper, its second argument) — there is no
 * path that leaves `unknown` in `E`. A throw inside `qualify` itself is treated
-* as a `Defect`.
+* as a `Defect`. `qualify` is **synchronous**: an `async` qualify is rejected at
+* compile time ({@link NotThenable}) — its `Promise` would land in `E` un-triaged
+* — and a thenable slipped past the types at runtime becomes a `Defect` (never
+* an `Err(Promise)`), its orphaned rejection silenced.
 *
 * The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
 * `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
@@ -917,7 +990,10 @@ function fromSafeThrowable(fn) {
 * `qualify` **must** map each rejection cause into a modeled error `E` or a
 * `Defect` (via the injected `defect` helper, its second argument). The returned
 * `AsyncResult`'s internal promise never rejects; `await`-ing it always yields a
-* `Result`. A throw inside `qualify` is itself a `Defect`.
+* `Result`. A throw inside `qualify` is itself a `Defect`. `qualify` is
+* **synchronous**: an `async` qualify is rejected at compile time
+* ({@link NotThenable}), and a thenable slipped past the types at runtime
+* becomes a `Defect` (never an `Err(Promise)`), its orphaned rejection silenced.
 *
 * The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
 * `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
@@ -980,26 +1056,50 @@ function fromSafePromise(promise) {
 function qualifyToResult(cause, qualify) {
 	try {
 		const q = qualify(cause, defect);
-		return isDefectMarker(q) ? defectRes(q.cause) : errRes(q);
+		if (isDefectMarker(q)) return defectRes(q.cause);
+		if (isThenable(q)) {
+			Promise.resolve(q).then(void 0, () => void 0);
+			return defectRes(/* @__PURE__ */ new TypeError("unthrown: qualify must be synchronous — it returned a thenable; triage the cause without awaiting"));
+		}
+		return errRes(q);
 	} catch (qErr) {
 		return defectRes(qErr);
 	}
 }
 /**
+* Runtime thenable probe for the belt-and-braces guard above. Called inside the
+* caller's `try`, so even a hostile `.then` getter lands on the Defect path.
+*
+* @internal
+*/
+function isThenable(x) {
+	return (typeof x === "object" || typeof x === "function") && x !== null && typeof x.then === "function";
+}
+/**
 * Fold an array of settled `Result`s: first `Err` wins, any `Defect` dominates,
 * else `Ok` of the values array.
 *
 * @internal
 */
+/** The Defect minted for an out-of-contract non-`Result` element in an aggregate. */
+function nonResultDefect() {
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: aggregate received a non-Result element"));
+}
 function foldArray(results) {
 	let firstErr;
 	let firstDefect;
 	const values = [];
-	for (const r of results) if (r.tag === "Defect") {
-		firstDefect ??= r;
-		break;
-	} else if (r.tag === "Err") firstErr ??= r;
-	else values.push(r.value);
+	for (const r of results) {
+		if (!isResult(r)) {
+			firstDefect ??= nonResultDefect();
+			break;
+		}
+		if (r.tag === "Defect") {
+			firstDefect ??= r;
+			break;
+		} else if (r.tag === "Err") firstErr ??= r;
+		else values.push(r.value);
+	}
 	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
@@ -1013,16 +1113,22 @@ function foldRecord(results) {
 	let firstErr;
 	let firstDefect;
 	const values = {};
-	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,
-		writable: true,
-		configurable: true
-	});
+	for (const [key, r] of Object.entries(results)) {
+		if (!isResult(r)) {
+			firstDefect ??= nonResultDefect();
+			break;
+		}
+		if (r.tag === "Defect") {
+			firstDefect ??= r;
+			break;
+		} else if (r.tag === "Err") firstErr ??= r;
+		else Object.defineProperty(values, key, {
+			value: r.value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
 	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
@@ -1094,7 +1200,7 @@ function allFromDict(results) {
 * ```
 */
 function allAsync(results) {
-	return new AsyncRes(Promise.all(results).then((resolved) => foldArray(resolved)));
+	return new AsyncRes(Promise.all(results.map((r) => Promise.resolve(r).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => foldArray(resolved)));
 }
 /**
 * The asynchronous counterpart of {@link allFromDict}: combine a record of
@@ -1119,7 +1225,7 @@ function allAsync(results) {
 */
 function allFromDictAsync(results) {
 	const entries = Object.entries(results);
-	return new AsyncRes(Promise.all(entries.map(([, ar]) => ar)).then((resolved) => {
+	return new AsyncRes(Promise.all(entries.map(([, ar]) => Promise.resolve(ar).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => {
 		const byKey = Object.create(null);
 		entries.forEach(([key], i) => {
 			byKey[key] = resolved[i];
@@ -1172,8 +1278,9 @@ const Result = {
 /**
 * Companion object grouping the **`AsyncResult`-producing** entry points under
 * the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
-* {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
-* {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
+* {@link AsyncResult.Do}, {@link AsyncResult.fromPromise},
+* {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
+* {@link AsyncResult.allFromDict}.
 *
 * @remarks
 * The async sibling of {@link Result}. Statics are grouped by what they
@@ -1181,7 +1288,8 @@ const Result = {
 * and the async aggregates sit here rather than on {@link Result}; the namespace
 * already conveys "async", so the members drop the `Async` suffix their free
 * functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
-* `ErrAsync`; `AsyncResult.all` is `allAsync`; `AsyncResult.allFromDict` is
+* `ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
+* `AsyncResult.allFromDict` is
 * `allFromDictAsync`). Like {@link Result}, the free functions remain the
 * primary, tree-shakeable API; the value `AsyncResult` and the type
 * {@link AsyncResult} share one name.
@@ -1198,6 +1306,7 @@ const Result = {
 const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
+	Do: DoAsync,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1221,10 +1330,16 @@ const AsyncResult = {
 * `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
+* shadow `Error.name`. `stack` is reserved the same way — it is `Error`'s
+* trace, and even an untyped payload `stack` cannot clobber the real one.
+* `cause` is deliberately **not** reserved: `Error.cause` is typed `unknown`,
+* so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
+* *narrowing* structured field.
+*
+* `_tag` is the discriminant matched by {@link tag} in the error combinators
+* (`result.mapErr((matcher) => matcher.with(tag("NotFound"), …))`) and in
+* `match`; `Error.name` is the human-facing label in stack traces and logs. By
+* default they coincide, but
 * they can be **decoupled** with `options.name` — so a tag can be namespaced for
 * collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
 * string leaking into `Error.name`:
@@ -1264,7 +1379,17 @@ function TaggedError(tag, options) {
 		_tag;
 		constructor(props) {
 			super();
-			if (props) Object.assign(this, props);
+			if (props) {
+				const stack = this.stack;
+				Object.assign(this, props);
+				delete this.stack;
+				if (stack !== void 0) Object.defineProperty(this, "stack", {
+					value: stack,
+					writable: true,
+					enumerable: false,
+					configurable: true
+				});
+			}
 			this._tag = tag;
 			this.name = displayName;
 			delete this.message;
@@ -1273,28 +1398,46 @@ function TaggedError(tag, options) {
 	}
 	return TaggedErrorBase;
 }
-function matchTags(result, handlers) {
-	const onErr = (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,
-		err: onErr,
-		defect: handlers.Defect
-	});
+/**
+* A `ts-pattern` pattern matching any value whose `_tag` equals `value` — a
+* {@link TaggedError}, or any discriminated member. Equivalent to the object
+* pattern `{ _tag: value }`, but reads better inside an error-matching
+* combinator and narrows to the matching variant, payload included.
+*
+* @typeParam Tag - the string literal tag to match.
+* @param value - the `_tag` to match.
+*
+* @category Tagged errors
+*
+* @example
+* ```ts
+* result.mapErr((matcher) =>
+*   matcher
+*     .with(tag("NotFound"), () => new NotFoundException())
+*     .with(tag("Conflict"), (e) => new ConflictException(e.key)),
+* );
+* ```
+*/
+function tag(value) {
+	return { _tag: value };
 }
 //#endregion
 exports.AsyncResult = AsyncResult;
 exports.Do = Do;
+exports.DoAsync = DoAsync;
 exports.Err = Err;
 exports.ErrAsync = ErrAsync;
+exports.GetError = GetError;
 exports.Ok = Ok;
 exports.OkAsync = OkAsync;
+Object.defineProperty(exports, "P", {
+	enumerable: true,
+	get: function() {
+		return ts_pattern.P;
+	}
+});
 exports.Result = Result;
 exports.TaggedError = TaggedError;
-exports.UnwrapError = UnwrapError;
 exports.all = all;
 exports.allAsync = allAsync;
 exports.allFromDict = allFromDict;
@@ -1308,4 +1451,10 @@ exports.isDefect = isDefect;
 exports.isErr = isErr;
 exports.isOk = isOk;
 exports.isResult = isResult;
-exports.matchTags = matchTags;
+Object.defineProperty(exports, "match", {
+	enumerable: true,
+	get: function() {
+		return ts_pattern.match;
+	}
+});
+exports.tag = tag;