unthrown 4.2.0 → 5.0.0-beta.0

package/dist/index.d.cts

@@ -1,3 +1,25 @@
+import { P, match, match as match$1 } from "ts-pattern";
+//#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/types.d.ts
 /**
  * Flatten an intersection into a single object literal so accumulated `bind` /
@@ -32,6 +54,49 @@ type Bound<T, K extends string, U> = Prettify<Omit<T, K> & { readonly [P in K]:
  * @category Types
  */
 type NotThenable<R> = [R] extends [PromiseLike<unknown>] ? "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap" : unknown;
+/**
+ * The ts-pattern match builder over an error union `E`, as produced by
+ * `match(error)`. This is what an error combinator's callback receives — chain
+ * `.with(pattern, handler)` on it; the combinator itself calls `.exhaustive()`,
+ * so the callback returns the **un-terminated** builder.
+ *
+ * @remarks
+ * Named via `ReturnType<typeof match<E>>` so the internal ts-pattern `Match`
+ * type (not part of ts-pattern's public exports) never has to be imported.
+ *
+ * @typeParam E - the error union being matched.
+ * @category Types
+ */
+type ErrMatcher<E> = ReturnType<typeof match$1<E>>;
+/**
+ * The shape an error-combinator callback must return: an **exhaustive**
+ * ts-pattern builder. `exhaustive` is required to be *callable* — on a builder
+ * that hasn't covered every case ts-pattern types it as a `NonExhaustiveError`
+ * (not a function), so a non-exhaustive chain fails to satisfy this and errors
+ * at the call site. `run` carries the output type.
+ *
+ * @typeParam O - the union of the branch return types (the builder's output).
+ * @internal
+ */
+type ExhaustiveMatch<O> = {
+  exhaustive: (...args: never[]) => unknown;
+  run: () => O;
+};
+/**
+ * The output of an `ExhaustiveMatch` — the union of its branch returns.
+ *
+ * @internal
+ */
+type MatchOut<M> = M extends ExhaustiveMatch<infer O> ? O : never;
+/**
+ * The outgoing modeled-error type a transforming match produces: the builder's
+ * output with the `Defect` arm **subtracted** (`Exclude<O, Defect>`, the same
+ * inference as the boundary `qualify`, Thesis #3). A branch that returns
+ * `defect(cause)` therefore contributes nothing to the modeled channel.
+ *
+ * @internal
+ */
+type MatchErrOut<M> = Exclude<MatchOut<M>, Defect>;
 /**
  * The fluent method surface every {@link Result} variant carries — the
  * combinators (`map`, `flatMap`, `mapErr`, `match`, `get`, …), documented one
@@ -48,7 +113,7 @@ type NotThenable<R> = [R] extends [PromiseLike<unknown>] ? "unthrown: combinator
  * @typeParam E - the modeled error type.
  * @category Methods
  */
