unthrown 1.1.0 → 3.0.0

package/README.md

@@ -11,10 +11,10 @@ pnpm add unthrown
 ```
 
 ```ts
-import { Ok, Err, fromPromise, Defect, type Result } from "unthrown";
+import { Ok, Err, fromPromise, type Result } from "unthrown";
 
-const user = fromPromise(fetchUser(id), (cause) =>
-  cause instanceof NotFoundError ? new NotFound() : Defect(cause),
+const user = fromPromise(fetchUser(id), (cause, defect) =>
+  cause instanceof NotFoundError ? new NotFound() : defect(cause),
 );
 
 const status = await user.match({

package/dist/index.cjs

@@ -6,6 +6,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * `Ok`.
 *
 * @remarks
+* The offending value is exposed two ways: the typed {@link UnwrapError.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
 * re-thrown (with its original stack) instead.
 *
@@ -18,7 +23,7 @@ var UnwrapError = class extends Error {
 	*/
 	error;
 	constructor(error) {
-		super("unthrown: called unwrap on a non-matching Result");
+		super("unthrown: called unwrap on a non-matching Result", { cause: error });
 		this.name = "UnwrapError";
 		this.error = error;
 		Object.setPrototypeOf(this, new.target.prototype);
@@ -279,7 +284,7 @@ function passThrough(self) {
 * though, so a primitive `Ok` (e.g. `Ok(5).bind(...)`, or a chain whose value was
 * `map`-ped away from its scope) could reach it. Rather than let `{ ...5 }`
 * silently collapse to `{}` and drop the prior scope, we throw here — the
-* surrounding `try` turns it into a {@link Defect}, surfacing the misuse as the
+* surrounding `try` turns it into a `Defect`, surfacing the misuse as the
 * bug it is (a defect is a bug, not an absent value). A `this: object` constraint
 * was rejected: TypeScript does not hard-enforce a constraint inferred solely
 * from `this`, and it breaks `AsyncRes implements AsyncResult`.
@@ -541,41 +546,6 @@ function isDefect(r) {
 	return r.tag === "Defect";
 }
 //#endregion
-//#region src/defect.ts
-const DEFECT = Symbol("unthrown/Defect");
-/**
-* Wrap a cause as a {@link Defect} — the value you return from a `qualify`
-* function when a failure is **not** a modeled domain error.
-*
-* @param cause - the original thrown/rejected value.
-* @returns an opaque Defect marker carrying `cause`.
-*
-* @example
-* ```ts
-* import { fromPromise, Defect } from "unthrown";
-*
-* const user = fromPromise(fetchUser(id), (cause) =>
-*   cause instanceof NotFoundError ? cause : Defect(cause),
-* );
-* ```
-*/
-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`.
-*
-* @internal
-*/
-function isDefectMarker(x) {
-	return typeof x === "object" && x !== null && x[DEFECT] === true;
-}
-//#endregion
 //#region src/do.ts
 /**
 * Start a do-notation chain with an empty object scope, grown step by step with
@@ -603,6 +573,36 @@ 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.
+*
+* @param cause - the original thrown/rejected value.
+* @returns an opaque Defect marker carrying `cause`.
+*
+* @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`.
+*
+* @internal
+*/
+function isDefectMarker(x) {
+	return typeof x === "object" && x !== null && x[DEFECT] === true;
+}
+//#endregion
 //#region src/interop.ts
 /**
 * Bridge a nullable value into a {@link Result}: absence becomes a **modeled**
@@ -632,12 +632,13 @@ function fromNullable(value, onAbsent) {
 *
 * @remarks
 * `qualify` **must** triage every thrown cause into a modeled error `E` or a
-* {@link Defect} (via {@link Defect}) — there is no path that leaves `unknown`
-* in `E`. A throw inside `qualify` itself is treated as a `Defect`.
+* `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`.
 *
 * 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
+* `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
 * out-of-band and must not pollute the error channel); reach for
 * {@link fromSafePromise} when every failure is a Defect.
 *
@@ -646,13 +647,14 @@ function fromNullable(value, onAbsent) {
 * @typeParam R - `qualify`'s return type; the modeled error `E` is
 * `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted).
 * @param fn - the throwing function to wrap.
-* @param qualify - triages a thrown cause into `E` or a `Defect`.
+* @param qualify - triages a thrown `cause` into a modeled `E`, or marks it
+* unmodeled by returning `defect(cause)` (the helper passed as its second arg).
 * @returns a function with the same arguments returning `Result<T, E>`.
 *
 * @example
 * ```ts
-* import { fromThrowable, Defect } from "unthrown";
-* const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
+* import { fromThrowable } from "unthrown";
+* const parse = fromThrowable(JSON.parse, (cause, defect) => defect(cause));
 * parse("{}").unwrap();
 * ```
 */
@@ -672,26 +674,27 @@ function fromThrowable(fn, qualify) {
 *
 * @remarks
 * `qualify` **must** map each rejection cause into a modeled error `E` or a
-* {@link Defect}. The returned `AsyncResult`'s internal promise never rejects;
-* `await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
-* `Defect`.
+* `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`.
 *
 * 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`; when every
+* `qualify` that returns *only* `defect(cause)` yields `E = never`; when every
 * rejection is a Defect, prefer {@link fromSafePromise}.
 *
 * @typeParam T - the resolved value type.
 * @typeParam R - `qualify`'s return type; the modeled error `E` is
 * `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted).
 * @param promise - the promise, or a thunk returning one.
-* @param qualify - triages a rejection cause into `E` or a `Defect`.
+* @param qualify - triages a rejection `cause` into a modeled `E`, or marks it
+* unmodeled by returning `defect(cause)` (the helper passed as its second arg).
 *
 * @example
 * ```ts
-* import { fromPromise, Defect } from "unthrown";
-* const user = await fromPromise(fetchUser(id), (cause) =>
-*   cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
+* import { fromPromise } from "unthrown";
+* const user = await fromPromise(fetchUser(id), (cause, defect) =>
+*   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
 * );
 * ```
 */
@@ -716,7 +719,7 @@ function fromSafePromise(promise) {
 }
 function qualifyToResult(cause, qualify) {
 	try {
-		const q = qualify(cause);
+		const q = qualify(cause, defect);
 		return isDefectMarker(q) ? defectRes(q.cause) : errRes(q);
 	} catch (qErr) {
 		return defectRes(qErr);
@@ -845,13 +848,11 @@ function allFromDictAsync(results) {
 //#endregion
 //#region src/facade.ts
 /**
-* Companion object grouping the standalone entry points under a single,
-* discoverable namespace: {@link Result.Ok}, {@link Result.Err},
-* {@link Result.Defect}, {@link Result.fromNullable}, {@link Result.fromThrowable},
-* {@link Result.fromPromise}, {@link Result.fromSafePromise}, {@link Result.all},
-* {@link Result.allAsync}, {@link Result.allFromDict},
-* {@link Result.allFromDictAsync}, {@link Result.isOk}, {@link Result.isErr},
-* {@link Result.isDefect}, {@link Result.isResult}.
+* Companion object grouping the **`Result`-producing** entry points under a
+* single, discoverable namespace: {@link Result.Ok}, {@link Result.Err},
+* {@link Result.Do}, {@link Result.fromNullable}, {@link Result.fromThrowable},
+* {@link Result.all}, {@link Result.allFromDict}, {@link Result.isOk},
+* {@link Result.isErr}, {@link Result.isDefect}, {@link Result.isResult}.
 *
 * @remarks
 * Purely additive sugar — each member **is** the corresponding free function.
@@ -859,6 +860,10 @@ function allFromDictAsync(results) {
 * `{ Ok }` never pulls this object in. The value `Result` and the type
 * {@link Result} share one name (the companion-object pattern).
 *
+* The **async** entry points live on the sibling {@link AsyncResult} companion
+* (`AsyncResult.fromPromise`, `AsyncResult.all`, …), grouped by what they
+* return — a static lives in exactly one namespace.
+*
 * @example
 * ```ts
 * import { Result } from "unthrown";
@@ -868,21 +873,43 @@ function allFromDictAsync(results) {
 const Result = {
 	Ok,
 	Err,
-	Defect,
 	Do,
 	fromNullable,
 	fromThrowable,
-	fromPromise,
-	fromSafePromise,
 	all,
-	allAsync,
 	allFromDict,
-	allFromDictAsync,
 	isOk,
 	isErr,
 	isDefect,
 	isResult
 };
+/**
+* Companion object grouping the **`AsyncResult`-producing** entry points under
+* the matching namespace: {@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
+* **return**, so `fromPromise`/`fromSafePromise` and the async aggregates sit
+* here rather than on {@link Result}; the namespace already conveys "async", so
+* the aggregates drop the `Async` suffix (`AsyncResult.all` is the free function
+* `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.
+*
+* @example
+* ```ts
+* import { AsyncResult } from "unthrown";
+* const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+* ```
+*/
+const AsyncResult = {
+	fromPromise,
+	fromSafePromise,
+	all: allAsync,
+	allFromDict: allFromDictAsync
+};
 //#endregion
 //#region src/tagged.ts
 /**
@@ -951,7 +978,7 @@ function matchTags(result, handlers) {
 	});
 }
 //#endregion
-exports.Defect = Defect;
+exports.AsyncResult = AsyncResult;
 exports.Do = Do;
 exports.Err = Err;
 exports.Ok = Ok;

package/dist/index.d.cts

@@ -261,7 +261,7 @@ type ResultMethods<T, E> = {
   isOk(): this is OkView<T, E>; /** Whether this result is `Err` — narrows `this` to its {@link ErrView} on `true`. */
   isErr(): this is ErrView<E, T>; /** Whether this result is a `Defect` — narrows `this` to its {@link DefectView} on `true`. */
   isDefect(): this is DefectView<T, E>; /** Lift this synchronous `Result` into an {@link AsyncResult}. */
-  toAsync(): AsyncResult<T, E>;
+  toAsync(): AsyncResult$1<T, E>;
 };
 /** The `Ok` variant of a {@link Result}: a success carrying a `value`. */
 type OkView<T, E = never> = ResultMethods<T, E> & {
@@ -351,40 +351,40 @@ type Awaitable<T> = {
  * @typeParam T - the success value type.
  * @typeParam E - the modeled error type.
  */
-type AsyncResult<T, E> = Awaitable<Result$1<T, E>> & {
-  /** Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. */map<U>(f: (value: T) => U): AsyncResult<U, E>;
+type AsyncResult$1<T, E> = Awaitable<Result$1<T, E>> & {
+  /** Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. */map<U>(f: (value: T) => U): AsyncResult$1<U, E>;
   /**
    * Asynchronous `flatMap`. `f` may return a `Result` **or** an `AsyncResult`
    * (never a raw `Promise`); a throw becomes a `Defect`.
    */
-  flatMap<U, E2>(f: (value: T) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<U, E | E2>; /** Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. */
-  tap(f: (value: T) => void): AsyncResult<T, E>;
+  flatMap<U, E2>(f: (value: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<U, E | E2>; /** Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. */
+  tap(f: (value: T) => void): AsyncResult$1<T, E>;
   /**
    * Asynchronous `flatTap` — a failable tap that keeps the original value. `f`
    * may return a `Result` **or** an `AsyncResult`; its `Ok` value is discarded,
    * an `Err`/`Defect` short-circuits, and a throw becomes a `Defect`.
    */
-  flatTap<E2>(f: (value: T) => Result$1<unknown, E2> | AsyncResult<unknown, E2>): AsyncResult<T, E | E2>;
+  flatTap<E2>(f: (value: T) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>;
   /**
    * Asynchronous `bind` (do-notation). `f` may return a `Result` **or** an
    * `AsyncResult`; its value is bound under `name` in the accumulating scope.
    */
-  bind<K extends string, U, E2>(name: K, f: (scope: T) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<Bound<T, K, U>, E | E2>; /** Asynchronous `let` (do-notation). `f` returns a plain value, bound under `name`. */
-  let<K extends string, U>(name: K, f: (scope: T) => U): AsyncResult<Bound<T, K, U>, E>; /** Asynchronous `as`. */
-  as<U>(value: U): AsyncResult<U, E>; /** Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. */
-  mapErr<E2>(f: (error: E) => E2): AsyncResult<T, E2>; /** Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. */
-  orElse<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<T | U, E2>; /** Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. */
-  recover<U>(f: (error: E) => U): AsyncResult<T | U, never>; /** Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. */
-  tapErr(f: (error: E) => void): AsyncResult<T, E>;
+  bind<K extends string, U, E2>(name: K, f: (scope: T) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<Bound<T, K, U>, E | E2>; /** Asynchronous `let` (do-notation). `f` returns a plain value, bound under `name`. */
+  let<K extends string, U>(name: K, f: (scope: T) => U): AsyncResult$1<Bound<T, K, U>, E>; /** Asynchronous `as`. */
+  as<U>(value: U): AsyncResult$1<U, E>; /** Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. */
+  mapErr<E2>(f: (error: E) => E2): AsyncResult$1<T, E2>; /** Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. */
+  orElse<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E2>; /** Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. */
+  recover<U>(f: (error: E) => U): AsyncResult$1<T | U, never>; /** Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. */
+  tapErr(f: (error: E) => void): AsyncResult$1<T, E>;
   /**
    * Asynchronous `flatTapErr` — a failable tap on the error that keeps the
    * original error. `f` may return a `Result` **or** an `AsyncResult`; its `Ok`
    * value is discarded, an `Err`/`Defect` from `f` threads through, and a throw
    * becomes a `Defect`.
    */
-  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2> | AsyncResult<unknown, E2>): AsyncResult<T, E | E2>; /** Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. */
-  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<T | U, E | E2>; /** Asynchronous `tapDefect`. */
-  tapDefect(f: (cause: unknown) => void): AsyncResult<T, E>; /** Asynchronous `match`. Handlers are synchronous; resolves to `R`. */
+  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>; /** Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. */
+  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E | E2>; /** Asynchronous `tapDefect`. */
+  tapDefect(f: (cause: unknown) => void): AsyncResult$1<T, E>; /** Asynchronous `match`. Handlers are synchronous; resolves to `R`. */
   match<R>(cases: {
     ok: (value: T) => R;
     err: (error: E) => R;
@@ -420,13 +420,13 @@ type ErrOf<R> = R extends {
  *
  * @typeParam R - the `AsyncResult` type to inspect.
  */
-type AsyncOkOf<R> = R extends AsyncResult<infer T, unknown> ? T : never;
+type AsyncOkOf<R> = R extends AsyncResult$1<infer T, unknown> ? T : never;
 /**
  * Extract the error type `E` from an {@link AsyncResult}.
  *
  * @typeParam R - the `AsyncResult` type to inspect.
  */
-type AsyncErrOf<R> = R extends AsyncResult<unknown, infer E> ? E : never;
+type AsyncErrOf<R> = R extends AsyncResult$1<unknown, infer E> ? E : never;
 //#endregion
 //#region src/constructors.d.ts
 /**
@@ -488,6 +488,11 @@ declare function isDefect<T, E>(r: Result$1<T, E>): r is DefectView<T, E>;
  * `Ok`.
  *
  * @remarks
+ * The offending value is exposed two ways: the typed {@link UnwrapError.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
  * re-thrown (with its original stack) instead.
  *
@@ -515,40 +520,6 @@ declare class UnwrapError<E = unknown> extends Error {
  */
 declare function isResult(x: unknown): x is Result$1<unknown, unknown>;
 //#endregion
-//#region src/defect.d.ts
-declare const DEFECT: unique symbol;
-/**
- * The marker a `qualify` function returns to triage a cause as **unexpected**.
- *
- * @remarks
- * `qualify` (passed to {@link fromPromise} / {@link fromThrowable}) returns
- * `E | Defect`: either a modeled domain error, or a `Defect` produced by
- * {@link Defect} to say "this failure is not modeled". A `Defect` is opaque —
- * it carries the original cause for the boundary to convert into the third
- * runtime state of a `Result`.
- */
-type Defect = {
-  readonly [DEFECT]: true;
-  readonly cause: unknown;
-};
-/**
- * Wrap a cause as a {@link Defect} — the value you return from a `qualify`
- * function when a failure is **not** a modeled domain error.
- *
- * @param cause - the original thrown/rejected value.
- * @returns an opaque Defect marker carrying `cause`.
- *
- * @example
- * ```ts
- * import { fromPromise, Defect } from "unthrown";
- *
- * const user = fromPromise(fetchUser(id), (cause) =>
- *   cause instanceof NotFoundError ? cause : Defect(cause),
- * );
- * ```
- */
-declare function Defect(cause: unknown): Defect;
-//#endregion
 //#region src/do.d.ts
 /**
  * Start a do-notation chain with an empty object scope, grown step by step with
@@ -574,6 +545,27 @@ declare function Defect(cause: unknown): Defect;
  */
 declare function Do(): Result$1<{}, never>;
 //#endregion
+//#region src/defect.d.ts
+declare const DEFECT: unique symbol;
+/**
+ * The opaque marker a `qualify` function returns to triage a cause as
+ * **unexpected**.
+ *
+ * @remarks
+ * `qualify` (passed to {@link fromPromise} / {@link fromThrowable}) returns
+ * `E | Defect`: either a modeled domain error, or a `Defect` produced by the
+ * injected `defect` helper to say "this failure is not modeled". A `Defect` is
+ * opaque — it carries the original cause for the boundary to convert into the
+ * third runtime state of a `Result`. It is **not** a public value; the only way
+ * to mint one is the `defect` helper the boundary passes to `qualify`.
+ *
+ * @internal
+ */
+type Defect = {
+  readonly [DEFECT]: true;
+  readonly cause: unknown;
+};
+//#endregion
 //#region src/interop.d.ts
 /**
  * Bridge a nullable value into a {@link Result}: absence becomes a **modeled**
@@ -601,12 +593,13 @@ declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () =>
  *
  * @remarks
  * `qualify` **must** triage every thrown cause into a modeled error `E` or a
- * {@link Defect} (via {@link Defect}) — there is no path that leaves `unknown`
- * in `E`. A throw inside `qualify` itself is treated as a `Defect`.
+ * `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`.
  *
  * 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
+ * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
  * out-of-band and must not pollute the error channel); reach for
  * {@link fromSafePromise} when every failure is a Defect.
  *
@@ -615,47 +608,49 @@ declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () =>
  * @typeParam R - `qualify`'s return type; the modeled error `E` is
  * `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted).
  * @param fn - the throwing function to wrap.
- * @param qualify - triages a thrown cause into `E` or a `Defect`.
+ * @param qualify - triages a thrown `cause` into a modeled `E`, or marks it
+ * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
  * @returns a function with the same arguments returning `Result<T, E>`.
  *
  * @example
  * ```ts
- * import { fromThrowable, Defect } from "unthrown";
- * const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
+ * import { fromThrowable } from "unthrown";
+ * const parse = fromThrowable(JSON.parse, (cause, defect) => defect(cause));
  * parse("{}").unwrap();
  * ```
  */
-declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T, qualify: (cause: unknown) => R): (...args: A) => Result$1<T, Exclude<R, Defect>>;
+declare function fromThrowable<A extends unknown[], T, R>(fn: (...args: A) => T, qualify: (cause: unknown, defect: (cause: unknown) => Defect) => R): (...args: A) => Result$1<T, Exclude<R, Defect>>;
 /**
  * Wrap a `Promise` (or a thunk producing one) as an {@link AsyncResult}, forcing
  * every rejection to be triaged.
  *
  * @remarks
  * `qualify` **must** map each rejection cause into a modeled error `E` or a
- * {@link Defect}. The returned `AsyncResult`'s internal promise never rejects;
- * `await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
- * `Defect`.
+ * `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`.
  *
  * 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`; when every
+ * `qualify` that returns *only* `defect(cause)` yields `E = never`; when every
  * rejection is a Defect, prefer {@link fromSafePromise}.
  *
  * @typeParam T - the resolved value type.
  * @typeParam R - `qualify`'s return type; the modeled error `E` is
  * `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted).
  * @param promise - the promise, or a thunk returning one.
- * @param qualify - triages a rejection cause into `E` or a `Defect`.
+ * @param qualify - triages a rejection `cause` into a modeled `E`, or marks it
+ * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
  *
  * @example
  * ```ts
- * import { fromPromise, Defect } from "unthrown";
- * const user = await fromPromise(fetchUser(id), (cause) =>
- *   cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
+ * import { fromPromise } from "unthrown";
+ * const user = await fromPromise(fetchUser(id), (cause, defect) =>
+ *   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
  * );
  * ```
  */
-declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qualify: (cause: unknown) => R): AsyncResult<T, Exclude<R, Defect>>;
+declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qualify: (cause: unknown, defect: (cause: unknown) => Defect) => R): AsyncResult$1<T, Exclude<R, Defect>>;
 /**
  * Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
  * becomes a `Defect`.
@@ -668,7 +663,7 @@ declare function fromPromise<T, R>(promise: Promise<T> | (() => Promise<T>), qua
  * @typeParam T - the resolved value type.
  * @param promise - the promise, or a thunk returning one.
  */
-declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult<T, never>;
+declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult$1<T, never>;
 /**
  * The success channel of {@link all} / {@link allAsync}: a **positional tuple**
  * for a fixed-length input (including the empty tuple), or a homogeneous
@@ -690,7 +685,7 @@ type AllOk<Rs extends readonly unknown[], Ts extends readonly unknown[]> = numbe
 /** A record of `Result`s — the input to {@link allFromDict}. */
 type ResultRecord = Record<string, Result$1<unknown, unknown>>;
 /** A record of `AsyncResult`s — the input to {@link allFromDictAsync}. */
-type AsyncResultRecord = Record<string, AsyncResult<unknown, unknown>>;
+type AsyncResultRecord = Record<string, AsyncResult$1<unknown, unknown>>;
 /**
  * Collect a tuple/array of {@link Result}s into a single `Result` of all their
  * success values.
@@ -744,7 +739,7 @@ declare function allFromDict<R extends ResultRecord>(results: R): Result$1<{ [K
  * await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
  * ```
  */
-declare function allAsync<Rs extends readonly AsyncResult<unknown, unknown>[]>(results: readonly [...Rs]): AsyncResult<AllOk<Rs, { [K in keyof Rs]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
+declare function allAsync<Rs extends readonly AsyncResult$1<unknown, unknown>[]>(results: readonly [...Rs]): AsyncResult$1<AllOk<Rs, { [K in keyof Rs]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
 /**
  * The asynchronous counterpart of {@link allFromDict}: combine a record of
  * {@link AsyncResult}s into one `AsyncResult` of a record of their values.
@@ -759,17 +754,15 @@ declare function allAsync<Rs extends readonly AsyncResult<unknown, unknown>[]>(r
  * await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
  * ```
  */
-declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): AsyncResult<{ [K in keyof R]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
+declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): AsyncResult$1<{ [K in keyof R]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
 //#endregion
 //#region src/facade.d.ts
 /**
- * Companion object grouping the standalone entry points under a single,
- * discoverable namespace: {@link Result.Ok}, {@link Result.Err},
- * {@link Result.Defect}, {@link Result.fromNullable}, {@link Result.fromThrowable},
- * {@link Result.fromPromise}, {@link Result.fromSafePromise}, {@link Result.all},
- * {@link Result.allAsync}, {@link Result.allFromDict},
- * {@link Result.allFromDictAsync}, {@link Result.isOk}, {@link Result.isErr},
- * {@link Result.isDefect}, {@link Result.isResult}.
+ * Companion object grouping the **`Result`-producing** entry points under a
+ * single, discoverable namespace: {@link Result.Ok}, {@link Result.Err},
+ * {@link Result.Do}, {@link Result.fromNullable}, {@link Result.fromThrowable},
+ * {@link Result.all}, {@link Result.allFromDict}, {@link Result.isOk},
+ * {@link Result.isErr}, {@link Result.isDefect}, {@link Result.isResult}.
  *
  * @remarks
  * Purely additive sugar — each member **is** the corresponding free function.
@@ -777,6 +770,10 @@ declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): Asyn
  * `{ Ok }` never pulls this object in. The value `Result` and the type
  * {@link Result} share one name (the companion-object pattern).
  *
+ * The **async** entry points live on the sibling {@link AsyncResult} companion
+ * (`AsyncResult.fromPromise`, `AsyncResult.all`, …), grouped by what they
+ * return — a static lives in exactly one namespace.
+ *
  * @example
  * ```ts
  * import { Result } from "unthrown";
@@ -786,22 +783,45 @@ declare function allFromDictAsync<R extends AsyncResultRecord>(results: R): Asyn
 declare const Result: {
   readonly Ok: typeof Ok;
   readonly Err: typeof Err;
-  readonly Defect: typeof Defect;
   readonly Do: typeof Do;
   readonly fromNullable: typeof fromNullable;
   readonly fromThrowable: typeof fromThrowable;
-  readonly fromPromise: typeof fromPromise;
-  readonly fromSafePromise: typeof fromSafePromise;
   readonly all: typeof all;
-  readonly allAsync: typeof allAsync;
   readonly allFromDict: typeof allFromDict;
-  readonly allFromDictAsync: typeof allFromDictAsync;
   readonly isOk: typeof isOk;
   readonly isErr: typeof isErr;
   readonly isDefect: typeof isDefect;
   readonly isResult: typeof isResult;
 };
 type Result<T, E> = Result$1<T, E>;
+/**
+ * Companion object grouping the **`AsyncResult`-producing** entry points under
+ * the matching namespace: {@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
+ * **return**, so `fromPromise`/`fromSafePromise` and the async aggregates sit
+ * here rather than on {@link Result}; the namespace already conveys "async", so
+ * the aggregates drop the `Async` suffix (`AsyncResult.all` is the free function
+ * `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.
+ *
+ * @example
+ * ```ts
+ * import { AsyncResult } from "unthrown";
+ * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
+ * ```
+ */
+declare const AsyncResult: {
+  readonly fromPromise: typeof fromPromise;
+  readonly fromSafePromise: typeof fromSafePromise;
+  readonly all: typeof allAsync;
+  readonly allFromDict: typeof allFromDictAsync;
+};
+type AsyncResult<T, E> = AsyncResult$1<T, E>;
 //#endregion
 //#region src/tagged.d.ts
 type Props = Record<string, unknown>;
@@ -923,7 +943,7 @@ declare function matchTags<T, E extends {
 }, R>(result: Result$1<T, E>, handlers: TagHandlers<T, E, R>): R;
 declare function matchTags<T, E extends {
   _tag: string;
-}, R>(result: AsyncResult<T, E>, handlers: TagHandlers<T, E, R>): Promise<R>;
+}, R>(result: AsyncResult$1<T, E>, handlers: TagHandlers<T, E, R>): Promise<R>;
 //#endregion
-export { type AsyncErrOf, type AsyncOkOf, type AsyncResult, type Awaitable, Defect, type DefectView, Do, Err, type ErrOf, type ErrView, Ok, type OkOf, type OkView, Result, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromThrowable, isDefect, isErr, isOk, isResult, matchTags };
+export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type Awaitable, type DefectView, Do, Err, type ErrOf, type ErrView, Ok, type OkOf, type OkView, Result, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromThrowable, isDefect, isErr, isOk, isResult, matchTags };
 //# sourceMappingURL=index.d.cts.map