unthrown 5.0.0 → 5.2.0

package/dist/index.cjs

@@ -25,7 +25,7 @@ var NonExhaustiveError = class extends Error {
 	constructor(input) {
 		let printed;
 		try {
-			printed = JSON.stringify(input);
+			printed = JSON.stringify(input) ?? String(input);
 		} catch {
 			printed = String(input);
 		}
@@ -261,7 +261,7 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			const r = f(this.value);
-			return isResult(r) ? r : nonResultCallbackDefect();
+			return isResult(r) ? r : nonResultCallbackDefect(r);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -269,7 +269,7 @@ var Res = class {
 	tap(f) {
 		if (this.tag !== "Ok") return this;
 		try {
-			f(this.value);
+			silenceIfThenable(f(this.value));
 			return this;
 		} catch (cause) {
 			return defectRes(cause);
@@ -279,7 +279,7 @@ var Res = class {
 		if (this.tag !== "Ok") return this;
 		try {
 			const r = f(this.value);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return defectRes(cause);
@@ -289,7 +289,7 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			const r = f(this.value);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			if (r.tag !== "Ok") return passThrough(r);
 			return okRes({
 				...scopeOf(this.value),
@@ -341,7 +341,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return defectRes(out.cause);
-			if (!isResult(out)) return nonResultCallbackDefect();
+			if (!isResult(out)) return nonResultCallbackDefect(out);
 			return out;
 		} catch (cause) {
 			return defectRes(cause);
@@ -362,6 +362,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return observerThrowToDefect(out.cause, this.error);
+			silenceIfThenable(out);
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -372,7 +373,7 @@ var Res = class {
 		try {
 			const r = runMatch(f, this.error);
 			if (isDefectMarker(r)) return observerThrowToDefect(r.cause, this.error);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -382,7 +383,7 @@ var Res = class {
 		if (this.tag !== "Defect") return this;
 		try {
 			const r = f(this.cause);
-			return isResult(r) ? r : nonResultCallbackDefect();
+			return isResult(r) ? r : nonResultCallbackDefect(r);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -390,7 +391,7 @@ var Res = class {
 	tapDefect(f) {
 		if (this.tag !== "Defect") return this;
 		try {
-			f(this.cause);
+			silenceIfThenable(f(this.cause));
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.cause);
@@ -399,7 +400,7 @@ var Res = class {
 	tapFailure(f) {
 		if (this.tag === "Ok") return this;
 		try {
-			f(this);
+			silenceIfThenable(f(this));
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.tag === "Err" ? this.error : this.cause);
@@ -537,7 +538,11 @@ function defectRes(cause) {
 *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
 *   // so the `P._` escape hatch is the only arm that can terminate the match:
 *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
-*   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+*   x.match({
+*     ok: () => 1,
+*     errCases: (m) => m.with(P._, () => 0),
+*     defect: () => -1,
+*   });
 * ```
 *
 * @category Guards
@@ -564,6 +569,30 @@ function passThrough(self) {
 	return self;
 }
 /**
+* Adopt-and-silence a thenable a combinator is about to **discard**.
+*
+* @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
+* 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.
+*
+* 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.
+*
+* @internal
+*/
+function silenceIfThenable(value) {
+	try {
+		if ((typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function") Promise.resolve(value).then(void 0, () => void 0);
+	} catch {}
+}
+/**
 * 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
@@ -573,7 +602,8 @@ function passThrough(self) {
 *
 * @internal
 */
-function nonResultCallbackDefect() {
+function nonResultCallbackDefect(returned) {
+	silenceIfThenable(returned);
 	return defectRes(/* @__PURE__ */ new TypeError("unthrown: a combinator callback returned a non-Result value"));
 }
 /**
@@ -658,7 +688,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				return isResult(inner) ? inner : nonResultCallbackDefect();
+				return isResult(inner) ? inner : nonResultCallbackDefect(inner);
 			} catch (cause) {
 				return defectRes(cause);
 			}
@@ -668,7 +698,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Ok") return r;
 			try {
-				f(r.value);
+				silenceIfThenable(f(r.value));
 				return r;
 			} catch (cause) {
 				return defectRes(cause);
@@ -680,7 +710,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner.tag === "Ok" ? r : passThrough(inner);
 			} catch (cause) {
 				return defectRes(cause);
@@ -692,7 +722,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				if (inner.tag !== "Ok") return passThrough(inner);
 				return okRes({
 					...scopeOf(r.value),
@@ -751,7 +781,7 @@ var AsyncRes = class AsyncRes {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return defectRes(out.cause);
 				const inner = await out;
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner;
 			} catch (cause) {
 				return defectRes(cause);
@@ -776,6 +806,7 @@ var AsyncRes = class AsyncRes {
 			try {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
+				silenceIfThenable(out);
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -789,7 +820,7 @@ var AsyncRes = class AsyncRes {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
 				const inner = await out;
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -801,7 +832,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Defect") return r;
 			try {
 				const inner = await f(r.cause);
-				return isResult(inner) ? inner : nonResultCallbackDefect();
+				return isResult(inner) ? inner : nonResultCallbackDefect(inner);
 			} catch (cause) {
 				return defectRes(cause);
 			}
@@ -811,7 +842,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Defect") return r;
 			try {
-				f(r.cause);
+				silenceIfThenable(f(r.cause));
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.cause);
@@ -822,7 +853,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag === "Ok") return r;
 			try {
-				f(r);
+				silenceIfThenable(f(r));
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.tag === "Err" ? r.error : r.cause);
@@ -1090,6 +1121,11 @@ function fromNullable(value, onAbsent) {
 * — and a thenable slipped past the types at runtime becomes a `Defect` (never
 * an `Err(Promise)`), its orphaned rejection silenced.
 *
+* `fn` is **synchronous** too. An `async` `fn` rejects *after* this boundary has
+* already returned, so its rejection could never reach `qualify`: it becomes a
+* `Defect` (never `Ok(<Promise>)`) and the orphaned rejection is silenced rather
+* than left to float. Reach for {@link fromPromise} to wrap async work.
+*
 * 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
 * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
@@ -1126,7 +1162,8 @@ function fromThrowable(fn, qualify) {
 	const triage = qualify;
 	return (...args) => {
 		try {
-			return Ok(fn(...args));
+			const value = fn(...args);
+			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
 		} catch (cause) {
 			return qualifyToResult(cause, triage);
 		}
@@ -1143,6 +1180,10 @@ function fromThrowable(fn, qualify) {
 * `qualify`. When some throws *are* anticipated, reach for
 * {@link fromThrowable} and triage them.
 *
+* `fn` is **synchronous**: an `async` `fn` becomes a `Defect` (never
+* `Ok(<Promise>)`), with its orphaned rejection silenced rather than left to
+* float. Reach for {@link fromSafePromise} to wrap async work.
+*
 * @typeParam A - the wrapped function's argument tuple.
 * @typeParam T - the wrapped function's return type.
 * @param fn - the throwing function to wrap.
@@ -1164,7 +1205,8 @@ function fromThrowable(fn, qualify) {
 function fromSafeThrowable(fn) {
 	return (...args) => {
 		try {
-			return Ok(fn(...args));
+			const value = fn(...args);
+			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -1260,7 +1302,33 @@ function qualifyToResult(cause, qualify) {
 	}
 }
 /**
-* Runtime thenable probe for the belt-and-braces guard above. Called inside the
+* The Defect minted when a **synchronous** boundary's `fn` returns a thenable —
+* i.e. an `async` function was handed to {@link fromThrowable} /
+* {@link fromSafeThrowable}.
+*
+* @remarks
+* This is the sibling of the thenable-`qualify` net in {@link qualifyToResult},
+* and it closes a strictly worse hole. A synchronous boundary only ever sees a
+* synchronous `throw`, so an async `fn`'s rejection never reaches `qualify` at
+* all: it would sit inside `Ok(<Promise>)`, un-triaged, and then float as an
+* unhandled rejection — which terminates the process on Node by default.
+*
+* Unlike the combinator callbacks, this cannot be banned at compile time
+* without collateral damage: `T & NotThenable<T>` on `fn`'s return makes a
+* **generic** function unassignable, so `fromSafeThrowable(structuredClone)`
+* stops compiling and `T` collapses to `unknown`. (The phantom rest-tuple guard
+* `fromPromise` uses fares worse.) So the ban is enforced here, at runtime,
+* where it costs nothing: a Defect, plus adopt-and-silence so the orphaned
+* rejection cannot float.
+*
+* @internal
+*/
+function thenableReturnDefect(value) {
+	Promise.resolve(value).then(void 0, () => void 0);
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: fromThrowable/fromSafeThrowable wrap a SYNCHRONOUS function, but `fn` returned a thenable — its rejection would escape qualification. Use fromPromise/fromSafePromise instead."));
+}
+/**
+* Runtime thenable probe for the belt-and-braces guards above. Called inside the
 * caller's `try`, so even a hostile `.then` getter lands on the Defect path.
 *
 * @internal
@@ -1388,7 +1456,10 @@ function allFromDict(results) {
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
 *
-* const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+* const both = allAsync([
+*   fromSafePromise(Promise.resolve(1)),
+*   fromSafePromise(Promise.resolve(2)),
+* ]);
 * (await both).get(); // => [1, 2]
 * ```
 */
@@ -1492,7 +1563,10 @@ const Result = {
 * @example
 * ```ts
 * import { AsyncResult } from "unthrown";
-* const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* const user = await AsyncResult.fromPromise(
+*   fetchUser(id),
+*   (c, defect) => defect(c),
+* );
 * user.get(); // => the fetched user (on success)
 * ```
 */

package/dist/index.d.cts

@@ -296,10 +296,17 @@ type Bound<T, K extends string, U> = Prettify<Omit<T, K> & { readonly [P in K]:
  * would escape the pipeline as an unhandled rejection instead of a `Defect`.
  * Lift async work with {@link fromPromise} and compose it with `flatMap`.
  *
+ * Spelled with `Extract`, not `[R] extends [PromiseLike<…>]`, so the ban also
+ * fires when only SOME arms of a union return are thenable — a *sometimes*-async
+ * callback (`flag ? 1 : work()`) is still an unawaited effect whose rejection
+ * the pipeline never sees. The tuple-wrapped form is false for a partial union
+ * and let exactly that through. This is the same reasoning `fromPromise`'s
+ * async-qualify guard already used.
+ *
  * @typeParam R - the callback's inferred return type.
  * @category Types
  */
-type NotThenable<R> = [R] extends [PromiseLike<unknown>] ? "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap" : unknown;
+type NotThenable<R> = [Extract<R, PromiseLike<unknown>>] extends [never] ? unknown : "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap";
 /**
  * The built-in match builder over an error union `E`, as produced by
  * `match(error)`. This is what an error combinator's callback receives — chain
@@ -759,12 +766,20 @@ type ResultMethods<out T, out E> = {
    *
    * @remarks
    * A deliberate escape hatch off the errors-as-values model — it **throws the
-   * `Err` value as-is** at the call site. Its purpose is to move a literal
-   * `throw` behind a method, so a `no-throw` lint rule can ban raw throws while
-   * this one sanctioned extraction remains — _not_ to replace principled
-   * handling. When you can keep the error a value, prefer
-   * {@link ResultMethods.match | match} / {@link ResultMethods.recoverErrCases | recoverErrCases} /
-   * {@link ResultMethods.flatMapErrCases | flatMapErrCases}.
+   * `Err` value as-is** at the call site, so a caller of the enclosing function
+   * sees a throw rather than a channel. Its home is **tests and scripts**,
+   * where "this `Result` had better be `Ok`" is the assertion and a throw is
+   * the correct failure mode.
+   *
+   * In production code, fold the error channel instead:
+   * {@link ResultMethods.recoverErrCases | recoverErrCases} empties `E`, so
+   * {@link ResultMethods.get | get} compiles and a case routed to the injected
+   * `defect(...)` panics with its original cause — with every case still named.
+   * {@link ResultMethods.match | match} and
+   * {@link ResultMethods.flatMapErrCases | flatMapErrCases} are the other two
+   * ways to keep the error a value. `@unthrown/oxlint`'s opt-in
+   * `no-get-or-throw` rule enforces this, exempting test files through an
+   * oxlint `overrides` entry.
    *
    * Type-gated as the **complement** of {@link ResultMethods.get | get}: it
    * compiles only when the error channel is **non-empty** (`E` is not `never`) —
@@ -1443,7 +1458,11 @@ declare class GetError<E = unknown> extends Error {
  *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
  *   // so the `P._` escape hatch is the only arm that can terminate the match:
  *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
- *   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+ *   x.match({
+ *     ok: () => 1,
+ *     errCases: (m) => m.with(P._, () => 0),
+ *     defect: () => -1,
+ *   });
  * ```
  *
  * @category Guards
@@ -1558,6 +1577,11 @@ declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () =>
  * — and a thenable slipped past the types at runtime becomes a `Defect` (never
  * an `Err(Promise)`), its orphaned rejection silenced.
  *
+ * `fn` is **synchronous** too. An `async` `fn` rejects *after* this boundary has
+ * already returned, so its rejection could never reach `qualify`: it becomes a
+ * `Defect` (never `Ok(<Promise>)`) and the orphaned rejection is silenced rather
+ * than left to float. Reach for {@link fromPromise} to wrap async work.
+ *
  * 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
  * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
@@ -1602,6 +1626,10 @@ declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T,
  * `qualify`. When some throws *are* anticipated, reach for
  * {@link fromThrowable} and triage them.
  *
+ * `fn` is **synchronous**: an `async` `fn` becomes a `Defect` (never
+ * `Ok(<Promise>)`), with its orphaned rejection silenced rather than left to
+ * float. Reach for {@link fromSafePromise} to wrap async work.
+ *
  * @typeParam A - the wrapped function's argument tuple.
  * @typeParam T - the wrapped function's return type.
  * @param fn - the throwing function to wrap.
@@ -1774,7 +1802,10 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * ```ts
  * import { allAsync, fromSafePromise } from "unthrown";
  *
- * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+ * const both = allAsync([
+ *   fromSafePromise(Promise.resolve(1)),
+ *   fromSafePromise(Promise.resolve(2)),
+ * ]);
  * (await both).get(); // => [1, 2]
  * ```
  */
@@ -1882,7 +1913,10 @@ type Result<T, E> = Result$1<T, E>;
  * @example
  * ```ts
  * import { AsyncResult } from "unthrown";
- * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * const user = await AsyncResult.fromPromise(
+ *   fetchUser(id),
+ *   (c, defect) => defect(c),
+ * );
  * user.get(); // => the fetched user (on success)
  * ```
  */

package/dist/index.d.mts

@@ -296,10 +296,17 @@ type Bound<T, K extends string, U> = Prettify<Omit<T, K> & { readonly [P in K]:
  * would escape the pipeline as an unhandled rejection instead of a `Defect`.
  * Lift async work with {@link fromPromise} and compose it with `flatMap`.
  *
+ * Spelled with `Extract`, not `[R] extends [PromiseLike<…>]`, so the ban also
+ * fires when only SOME arms of a union return are thenable — a *sometimes*-async
+ * callback (`flag ? 1 : work()`) is still an unawaited effect whose rejection
+ * the pipeline never sees. The tuple-wrapped form is false for a partial union
+ * and let exactly that through. This is the same reasoning `fromPromise`'s
+ * async-qualify guard already used.
+ *
  * @typeParam R - the callback's inferred return type.
  * @category Types
  */
-type NotThenable<R> = [R] extends [PromiseLike<unknown>] ? "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap" : unknown;
+type NotThenable<R> = [Extract<R, PromiseLike<unknown>>] extends [never] ? unknown : "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap";
 /**
  * The built-in match builder over an error union `E`, as produced by
  * `match(error)`. This is what an error combinator's callback receives — chain
@@ -759,12 +766,20 @@ type ResultMethods<out T, out E> = {
    *
    * @remarks
    * A deliberate escape hatch off the errors-as-values model — it **throws the
-   * `Err` value as-is** at the call site. Its purpose is to move a literal
-   * `throw` behind a method, so a `no-throw` lint rule can ban raw throws while
-   * this one sanctioned extraction remains — _not_ to replace principled
-   * handling. When you can keep the error a value, prefer
-   * {@link ResultMethods.match | match} / {@link ResultMethods.recoverErrCases | recoverErrCases} /
-   * {@link ResultMethods.flatMapErrCases | flatMapErrCases}.
+   * `Err` value as-is** at the call site, so a caller of the enclosing function
+   * sees a throw rather than a channel. Its home is **tests and scripts**,
+   * where "this `Result` had better be `Ok`" is the assertion and a throw is
+   * the correct failure mode.
+   *
+   * In production code, fold the error channel instead:
+   * {@link ResultMethods.recoverErrCases | recoverErrCases} empties `E`, so
+   * {@link ResultMethods.get | get} compiles and a case routed to the injected
+   * `defect(...)` panics with its original cause — with every case still named.
+   * {@link ResultMethods.match | match} and
+   * {@link ResultMethods.flatMapErrCases | flatMapErrCases} are the other two
+   * ways to keep the error a value. `@unthrown/oxlint`'s opt-in
+   * `no-get-or-throw` rule enforces this, exempting test files through an
+   * oxlint `overrides` entry.
    *
    * Type-gated as the **complement** of {@link ResultMethods.get | get}: it
    * compiles only when the error channel is **non-empty** (`E` is not `never`) —
@@ -1443,7 +1458,11 @@ declare class GetError<E = unknown> extends Error {
  *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
  *   // so the `P._` escape hatch is the only arm that can terminate the match:
  *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
- *   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+ *   x.match({
+ *     ok: () => 1,
+ *     errCases: (m) => m.with(P._, () => 0),
+ *     defect: () => -1,
+ *   });
  * ```
  *
  * @category Guards
@@ -1558,6 +1577,11 @@ declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () =>
  * — and a thenable slipped past the types at runtime becomes a `Defect` (never
  * an `Err(Promise)`), its orphaned rejection silenced.
  *
+ * `fn` is **synchronous** too. An `async` `fn` rejects *after* this boundary has
+ * already returned, so its rejection could never reach `qualify`: it becomes a
+ * `Defect` (never `Ok(<Promise>)`) and the orphaned rejection is silenced rather
+ * than left to float. Reach for {@link fromPromise} to wrap async work.
+ *
  * 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
  * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
@@ -1602,6 +1626,10 @@ declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T,
  * `qualify`. When some throws *are* anticipated, reach for
  * {@link fromThrowable} and triage them.
  *
+ * `fn` is **synchronous**: an `async` `fn` becomes a `Defect` (never
+ * `Ok(<Promise>)`), with its orphaned rejection silenced rather than left to
+ * float. Reach for {@link fromSafePromise} to wrap async work.
+ *
  * @typeParam A - the wrapped function's argument tuple.
  * @typeParam T - the wrapped function's return type.
  * @param fn - the throwing function to wrap.
@@ -1774,7 +1802,10 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * ```ts
  * import { allAsync, fromSafePromise } from "unthrown";
  *
- * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+ * const both = allAsync([
+ *   fromSafePromise(Promise.resolve(1)),
+ *   fromSafePromise(Promise.resolve(2)),
+ * ]);
  * (await both).get(); // => [1, 2]
  * ```
  */
@@ -1882,7 +1913,10 @@ type Result<T, E> = Result$1<T, E>;
  * @example
  * ```ts
  * import { AsyncResult } from "unthrown";
- * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * const user = await AsyncResult.fromPromise(
+ *   fetchUser(id),
+ *   (c, defect) => defect(c),
+ * );
  * user.get(); // => the fetched user (on success)
  * ```
  */

package/dist/index.mjs

@@ -24,7 +24,7 @@ var NonExhaustiveError = class extends Error {
 	constructor(input) {
 		let printed;
 		try {
-			printed = JSON.stringify(input);
+			printed = JSON.stringify(input) ?? String(input);
 		} catch {
 			printed = String(input);
 		}
@@ -260,7 +260,7 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			const r = f(this.value);
-			return isResult(r) ? r : nonResultCallbackDefect();
+			return isResult(r) ? r : nonResultCallbackDefect(r);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -268,7 +268,7 @@ var Res = class {
 	tap(f) {
 		if (this.tag !== "Ok") return this;
 		try {
-			f(this.value);
+			silenceIfThenable(f(this.value));
 			return this;
 		} catch (cause) {
 			return defectRes(cause);
@@ -278,7 +278,7 @@ var Res = class {
 		if (this.tag !== "Ok") return this;
 		try {
 			const r = f(this.value);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return defectRes(cause);
@@ -288,7 +288,7 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			const r = f(this.value);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			if (r.tag !== "Ok") return passThrough(r);
 			return okRes({
 				...scopeOf(this.value),
@@ -340,7 +340,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return defectRes(out.cause);
-			if (!isResult(out)) return nonResultCallbackDefect();
+			if (!isResult(out)) return nonResultCallbackDefect(out);
 			return out;
 		} catch (cause) {
 			return defectRes(cause);
@@ -361,6 +361,7 @@ var Res = class {
 		try {
 			const out = runMatch(f, this.error);
 			if (isDefectMarker(out)) return observerThrowToDefect(out.cause, this.error);
+			silenceIfThenable(out);
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -371,7 +372,7 @@ var Res = class {
 		try {
 			const r = runMatch(f, this.error);
 			if (isDefectMarker(r)) return observerThrowToDefect(r.cause, this.error);
-			if (!isResult(r)) return nonResultCallbackDefect();
+			if (!isResult(r)) return nonResultCallbackDefect(r);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -381,7 +382,7 @@ var Res = class {
 		if (this.tag !== "Defect") return this;
 		try {
 			const r = f(this.cause);
-			return isResult(r) ? r : nonResultCallbackDefect();
+			return isResult(r) ? r : nonResultCallbackDefect(r);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -389,7 +390,7 @@ var Res = class {
 	tapDefect(f) {
 		if (this.tag !== "Defect") return this;
 		try {
-			f(this.cause);
+			silenceIfThenable(f(this.cause));
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.cause);
@@ -398,7 +399,7 @@ var Res = class {
 	tapFailure(f) {
 		if (this.tag === "Ok") return this;
 		try {
-			f(this);
+			silenceIfThenable(f(this));
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.tag === "Err" ? this.error : this.cause);
@@ -536,7 +537,11 @@ function defectRes(cause) {
 *   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
 *   // so the `P._` escape hatch is the only arm that can terminate the match:
 *   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
-*   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
+*   x.match({
+*     ok: () => 1,
+*     errCases: (m) => m.with(P._, () => 0),
+*     defect: () => -1,
+*   });
 * ```
 *
 * @category Guards
@@ -563,6 +568,30 @@ function passThrough(self) {
 	return self;
 }
 /**
+* Adopt-and-silence a thenable a combinator is about to **discard**.
+*
+* @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
+* 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.
+*
+* 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.
+*
+* @internal
+*/
+function silenceIfThenable(value) {
+	try {
+		if ((typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function") Promise.resolve(value).then(void 0, () => void 0);
+	} catch {}
+}
+/**
 * 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
@@ -572,7 +601,8 @@ function passThrough(self) {
 *
 * @internal
 */
-function nonResultCallbackDefect() {
+function nonResultCallbackDefect(returned) {
+	silenceIfThenable(returned);
 	return defectRes(/* @__PURE__ */ new TypeError("unthrown: a combinator callback returned a non-Result value"));
 }
 /**
@@ -657,7 +687,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				return isResult(inner) ? inner : nonResultCallbackDefect();
+				return isResult(inner) ? inner : nonResultCallbackDefect(inner);
 			} catch (cause) {
 				return defectRes(cause);
 			}
@@ -667,7 +697,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Ok") return r;
 			try {
-				f(r.value);
+				silenceIfThenable(f(r.value));
 				return r;
 			} catch (cause) {
 				return defectRes(cause);
@@ -679,7 +709,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner.tag === "Ok" ? r : passThrough(inner);
 			} catch (cause) {
 				return defectRes(cause);
@@ -691,7 +721,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				const inner = await f(r.value);
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				if (inner.tag !== "Ok") return passThrough(inner);
 				return okRes({
 					...scopeOf(r.value),
@@ -750,7 +780,7 @@ var AsyncRes = class AsyncRes {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return defectRes(out.cause);
 				const inner = await out;
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner;
 			} catch (cause) {
 				return defectRes(cause);
@@ -775,6 +805,7 @@ var AsyncRes = class AsyncRes {
 			try {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
+				silenceIfThenable(out);
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -788,7 +819,7 @@ var AsyncRes = class AsyncRes {
 				const out = runMatch(f, r.error);
 				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
 				const inner = await out;
-				if (!isResult(inner)) return nonResultCallbackDefect();
+				if (!isResult(inner)) return nonResultCallbackDefect(inner);
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -800,7 +831,7 @@ var AsyncRes = class AsyncRes {
 			if (r.tag !== "Defect") return r;
 			try {
 				const inner = await f(r.cause);
-				return isResult(inner) ? inner : nonResultCallbackDefect();
+				return isResult(inner) ? inner : nonResultCallbackDefect(inner);
 			} catch (cause) {
 				return defectRes(cause);
 			}
@@ -810,7 +841,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Defect") return r;
 			try {
-				f(r.cause);
+				silenceIfThenable(f(r.cause));
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.cause);
@@ -821,7 +852,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag === "Ok") return r;
 			try {
-				f(r);
+				silenceIfThenable(f(r));
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.tag === "Err" ? r.error : r.cause);
@@ -1089,6 +1120,11 @@ function fromNullable(value, onAbsent) {
 * — and a thenable slipped past the types at runtime becomes a `Defect` (never
 * an `Err(Promise)`), its orphaned rejection silenced.
 *
+* `fn` is **synchronous** too. An `async` `fn` rejects *after* this boundary has
+* already returned, so its rejection could never reach `qualify`: it becomes a
+* `Defect` (never `Ok(<Promise>)`) and the orphaned rejection is silenced rather
+* than left to float. Reach for {@link fromPromise} to wrap async work.
+*
 * 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
 * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
@@ -1125,7 +1161,8 @@ function fromThrowable(fn, qualify) {
 	const triage = qualify;
 	return (...args) => {
 		try {
-			return Ok(fn(...args));
+			const value = fn(...args);
+			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
 		} catch (cause) {
 			return qualifyToResult(cause, triage);
 		}
@@ -1142,6 +1179,10 @@ function fromThrowable(fn, qualify) {
 * `qualify`. When some throws *are* anticipated, reach for
 * {@link fromThrowable} and triage them.
 *
+* `fn` is **synchronous**: an `async` `fn` becomes a `Defect` (never
+* `Ok(<Promise>)`), with its orphaned rejection silenced rather than left to
+* float. Reach for {@link fromSafePromise} to wrap async work.
+*
 * @typeParam A - the wrapped function's argument tuple.
 * @typeParam T - the wrapped function's return type.
 * @param fn - the throwing function to wrap.
@@ -1163,7 +1204,8 @@ function fromThrowable(fn, qualify) {
 function fromSafeThrowable(fn) {
 	return (...args) => {
 		try {
-			return Ok(fn(...args));
+			const value = fn(...args);
+			return isThenable(value) ? thenableReturnDefect(value) : Ok(value);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -1259,7 +1301,33 @@ function qualifyToResult(cause, qualify) {
 	}
 }
 /**
-* Runtime thenable probe for the belt-and-braces guard above. Called inside the
+* The Defect minted when a **synchronous** boundary's `fn` returns a thenable —
+* i.e. an `async` function was handed to {@link fromThrowable} /
+* {@link fromSafeThrowable}.
+*
+* @remarks
+* This is the sibling of the thenable-`qualify` net in {@link qualifyToResult},
+* and it closes a strictly worse hole. A synchronous boundary only ever sees a
+* synchronous `throw`, so an async `fn`'s rejection never reaches `qualify` at
+* all: it would sit inside `Ok(<Promise>)`, un-triaged, and then float as an
+* unhandled rejection — which terminates the process on Node by default.
+*
+* Unlike the combinator callbacks, this cannot be banned at compile time
+* without collateral damage: `T & NotThenable<T>` on `fn`'s return makes a
+* **generic** function unassignable, so `fromSafeThrowable(structuredClone)`
+* stops compiling and `T` collapses to `unknown`. (The phantom rest-tuple guard
+* `fromPromise` uses fares worse.) So the ban is enforced here, at runtime,
+* where it costs nothing: a Defect, plus adopt-and-silence so the orphaned
+* rejection cannot float.
+*
+* @internal
+*/
+function thenableReturnDefect(value) {
+	Promise.resolve(value).then(void 0, () => void 0);
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: fromThrowable/fromSafeThrowable wrap a SYNCHRONOUS function, but `fn` returned a thenable — its rejection would escape qualification. Use fromPromise/fromSafePromise instead."));
+}
+/**
+* Runtime thenable probe for the belt-and-braces guards above. Called inside the
 * caller's `try`, so even a hostile `.then` getter lands on the Defect path.
 *
 * @internal
@@ -1387,7 +1455,10 @@ function allFromDict(results) {
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
 *
-* const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
+* const both = allAsync([
+*   fromSafePromise(Promise.resolve(1)),
+*   fromSafePromise(Promise.resolve(2)),
+* ]);
 * (await both).get(); // => [1, 2]
 * ```
 */
@@ -1491,7 +1562,10 @@ const Result = {
 * @example
 * ```ts
 * import { AsyncResult } from "unthrown";
-* const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* const user = await AsyncResult.fromPromise(
+*   fetchUser(id),
+*   (c, defect) => defect(c),
+* );
 * user.get(); // => the fetched user (on success)
 * ```
 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unthrown",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Explicit errors as values, with a separate defect (panic) channel",
   "keywords": [
     "defect",
@@ -47,13 +47,10 @@
   },
   "devDependencies": {
     "@btravstack/tsconfig": "0.2.0",
-    "@btravstack/typedoc": "0.1.0",
-    "@types/node": "26.1.1",
+    "@types/node": "26.1.2",
     "@vitest/coverage-v8": "4.1.10",
-    "tsdown": "0.22.12",
-    "typedoc": "0.28.20",
-    "typedoc-plugin-markdown": "4.12.0",
-    "typescript": "6.0.3",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
     "vitest": "4.1.10"
   },
   "engines": {
@@ -61,7 +58,6 @@
   },
   "scripts": {
     "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
-    "build:docs": "typedoc",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "test:types": "tsc --noEmit -p tsconfig.test-d.json",