-type ResultMethods<T, E> = {
+type ResultMethods<out T, out E> = {
   /**
    * Transform the success value with `f`.
    *
@@ -162,103 +227,90 @@ type ResultMethods<T, E> = {
    */
   discard(): Result$1<void, E>;
   /**
-   * Transform the modeled error with `f`.
-   *
-   * Runs `f` only on `Err`; `Ok` passes through and a `Defect` is **never**
-   * touched. If `f` throws, the throw becomes a `Defect`. An async callback is
-   * rejected at compile time ({@link NotThenable}).
+   * Transform the modeled error by **matching it exhaustively** with ts-pattern.
    *
-   * @typeParam E2 - the mapped error type.
-   * @param f - maps the current error to a new one.
-   */
-  mapErr<E2>(f: (error: E) => E2 & NotThenable<E2>): Result$1<T, E2>;
-  /**
-   * Sequence from an `Err` by producing another `Result` — the error-channel
-   * mirror of {@link ResultMethods.flatMap | flatMap}.
+   * @remarks
+   * The callback receives `match(error)` (an {@link ErrMatcher}) and the
+   * injected `defect` helper. Chain `.with(pattern, handler)` and **return the
+   * un-terminated builder** — `mapErr` calls `.exhaustive()` itself, so a
+   * missing case is a compile error at the call site (there is no `.exhaustive()`
+   * to forget, and no way to slip in `.otherwise()`). The outgoing error type is
+   * the union of the branch returns with the `Defect` arm subtracted
+   * (`Exclude<O, Defect>`) — a branch returning `defect(cause)` converts that case
+   * to a `Defect` and drops it from `E`. Runs only on `Err`; `Ok` and `Defect`
+   * pass through. A branch that throws also becomes a `Defect`.
    *
-   * Runs `f` only on `Err`; `Ok` and `Defect` pass through. If `f` throws, the
-   * throw becomes a `Defect`.
+   * `.with(P._, …)` is the deliberate uniform/catch-all (it makes the match
+   * exhaustive). Match on anything ts-pattern supports — `_tag`, `code`,
+   * structural shape, guards, or grouped patterns `.with(a, b, handler)`.
    *
-   * @typeParam U - an alternative success type `f` may produce.
-   * @typeParam E2 - the error type `f` may produce instead.
-   * @param f - produces a fallback `Result` from the current error.
+   * @typeParam M - the exhaustive builder the callback returns.
+   * @param f - builds the match over the error (returns the un-terminated builder).
    */
-  flatMapErr<U, E2>(f: (error: E) => Result$1<U, E2>): Result$1<T | U, E2>;
+  mapErr<M extends ExhaustiveMatch<unknown>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): Result$1<T, MatchErrOut<M>>;
   /**
-   * Sequence from an `Err` by producing another `Result`.
+   * Sequence from an `Err` by producing another `Result` — the error-channel
+   * mirror of {@link ResultMethods.flatMap | flatMap}, **matching the error
+   * exhaustively** ({@link ErrMatcher}; the combinator calls `.exhaustive()`).
    *
-   * @deprecated Renamed to {@link ResultMethods.flatMapErr | flatMapErr} — it is
-   * `flatMap` on the error channel, so it now follows the `…Err` convention. This
-   * alias will be removed in a future major.
+   * Each branch returns a `Result`; the outgoing channels are the unions of the
+   * branch-returned `Result`s' channels. A branch may return `defect(cause)`.
+   * Runs only on `Err`; `Ok` and `Defect` pass through.
    *
-   * @typeParam U - an alternative success type `f` may produce.
-   * @typeParam E2 - the error type `f` may produce instead.
-   * @param f - produces a fallback `Result` from the current error.
+   * @typeParam M - the exhaustive builder the callback returns.
+   * @param f - builds the match; each branch produces a fallback `Result`.
    */
-  orElse<U, E2>(f: (error: E) => Result$1<U, E2>): Result$1<T | U, E2>;
+  flatMapErr<M extends ExhaustiveMatch<Result$1<unknown, unknown> | Defect>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): Result$1<T | OkOf<MatchOut<M>>, ErrOf<MatchOut<M>>>;
   /**
    * Recover from an `Err` by producing a success value, emptying the error
-   * channel. Pairs with {@link ResultMethods.recoverDefect | recoverDefect}.
+   * channel — **matching the error exhaustively** ({@link ErrMatcher}). Pairs
+   * with {@link ResultMethods.recoverDefect | recoverDefect}.
    *
    * @remarks
    * The result type is `Result<T | U, never>`, but `never` describes only the
-   * **error** channel — a `Defect` can still be present at runtime, so do not
-   * read `never` as "total". Runs `f` only on `Err`; `Ok` and `Defect` pass
-   * through. If `f` throws, the throw becomes a `Defect`. An async callback is
-   * rejected at compile time ({@link NotThenable}).
-   *
-   * @typeParam U - the recovered success type.
-   * @param f - produces a success value from the current error.
-   */
-  recoverErr<U>(f: (error: E) => U & NotThenable<U>): Result$1<T | U, never>;
-  /**
-   * Recover from an `Err` by producing a success value.
-   *
-   * @deprecated Renamed to {@link ResultMethods.recoverErr | recoverErr} — it now
-   * pairs with {@link ResultMethods.recoverDefect | recoverDefect} and follows the
-   * `…Err` convention. This alias will be removed in a future major.
+   * **error** channel — a `Defect` can still be present at runtime. A branch may
+   * return `defect(cause)` (which stays a `Defect`, not a recovery). Runs only on
+   * `Err`; `Ok` and `Defect` pass through.
    *
-   * @typeParam U - the recovered success type.
-   * @param f - produces a success value from the current error.
+   * @typeParam M - the exhaustive builder the callback returns.
+   * @param f - builds the match; each branch produces a success value.
    */
