unthrown 5.0.0-beta.0 → 5.0.0-beta.2

package/dist/index.cjs

@@ -14,10 +14,10 @@ const DEFECT = Symbol("unthrown/Defect");
 * @internal
 */
 function defect(cause) {
-	return {
+	return Object.freeze({
 		[DEFECT]: true,
 		cause
-	};
+	});
 }
 /**
 * Internal guard for the qualify-time marker. Distinct from the public
@@ -86,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);
 		}
@@ -104,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);
@@ -113,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),
@@ -141,6 +144,14 @@ 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 {
@@ -156,6 +167,7 @@ var Res = class {
 		try {
 			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);
@@ -184,6 +196,7 @@ var Res = class {
 		if (this.tag !== "Err") return this;
 		try {
 			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);
@@ -192,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);
 		}
@@ -273,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.
 *
@@ -313,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.
 *
@@ -334,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
@@ -350,6 +384,19 @@ 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
@@ -404,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));
@@ -422,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);
@@ -443,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);
@@ -454,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),
@@ -469,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({
@@ -482,13 +532,23 @@ 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 {
 				const out = runMatch(f, r.error);
@@ -500,19 +560,21 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	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 {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return defectRes(out.cause);
-				return await out;
+				const inner = await out;
+				if (!isResult(inner)) return nonResultCallbackDefect();
+				return inner;
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
 	recoverErr(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
 				const out = runMatch(f, r.error);
@@ -524,7 +586,7 @@ var AsyncRes = class AsyncRes {
 		}));
 	}
 	tapErr(f) {
-		return new AsyncRes(this.promise.then((r) => {
+		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return r;
 			try {
 				runMatch(f, r.error);
@@ -535,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 runMatch(f, r.error);
+				if (!isResult(inner)) return nonResultCallbackDefect();
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -546,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);
@@ -567,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);
@@ -578,30 +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());
+		return this.#promise.then((r) => r.get());
 	}
 	getErr() {
-		return this.promise.then((r) => r.getErr());
+		return this.#promise.then((r) => r.getErr());
 	}
 	getOr(fallback) {
-		return this.promise.then((r) => r.getOr(fallback));
+		return this.#promise.then((r) => r.getOr(fallback));
 	}
 	getOrElse(f) {
-		return this.promise.then((r) => r.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) {
@@ -767,6 +832,33 @@ function isDefect(r) {
 function Do() {
 	return Ok({});
 }
+/**
+* Start an **asynchronous** do-notation chain with an empty object scope — the
+* pre-lifted form of {@link Do}, sparing you `Do().toAsync()`.
+*
+* @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).
+*
+* @example
+* ```ts
+* import { DoAsync, Ok } from "unthrown";
+*
+* 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 DoAsync() {
+	return Do().toAsync();
+}
 //#endregion
 //#region src/interop.ts
 /**
@@ -805,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
@@ -895,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
@@ -958,12 +1056,26 @@ 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.
 *
@@ -1166,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
@@ -1175,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.
@@ -1192,6 +1306,7 @@ const Result = {
 const AsyncResult = {
 	Ok: OkAsync,
 	Err: ErrAsync,
+	Do: DoAsync,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1215,7 +1330,11 @@ 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`.
+* 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
@@ -1260,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;
@@ -1295,6 +1424,7 @@ function tag(value) {
 //#endregion
 exports.AsyncResult = AsyncResult;
 exports.Do = Do;
+exports.DoAsync = DoAsync;
 exports.Err = Err;
 exports.ErrAsync = ErrAsync;
 exports.GetError = GetError;