-  recover<U>(f: (error: E) => U & NotThenable<U>): Result$1<T | U, never>;
+  recoverErr<M extends ExhaustiveMatch<unknown>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): Result$1<T | MatchErrOut<M>, never>;
   /**
-   * Run a side effect on the error and pass the `Result` through unchanged.
-   *
-   * Runs only on `Err`. If `f` throws, the result is a `Defect` whose cause is
-   * an `AggregateError` of `[thrown, original failure]` — observing a failure
-   * never destroys it. An async callback is rejected at compile time
-   * ({@link NotThenable}).
+   * Run a side effect on the error — **matched exhaustively** ({@link ErrMatcher})
+   * — and pass the `Result` through unchanged.
    *
    * @remarks
-   * As with {@link ResultMethods.tap | tap}, `f`'s return value is ignored — a
-   * failable `Result`-returning effect belongs in
-   * {@link ResultMethods.flatTapErr | flatTapErr}; an `AsyncResult`-returning
-   * one needs the chain lifted with {@link ResultMethods.toAsync | toAsync}
-   * first (the async {@link AsyncResultMethods.flatTapErr | flatTapErr}
-   * accepts both).
+   * The callback builds a match whose branches run side effects; their return
+   * values are ignored and the original `Err` flows through. Exhaustive like the
+   * transformers (use `.with(P._, …)` for a catch-all). If a branch throws, the
+   * result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
+   * failure]` — observing a failure never destroys it. A failable
+   * `Result`-returning effect belongs in
+   * {@link ResultMethods.flatTapErr | flatTapErr}.
    *
-   * @param f - the side effect (its return value is ignored).
+   * @param f - builds the match; branch returns are ignored.
    */
-  tapErr<R>(f: (error: E) => R & NotThenable<R>): Result$1<T, E>;
+  tapErr(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => ExhaustiveMatch<unknown>): Result$1<T, E>;
   /**
    * Run a **failable** side effect on the error, keeping the original error but
-   * threading the effect's own error.
+   * threading the effect's own error — **matched exhaustively**
+   * ({@link ErrMatcher}).
    *
    * @remarks
-   * The error-channel mirror of {@link ResultMethods.flatTap | flatTap}: `f`
-   * returns a `Result`, but its **success value is discarded** — on the effect's
-   * `Ok` the original `Err` flows through unchanged, while an `Err` (or `Defect`)
-   * from `f` short-circuits and threads its error (`Result<T, E | E2>`). Runs only
-   * on `Err`; `Ok` and `Defect` pass through. If `f` throws, the result is a
-   * `Defect` whose cause is an `AggregateError` of `[thrown, original failure]` —
-   * observing a failure never destroys it. Use it for a failable effect _during_
-   * error handling (e.g. writing the error to an audit log that may itself fail).
+   * The error-channel mirror of {@link ResultMethods.flatTap | flatTap}: each
+   * branch returns a `Result` whose **success value is discarded** — on the
+   * effect's `Ok` the original `Err` flows through, while an `Err`/`Defect` from a
+   * branch short-circuits and threads its error. Note the asymmetry with a
+   * *throw*: a branch that **returns** a `Defect` **replaces** the original `Err`
+   * (Defect-dominance, the short-circuit rule — it is not aggregated), whereas a
+   * branch that **throws** produces a `Defect` aggregating `[thrown, original
+   * failure]` (observing a failure by throwing never destroys it).
    *
-   * @typeParam E2 - the error type the effect may introduce.
-   * @param f - the failable side effect; its `Ok` value is ignored.
+   * @typeParam M - the exhaustive builder the callback returns.
+   * @param f - builds the match; each branch is a failable effect (its `Ok` is ignored).
    */
-  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2>): Result$1<T, E | E2>;
+  flatTapErr<E2>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => ExhaustiveMatch<Result$1<unknown, E2>>): Result$1<T, E | E2>;
   /**
    * Recover from a `Defect` — the **only** combinator that can touch one.
    *
@@ -284,23 +336,59 @@ type ResultMethods<T, E> = {
    */
   tapDefect<R>(f: (cause: unknown) => R & NotThenable<R>): Result$1<T, E>;
   /**
-   * Exhaustively fold all three runtime states into a single value of type `R`.
+   * Run a side effect on **any failure** — `Err` or `Defect` — and pass the
+   * `Result` through unchanged. The one cross-channel observer, for the shared
+   * "it went KO" concern (logging, metrics, rollback) that would otherwise be
+   * duplicated across {@link ResultMethods.tapErr | tapErr} and
+   * {@link ResultMethods.tapDefect | tapDefect}.
+   *
+   * @remarks
+   * `f` receives the narrowed **failure variant** ({@link FailureView}), not a
+   * payload — the payload union `E | unknown` would collapse to `unknown` and
+   * lose `E`'s typing. Branch on `failure.tag` to reach the typed payload
+   * (`"Err"` → `failure.error: E`, `"Defect"` → `failure.cause: unknown`), or
+   * treat it opaquely for a shared logger. Runs on `Err` and `Defect`; `Ok`
+   * passes through. It **observes without consuming**: the failure flows on
+   * unchanged — to also recover, use
+   * {@link ResultMethods.recoverErr | recoverErr} /
+   * {@link ResultMethods.recoverDefect | recoverDefect} (deliberately separate
+   * acts) or {@link ResultMethods.match | match} at the edge. If `f` throws, the
+   * result is a `Defect` whose cause is an `AggregateError` of `[thrown,
+   * original failure]` — observing a failure never destroys it. An async
+   * callback is rejected at compile time ({@link NotThenable}).
+   *
+   * @param f - the side effect over the failure variant (its return value is ignored).
+   */
+  tapFailure<R>(f: (failure: FailureView<E, T>) => R & NotThenable<R>): Result$1<T, E>;
+  /**
+   * Exhaustively fold all three runtime states into a single value.
    *
    * @remarks
    * Exactly one handler runs. Together with the throw-to-Defect guarantee, this
    * is typically the single place a pipeline is handled at the edge — mapping
    * `Ok`/`Err`/`Defect` to (for example) 2xx / 4xx / 5xx with no `try`/`catch`.
-   * (For richer matching, a `Result` is also a discriminated union — branch on
-   * its `tag` property, e.g. with `ts-pattern`.)
    *
-   * @typeParam R - the folded result type.
-   * @param cases - one handler per channel.
+   * The `err` handler does not take a single blanket callback: it receives
+   * `match(error)` (an {@link ErrMatcher}) and **matches the error exhaustively**,
+   * exactly like the error combinators. Chain `.with(pattern, handler)` and
+   * **return the un-terminated builder** — `match` calls `.exhaustive()` itself,
+   * so a missing case is a compile error at the call site (no `.exhaustive()` to
+   * forget). Use `.with(P._, …)` for a uniform catch-all. Unlike the combinators
+   * the branches receive **no `defect` helper** — `match` is total elimination
+   * to a value, with no `Defect` output channel; the `defect` case handles a
+   * `Result` that already carries one. (A `Result` is also a discriminated
+   * union — for richer whole-`Result` matching, `match(result).with(…)`.)
+   *
+   * @typeParam ROk - the `ok` handler return type.
+   * @typeParam RDefect - the `defect` handler return type.
+   * @typeParam M - the exhaustive builder the `err` handler returns.
+   * @param cases - the `ok`/`defect` handlers plus the `err` matcher builder.
    */
-  match<R>(cases: {
-    ok: (value: T) => R;
-    err: (error: E) => R;
-    defect: (cause: unknown) => R;
-  }): R;
+  match<ROk, RDefect, M extends ExhaustiveMatch<unknown>>(cases: {
+    ok: (value: T) => ROk;
+    err: (matcher: ErrMatcher<E>) => M;
+    defect: (cause: unknown) => RDefect;
+  }): ROk | RDefect | MatchOut<M>;
   /**
    * Extract the success value.
    *
@@ -318,15 +406,6 @@ type ResultMethods<T, E> = {
    * @returns the `Ok` value.
    */
   get(this: Result$1<T, never>): T;
-  /**
-   * Extract the success value.
-   *
-   * @deprecated Renamed to {@link ResultMethods.get | get}, unifying the extractor
-   * family under `get…`. This alias will be removed in a future major.
-   *
-   * @returns the `Ok` value.
-   */
-  unwrap(this: Result$1<T, never>): T;
   /**
    * Extract the modeled error.
    *
@@ -341,15 +420,6 @@ type ResultMethods<T, E> = {
    * @returns the `Err` value.
    */
   getErr(this: Result$1<never, E>): E;
-  /**
-   * Extract the modeled error.
-   *
-   * @deprecated Renamed to {@link ResultMethods.getErr | getErr}, unifying the
-   * extractor family under `get…`. This alias will be removed in a future major.
-   *
-   * @returns the `Err` value.
-   */
-  unwrapErr(this: Result$1<never, E>): E;
   /**
    * The success value, or `fallback` on `Err`.
    *
@@ -359,17 +429,6 @@ type ResultMethods<T, E> = {
    * it is never silently replaced.
    */
   getOr<U>(fallback: U): T | U;
-  /**
-   * The success value, or `fallback` on `Err`.
-   *
-   * @deprecated Renamed to {@link ResultMethods.getOr | getOr}, unifying the
-   * extractor family under `get…`. This alias will be removed in a future major.
-   *
-   * @typeParam U - the fallback type (may differ from `T`; the return widens to `T | U`).
-   * @param fallback - returned when the result is an `Err`.
-   * @throws Re-throws on a `Defect`.
-   */
-  unwrapOr<U>(fallback: U): T | U;
   /**
    * The success value, or `f(error)` on `Err`.
    *
@@ -378,17 +437,6 @@ type ResultMethods<T, E> = {
    * @throws Re-throws on a `Defect`.
    */
   getOrElse<U>(f: (error: E) => U): T | U;
-  /**
-   * The success value, or `f(error)` on `Err`.
-   *
-   * @deprecated Renamed to {@link ResultMethods.getOrElse | getOrElse}, unifying
-   * the extractor family under `get…`. This alias will be removed in a future major.
-   *
-   * @typeParam U - the fallback type (may differ from `T`; the return widens to `T | U`).
-   * @param f - lazily computes the fallback from the error.
-   * @throws Re-throws on a `Defect`.
-   */
-  unwrapOrElse<U>(f: (error: E) => U): T | U;
   /**
    * The success value, or `null` on `Err`.
    *
@@ -405,20 +453,26 @@ type ResultMethods<T, E> = {
    * The success value, or **throw** the modeled error on `Err`.
    *
    * @remarks
-   * A deliberate escape hatch off the errors-as-values model. Unlike
-   * {@link ResultMethods.get | get} (type-gated to an empty error
-   * channel), this compiles on any `Result<T, E>` and **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.recoverErr | recoverErr} / {@link ResultMethods.flatMapErr | flatMapErr}.
+   * 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.recoverErr | recoverErr} /
+   * {@link ResultMethods.flatMapErr | flatMapErr}.
+   *
+   * Type-gated as the **complement** of {@link ResultMethods.get | get}: it
+   * compiles only when the error channel is **non-empty** (`E` is not `never`) —
+   * there must be a modeled error for it to throw. On a `Result<T, never>` there
+   * is nothing to throw, so `getOrThrow` does not compile; use `get()` (which
+   * gates the other way). Together they partition extraction by the error
+   * channel's state, with no overlap.
    *
    * @returns the `Ok` value.
    * @throws the modeled `error` on `Err`; re-throws the original `cause` on a
    * `Defect` (a panic, like the rest of the `getOr…` family).
    */
-  getOrThrow(): T;
+  getOrThrow(this: [E] extends [never] ? never : Result$1<T, E>): T;
   /** Whether this result is `Ok` — narrows `this` to its {@link OkView} on `true`. */
   isOk(): this is OkView<T, E>;
   /** Whether this result is `Err` — narrows `this` to its {@link ErrView} on `true`. */
@@ -484,6 +538,30 @@ type DefectView<T = never, E = never> = ResultMethods<T, E> & {
   readonly tag: "Defect";
   readonly cause: unknown;
 };
+/**
+ * A failure variant of a {@link Result}: an {@link ErrView} **or** a
+ * {@link DefectView}. This is what a `tapFailure` callback receives — the
+ * discriminated variant rather than a payload, because the payload union
+ * `E | unknown` would collapse to `unknown` and lose `E`'s typing. Branch on
+ * `tag` to narrow (`"Err"` → `.error: E`, `"Defect"` → `.cause: unknown`).
+ *
+ * @remarks
+ * Like {@link ErrView}, the error type comes **first** (`FailureView<E, T>`) —
+ * the error is the payload you are usually here for, and a shared observer can
+ * spell just `FailureView<MyError>`.
+ *
+ * @example
+ * ```ts
+ * const logKo = (f: FailureView<ApiError>) =>
+ *   f.tag === "Err" ? logger.warn(f.error) : logger.error(f.cause);
+ * result.tapFailure(logKo);
+ * ```
+ *
+ * @typeParam E - the modeled error type.
+ * @typeParam T - the success value type (phantom here; a failure carries none).
+ * @category Types
+ */
+type FailureView<E, T = never> = ErrView<E, T> | DefectView<T, E>;
 /**
  * The core type of the library: a computation that has either succeeded with a
  * value of type `T` or failed with a *modeled* error of type `E`.
@@ -540,7 +618,7 @@ type Result$1<T, E> = OkView<T, E> | ErrView<E, T> | DefectView<T, E>;
  *
  * @category Types
  */
-type Awaitable<T> = {
+type Awaitable<out T> = {
   then<R = T>(onfulfilled?: ((value: T) => R | PromiseLike<R>) | null): PromiseLike<R>;
 };
 /**
@@ -563,7 +641,7 @@ type Awaitable<T> = {
  * @typeParam E - the modeled error type.
  * @category Methods
  */
-type AsyncResultMethods<T, E> = {
+type AsyncResultMethods<out T, out E> = {
   /**
    * Asynchronous {@link ResultMethods.map | map}: transforms the success value
    * with `f`. `f` is synchronous; a throw becomes a `Defect`. An async callback
@@ -611,32 +689,22 @@ type AsyncResultMethods<T, E> = {
   /** Asynchronous {@link ResultMethods.discard | discard}: drops the value, collapsing the success type to `void`. */
   discard(): AsyncResult$1<void, E>;
   /**
-   * Asynchronous {@link ResultMethods.mapErr | mapErr}. `f` is synchronous; a
-   * throw becomes a `Defect`. An async callback is rejected at compile time
-   * ({@link NotThenable}).
-   */
-  mapErr<E2>(f: (error: E) => E2 & NotThenable<E2>): AsyncResult$1<T, E2>;
-  /**
-   * Asynchronous {@link ResultMethods.flatMapErr | flatMapErr}. `f` may return a
-   * `Result` or an `AsyncResult`.
+   * Asynchronous {@link ResultMethods.mapErr | mapErr} — the same exhaustive
+   * {@link ErrMatcher} form; the combinator calls `.exhaustive()`.
    */
-  flatMapErr<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult$1<U, E2>): AsyncResult$1<T | U, E2>;
+  mapErr<M extends ExhaustiveMatch<unknown>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): AsyncResult$1<T, MatchErrOut<M>>;
   /**
-   * @deprecated Renamed to {@link AsyncResultMethods.flatMapErr | flatMapErr}.
-   * This alias will be removed in a future major.
+   * Asynchronous {@link ResultMethods.flatMapErr | flatMapErr} — the same
+   * exhaustive {@link ErrMatcher} form. Unlike the sync form, a branch 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>;
+  flatMapErr<M extends ExhaustiveMatch<Result$1<unknown, unknown> | AsyncResult$1<unknown, unknown> | Defect>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): AsyncResult$1<T | OkOf<MatchOut<M>> | AsyncOkOf<MatchOut<M>>, ErrOf<MatchOut<M>> | AsyncErrOf<MatchOut<M>>>;
   /**
-   * Asynchronous {@link ResultMethods.recoverErr | recoverErr}. `f` is
-   * synchronous; a throw becomes a `Defect`. An async callback is rejected at
-   * compile time ({@link NotThenable}).
-   */
-  recoverErr<U>(f: (error: E) => U & NotThenable<U>): AsyncResult$1<T | U, never>;
-  /**
-   * @deprecated Renamed to {@link AsyncResultMethods.recoverErr | recoverErr}.
-   * This alias will be removed in a future major.
+   * Asynchronous {@link ResultMethods.recoverErr | recoverErr} — the same
+   * exhaustive {@link ErrMatcher} form. Branches are synchronous; a throw
+   * becomes a `Defect`.
    */
-  recover<U>(f: (error: E) => U & NotThenable<U>): AsyncResult$1<T | U, never>;
+  recoverErr<M extends ExhaustiveMatch<unknown>>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => M): AsyncResult$1<T | MatchErrOut<M>, never>;
   /**
    * Asynchronous {@link ResultMethods.tapErr | tapErr}. `f` is synchronous; if it
    * throws, the result is a `Defect` whose cause is an `AggregateError` of
@@ -646,7 +714,7 @@ type AsyncResultMethods<T, E> = {
    * too — a failable effect belongs in
    * {@link AsyncResultMethods.flatTapErr | flatTapErr}.
    */
-  tapErr<R>(f: (error: E) => R & NotThenable<R>): AsyncResult$1<T, E>;
+  tapErr(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => ExhaustiveMatch<unknown>): AsyncResult$1<T, E>;
   /**
    * Asynchronous {@link ResultMethods.flatTapErr | flatTapErr} — the
    * error-channel mirror of `flatTap`. `f` may return a `Result` **or** an
@@ -655,7 +723,7 @@ type AsyncResultMethods<T, E> = {
    * an `AggregateError` of `[thrown, original failure]` — observing a failure
    * never destroys it.
    */
-  flatTapErr<E2>(f: (error: E) => Result$1<unknown, E2> | AsyncResult$1<unknown, E2>): AsyncResult$1<T, E | E2>;
+  flatTapErr<E2>(f: (matcher: ErrMatcher<E>, defect: (cause: unknown) => Defect) => ExhaustiveMatch<Result$1<unknown, E2> | AsyncResult$1<unknown, E2>>): AsyncResult$1<T, E | E2>;
   /**
    * Asynchronous {@link ResultMethods.recoverDefect | recoverDefect}. `f` may
    * return a `Result` or an `AsyncResult`.
@@ -669,50 +737,40 @@ type AsyncResultMethods<T, E> = {
    */
   tapDefect<R>(f: (cause: unknown) => R & NotThenable<R>): AsyncResult$1<T, E>;
   /**
-   * Asynchronous {@link ResultMethods.match | match}. Handlers are synchronous;
-   * resolves to a `Promise<R>`.
+   * Asynchronous {@link ResultMethods.tapFailure | tapFailure} — the
+   * cross-channel observer. `f` receives the narrowed failure variant
+   * ({@link FailureView}); if it throws, the result is a `Defect` whose cause
+   * is an `AggregateError` of `[thrown, original failure]` — observing a
+   * failure never destroys it. An async callback is rejected at compile time
+   * ({@link NotThenable}).
    */
-  match<R>(cases: {
-    ok: (value: T) => R;
-    err: (error: E) => R;
-    defect: (cause: unknown) => R;
-  }): Promise<R>;
+  tapFailure<R>(f: (failure: FailureView<E, T>) => R & NotThenable<R>): AsyncResult$1<T, E>;
+  /**
+   * Asynchronous {@link ResultMethods.match | match}. Handlers are synchronous
+   * (the `err` handler returns an exhaustive {@link ErrMatcher} builder, no
+   * `defect` helper); resolves to a `Promise` of the folded value.
+   */
+  match<ROk, RDefect, M extends ExhaustiveMatch<unknown>>(cases: {
+    ok: (value: T) => ROk;
+    err: (matcher: ErrMatcher<E>) => M;
+    defect: (cause: unknown) => RDefect;
+  }): Promise<ROk | RDefect | MatchOut<M>>;
   /**
    * Asynchronous {@link ResultMethods.get | get}. Compiles only when the
    * error channel is empty (`this: AsyncResult<T, never>`); the returned promise
    * rejects on a `Defect` (rethrowing its cause).
    */
   get(this: AsyncResult$1<T, never>): Promise<T>;
-  /**
-   * @deprecated Renamed to {@link AsyncResultMethods.get | get}. This alias will
-   * be removed in a future major.
-   */
-  unwrap(this: AsyncResult$1<T, never>): Promise<T>;
   /**
    * Asynchronous {@link ResultMethods.getErr | getErr}. Compiles only when
    * the success channel is empty (`this: AsyncResult<never, E>`); the returned
    * promise rejects on a `Defect` (rethrowing its cause).
    */
   getErr(this: AsyncResult$1<never, E>): Promise<E>;
-  /**
-   * @deprecated Renamed to {@link AsyncResultMethods.getErr | getErr}. This alias
-   * will be removed in a future major.
-   */
-  unwrapErr(this: AsyncResult$1<never, E>): Promise<E>;
   /** Asynchronous {@link ResultMethods.getOr | getOr}. */
   getOr<U>(fallback: U): Promise<T | U>;
-  /**
-   * @deprecated Renamed to {@link AsyncResultMethods.getOr | getOr}. This alias
-   * will be removed in a future major.
-   */
-  unwrapOr<U>(fallback: U): Promise<T | U>;
   /** Asynchronous {@link ResultMethods.getOrElse | getOrElse}. */
   getOrElse<U>(f: (error: E) => U): Promise<T | U>;
-  /**
-   * @deprecated Renamed to {@link AsyncResultMethods.getOrElse | getOrElse}. This
-   * alias will be removed in a future major.
-   */
-  unwrapOrElse<U>(f: (error: E) => U): Promise<T | U>;
   /** Asynchronous {@link ResultMethods.getOrNull | getOrNull}. */
   getOrNull(): Promise<T | null>;
   /** Asynchronous {@link ResultMethods.getOrUndefined | getOrUndefined}. */
@@ -720,9 +778,10 @@ type AsyncResultMethods<T, E> = {
   /**
    * Asynchronous {@link ResultMethods.getOrThrow | getOrThrow} — the returned
    * promise **rejects** with the modeled error on `Err` (or the original cause
-   * on a `Defect`), rather than throwing synchronously.
+   * on a `Defect`), rather than throwing synchronously. Gated the same way: it
+   * compiles only when the error channel is non-empty (`E` is not `never`).
    */
-  getOrThrow(): Promise<T>;
+  getOrThrow(this: [E] extends [never] ? never : AsyncResult$1<T, E>): Promise<T>;
 };
 /**
  * The asynchronous counterpart of {@link Result}: an awaitable wrapper carrying
@@ -795,7 +854,7 @@ type ErrOf<R> = R extends {
  *
  * @category Types
  */
-type AsyncOkOf<R> = R extends AsyncResult$1<infer T, unknown> ? T : never;
+type AsyncOkOf<R> = R extends Awaitable<infer Res> ? OkOf<Res> : never;
 /**
  * Extract the error type `E` from an {@link AsyncResult} type — the async
  * counterpart of {@link ErrOf}.
@@ -809,7 +868,7 @@ type AsyncOkOf<R> = R extends AsyncResult$1<infer T, unknown> ? T : never;
  *
  * @category Types
  */
-type AsyncErrOf<R> = R extends AsyncResult$1<unknown, infer E> ? E : never;
+type AsyncErrOf<R> = R extends Awaitable<infer Res> ? ErrOf<Res> : never;
 //#endregion
 //#region src/constructors.d.ts
 /**
@@ -996,12 +1055,12 @@ 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}
+ * 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>` /
@@ -1009,11 +1068,11 @@ declare function isDefect<T, E>(r: Result$1<T, E>): r is DefectView<T, E>;
  * 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
  */
-declare class UnwrapError<E = unknown> extends Error {
+declare class GetError<E = unknown> extends Error {
   /**
    * The offending value: the `Err` error for `get()`, or the `Ok` value for
    * `getErr()`.
@@ -1092,27 +1151,6 @@ declare function isResult(x: unknown): x is Result$1<unknown, unknown>;
  */
 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**
@@ -1547,8 +1585,10 @@ type TaggedErrorConstructor<Tag extends string> = {
  * 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
+ * `_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`:
@@ -1586,78 +1626,28 @@ declare function TaggedError<Tag extends string>(tag: Tag, options?: {
   readonly name?: string;
 }): TaggedErrorConstructor<Tag>;
 /**
- * The handler object {@link matchTags} requires: a branch per error tag, plus
- * `Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
- * enforced by the type, with no `.exhaustive()` to forget.
- *
- * @typeParam T - the success value type.
- * @typeParam E - the tagged error union.
- * @typeParam R - the folded result type.
- *
- * @category Types
- */
-type TagHandlers<T, E extends {
-  _tag: string;
-}, R> = {
-  Ok: (value: T) => R;
-  Defect: (cause: unknown) => R;
-} & { [K in E["_tag"]]: (error: Extract<E, {
-  _tag: K;
-}>) => R; };
-/**
- * The channel-handler names are reserved: an error tag named `"Ok"` or
- * `"Defect"` would collide with them inside {@link TagHandlers}, so
- * {@link matchTags} rejects such unions at the call site.
- *
- * @internal
- */
-type ReservedTagError = 'unthrown: error tags "Ok" and "Defect" are reserved by matchTags — rename the colliding tag (TaggedError\'s options.name can keep the display name)';
-/**
- * Exhaustively fold a {@link Result} (or {@link AsyncResult}) whose error type is
- * a tagged union, dispatching each error to the handler matching its `_tag`.
- *
- * @remarks
- * The `handlers` object must provide `Ok`, `Defect`, and exactly one function
- * per error tag; each tag's handler receives the narrowed error variant. A
- * missing tag is a compile error. For an `AsyncResult`, the fold resolves to a
- * `Promise<R>`. At runtime, an error whose `_tag` has no handler (possible only
- * outside the typed contract) is routed to the `Defect` handler — an unmodeled
- * tag is an unmodeled failure. Tags named `"Ok"` or `"Defect"` are rejected at
- * compile time.
+ * 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 T - the success value type.
- * @typeParam E - the tagged error union (`E extends { _tag: string }`).
- * @typeParam R - the folded result type.
- * @param result - the result to fold.
- * @param handlers - one branch per channel/tag.
+ * @typeParam Tag - the string literal tag to match.
+ * @param value - the `_tag` to match.
  *
  * @category Tagged errors
  *
  * @example
  * ```ts
- * import { Ok, Err, matchTags, TaggedError, type Result } from "unthrown";
- *
- * class NotFound extends TaggedError("NotFound") {}
- * class Forbidden extends TaggedError("Forbidden")<{ user: string }> {}
- *
- * const fold = (r: Result<number, NotFound | Forbidden>) =>
- *   matchTags(r, {
- *     Ok: (n) => `got ${n}`,
- *     Defect: (cause) => `bug: ${String(cause)}`,
- *     NotFound: () => "404",
- *     Forbidden: (e) => `403 for ${e.user}`,
- *   });
- *
- * fold(Ok(1)); // => "got 1"
- * fold(Err(new Forbidden({ user: "ada" }))); // => "403 for ada"
+ * result.mapErr((matcher) =>
+ *   matcher
+ *     .with(tag("NotFound"), () => new NotFoundException())
+ *     .with(tag("Conflict"), (e) => new ConflictException(e.key)),
+ * );
  * ```
  */
-declare function matchTags<T, E extends {
-  _tag: string;
-}, R>(result: Result$1<T, E>, handlers: TagHandlers<T, E, R> & ([Extract<E["_tag"], "Ok" | "Defect">] extends [never] ? unknown : ReservedTagError)): R;
-declare function matchTags<T, E extends {
-  _tag: string;
-}, R>(result: AsyncResult$1<T, E>, handlers: TagHandlers<T, E, R> & ([Extract<E["_tag"], "Ok" | "Defect">] extends [never] ? unknown : ReservedTagError)): Promise<R>;
+declare function tag<const Tag extends string>(value: Tag): {
+  _tag: Tag;
+};
 //#endregion
-export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, Err, ErrAsync, type ErrOf, type ErrView, type NotThenable, Ok, OkAsync, type OkOf, type OkView, Result, type ResultMethods, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, matchTags };
+export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match, tag };
 //# sourceMappingURL=index.d.cts.map