---
url: /unthrown/api/core.md
---
**unthrown**

***

# unthrown

## Facade

### AsyncResult

Defined in: [packages/core/src/facade.ts:160](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L160)

The asynchronous counterpart of [Result](#result-1): an awaitable wrapper carrying
the [AsyncResultMethods](#asyncresultmethods) surface, collapsing to a `Result<T, E>` when
`await`-ed. Shares its name with the [companion object](#asyncresult-1)
above (value and type are one name); this is the type half.

#### Remarks

**Combinator callbacks are synchronous.** A raw `Promise` may never enter an
`AsyncResult` method — that would be an un-qualified async boundary, and its
rejection would silently become a `Defect`, skipping the triage that
[fromPromise](#frompromise) forces. To do further async work, re-enter through a
qualified boundary and compose it: `ar.flatMap((v) => fromPromise(work(v),
qualify))`. The eliminators (`get`, …) return promises; the binds
(`flatMap`, `flatTap`, `flatMapErrCases`, `recoverDefect`) additionally accept an
`AsyncResult`. Its combinators are documented one per entry — with their
async signatures — on [AsyncResultMethods](#asyncresultmethods). For "which one do I reach
for?", see the [Choosing a combinator](/reference/combinators) guide.

To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.

#### Extends

* [`Awaitable`](#awaitable)<[`Result`](#result)<`T`, `E`>>.[`AsyncResultMethods`](#asyncresultmethods)<`T`, `E`>

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |
| `E` | the modeled error type. |

#### Methods

##### as()

```ts
as<U>(value): AsyncResult<U, E>;
```

Defined in: [packages/core/src/types.ts:879](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L879)

Asynchronous [as](#as-5): replaces the value with `value`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E`>

###### Inherited from

```ts
AsyncResultMethods.as
```

##### bind()

```ts
bind<K, U, E2>(name, f): AsyncResult<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:863](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L863)

Asynchronous [bind](#bind-5) (do-notation). `f` may return
a `Result` **or** an `AsyncResult`; its value is bound under `name` in the
accumulating scope.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `K` |
| `f` | (`scope`) => | [`Result`](#result)<`U`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`U`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.bind
```

##### discard()

```ts
discard(): AsyncResult<void, E>;
```

Defined in: [packages/core/src/types.ts:881](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L881)

Asynchronous [discard](#discard-5): drops the value, collapsing the success type to `void`.

###### Returns

[`AsyncResult`](#asyncresult)<`void`, `E`>

###### Inherited from

```ts
AsyncResultMethods.discard
```

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): AsyncResult<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:889](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L889)

Asynchronous [ensure](#ensure-5): validate the success
value — and, with a type-guard predicate (this overload), **refine** it —
failing into the modeled channel with `Err(onFail(value))`. Both callbacks
are synchronous (an async `onFail` is rejected at compile time,
[NotThenable](#notthenable)); a throw in either becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `value is U` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.ensure
```

###### Call Signature

```ts
ensure<E2>(predicate, onFail): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:894](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L894)

Boolean form of the asynchronous [ensure](#ensure-5) — validates without refining, keeping `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.ensure
```

##### flatMap()

```ts
flatMap<U, E2>(f): AsyncResult<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:830](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L830)

Asynchronous [flatMap](#flatmap-5). Unlike the sync form,
`f` may return a `Result` **or** an `AsyncResult` (never a raw `Promise`); a
throw becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => | [`Result`](#result)<`U`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`U`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E` | `E2`>

###### Remarks

The async branch of `f`'s return type is spelled `Awaitable<Result<U, E2>> &
{ flatMap: unknown }` rather than `AsyncResult<U, E2>`: this is what you get
by returning an `AsyncResult` (it satisfies both), but inference runs through
the `Awaitable` then-channel so `U`/`E2` stay precise instead of collapsing
to `unknown`, while the `{ flatMap: unknown }` marker still rejects a bare
`Promise` (it has no `flatMap`). Just return a `Result` or an `AsyncResult`.

###### Inherited from

```ts
AsyncResultMethods.flatMap
```

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): AsyncResult<
  | T
  | OkOf<MatchOut<M>>
  | AsyncOkOf<MatchOut<M>>, 
  | ErrOf<MatchOut<M>>
  | AsyncErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:915](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L915)

Asynchronous [flatMapErrCases](#flatmaperrcases-5) — the same
exhaustive [ErrMatcher](#errmatcher) form. Unlike the sync form, a branch may
return a `Result` **or** an `AsyncResult`.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`< | [`Result`](#result)<`unknown`, `unknown`> | `Defect` | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `unknown`>> & `ReturnAnAsyncResultNotAPromise`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |

###### Returns

[`AsyncResult`](#asyncresult)<
| `T`
| [`OkOf`](#okof)<`MatchOut`<`M`>>
| [`AsyncOkOf`](#asyncokof)<`MatchOut`<`M`>>,
| [`ErrOf`](#errof)<`MatchOut`<`M`>>
| [`AsyncErrOf`](#asyncerrof)<`MatchOut`<`M`>>>

###### Inherited from

```ts
AsyncResultMethods.flatMapErrCases
```

##### flatTap()

```ts
flatTap<E2>(f): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:851](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L851)

Asynchronous [flatTap](#flattap-5) — 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`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => | [`Result`](#result)<`unknown`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.flatTap
```

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:968](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L968)

Asynchronous [flatTapErrCases](#flattaperrcases-5) — the
error-channel mirror of `flatTap`. `f` may return a `Result` **or** an
`AsyncResult`; its `Ok` value is discarded, an `Err`/`Defect` from `f`
threads through, and if `f` throws — or a branch returns the injected
`defect(cause)` marker, the expression-position form of a throw — the result
is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`< | [`Result`](#result)<`unknown`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `E2`>> & `ReturnAnAsyncResultNotAPromise`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.flatTapErrCases
```

##### get()

```ts
get(this): Promise<T>;
```

Defined in: [packages/core/src/types.ts:1017](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1017)

Asynchronous [get](#get-5). Compiles only when the
error channel is empty (`this: AsyncResult<T, never>`); the returned promise
rejects on a `Defect` (rethrowing its cause).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`AsyncResult`](#asyncresult)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`Promise`<`T`>

###### Inherited from

```ts
AsyncResultMethods.get
```

##### getErr()

```ts
getErr(this): Promise<E>;
```

Defined in: [packages/core/src/types.ts:1027](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1027)

Asynchronous [getErr](#geterr-5). Compiles only when
the success channel is empty (`this: AsyncResult<never, E>`); the returned
promise rejects on a `Defect` (rethrowing its cause).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`AsyncResult`](#asyncresult)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`Promise`<`E`>

###### Inherited from

```ts
AsyncResultMethods.getErr
```

##### getOr()

```ts
getOr<U>(fallback): Promise<T | U>;
```

Defined in: [packages/core/src/types.ts:1033](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1033)

Asynchronous [getOr](#getor-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fallback` | `U` |

###### Returns

`Promise`<`T` | `U`>

###### Inherited from

```ts
AsyncResultMethods.getOr
```

##### getOrElse()

```ts
getOrElse<U>(f): Promise<T | U>;
```

Defined in: [packages/core/src/types.ts:1035](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1035)

Asynchronous [getOrElse](#getorelse-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`error`) => `U` |

###### Returns

`Promise`<`T` | `U`>

###### Inherited from

```ts
AsyncResultMethods.getOrElse
```

##### getOrNull()

```ts
getOrNull(): Promise<T | null>;
```

Defined in: [packages/core/src/types.ts:1037](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1037)

Asynchronous [getOrNull](#getornull-5).

###### Returns

`Promise`<`T` | `null`>

###### Inherited from

```ts
AsyncResultMethods.getOrNull
```

##### getOrThrow()

```ts
getOrThrow(this): Promise<T>;
```

Defined in: [packages/core/src/types.ts:1046](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1046)

Asynchronous [getOrThrow](#getorthrow-5) — the returned
promise **rejects** with the modeled error on `Err` (or the original cause
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`).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`AsyncResult`](#asyncresult)<`T`, `E`> |

###### Returns

`Promise`<`T`>

###### Inherited from

```ts
AsyncResultMethods.getOrThrow
```

##### getOrUndefined()

```ts
getOrUndefined(): Promise<T | undefined>;
```

Defined in: [packages/core/src/types.ts:1039](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1039)

Asynchronous [getOrUndefined](#getorundefined-5).

###### Returns

`Promise`<`T` | `undefined`>

###### Inherited from

```ts
AsyncResultMethods.getOrUndefined
```

##### let()

```ts
let<K, U>(name, f): AsyncResult<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:874](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L874)

Asynchronous [let](#let-5) (do-notation). `f` returns a
plain value, bound under `name`. An async callback is rejected at compile
time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `K` |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> |

###### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

###### Inherited from

```ts
AsyncResultMethods.let
```

##### map()

```ts
map<U>(f): AsyncResult<U, E>;
```

Defined in: [packages/core/src/types.ts:816](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L816)

Asynchronous [map](#map-5): transforms the success value
with `f`. `f` is synchronous; a throw becomes a `Defect`. An async callback
is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E`>

###### Inherited from

```ts
AsyncResultMethods.map
```

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): AsyncResult<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:904](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L904)

Asynchronous [mapErrCases](#maperrcases-5) — the same exhaustive
[ErrMatcher](#errmatcher) form; the combinator calls `.exhaustive()`. Branches are
synchronous — an `async` branch is a compile error, as on the sync surface.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

###### Inherited from

```ts
AsyncResultMethods.mapErrCases
```

##### match()

```ts
match<ROk, RDefect, M>(cases): Promise<ROk | RDefect | MatchOut<M>>;
```

Defined in: [packages/core/src/types.ts:1007](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1007)

Asynchronous [match](#match-5). Handlers are synchronous
(the `errCases` handler returns an exhaustive [ErrMatcher](#errmatcher) builder, no
`defect` helper); resolves to a `Promise` of the folded value.

###### Type Parameters

| Type Parameter |
| ------ |
| `ROk` |
| `RDefect` |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } |
| `cases.defect` | (`cause`) => `RDefect` |
| `cases.errCases` | (`matcher`) => `M` |
| `cases.ok` | (`value`) => `ROk` |

###### Returns

`Promise`<`ROk` | `RDefect` | `MatchOut`<`M`>>

###### Inherited from

```ts
AsyncResultMethods.match
```

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): AsyncResult<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:981](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L981)

Asynchronous [recoverDefect](#recoverdefect-5). `f` may
return a `Result` or an `AsyncResult`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`cause`) => | [`Result`](#result)<`U`, `E2`> | [`AsyncResult`](#asyncresult)<`U`, `E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T` | `U`, `E` | `E2`>

###### Inherited from

```ts
AsyncResultMethods.recoverDefect
```

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): AsyncResult<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:933](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L933)

Asynchronous [recoverErrCases](#recovererrcases-5) — the same
exhaustive [ErrMatcher](#errmatcher) form. Branches are synchronous; a throw
becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `T` | `E`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

###### Inherited from

```ts
AsyncResultMethods.recoverErrCases
```

##### tap()

```ts
tap<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:844](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L844)

Asynchronous [tap](#tap-5). `f` is synchronous; a throw
becomes a `Defect`. An async callback is rejected at compile time
([NotThenable](#notthenable)) — and so is a returned `AsyncResult` (it is
awaitable). Beware the near-miss: *calling* an `AsyncResult`-returning
effect inside the callback without returning it compiles and leaves the
effect floating — fire-and-forget, never awaited, its `Err`/`Defect`
unobserved. If the effect returns a `Result`/`AsyncResult`, use
[flatTap](#flattap-4).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
AsyncResultMethods.tap
```

##### tapDefect()

```ts
tapDefect<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:990](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L990)

Asynchronous [tapDefect](#tapdefect-5). 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 ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
AsyncResultMethods.tapDefect
```

##### tapErrCases()

```ts
tapErrCases<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:952](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L952)

Asynchronous [tapErrCases](#taperrcases-5). `f` is synchronous; if it
throws — or a branch returns the injected `defect(cause)` marker, the
expression-position form of a throw — the result is a `Defect` whose cause
is an `AggregateError` of `[thrown, original failure]` — observing a failure
never destroys it. An
async branch is rejected at compile time ([NotThenable](#notthenable) on the
builder output) — other branch results are discarded, so a rejected
`Promise` would float unobserved. The
[tap](#tap-4) fire-and-forget caveat applies here
too — a failable effect belongs in
[flatTapErrCases](#flattaperrcases-4).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
AsyncResultMethods.tapErrCases
```

##### tapFailure()

```ts
tapFailure<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:1000](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1000)

Asynchronous [tapFailure](#tapfailure-5) — the
cross-channel observer. `f` receives the narrowed failure variant
([FailureView](#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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
AsyncResultMethods.tapFailure
```

##### then()

```ts
then<R>(onfulfilled?): PromiseLike<R>;
```

Defined in: [packages/core/src/types.ts:787](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L787)

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | [`Result`](#result)<`T`, `E`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `onfulfilled?` | ((`value`) => `R` | `PromiseLike`<`R`>) | `null` |

###### Returns

`PromiseLike`<`R`>

###### Inherited from

```ts
Awaitable.then
```

***

### Result

```ts
type Result<T, E> = 
  | OkView<T, E>
  | ErrView<E, T>
  | DefectView<T, E>;
```

Defined in: [packages/core/src/facade.ts:59](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L59)

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`. Shares its
name with the [companion object](#result-1) above (the value and type are
one name); this is the type half.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |
| `E` | the modeled error type (only anticipated domain failures). |

#### Remarks

A `Result` is a **discriminated union** of three variants, distinguished by a
`tag` of `"Ok"` | `"Err"` | `"Defect"`:

* **`Ok`** — a success carrying a `value: T`.
* **`Err`** — a modeled, anticipated failure carrying an `error: E`.
* **`Defect`** — an *unmodeled* failure carrying an unknown `cause`. A Defect
  never appears in `E`; it is the library's third, out-of-band channel.

Because it is a real union, you can match it natively (a `switch` on `tag`, or
the built-in `match(...).with({ tag: "Ok" }, …).exhaustive()`), *and* it
carries the full method surface for fluent chaining. Either way, the payload
(`value`/`error`/`cause`) is only reachable after you narrow — so "check
before you access" still holds.

TypeDoc can't list a union's methods on this alias: its fluent combinators
(`map`, `flatMap`, `match`, `get`, …) are documented one per entry on
[ResultMethods](#resultmethods) — the shared method surface every variant carries. For
"which one do I reach for?", see the
[Choosing a combinator](/reference/combinators) guide.

#### Example

```ts
import { Ok, Err, type Result } from "unthrown";

function half(n: number): Result<number, "odd"> {
  return n % 2 === 0 ? Ok(n / 2) : Err("odd");
}

const message = half(10).match({
  ok: (n) => `got ${n}`,
  // every case of `E` named — here the one literal it holds
  errCases: (matcher) => matcher.with("odd", () => "failed: odd"),
  defect: (cause) => `bug: ${String(cause)}`,
});
```

***

### AsyncResult

```ts
const AsyncResult: object;
```

Defined in: [packages/core/src/facade.ts:160](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L160)

Companion object grouping the **`AsyncResult`-producing** entry points under
the matching namespace: [AsyncResult.Ok](#property-ok), [AsyncResult.Err](#property-err),
[AsyncResult.Do](#property-do), [AsyncResult.fromExecutor](#property-fromexecutor),
[AsyncResult.fromPromise](#property-frompromise), [AsyncResult.fromSafePromise](#property-fromsafepromise),
[AsyncResult.all](#property-all), [AsyncResult.allFromDict](#property-allfromdict),
[AsyncResult.validateAll](#property-validateall), [AsyncResult.validateAllFromDict](#property-validateallfromdict).

#### Type Declaration

#### Constructors

| Name | Type | Default value | Defined in |
| ------ | ------ | ------ | ------ |
|  `Err()` | <`E`>(`error`) => [`AsyncResult`](#asyncresult)<`never`, `E`> | `ErrAsync` | [packages/core/src/facade.ts:162](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L162) |
|  `Ok()` | { (): [`AsyncResult`](#asyncresult)<`void`, `never`>; <`T`> (`value`): [`AsyncResult`](#asyncresult)<`T`, `never`>; } | `OkAsync` | [packages/core/src/facade.ts:161](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L161) |

#### Interop

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `fromExecutor()` | <`T`, `E`>(`executor`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | [packages/core/src/facade.ts:164](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L164) |
|  `fromPromise()` | <`T`, `R`>(`promise`, `qualify`, ...`_guard`) => [`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, `Defect`>> | [packages/core/src/facade.ts:165](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L165) |
|  `fromSafePromise()` | <`T`>(`promise`) => [`AsyncResult`](#asyncresult)<`T`, `never`> | [packages/core/src/facade.ts:166](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L166) |

#### Do-notation

| Name | Type | Default value | Defined in |
| ------ | ------ | ------ | ------ |
|  `Do()` | () => [`AsyncResult`](#asyncresult)<{ }, `never`> | `DoAsync` | [packages/core/src/facade.ts:163](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L163) |

#### Aggregate

| Name | Type | Default value | Defined in |
| ------ | ------ | ------ | ------ |
|  `all()` | <`Rs`>(`results`) => [`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, { \[K in string | number | symbol]: AsyncOkOf\<Rs\[K]> }>, [`AsyncErrOf`](#asyncerrof)<`Rs`\[`number`]>> | `allAsync` | [packages/core/src/facade.ts:167](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L167) |
|  `allFromDict()` | <`R`>(`results`) => [`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: AsyncOkOf\<R\[K]> }, [`AsyncErrOf`](#asyncerrof)<`R`\[keyof `R`]>> | `allFromDictAsync` | [packages/core/src/facade.ts:168](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L168) |
|  `validateAll()` | <`Rs`, `E2`>(`results`, `merge`) => [`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, { \[K in string | number | symbol]: AsyncOkOf\<Rs\[K]> }>, `E2`> | `validateAllAsync` | [packages/core/src/facade.ts:169](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L169) |
|  `validateAllFromDict()` | <`R`, `E2`>(`results`, `merge`) => [`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: AsyncOkOf\<R\[K]> }, `E2`> | `validateAllFromDictAsync` | [packages/core/src/facade.ts:170](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L170) |

#### Remarks

The async sibling of [Result](#result-1). Statics are grouped by what they
**return**, so the pre-lifted constructors, `fromExecutor`,
`fromPromise`/`fromSafePromise`, and the async aggregates sit here rather
than on [Result](#result-1); the namespace
already conveys "async", so the members drop the `Async` suffix their free
functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
`ErrAsync`; `AsyncResult.Do` is `DoAsync`; `AsyncResult.all` is `allAsync`;
`AsyncResult.allFromDict` is
`allFromDictAsync`; `AsyncResult.validateAll` is `validateAllAsync`). Like
[Result](#result-1), the free functions remain the
primary, tree-shakeable API; the value `AsyncResult` and the type
[AsyncResult](#asyncresult-1) share one name.

#### Example

```ts
import { AsyncResult } from "unthrown";
const user = await AsyncResult.fromPromise(
  fetchUser(id),
  (c, defect) => defect(c),
);
user.get(); // => the fetched user (on success)
```

***

### Result

```ts
const Result: object;
```

Defined in: [packages/core/src/facade.ts:59](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L59)

Companion object grouping the **`Result`-producing** entry points under a
single, discoverable namespace: [Result.Ok](#property-ok-1), [Result.Err](#property-err-1),
[Result.Do](#property-do-1), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
[Result.fromSafeThrowable](#property-fromsafethrowable), [Result.all](#property-all-1),
[Result.allFromDict](#property-allfromdict-1), [Result.validateAll](#property-validateall-1),
[Result.validateAllFromDict](#property-validateallfromdict-1), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
[Result.isDefect](#property-isdefect), [Result.isResult](#property-isresult).

#### Type Declaration

#### Constructors

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `Err()` | <`E`>(`error`) => [`Result`](#result)<`never`, `E`> | [packages/core/src/facade.ts:61](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L61) |
|  `Ok()` | { (): [`Result`](#result)<`void`, `never`>; <`T`> (`value`): [`Result`](#result)<`T`, `never`>; } | [packages/core/src/facade.ts:60](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L60) |

#### Interop

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `fromNullable()` | <`T`, `E`>(`value`, `onAbsent`) => [`Result`](#result)<`NonNullable`<`T`>, `E`> | [packages/core/src/facade.ts:63](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L63) |
|  `fromSafeThrowable()` | <`A`, `T`>(`fn`) => (...`args`) => [`Result`](#result)<`T`, `never`> | [packages/core/src/facade.ts:65](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L65) |
|  `fromThrowable()` | <`A`, `T`, `R`>(`fn`, `qualify`) => (...`args`) => [`Result`](#result)<`T`, `Exclude`<`R`, `Defect`>> | [packages/core/src/facade.ts:64](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L64) |

#### Do-notation

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `Do()` | () => [`Result`](#result)<{ }, `never`> | [packages/core/src/facade.ts:62](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L62) |

#### Guards

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `isDefect()` | <`T`, `E`>(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:72](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L72) |
|  `isErr()` | <`T`, `E`>(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:71](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L71) |
|  `isOk()` | <`T`, `E`>(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:70](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L70) |
|  `isResult()` | (`x`) => `x is Result<unknown, unknown>` | [packages/core/src/facade.ts:73](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L73) |

#### Aggregate

| Name | Type | Defined in |
| ------ | ------ | ------ |
|  `all()` | <`Rs`>(`results`) => [`Result`](#result)<`AllOk`<`Rs`, { \[K in string | number | symbol]: OkOf\<Rs\[K]> }>, [`ErrOf`](#errof)<`Rs`\[`number`]>> | [packages/core/src/facade.ts:66](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L66) |
|  `allFromDict()` | <`R`>(`results`) => [`Result`](#result)<{ \[K in string | number | symbol]: OkOf\<R\[K]> }, [`ErrOf`](#errof)<`R`\[keyof `R`]>> | [packages/core/src/facade.ts:67](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L67) |
|  `validateAll()` | <`Rs`, `E2`>(`results`, `merge`) => [`Result`](#result)<`AllOk`<`Rs`, { \[K in string | number | symbol]: OkOf\<Rs\[K]> }>, `E2`> | [packages/core/src/facade.ts:68](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L68) |
|  `validateAllFromDict()` | <`R`, `E2`>(`results`, `merge`) => [`Result`](#result)<{ \[K in string | number | symbol]: OkOf\<R\[K]> }, `E2`> | [packages/core/src/facade.ts:69](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/facade.ts#L69) |

#### Remarks

Purely additive sugar — each member **is** the corresponding free function.
The free functions remain the primary, tree-shakeable API; importing only
`{ Ok }` never pulls this object in. The value `Result` and the type
[Result](#result-1) share one name (the companion-object pattern).

The **async** entry points live on the sibling [AsyncResult](#asyncresult-1) companion
(`AsyncResult.fromPromise`, `AsyncResult.all`, …), grouped by what they
return — a static lives in exactly one namespace.

#### Example

```ts
import { Result } from "unthrown";
Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).get(); // => 2
```

## Types

### DefectView

Defined in: [packages/core/src/types.ts:738](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L738)

The `Defect` variant of a [Result](#result-1): an unmodeled failure carrying a
`cause`. This is what a successful `isDefect` guard narrows to, exposing
`.cause`. It also carries the shared fluent surface ([ResultMethods](#resultmethods)).

#### Example

```ts
if (r.isDefect()) r.cause; // r: DefectView<T, E> here — .cause is `unknown`
```

#### Extends

* [`ResultMethods`](#resultmethods)<`T`, `E`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` | `never` |
| `E` | `never` |

#### Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
|  `cause` | `readonly` | `unknown` | [packages/core/src/types.ts:740](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L740) |
|  `tag` | `readonly` | `"Defect"` | [packages/core/src/types.ts:739](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L739) |

#### Methods

##### as()

```ts
as<U>(value): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:288](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L288)

Replace the success value with a constant `value`.

Runs only on `Ok`; `Err` and `Defect` pass through.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the replacement value type. |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.as
```

##### bind()

```ts
bind<K, U, E2>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:261](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L261)

Do-notation: run `f` for a `Result` and **bind its value** under `name` in
an accumulating object scope.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the bound value is stored under. |
| `U` | the bound value type. |
| `E2` | the error type `f` may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => [`Result`](#result)<`U`, `E2`> | produces a `Result` from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

###### Remarks

Begin a chain with [Do](#do) (an empty object scope) and grow it step by
step. `f` receives the scope accumulated so far and returns a `Result`; on
`Ok` the value is added as `{ ...scope, [name]: value }`, on `Err`/`Defect`
the chain short-circuits. Errors union (`E | E2`). A throw becomes a
`Defect` — as does calling `bind` on a non-object or non-plain scope (e.g.
`Ok(5).bind`, or a class instance whose getters the merge would drop), which
is misuse: the scope is always a plain object inside a real `Do()` chain.
(`let` is the pure-value counterpart.)

###### Inherited from

```ts
ResultMethods.bind
```

##### discard()

```ts
discard(): Result<void, E>;
```

Defined in: [packages/core/src/types.ts:297](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L297)

Drop the success value, collapsing the success type to `void`.

The named form of `map(() => undefined)`. Runs only on `Ok` (the value is
replaced with `undefined`); `Err` and `Defect` pass through. Unlike
`as(undefined)` — which produces `Result<undefined, E>` — the success type
is `void`: the value's story ends here.

###### Returns

[`Result`](#result)<`void`, `E`>

###### Inherited from

```ts
ResultMethods.discard
```

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:332](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L332)

Validate the success value — keep the `Ok` when `predicate` holds,
otherwise fail into the **modeled** channel with `Err(onFail(value))`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the refined success type (type-guard form). |
| `E2` | the error type `onFail` produces. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `predicate` | (`value`) => `value is U` | the check; a type guard refines `T` to `U`. |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | maps the failing value to the modeled error. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Remarks

The named form of `flatMap((v) => (p(v) ? Ok(v) : Err(e)))`. With a
**type-guard** predicate (`(v): v is U`) the success type is **refined** to
`U` on the way through (this overload). Runs only on `Ok` — a passing value
flows through as the *same* `Ok`; `Err` and `Defect` pass through
untouched. A throw in `predicate` or `onFail` becomes a `Defect`.

Both callbacks are synchronous: an async `onFail` is rejected at compile
time ([NotThenable](#notthenable)), and an async predicate does not type-check
either — its `Promise<boolean>` is not a `boolean` (and, being truthy,
would have silently always passed).

###### Example

```ts
// boolean form: gate a value
Ok(-1).ensure((n) => n > 0, (n) => `negative: ${n}`); // Err("negative: -1")

// type-guard form: refine the success type
declare const r: Result<string | number, "e">;
const s = r.ensure(
  (v): v is string => typeof v === "string",
  () => "not_a_string" as const,
); // Result<string, "e" | "not_a_string">
```

###### Inherited from

```ts
ResultMethods.ensure
```

###### Call Signature

```ts
ensure<E2>(predicate, onFail): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:340](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L340)

Boolean form of [ensure](#ensure-5) — validates without
refining, keeping the success type `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.ensure
```

##### flatMap()

```ts
flatMap<U, E2>(f): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:204](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L204)

Sequence a dependent, `Result`-returning step (monadic bind).

Runs `f` only on `Ok`; `Err` and `Defect` pass through. The error channels
combine, widening to `E | E2`. If `f` throws, the throw becomes a `Defect`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the success type of the next step. |
| `E2` | the error type the next step may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`U`, `E2`> | produces the next `Result` from the current success value. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.flatMap
```

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): Result<T | OkOf<MatchOut<M>>, ErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:397](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L397)

Sequence from an `Err` by producing another `Result` — the error-channel
mirror of [flatMap](#flatmap-5), **matching the error
exhaustively** ([ErrMatcher](#errmatcher); the combinator calls `.exhaustive()`).

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.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `unknown`> | `Defect`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a fallback `Result`. |

###### Returns

[`Result`](#result)<`T` | [`OkOf`](#okof)<`MatchOut`<`M`>>, [`ErrOf`](#errof)<`MatchOut`<`M`>>>

###### Inherited from

```ts
ResultMethods.flatMapErrCases
```

##### flatTap()

```ts
flatTap<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:240](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L240)

Run a **failable** side effect on the success value, keeping the original
value but threading the effect's error.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E2` | the error type the effect may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`unknown`, `E2`> | the failable side effect; its `Ok` value is ignored. |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

This is to [tap](#tap-5) what
[flatMap](#flatmap-5) is to [map](#map-5):
`f` returns a `Result`, but its **success value is discarded** — on success
the original value flows through (`Result<T, E | E2>`), while an `Err` (or
`Defect`) from `f` short-circuits. Runs only on `Ok`; `Err` and `Defect` pass
through. If `f` throws, the throw becomes a `Defect`. Use it for a validation
or write whose *result* matters but whose *value* you don't need.

###### Inherited from

```ts
ResultMethods.flatTap
```

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:478](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L478)

Run a **failable** side effect on the error, keeping the original error but
threading the effect's own error — **matched exhaustively**
([ErrMatcher](#errmatcher)).

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `E2`>> | builds the match; each branch is a failable effect (its `Ok` is ignored). |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

The error-channel mirror of [flatTap](#flattap-5): 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-state `Result` **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). A branch returning the injected `defect(cause)` marker —
reachable under a `returnType` pin — follows the *throw* rule, since it is
the lint-clean, expression-position form of one.

###### Inherited from

```ts
ResultMethods.flatTapErrCases
```

##### get()

```ts
get(this): T;
```

Defined in: [packages/core/src/types.ts:583](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L583)

Extract the success value.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`Result`](#result)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`T`

the `Ok` value.

###### Remarks

Compiles only when the error channel is empty (`E = never`) — eliminate
modeled errors first (`match` / `recoverErrCases` / `flatMapErrCases`), or reach for the
`getOr` / `getOrElse` / `getOrNull` / `getOrUndefined` family (which
recover an `Err`). The gate is a `this` type that becomes an explanatory
string when `E` is not `never`, so the compile error names the fix.

`E = never` empties only the **modeled** error channel — a `Defect` can
still be present, and `get()` **rethrows its original cause** (it
*panics*); `Result<T, never>` does not mean `get()` cannot throw.

###### Inherited from

```ts
ResultMethods.get
```

##### getErr()

```ts
getErr(this): E;
```

Defined in: [packages/core/src/types.ts:601](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L601)

Extract the modeled error.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`Result`](#result)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`E`

the `Err` value.

###### Remarks

Compiles only when the success channel is empty (`T = never`) — eliminate
the success case first. `T = never` is rarely the case in practice (a
`Result` you hold usually still has a success type), so to inspect an
error prefer an `isErr()` guard or, in tests, `@unthrown/vitest`'s
`toBeErrWith`. A `Defect` still **rethrows its original cause** (a defect is
a bug, not an absent value), so this does not mean `getErr()` can't throw.

###### Inherited from

```ts
ResultMethods.getErr
```

##### getOr()

```ts
getOr<U>(fallback): T | U;
```

Defined in: [packages/core/src/types.ts:614](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L614)

The success value, or `fallback` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fallback` | `U` | returned when the result is an `Err` (may be a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect` — a Defect is a bug, not an absent value, so
it is never silently replaced.

###### Inherited from

```ts
ResultMethods.getOr
```

##### getOrElse()

```ts
getOrElse<U>(f): T | U;
```

Defined in: [packages/core/src/types.ts:622](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L622)

The success value, or `f(error)` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`error`) => `U` | lazily computes the fallback from the error (may return a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrElse
```

##### getOrNull()

```ts
getOrNull(): T | null;
```

Defined in: [packages/core/src/types.ts:628](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L628)

The success value, or `null` on `Err`.

###### Returns

`T` | `null`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrNull
```

##### getOrThrow()

```ts
getOrThrow(this): T;
```

Defined in: [packages/core/src/types.ts:666](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L666)

The success value, or **throw** the modeled error on `Err`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`Result`](#result)<`T`, `E`> |

###### Returns

`T`

the `Ok` value.

###### Remarks

A deliberate escape hatch off the errors-as-values model — it **throws the
`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:
[recoverErrCases](#recovererrcases-5) empties `E`, so
[get](#get-5) compiles and a case routed to the injected
`defect(...)` panics with its original cause — with every case still named.
[match](#match-5) and
[flatMapErrCases](#flatmaperrcases-5) 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 [get](#get-5): 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.

###### Throws

the modeled `error` on `Err`; re-throws the original `cause` on a
`Defect` (a panic, like the rest of the `getOr…` family).

###### Inherited from

```ts
ResultMethods.getOrThrow
```

##### getOrUndefined()

```ts
getOrUndefined(): T | undefined;
```

Defined in: [packages/core/src/types.ts:634](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L634)

The success value, or `undefined` on `Err`.

###### Returns

`T` | `undefined`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrUndefined
```

##### isDefect()

```ts
isDefect(): this is DefectView<T, E>;
```

Defined in: [packages/core/src/types.ts:677](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L677)

Whether this result is a `Defect` — narrows `this` to its [DefectView](#defectview) on `true`.

###### Returns

`this is DefectView<T, E>`

###### Inherited from

```ts
ResultMethods.isDefect
```

##### isErr()

```ts
isErr(): this is ErrView<E, T>;
```

Defined in: [packages/core/src/types.ts:675](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L675)

Whether this result is `Err` — narrows `this` to its [ErrView](#errview) on `true`.

###### Returns

`this is ErrView<E, T>`

###### Inherited from

```ts
ResultMethods.isErr
```

##### isOk()

```ts
isOk(): this is OkView<T, E>;
```

Defined in: [packages/core/src/types.ts:673](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L673)

Whether this result is `Ok` — narrows `this` to its [OkView](#okview) on `true`.

###### Returns

`this is OkView<T, E>`

###### Inherited from

```ts
ResultMethods.isOk
```

##### let()

```ts
let<K, U>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L280)

Do-notation: run `f` for a **plain value** and bind it under `name` in the
accumulating object scope. The pure-value counterpart of [bind](#bind-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the value is stored under. |
| `U` | the value type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> | computes a value from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

###### Remarks

`f` receives the scope and returns a value (not a `Result`); it is added as
`{ ...scope, [name]: value }`. Runs only on `Ok`; `Err`/`Defect` pass
through. A throw becomes a `Defect`. An async callback is rejected at
compile time ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.let
```

##### map()

```ts
map<U>(f): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:193](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L193)

Transform the success value with `f`.

Runs `f` only on `Ok`; `Err` and `Defect` pass through untouched. If `f`
throws, the thrown value is captured as a `Defect`.

An async callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the mapped success type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> | maps the current success value to a new one. |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.map
```

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:379](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L379)

Transform the modeled error by **matching it exhaustively**.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match over the error (returns the un-terminated builder). |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

###### Remarks

The callback receives `match(error)` (an [ErrMatcher](#errmatcher)) and the
injected `defect` helper. Chain `.with(pattern, handler)` and **return the
un-terminated builder** — `mapErrCases` 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`. Branches are
**synchronous**: an `async` branch is a compile error (its `Promise` would
land in `E` un-triaged), and a thenable slipped past the types becomes a
`Defect`.

**Name every case.** Match on anything the matcher supports — `_tag`,
`code`, structural shape, guards — and group the cases that share a handler
with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
hatch**, not the default: it makes any match exhaustive, so it also absorbs
every case `E` grows later. Two uses are sanctioned — a helper generic in
`E`, where no arm list can prove exhaustiveness against an unresolved type
parameter, and an `E` that is a single type rather than a union of cases
(see [P](#p) for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
its `recommended` preset) flags the rest.

###### Inherited from

```ts
ResultMethods.mapErrCases
```

##### match()

```ts
match<ROk, RDefect, M>(cases): ROk | RDefect | MatchOut<M>;
```

Defined in: [packages/core/src/types.ts:562](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L562)

Exhaustively fold all three runtime states into a single value.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `ROk` | the `ok` handler return type. |
| `RDefect` | the `defect` handler return type. |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the `errCases` handler returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } | the `ok`/`defect` handlers plus the `errCases` matcher builder. |
| `cases.defect` | (`cause`) => `RDefect` | - |
| `cases.errCases` | (`matcher`) => `M` | - |
| `cases.ok` | (`value`) => `ROk` | - |

###### Returns

`ROk` | `RDefect` | `MatchOut`<`M`>

###### 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`.

The `errCases` handler does not take a single blanket callback: it receives
`match(error)` (an [ErrMatcher](#errmatcher)) and **matches the error exhaustively**,
exactly like the error combinators — which is why the key carries the same
`…Cases` suffix. 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).
Folding at the edge names every case too — `.with(P._, …)` is the wildcard
escape hatch, not the default. 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(…)`.)

###### Inherited from

```ts
ResultMethods.match
```

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): Result<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:498](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L498)

Recover from a `Defect` — the **only** combinator that can touch one.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | a success type the recovery may produce. |
| `E2` | an error type the recovery may produce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => [`Result`](#result)<`U`, `E2`> | maps the Defect's unknown cause to a recovering `Result`. |

###### Returns

[`Result`](#result)<`T` | `U`, `E` | `E2`>

###### Remarks

Runs `f` only when a `Defect` is present, re-entering the modeled world by
returning a `Result` (an `Ok` or a fresh `Err`). `Ok` and `Err` pass
through. Recovering a Defect should be rare: usually you let it bubble to
the edge. If `f` throws, the throw becomes a new `Defect`.

###### Inherited from

```ts
ResultMethods.recoverDefect
```

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:421](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L421)

Recover from an `Err` by producing a success value, emptying the error
channel — **matching the error exhaustively** ([ErrMatcher](#errmatcher)). Pairs
with [recoverDefect](#recoverdefect-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a success value. |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `T` | `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

###### Remarks

The result type is `Result<T | U, never>`, but `never` describes only the
**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. Branches are **synchronous**: an
`async` branch is a compile error, and a thenable slipped past the types
becomes a `Defect`.

###### Inherited from

```ts
ResultMethods.recoverErrCases
```

##### tap()

```ts
tap<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:223](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L223)

Run a side effect on the success value and pass the `Result` through
unchanged.

Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`. An async
callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f`'s return value is **ignored** — a `Result` returned by the effect
compiles but is discarded, `Err` and all. If the effect can fail, sequence
it instead of tapping it: a `Result`-returning effect goes in
[flatTap](#flattap-5); an `AsyncResult`-returning effect
cannot be sequenced from the sync surface — lift the chain with
[toAsync](#toasync-3) and use the async
[flatTap](#flattap-4) (which accepts both).

###### Inherited from

```ts
ResultMethods.tap
```

##### tapDefect()

```ts
tapDefect<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:508](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L508)

Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
`Defect` through unchanged. 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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the unknown cause. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.tapDefect
```

##### tapErrCases()

```ts
tapErrCases<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L450)

Run a side effect on the error — **matched exhaustively** ([ErrMatcher](#errmatcher))
— and pass the `Result` through unchanged.

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> | builds the match; branch returns are ignored, bar `defect(cause)`. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

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, and like them it wants every case named — `.with(P._, …)`
remains the wildcard escape hatch. If a branch throws, the
result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it. An **async branch is
rejected at compile time** ([NotThenable](#notthenable) on the builder output):
because the branch results are discarded, a returned `Promise` would float
unobserved and its rejection would vanish. The one branch return that is
**not** discarded is the injected `defect(cause)` marker: it is the
lint-clean, expression-position form of a `throw`, so it follows the throw
rule above (an `AggregateError` of `[the branch's cause, original
failure]`), never a silent no-op. A failable
`Result`-returning effect belongs in
[flatTapErrCases](#flattaperrcases-5).

###### Inherited from

```ts
ResultMethods.tapErrCases
```

##### tapFailure()

```ts
tapFailure<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:534](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L534)

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 [tapErrCases](#taperrcases-5) and
[tapDefect](#tapdefect-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the failure variant (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f` receives the narrowed **failure variant** ([FailureView](#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
[recoverErrCases](#recovererrcases-5) /
[recoverDefect](#recoverdefect-5) (deliberately separate
acts) or [match](#match-5) 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 ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.tapFailure
```

##### toAsync()

```ts
toAsync(): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:680](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L680)

Lift this synchronous `Result` into an [AsyncResult](#asyncresult-1).

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.toAsync
```

***

### ErrView

Defined in: [packages/core/src/types.ts:721](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L721)

The `Err` variant of a [Result](#result-1): a modeled failure carrying an `error`.
This is what a successful `isErr` guard narrows to, exposing `.error`. It also
carries the shared fluent surface ([ResultMethods](#resultmethods)).

#### Remarks

**Note the parameter order: `ErrView<E, T>` puts the error type *first*** — the
reverse of the `<T, E>` order used by [OkView](#okview), [DefectView](#defectview), and
[Result](#result-1) — because `Result<T, E>` narrows to `ErrView<E, T>` (the error is
the payload the guard makes reachable). You rarely write it by hand (a failed
`isErr()` narrows to it for you); if you do, mind the flip — `ErrView<MyError,
MyValue>`, not `ErrView<MyValue, MyError>`.

#### Example

```ts
if (r.isErr()) r.error; // r: ErrView<E, T> here — .error is an E
```

#### Extends

* [`ResultMethods`](#resultmethods)<`T`, `E`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `E` | - |
| `T` | `never` |

#### Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
|  `error` | `readonly` | `E` | [packages/core/src/types.ts:723](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L723) |
|  `tag` | `readonly` | `"Err"` | [packages/core/src/types.ts:722](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L722) |

#### Methods

##### as()

```ts
as<U>(value): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:288](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L288)

Replace the success value with a constant `value`.

Runs only on `Ok`; `Err` and `Defect` pass through.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the replacement value type. |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.as
```

##### bind()

```ts
bind<K, U, E2>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:261](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L261)

Do-notation: run `f` for a `Result` and **bind its value** under `name` in
an accumulating object scope.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the bound value is stored under. |
| `U` | the bound value type. |
| `E2` | the error type `f` may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => [`Result`](#result)<`U`, `E2`> | produces a `Result` from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

###### Remarks

Begin a chain with [Do](#do) (an empty object scope) and grow it step by
step. `f` receives the scope accumulated so far and returns a `Result`; on
`Ok` the value is added as `{ ...scope, [name]: value }`, on `Err`/`Defect`
the chain short-circuits. Errors union (`E | E2`). A throw becomes a
`Defect` — as does calling `bind` on a non-object or non-plain scope (e.g.
`Ok(5).bind`, or a class instance whose getters the merge would drop), which
is misuse: the scope is always a plain object inside a real `Do()` chain.
(`let` is the pure-value counterpart.)

###### Inherited from

```ts
ResultMethods.bind
```

##### discard()

```ts
discard(): Result<void, E>;
```

Defined in: [packages/core/src/types.ts:297](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L297)

Drop the success value, collapsing the success type to `void`.

The named form of `map(() => undefined)`. Runs only on `Ok` (the value is
replaced with `undefined`); `Err` and `Defect` pass through. Unlike
`as(undefined)` — which produces `Result<undefined, E>` — the success type
is `void`: the value's story ends here.

###### Returns

[`Result`](#result)<`void`, `E`>

###### Inherited from

```ts
ResultMethods.discard
```

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:332](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L332)

Validate the success value — keep the `Ok` when `predicate` holds,
otherwise fail into the **modeled** channel with `Err(onFail(value))`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the refined success type (type-guard form). |
| `E2` | the error type `onFail` produces. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `predicate` | (`value`) => `value is U` | the check; a type guard refines `T` to `U`. |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | maps the failing value to the modeled error. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Remarks

The named form of `flatMap((v) => (p(v) ? Ok(v) : Err(e)))`. With a
**type-guard** predicate (`(v): v is U`) the success type is **refined** to
`U` on the way through (this overload). Runs only on `Ok` — a passing value
flows through as the *same* `Ok`; `Err` and `Defect` pass through
untouched. A throw in `predicate` or `onFail` becomes a `Defect`.

Both callbacks are synchronous: an async `onFail` is rejected at compile
time ([NotThenable](#notthenable)), and an async predicate does not type-check
either — its `Promise<boolean>` is not a `boolean` (and, being truthy,
would have silently always passed).

###### Example

```ts
// boolean form: gate a value
Ok(-1).ensure((n) => n > 0, (n) => `negative: ${n}`); // Err("negative: -1")

// type-guard form: refine the success type
declare const r: Result<string | number, "e">;
const s = r.ensure(
  (v): v is string => typeof v === "string",
  () => "not_a_string" as const,
); // Result<string, "e" | "not_a_string">
```

###### Inherited from

```ts
ResultMethods.ensure
```

###### Call Signature

```ts
ensure<E2>(predicate, onFail): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:340](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L340)

Boolean form of [ensure](#ensure-5) — validates without
refining, keeping the success type `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.ensure
```

##### flatMap()

```ts
flatMap<U, E2>(f): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:204](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L204)

Sequence a dependent, `Result`-returning step (monadic bind).

Runs `f` only on `Ok`; `Err` and `Defect` pass through. The error channels
combine, widening to `E | E2`. If `f` throws, the throw becomes a `Defect`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the success type of the next step. |
| `E2` | the error type the next step may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`U`, `E2`> | produces the next `Result` from the current success value. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.flatMap
```

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): Result<T | OkOf<MatchOut<M>>, ErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:397](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L397)

Sequence from an `Err` by producing another `Result` — the error-channel
mirror of [flatMap](#flatmap-5), **matching the error
exhaustively** ([ErrMatcher](#errmatcher); the combinator calls `.exhaustive()`).

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.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `unknown`> | `Defect`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a fallback `Result`. |

###### Returns

[`Result`](#result)<`T` | [`OkOf`](#okof)<`MatchOut`<`M`>>, [`ErrOf`](#errof)<`MatchOut`<`M`>>>

###### Inherited from

```ts
ResultMethods.flatMapErrCases
```

##### flatTap()

```ts
flatTap<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:240](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L240)

Run a **failable** side effect on the success value, keeping the original
value but threading the effect's error.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E2` | the error type the effect may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`unknown`, `E2`> | the failable side effect; its `Ok` value is ignored. |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

This is to [tap](#tap-5) what
[flatMap](#flatmap-5) is to [map](#map-5):
`f` returns a `Result`, but its **success value is discarded** — on success
the original value flows through (`Result<T, E | E2>`), while an `Err` (or
`Defect`) from `f` short-circuits. Runs only on `Ok`; `Err` and `Defect` pass
through. If `f` throws, the throw becomes a `Defect`. Use it for a validation
or write whose *result* matters but whose *value* you don't need.

###### Inherited from

```ts
ResultMethods.flatTap
```

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:478](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L478)

Run a **failable** side effect on the error, keeping the original error but
threading the effect's own error — **matched exhaustively**
([ErrMatcher](#errmatcher)).

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `E2`>> | builds the match; each branch is a failable effect (its `Ok` is ignored). |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

The error-channel mirror of [flatTap](#flattap-5): 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-state `Result` **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). A branch returning the injected `defect(cause)` marker —
reachable under a `returnType` pin — follows the *throw* rule, since it is
the lint-clean, expression-position form of one.

###### Inherited from

```ts
ResultMethods.flatTapErrCases
```

##### get()

```ts
get(this): T;
```

Defined in: [packages/core/src/types.ts:583](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L583)

Extract the success value.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`Result`](#result)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`T`

the `Ok` value.

###### Remarks

Compiles only when the error channel is empty (`E = never`) — eliminate
modeled errors first (`match` / `recoverErrCases` / `flatMapErrCases`), or reach for the
`getOr` / `getOrElse` / `getOrNull` / `getOrUndefined` family (which
recover an `Err`). The gate is a `this` type that becomes an explanatory
string when `E` is not `never`, so the compile error names the fix.

`E = never` empties only the **modeled** error channel — a `Defect` can
still be present, and `get()` **rethrows its original cause** (it
*panics*); `Result<T, never>` does not mean `get()` cannot throw.

###### Inherited from

```ts
ResultMethods.get
```

##### getErr()

```ts
getErr(this): E;
```

Defined in: [packages/core/src/types.ts:601](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L601)

Extract the modeled error.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`Result`](#result)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`E`

the `Err` value.

###### Remarks

Compiles only when the success channel is empty (`T = never`) — eliminate
the success case first. `T = never` is rarely the case in practice (a
`Result` you hold usually still has a success type), so to inspect an
error prefer an `isErr()` guard or, in tests, `@unthrown/vitest`'s
`toBeErrWith`. A `Defect` still **rethrows its original cause** (a defect is
a bug, not an absent value), so this does not mean `getErr()` can't throw.

###### Inherited from

```ts
ResultMethods.getErr
```

##### getOr()

```ts
getOr<U>(fallback): T | U;
```

Defined in: [packages/core/src/types.ts:614](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L614)

The success value, or `fallback` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fallback` | `U` | returned when the result is an `Err` (may be a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect` — a Defect is a bug, not an absent value, so
it is never silently replaced.

###### Inherited from

```ts
ResultMethods.getOr
```

##### getOrElse()

```ts
getOrElse<U>(f): T | U;
```

Defined in: [packages/core/src/types.ts:622](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L622)

The success value, or `f(error)` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`error`) => `U` | lazily computes the fallback from the error (may return a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrElse
```

##### getOrNull()

```ts
getOrNull(): T | null;
```

Defined in: [packages/core/src/types.ts:628](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L628)

The success value, or `null` on `Err`.

###### Returns

`T` | `null`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrNull
```

##### getOrThrow()

```ts
getOrThrow(this): T;
```

Defined in: [packages/core/src/types.ts:666](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L666)

The success value, or **throw** the modeled error on `Err`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`Result`](#result)<`T`, `E`> |

###### Returns

`T`

the `Ok` value.

###### Remarks

A deliberate escape hatch off the errors-as-values model — it **throws the
`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:
[recoverErrCases](#recovererrcases-5) empties `E`, so
[get](#get-5) compiles and a case routed to the injected
`defect(...)` panics with its original cause — with every case still named.
[match](#match-5) and
[flatMapErrCases](#flatmaperrcases-5) 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 [get](#get-5): 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.

###### Throws

the modeled `error` on `Err`; re-throws the original `cause` on a
`Defect` (a panic, like the rest of the `getOr…` family).

###### Inherited from

```ts
ResultMethods.getOrThrow
```

##### getOrUndefined()

```ts
getOrUndefined(): T | undefined;
```

Defined in: [packages/core/src/types.ts:634](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L634)

The success value, or `undefined` on `Err`.

###### Returns

`T` | `undefined`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrUndefined
```

##### isDefect()

```ts
isDefect(): this is DefectView<T, E>;
```

Defined in: [packages/core/src/types.ts:677](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L677)

Whether this result is a `Defect` — narrows `this` to its [DefectView](#defectview) on `true`.

###### Returns

`this is DefectView<T, E>`

###### Inherited from

```ts
ResultMethods.isDefect
```

##### isErr()

```ts
isErr(): this is ErrView<E, T>;
```

Defined in: [packages/core/src/types.ts:675](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L675)

Whether this result is `Err` — narrows `this` to its [ErrView](#errview) on `true`.

###### Returns

`this is ErrView<E, T>`

###### Inherited from

```ts
ResultMethods.isErr
```

##### isOk()

```ts
isOk(): this is OkView<T, E>;
```

Defined in: [packages/core/src/types.ts:673](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L673)

Whether this result is `Ok` — narrows `this` to its [OkView](#okview) on `true`.

###### Returns

`this is OkView<T, E>`

###### Inherited from

```ts
ResultMethods.isOk
```

##### let()

```ts
let<K, U>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L280)

Do-notation: run `f` for a **plain value** and bind it under `name` in the
accumulating object scope. The pure-value counterpart of [bind](#bind-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the value is stored under. |
| `U` | the value type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> | computes a value from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

###### Remarks

`f` receives the scope and returns a value (not a `Result`); it is added as
`{ ...scope, [name]: value }`. Runs only on `Ok`; `Err`/`Defect` pass
through. A throw becomes a `Defect`. An async callback is rejected at
compile time ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.let
```

##### map()

```ts
map<U>(f): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:193](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L193)

Transform the success value with `f`.

Runs `f` only on `Ok`; `Err` and `Defect` pass through untouched. If `f`
throws, the thrown value is captured as a `Defect`.

An async callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the mapped success type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> | maps the current success value to a new one. |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.map
```

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:379](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L379)

Transform the modeled error by **matching it exhaustively**.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match over the error (returns the un-terminated builder). |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

###### Remarks

The callback receives `match(error)` (an [ErrMatcher](#errmatcher)) and the
injected `defect` helper. Chain `.with(pattern, handler)` and **return the
un-terminated builder** — `mapErrCases` 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`. Branches are
**synchronous**: an `async` branch is a compile error (its `Promise` would
land in `E` un-triaged), and a thenable slipped past the types becomes a
`Defect`.

**Name every case.** Match on anything the matcher supports — `_tag`,
`code`, structural shape, guards — and group the cases that share a handler
with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
hatch**, not the default: it makes any match exhaustive, so it also absorbs
every case `E` grows later. Two uses are sanctioned — a helper generic in
`E`, where no arm list can prove exhaustiveness against an unresolved type
parameter, and an `E` that is a single type rather than a union of cases
(see [P](#p) for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
its `recommended` preset) flags the rest.

###### Inherited from

```ts
ResultMethods.mapErrCases
```

##### match()

```ts
match<ROk, RDefect, M>(cases): ROk | RDefect | MatchOut<M>;
```

Defined in: [packages/core/src/types.ts:562](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L562)

Exhaustively fold all three runtime states into a single value.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `ROk` | the `ok` handler return type. |
| `RDefect` | the `defect` handler return type. |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the `errCases` handler returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } | the `ok`/`defect` handlers plus the `errCases` matcher builder. |
| `cases.defect` | (`cause`) => `RDefect` | - |
| `cases.errCases` | (`matcher`) => `M` | - |
| `cases.ok` | (`value`) => `ROk` | - |

###### Returns

`ROk` | `RDefect` | `MatchOut`<`M`>

###### 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`.

The `errCases` handler does not take a single blanket callback: it receives
`match(error)` (an [ErrMatcher](#errmatcher)) and **matches the error exhaustively**,
exactly like the error combinators — which is why the key carries the same
`…Cases` suffix. 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).
Folding at the edge names every case too — `.with(P._, …)` is the wildcard
escape hatch, not the default. 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(…)`.)

###### Inherited from

```ts
ResultMethods.match
```

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): Result<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:498](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L498)

Recover from a `Defect` — the **only** combinator that can touch one.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | a success type the recovery may produce. |
| `E2` | an error type the recovery may produce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => [`Result`](#result)<`U`, `E2`> | maps the Defect's unknown cause to a recovering `Result`. |

###### Returns

[`Result`](#result)<`T` | `U`, `E` | `E2`>

###### Remarks

Runs `f` only when a `Defect` is present, re-entering the modeled world by
returning a `Result` (an `Ok` or a fresh `Err`). `Ok` and `Err` pass
through. Recovering a Defect should be rare: usually you let it bubble to
the edge. If `f` throws, the throw becomes a new `Defect`.

###### Inherited from

```ts
ResultMethods.recoverDefect
```

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:421](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L421)

Recover from an `Err` by producing a success value, emptying the error
channel — **matching the error exhaustively** ([ErrMatcher](#errmatcher)). Pairs
with [recoverDefect](#recoverdefect-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a success value. |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E` | `T`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

###### Remarks

The result type is `Result<T | U, never>`, but `never` describes only the
**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. Branches are **synchronous**: an
`async` branch is a compile error, and a thenable slipped past the types
becomes a `Defect`.

###### Inherited from

```ts
ResultMethods.recoverErrCases
```

##### tap()

```ts
tap<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:223](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L223)

Run a side effect on the success value and pass the `Result` through
unchanged.

Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`. An async
callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f`'s return value is **ignored** — a `Result` returned by the effect
compiles but is discarded, `Err` and all. If the effect can fail, sequence
it instead of tapping it: a `Result`-returning effect goes in
[flatTap](#flattap-5); an `AsyncResult`-returning effect
cannot be sequenced from the sync surface — lift the chain with
[toAsync](#toasync-3) and use the async
[flatTap](#flattap-4) (which accepts both).

###### Inherited from

```ts
ResultMethods.tap
```

##### tapDefect()

```ts
tapDefect<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:508](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L508)

Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
`Defect` through unchanged. 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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the unknown cause. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.tapDefect
```

##### tapErrCases()

```ts
tapErrCases<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L450)

Run a side effect on the error — **matched exhaustively** ([ErrMatcher](#errmatcher))
— and pass the `Result` through unchanged.

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> | builds the match; branch returns are ignored, bar `defect(cause)`. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

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, and like them it wants every case named — `.with(P._, …)`
remains the wildcard escape hatch. If a branch throws, the
result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it. An **async branch is
rejected at compile time** ([NotThenable](#notthenable) on the builder output):
because the branch results are discarded, a returned `Promise` would float
unobserved and its rejection would vanish. The one branch return that is
**not** discarded is the injected `defect(cause)` marker: it is the
lint-clean, expression-position form of a `throw`, so it follows the throw
rule above (an `AggregateError` of `[the branch's cause, original
failure]`), never a silent no-op. A failable
`Result`-returning effect belongs in
[flatTapErrCases](#flattaperrcases-5).

###### Inherited from

```ts
ResultMethods.tapErrCases
```

##### tapFailure()

```ts
tapFailure<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:534](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L534)

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 [tapErrCases](#taperrcases-5) and
[tapDefect](#tapdefect-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the failure variant (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f` receives the narrowed **failure variant** ([FailureView](#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
[recoverErrCases](#recovererrcases-5) /
[recoverDefect](#recoverdefect-5) (deliberately separate
acts) or [match](#match-5) 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 ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.tapFailure
```

##### toAsync()

```ts
toAsync(): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:680](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L680)

Lift this synchronous `Result` into an [AsyncResult](#asyncresult-1).

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.toAsync
```

***

### OkView

Defined in: [packages/core/src/types.ts:696](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L696)

The `Ok` variant of a [Result](#result-1): a success carrying a `value`. This is
what a successful `isOk` guard narrows to, making `.value` reachable. It also
carries the shared fluent surface ([ResultMethods](#resultmethods)).

#### Example

```ts
if (r.isOk()) r.value; // r: OkView<T, E> here — .value is a T
```

#### Extends

* [`ResultMethods`](#resultmethods)<`T`, `E`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` | - |
| `E` | `never` |

#### Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
|  `tag` | `readonly` | `"Ok"` | [packages/core/src/types.ts:697](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L697) |
|  `value` | `readonly` | `T` | [packages/core/src/types.ts:698](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L698) |

#### Methods

##### as()

```ts
as<U>(value): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:288](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L288)

Replace the success value with a constant `value`.

Runs only on `Ok`; `Err` and `Defect` pass through.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the replacement value type. |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.as
```

##### bind()

```ts
bind<K, U, E2>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:261](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L261)

Do-notation: run `f` for a `Result` and **bind its value** under `name` in
an accumulating object scope.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the bound value is stored under. |
| `U` | the bound value type. |
| `E2` | the error type `f` may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => [`Result`](#result)<`U`, `E2`> | produces a `Result` from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

###### Remarks

Begin a chain with [Do](#do) (an empty object scope) and grow it step by
step. `f` receives the scope accumulated so far and returns a `Result`; on
`Ok` the value is added as `{ ...scope, [name]: value }`, on `Err`/`Defect`
the chain short-circuits. Errors union (`E | E2`). A throw becomes a
`Defect` — as does calling `bind` on a non-object or non-plain scope (e.g.
`Ok(5).bind`, or a class instance whose getters the merge would drop), which
is misuse: the scope is always a plain object inside a real `Do()` chain.
(`let` is the pure-value counterpart.)

###### Inherited from

```ts
ResultMethods.bind
```

##### discard()

```ts
discard(): Result<void, E>;
```

Defined in: [packages/core/src/types.ts:297](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L297)

Drop the success value, collapsing the success type to `void`.

The named form of `map(() => undefined)`. Runs only on `Ok` (the value is
replaced with `undefined`); `Err` and `Defect` pass through. Unlike
`as(undefined)` — which produces `Result<undefined, E>` — the success type
is `void`: the value's story ends here.

###### Returns

[`Result`](#result)<`void`, `E`>

###### Inherited from

```ts
ResultMethods.discard
```

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:332](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L332)

Validate the success value — keep the `Ok` when `predicate` holds,
otherwise fail into the **modeled** channel with `Err(onFail(value))`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the refined success type (type-guard form). |
| `E2` | the error type `onFail` produces. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `predicate` | (`value`) => `value is U` | the check; a type guard refines `T` to `U`. |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | maps the failing value to the modeled error. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Remarks

The named form of `flatMap((v) => (p(v) ? Ok(v) : Err(e)))`. With a
**type-guard** predicate (`(v): v is U`) the success type is **refined** to
`U` on the way through (this overload). Runs only on `Ok` — a passing value
flows through as the *same* `Ok`; `Err` and `Defect` pass through
untouched. A throw in `predicate` or `onFail` becomes a `Defect`.

Both callbacks are synchronous: an async `onFail` is rejected at compile
time ([NotThenable](#notthenable)), and an async predicate does not type-check
either — its `Promise<boolean>` is not a `boolean` (and, being truthy,
would have silently always passed).

###### Example

```ts
// boolean form: gate a value
Ok(-1).ensure((n) => n > 0, (n) => `negative: ${n}`); // Err("negative: -1")

// type-guard form: refine the success type
declare const r: Result<string | number, "e">;
const s = r.ensure(
  (v): v is string => typeof v === "string",
  () => "not_a_string" as const,
); // Result<string, "e" | "not_a_string">
```

###### Inherited from

```ts
ResultMethods.ensure
```

###### Call Signature

```ts
ensure<E2>(predicate, onFail): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:340](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L340)

Boolean form of [ensure](#ensure-5) — validates without
refining, keeping the success type `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.ensure
```

##### flatMap()

```ts
flatMap<U, E2>(f): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:204](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L204)

Sequence a dependent, `Result`-returning step (monadic bind).

Runs `f` only on `Ok`; `Err` and `Defect` pass through. The error channels
combine, widening to `E | E2`. If `f` throws, the throw becomes a `Defect`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the success type of the next step. |
| `E2` | the error type the next step may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`U`, `E2`> | produces the next `Result` from the current success value. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Inherited from

```ts
ResultMethods.flatMap
```

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): Result<T | OkOf<MatchOut<M>>, ErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:397](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L397)

Sequence from an `Err` by producing another `Result` — the error-channel
mirror of [flatMap](#flatmap-5), **matching the error
exhaustively** ([ErrMatcher](#errmatcher); the combinator calls `.exhaustive()`).

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.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `unknown`> | `Defect`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a fallback `Result`. |

###### Returns

[`Result`](#result)<`T` | [`OkOf`](#okof)<`MatchOut`<`M`>>, [`ErrOf`](#errof)<`MatchOut`<`M`>>>

###### Inherited from

```ts
ResultMethods.flatMapErrCases
```

##### flatTap()

```ts
flatTap<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:240](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L240)

Run a **failable** side effect on the success value, keeping the original
value but threading the effect's error.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E2` | the error type the effect may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`unknown`, `E2`> | the failable side effect; its `Ok` value is ignored. |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

This is to [tap](#tap-5) what
[flatMap](#flatmap-5) is to [map](#map-5):
`f` returns a `Result`, but its **success value is discarded** — on success
the original value flows through (`Result<T, E | E2>`), while an `Err` (or
`Defect`) from `f` short-circuits. Runs only on `Ok`; `Err` and `Defect` pass
through. If `f` throws, the throw becomes a `Defect`. Use it for a validation
or write whose *result* matters but whose *value* you don't need.

###### Inherited from

```ts
ResultMethods.flatTap
```

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:478](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L478)

Run a **failable** side effect on the error, keeping the original error but
threading the effect's own error — **matched exhaustively**
([ErrMatcher](#errmatcher)).

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `E2`>> | builds the match; each branch is a failable effect (its `Ok` is ignored). |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

The error-channel mirror of [flatTap](#flattap-5): 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-state `Result` **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). A branch returning the injected `defect(cause)` marker —
reachable under a `returnType` pin — follows the *throw* rule, since it is
the lint-clean, expression-position form of one.

###### Inherited from

```ts
ResultMethods.flatTapErrCases
```

##### get()

```ts
get(this): T;
```

Defined in: [packages/core/src/types.ts:583](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L583)

Extract the success value.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`Result`](#result)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`T`

the `Ok` value.

###### Remarks

Compiles only when the error channel is empty (`E = never`) — eliminate
modeled errors first (`match` / `recoverErrCases` / `flatMapErrCases`), or reach for the
`getOr` / `getOrElse` / `getOrNull` / `getOrUndefined` family (which
recover an `Err`). The gate is a `this` type that becomes an explanatory
string when `E` is not `never`, so the compile error names the fix.

`E = never` empties only the **modeled** error channel — a `Defect` can
still be present, and `get()` **rethrows its original cause** (it
*panics*); `Result<T, never>` does not mean `get()` cannot throw.

###### Inherited from

```ts
ResultMethods.get
```

##### getErr()

```ts
getErr(this): E;
```

Defined in: [packages/core/src/types.ts:601](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L601)

Extract the modeled error.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`Result`](#result)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`E`

the `Err` value.

###### Remarks

Compiles only when the success channel is empty (`T = never`) — eliminate
the success case first. `T = never` is rarely the case in practice (a
`Result` you hold usually still has a success type), so to inspect an
error prefer an `isErr()` guard or, in tests, `@unthrown/vitest`'s
`toBeErrWith`. A `Defect` still **rethrows its original cause** (a defect is
a bug, not an absent value), so this does not mean `getErr()` can't throw.

###### Inherited from

```ts
ResultMethods.getErr
```

##### getOr()

```ts
getOr<U>(fallback): T | U;
```

Defined in: [packages/core/src/types.ts:614](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L614)

The success value, or `fallback` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fallback` | `U` | returned when the result is an `Err` (may be a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect` — a Defect is a bug, not an absent value, so
it is never silently replaced.

###### Inherited from

```ts
ResultMethods.getOr
```

##### getOrElse()

```ts
getOrElse<U>(f): T | U;
```

Defined in: [packages/core/src/types.ts:622](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L622)

The success value, or `f(error)` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`error`) => `U` | lazily computes the fallback from the error (may return a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrElse
```

##### getOrNull()

```ts
getOrNull(): T | null;
```

Defined in: [packages/core/src/types.ts:628](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L628)

The success value, or `null` on `Err`.

###### Returns

`T` | `null`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrNull
```

##### getOrThrow()

```ts
getOrThrow(this): T;
```

Defined in: [packages/core/src/types.ts:666](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L666)

The success value, or **throw** the modeled error on `Err`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`Result`](#result)<`T`, `E`> |

###### Returns

`T`

the `Ok` value.

###### Remarks

A deliberate escape hatch off the errors-as-values model — it **throws the
`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:
[recoverErrCases](#recovererrcases-5) empties `E`, so
[get](#get-5) compiles and a case routed to the injected
`defect(...)` panics with its original cause — with every case still named.
[match](#match-5) and
[flatMapErrCases](#flatmaperrcases-5) 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 [get](#get-5): 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.

###### Throws

the modeled `error` on `Err`; re-throws the original `cause` on a
`Defect` (a panic, like the rest of the `getOr…` family).

###### Inherited from

```ts
ResultMethods.getOrThrow
```

##### getOrUndefined()

```ts
getOrUndefined(): T | undefined;
```

Defined in: [packages/core/src/types.ts:634](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L634)

The success value, or `undefined` on `Err`.

###### Returns

`T` | `undefined`

###### Throws

Re-throws on a `Defect`.

###### Inherited from

```ts
ResultMethods.getOrUndefined
```

##### isDefect()

```ts
isDefect(): this is DefectView<T, E>;
```

Defined in: [packages/core/src/types.ts:677](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L677)

Whether this result is a `Defect` — narrows `this` to its [DefectView](#defectview) on `true`.

###### Returns

`this is DefectView<T, E>`

###### Inherited from

```ts
ResultMethods.isDefect
```

##### isErr()

```ts
isErr(): this is ErrView<E, T>;
```

Defined in: [packages/core/src/types.ts:675](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L675)

Whether this result is `Err` — narrows `this` to its [ErrView](#errview) on `true`.

###### Returns

`this is ErrView<E, T>`

###### Inherited from

```ts
ResultMethods.isErr
```

##### isOk()

```ts
isOk(): this is OkView<T, E>;
```

Defined in: [packages/core/src/types.ts:673](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L673)

Whether this result is `Ok` — narrows `this` to its [OkView](#okview) on `true`.

###### Returns

`this is OkView<T, E>`

###### Inherited from

```ts
ResultMethods.isOk
```

##### let()

```ts
let<K, U>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L280)

Do-notation: run `f` for a **plain value** and bind it under `name` in the
accumulating object scope. The pure-value counterpart of [bind](#bind-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the value is stored under. |
| `U` | the value type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> | computes a value from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

###### Remarks

`f` receives the scope and returns a value (not a `Result`); it is added as
`{ ...scope, [name]: value }`. Runs only on `Ok`; `Err`/`Defect` pass
through. A throw becomes a `Defect`. An async callback is rejected at
compile time ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.let
```

##### map()

```ts
map<U>(f): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:193](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L193)

Transform the success value with `f`.

Runs `f` only on `Ok`; `Err` and `Defect` pass through untouched. If `f`
throws, the thrown value is captured as a `Defect`.

An async callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the mapped success type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> | maps the current success value to a new one. |

###### Returns

[`Result`](#result)<`U`, `E`>

###### Inherited from

```ts
ResultMethods.map
```

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:379](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L379)

Transform the modeled error by **matching it exhaustively**.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match over the error (returns the un-terminated builder). |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

###### Remarks

The callback receives `match(error)` (an [ErrMatcher](#errmatcher)) and the
injected `defect` helper. Chain `.with(pattern, handler)` and **return the
un-terminated builder** — `mapErrCases` 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`. Branches are
**synchronous**: an `async` branch is a compile error (its `Promise` would
land in `E` un-triaged), and a thenable slipped past the types becomes a
`Defect`.

**Name every case.** Match on anything the matcher supports — `_tag`,
`code`, structural shape, guards — and group the cases that share a handler
with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
hatch**, not the default: it makes any match exhaustive, so it also absorbs
every case `E` grows later. Two uses are sanctioned — a helper generic in
`E`, where no arm list can prove exhaustiveness against an unresolved type
parameter, and an `E` that is a single type rather than a union of cases
(see [P](#p) for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
its `recommended` preset) flags the rest.

###### Inherited from

```ts
ResultMethods.mapErrCases
```

##### match()

```ts
match<ROk, RDefect, M>(cases): ROk | RDefect | MatchOut<M>;
```

Defined in: [packages/core/src/types.ts:562](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L562)

Exhaustively fold all three runtime states into a single value.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `ROk` | the `ok` handler return type. |
| `RDefect` | the `defect` handler return type. |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the `errCases` handler returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } | the `ok`/`defect` handlers plus the `errCases` matcher builder. |
| `cases.defect` | (`cause`) => `RDefect` | - |
| `cases.errCases` | (`matcher`) => `M` | - |
| `cases.ok` | (`value`) => `ROk` | - |

###### Returns

`ROk` | `RDefect` | `MatchOut`<`M`>

###### 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`.

The `errCases` handler does not take a single blanket callback: it receives
`match(error)` (an [ErrMatcher](#errmatcher)) and **matches the error exhaustively**,
exactly like the error combinators — which is why the key carries the same
`…Cases` suffix. 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).
Folding at the edge names every case too — `.with(P._, …)` is the wildcard
escape hatch, not the default. 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(…)`.)

###### Inherited from

```ts
ResultMethods.match
```

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): Result<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:498](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L498)

Recover from a `Defect` — the **only** combinator that can touch one.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | a success type the recovery may produce. |
| `E2` | an error type the recovery may produce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => [`Result`](#result)<`U`, `E2`> | maps the Defect's unknown cause to a recovering `Result`. |

###### Returns

[`Result`](#result)<`T` | `U`, `E` | `E2`>

###### Remarks

Runs `f` only when a `Defect` is present, re-entering the modeled world by
returning a `Result` (an `Ok` or a fresh `Err`). `Ok` and `Err` pass
through. Recovering a Defect should be rare: usually you let it bubble to
the edge. If `f` throws, the throw becomes a new `Defect`.

###### Inherited from

```ts
ResultMethods.recoverDefect
```

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:421](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L421)

Recover from an `Err` by producing a success value, emptying the error
channel — **matching the error exhaustively** ([ErrMatcher](#errmatcher)). Pairs
with [recoverDefect](#recoverdefect-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a success value. |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `T` | `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

###### Remarks

The result type is `Result<T | U, never>`, but `never` describes only the
**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. Branches are **synchronous**: an
`async` branch is a compile error, and a thenable slipped past the types
becomes a `Defect`.

###### Inherited from

```ts
ResultMethods.recoverErrCases
```

##### tap()

```ts
tap<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:223](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L223)

Run a side effect on the success value and pass the `Result` through
unchanged.

Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`. An async
callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f`'s return value is **ignored** — a `Result` returned by the effect
compiles but is discarded, `Err` and all. If the effect can fail, sequence
it instead of tapping it: a `Result`-returning effect goes in
[flatTap](#flattap-5); an `AsyncResult`-returning effect
cannot be sequenced from the sync surface — lift the chain with
[toAsync](#toasync-3) and use the async
[flatTap](#flattap-4) (which accepts both).

###### Inherited from

```ts
ResultMethods.tap
```

##### tapDefect()

```ts
tapDefect<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:508](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L508)

Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
`Defect` through unchanged. 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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the unknown cause. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.tapDefect
```

##### tapErrCases()

```ts
tapErrCases<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L450)

Run a side effect on the error — **matched exhaustively** ([ErrMatcher](#errmatcher))
— and pass the `Result` through unchanged.

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> | builds the match; branch returns are ignored, bar `defect(cause)`. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

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, and like them it wants every case named — `.with(P._, …)`
remains the wildcard escape hatch. If a branch throws, the
result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it. An **async branch is
rejected at compile time** ([NotThenable](#notthenable) on the builder output):
because the branch results are discarded, a returned `Promise` would float
unobserved and its rejection would vanish. The one branch return that is
**not** discarded is the injected `defect(cause)` marker: it is the
lint-clean, expression-position form of a `throw`, so it follows the throw
rule above (an `AggregateError` of `[the branch's cause, original
failure]`), never a silent no-op. A failable
`Result`-returning effect belongs in
[flatTapErrCases](#flattaperrcases-5).

###### Inherited from

```ts
ResultMethods.tapErrCases
```

##### tapFailure()

```ts
tapFailure<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:534](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L534)

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 [tapErrCases](#taperrcases-5) and
[tapDefect](#tapdefect-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the failure variant (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f` receives the narrowed **failure variant** ([FailureView](#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
[recoverErrCases](#recovererrcases-5) /
[recoverDefect](#recoverdefect-5) (deliberately separate
acts) or [match](#match-5) 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 ([NotThenable](#notthenable)).

###### Inherited from

```ts
ResultMethods.tapFailure
```

##### toAsync()

```ts
toAsync(): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:680](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L680)

Lift this synchronous `Result` into an [AsyncResult](#asyncresult-1).

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

###### Inherited from

```ts
ResultMethods.toAsync
```

***

### AsyncErrOf

```ts
type AsyncErrOf<R> = R extends Awaitable<infer Res> ? ErrOf<Res> : never;
```

Defined in: [packages/core/src/types.ts:1110](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1110)

Extract the error type `E` from an [AsyncResult](#asyncresult-1) type — the async
counterpart of [ErrOf](#errof).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` | the `AsyncResult` type to inspect. |

#### Example

```ts
type E = AsyncErrOf<AsyncResult<User, NotFound>>; // NotFound
```

***

### AsyncOkOf

```ts
type AsyncOkOf<R> = R extends Awaitable<infer Res> ? OkOf<Res> : never;
```

Defined in: [packages/core/src/types.ts:1096](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1096)

Extract the success type `T` from an [AsyncResult](#asyncresult-1) type — the async
counterpart of [OkOf](#okof).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` | the `AsyncResult` type to inspect. |

#### Example

```ts
type T = AsyncOkOf<AsyncResult<User, NotFound>>; // User
```

***

### Awaitable

```ts
type Awaitable<T> = object;
```

Defined in: [packages/core/src/types.ts:786](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L786)

A success-only thenable: awaitable, but deliberately **not** a full
`PromiseLike`.

#### Remarks

An [AsyncResult](#asyncresult-1)'s internal promise never rejects, so `await`-ing one
always yields a [Result](#result-1) and never throws — there is no rejection
channel to model, and none is advertised. At runtime it is still a thenable
(the only way `await` can collapse it), and `Promise.all` / `Promise.resolve`
will still adopt it — harmlessly, since it settles to a `Result` and never
rejects. What the narrowing prevents is treating it as a full promise:
`.catch()` / `.finally()` do not type-check, because there is no rejection to
handle.

#### Extended by

* [`AsyncResult`](#asyncresult)

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the value `await` resolves to. |

#### Methods

##### then()

```ts
then<R>(onfulfilled?): PromiseLike<R>;
```

Defined in: [packages/core/src/types.ts:787](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L787)

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `onfulfilled?` | ((`value`) => `R` | `PromiseLike`<`R`>) | `null` |

###### Returns

`PromiseLike`<`R`>

***

### ErrMatcher

```ts
type ErrMatcher<E> = ReturnType<typeof match>;
```

Defined in: [packages/core/src/types.ts:73](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L73)

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
`.with(pattern, handler)` on it; the combinator itself calls `.exhaustive()`,
so the callback returns the **un-terminated** builder.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E` | the error union being matched. |

#### Remarks

Named via `ReturnType<typeof match<E>>` (i.e. `Matcher<E, E, never>`),
keeping this alias stable however the builder evolves.

***

### ErrOf

```ts
type ErrOf<R> = R extends object ? E : never;
```

Defined in: [packages/core/src/types.ts:1082](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1082)

Extract the error type `E` from a `Result` type — the counterpart of
[OkOf](#okof).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` | the `Result` type to inspect. |

#### Example

```ts
type E = ErrOf<Result<User, NotFound>>; // NotFound
```

***

### FailureView

```ts
type FailureView<E, T> = 
  | ErrView<E, T>
  | DefectView<T, E>;
```

Defined in: [packages/core/src/types.ts:766](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L766)

A failure variant of a [Result](#result-1): an [ErrView](#errview) **or** a
[DefectView](#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`).

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `E` | - | the modeled error type. |
| `T` | `never` | the success value type (phantom here; a failure carries none). |

#### Remarks

Like [ErrView](#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);
```

***

### Matcher

```ts
type Matcher<E, Remaining, O, Declared> = object;
```

Defined in: [packages/core/src/matcher.ts:185](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L185)

The match builder over an input union `E`. `Remaining` tracks the cases not
yet covered by a `.with(…)` arm; `O` accumulates the branch output union.
`.exhaustive` is callable only once `Remaining` is `never` — which is what
the `ExhaustiveMatch` constraint requires — and `.run()` executes it.

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `E` | - | the full input union being matched. |
| `Remaining` | - | the cases not yet covered. |
| `O` | - | the union of branch return types so far. |
| `Declared` | `Unset` | - |

#### Properties

| Property | Type | Description | Defined in |
| ------ | ------ | ------ | ------ |
|  `exhaustive` | \[`Remaining`] *extends* \[`never`] ? () => `PinnedOut`<`Declared`, `O`> : `UnhandledCases`<`Remaining`> | Terminate the match. Typed callable only when every case is covered (`Remaining` is `never`); otherwise it is a branded diagnostic object naming the remaining cases, and the builder fails the `ExhaustiveMatch` constraint at the combinator call site. | [packages/core/src/matcher.ts:257](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L257) |
|  `returnType` | \[`O`] *extends* \[`never`] ? \[`Declared`] *extends* \[`Unset`] ? <`R`>() => [`Matcher`](#matcher)<`E`, `Remaining`, `never`, `R`> : `PinTooLate` : `PinTooLate` | Declare the match's output type up front: every subsequent branch handler is checked against `R`, and the match evaluates to `R` instead of the union of whatever the branches happened to return. **Remarks** Reach for it when the output is **decided by a signature rather than by the branches** — most sharply in code generic in `E`, where the fold's type has to be declared. It also stops a drifting branch from silently widening the outgoing type, reports the mismatch **on the offending branch**, and gives branch returns a contextual type (so object literals need no annotation). A branch may still return the injected `defect` helper's marker; the defect channel is not part of the declared output. Callable **before any arm has produced an output**, and only once (mirroring ts-pattern's up-front pin): once there is an inferred output for the pin to contradict — or the builder is already pinned — this is typed as a non-callable diagnostic. In practice that means calling it directly after `match(…)`; the gate is about output rather than position, so an earlier arm whose handler returns `never` (it always throws) contributes nothing and does not close it — sound, since a `never` branch can contradict no declared type. A no-op at runtime. **Type Param** **R** the declared output type of every branch. | [packages/core/src/matcher.ts:245](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L245) |

#### Methods

##### run()

```ts
run(): PinnedOut<Declared, O>;
```

Defined in: [packages/core/src/matcher.ts:266](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L266)

Execute the match (the combinators call this; it runs `.exhaustive()`).
A value with no matching arm throws [NonExhaustiveError](#nonexhaustiveerror) —
unreachable for well-typed callers.

###### Returns

`PinnedOut`<`Declared`, `O`>

##### with()

###### Call Signature

```ts
with<O2>(pattern, handler): Matcher<E, never, O | O2, Declared>;
```

Defined in: [packages/core/src/matcher.ts:200](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L200)

The catch-all arm: `.with(P._, handler)` — the
wildcard **escape hatch**, not the way to handle a concrete error union
(name those cases; `@unthrown/oxlint`'s `no-catch-all-pattern`, in its
`recommended` preset, flags the wildcard).

It is a **state transition**, not a computation — it returns
`Matcher<E, never, …>` with the remaining cases literally `never`, so the
builder is provably exhaustive even when `E` is an unresolved type
parameter (a lazily-deferred `Exclude<E, unknown>` would not resolve
there). That is what makes it irreplaceable for a helper generic in `E`:
it can terminate a match no arm list could (issue #145) — one of the two
sanctioned uses (see [P](#p)).

###### Type Parameters

| Type Parameter |
| ------ |
| `O2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `pattern` | [`UniversalPattern`](#universalpattern) |
| `handler` | (`value`) => `BranchReturn`<`Declared`, `O2`> |

###### Returns

[`Matcher`](#matcher)<`E`, `never`, `O` | `O2`, `Declared`>

###### Call Signature

```ts
with<Pts, O2>(...args): Matcher<E, Exclude<Remaining, MatchedOf<Pts[number]>>, O | O2, Declared>;
```

Defined in: [packages/core/src/matcher.ts:211](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L211)

Add an arm: one or more patterns sharing a single handler (grouped
patterns — `matcher.with(P.tag("A"), P.tag("B"), handler)`). The handler
receives the input narrowed to what the patterns match (computed against
`Remaining`, so cases already handled by earlier arms are excluded); the
matched cases are subtracted from `Remaining`.

###### Type Parameters

| Type Parameter |
| ------ |
| `Pts` *extends* readonly \[`unknown`, `unknown`] |
| `O2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`args` | \[...patterns: { \[I in string | number | symbol]: NoEmptyPattern\<Pts\[I]> }\[], (`value`) => `BranchReturn`<`Declared`, `O2`>] |

###### Returns

[`Matcher`](#matcher)<`E`, `Exclude`<`Remaining`, `MatchedOf`<`Pts`\[`number`]>>, `O` | `O2`, `Declared`>

***

### NotThenable

```ts
type NotThenable<R> = [Extract<R, PromiseLike<unknown>>] extends [never] ? unknown : "unthrown: combinator callbacks are synchronous — lift async work with fromPromise and compose with flatMap";
```

Defined in: [packages/core/src/types.ts:56](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L56)

Compile-time rejection of a thenable callback result — the type-level
enforcement of "combinator callbacks are synchronous" (see the
[AsyncResult](#asyncresult-1) remarks).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` | the callback's inferred return type. |

#### Remarks

Resolves to `unknown` (a no-op in an intersection) for any non-thenable `R`,
and to an explanatory string-literal type when `R` is a `PromiseLike` — so an
`async` callback fails to compile with the explanation in the error. Without
this, `async () => …` would be assignable to `() => void`, and its rejection
would escape the pipeline as an unhandled rejection instead of a `Defect`.
Lift async work with [fromPromise](#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.

***

### OkOf

```ts
type OkOf<R> = R extends object ? T : never;
```

Defined in: [packages/core/src/types.ts:1068](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1068)

Extract the success type `T` from a `Result` type — derive one type from
another instead of restating it (e.g. the payload a function returns).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` | the `Result` type to inspect. |

#### Example

```ts
type R = Result<User, NotFound>;
type U = OkOf<R>; // User
type E = ErrOf<R>; // NotFound
```

***

### PatternMatcher

```ts
type PatternMatcher<M> = object;
```

Defined in: [packages/core/src/matcher.ts:50](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L50)

A `P.*` pattern: a runtime predicate plus the phantom type `M` it matches.
The phantom is declaration-only (never present at runtime); it drives the
type-level narrowing (`Extract`) and exhaustiveness (`Exclude`).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` | the type this pattern matches. |

#### Properties

| Property | Modifier | Type | Defined in |
| ------ | ------ | ------ | ------ |
|  `[MATCHES]?` | `readonly` | `M` | [packages/core/src/matcher.ts:52](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L52) |
|  `[PATTERN_BRAND]` | `readonly` | (`value`) => `boolean` | [packages/core/src/matcher.ts:51](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L51) |

***

### Settle

```ts
type Settle<T, E> = (result) => void;
```

Defined in: [packages/core/src/interop.ts:308](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L308)

The settler a [fromExecutor](#fromexecutor) executor receives. Settles the pending
`AsyncResult` **once** — later calls are no-ops, exactly as `resolve` is on a
`Promise`.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success type. |
| `E` | the modeled error type. |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `result` | [`Result`](#result)<`T`, `E`> | `Defect` |

#### Returns

`void`

***

### TaggedErrorConstructor

```ts
type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
```

Defined in: [packages/core/src/tagged.ts:39](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/tagged.ts#L39)

The class constructor returned by [TaggedError](#taggederror). Generic in its payload:
apply it with an instantiation expression at the `extends` site.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `Tag` *extends* `string` | the string literal discriminant. |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `args` | keyof `A` *extends* `never` ? `void` : `A` & `object` |

#### Returns

[`TaggedErrorInstance`](#taggederrorinstance)<`Tag`, `A`>

#### Remarks

When the payload is empty, the constructor takes **no** arguments (the
`keyof A extends never ? void : A` trick); otherwise it takes the payload. The
`name`, `message`, and `stack` keys are all **rejected** (`?: never`) because
all three are reserved: `name` is the display label, `message` is the human
string owned by `Error`, and `stack` is `Error`'s trace. Set the message the
standard way — `override message = "…"` (or a constructor override) on the
subclass — never as a free-form per-call payload field. The reservations are
enforced at the call site, mirroring how [TaggedErrorInstance](#taggederrorinstance) excludes
all three. (`cause` is deliberately **not** reserved: `Error.cause` is
`unknown`, so a typed payload `cause` is a legitimate structured field.)

***

### TaggedErrorInstance

```ts
type TaggedErrorInstance<Tag, A> = Error & Readonly<Omit<A, "name" | "message" | "stack">> & object;
```

Defined in: [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/tagged.ts#L16)

The instance shape produced by a [TaggedError](#taggederror) class: an `Error` plus a
`_tag` discriminant and the (readonly) payload fields.

#### Type Declaration

| Name | Type | Defined in |
| ------ | ------ | ------ |
| `_tag` | `Tag` | [packages/core/src/tagged.ts:17](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/tagged.ts#L17) |

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `Tag` *extends* `string` | the string literal discriminant. |
| `A` *extends* `Props` | the payload object type. |

***

### UniversalPattern

```ts
type UniversalPattern = PatternMatcher<unknown> & object;
```

Defined in: [packages/core/src/matcher.ts:64](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L64)

The statically-known universal pattern — the type of `P._` only.
The phantom `UNIVERSAL` marker is *required*, so no other
`PatternMatcher<unknown>` (e.g. a `P.when` guard that happens to be
universal) is assignable: the catch-all `.with` overload must only fire for
a pattern the type system KNOWS covers everything.

#### Type Declaration

| Name | Type | Defined in |
| ------ | ------ | ------ |
| `[UNIVERSAL]` | `true` | [packages/core/src/matcher.ts:65](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L65) |

## Methods

### AsyncResultMethods

```ts
type AsyncResultMethods<T, E> = object;
```

Defined in: [packages/core/src/types.ts:810](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L810)

The async method surface every [AsyncResult](#asyncresult-1) carries — the combinators
(`map`, `flatMap`, `mapErrCases`, `match`, `get`, …) with their asynchronous
signatures, documented one per entry below. The async mirror of
[ResultMethods](#resultmethods): each entry links its synchronous counterpart and states
only the async delta.

#### Remarks

Like [ResultMethods](#resultmethods), this type exists to **document** the surface — not
to be authored against; you obtain it by holding an `AsyncResult`. Its
combinator callbacks are **synchronous** (a raw `Promise` may never enter — see
the [AsyncResult](#asyncresult-1) remarks); async work re-enters via [fromPromise](#frompromise)
and composes with `flatMap`. Systematic differences from the sync surface: the
binds return an `AsyncResult` (and additionally accept one), and the
eliminators return a `Promise`.

#### Extended by

* [`AsyncResult`](#asyncresult)

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |
| `E` | the modeled error type. |

#### Methods

##### as()

```ts
as<U>(value): AsyncResult<U, E>;
```

Defined in: [packages/core/src/types.ts:879](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L879)

Asynchronous [as](#as-5): replaces the value with `value`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E`>

##### bind()

```ts
bind<K, U, E2>(name, f): AsyncResult<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:863](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L863)

Asynchronous [bind](#bind-5) (do-notation). `f` may return
a `Result` **or** an `AsyncResult`; its value is bound under `name` in the
accumulating scope.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `K` |
| `f` | (`scope`) => | [`Result`](#result)<`U`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`U`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

##### discard()

```ts
discard(): AsyncResult<void, E>;
```

Defined in: [packages/core/src/types.ts:881](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L881)

Asynchronous [discard](#discard-5): drops the value, collapsing the success type to `void`.

###### Returns

[`AsyncResult`](#asyncresult)<`void`, `E`>

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): AsyncResult<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:889](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L889)

Asynchronous [ensure](#ensure-5): validate the success
value — and, with a type-guard predicate (this overload), **refine** it —
failing into the modeled channel with `Err(onFail(value))`. Both callbacks
are synchronous (an async `onFail` is rejected at compile time,
[NotThenable](#notthenable)); a throw in either becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `value is U` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E` | `E2`>

###### Call Signature

```ts
ensure<E2>(predicate, onFail): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:894](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L894)

Boolean form of the asynchronous [ensure](#ensure-5) — validates without refining, keeping `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

##### flatMap()

```ts
flatMap<U, E2>(f): AsyncResult<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:830](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L830)

Asynchronous [flatMap](#flatmap-5). Unlike the sync form,
`f` may return a `Result` **or** an `AsyncResult` (never a raw `Promise`); a
throw becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => | [`Result`](#result)<`U`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`U`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E` | `E2`>

###### Remarks

The async branch of `f`'s return type is spelled `Awaitable<Result<U, E2>> &
{ flatMap: unknown }` rather than `AsyncResult<U, E2>`: this is what you get
by returning an `AsyncResult` (it satisfies both), but inference runs through
the `Awaitable` then-channel so `U`/`E2` stay precise instead of collapsing
to `unknown`, while the `{ flatMap: unknown }` marker still rejects a bare
`Promise` (it has no `flatMap`). Just return a `Result` or an `AsyncResult`.

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): AsyncResult<
  | T
  | OkOf<MatchOut<M>>
  | AsyncOkOf<MatchOut<M>>, 
  | ErrOf<MatchOut<M>>
  | AsyncErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:915](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L915)

Asynchronous [flatMapErrCases](#flatmaperrcases-5) — the same
exhaustive [ErrMatcher](#errmatcher) form. Unlike the sync form, a branch may
return a `Result` **or** an `AsyncResult`.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`< | [`Result`](#result)<`unknown`, `unknown`> | `Defect` | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `unknown`>> & `ReturnAnAsyncResultNotAPromise`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |

###### Returns

[`AsyncResult`](#asyncresult)<
| `T`
| [`OkOf`](#okof)<`MatchOut`<`M`>>
| [`AsyncOkOf`](#asyncokof)<`MatchOut`<`M`>>,
| [`ErrOf`](#errof)<`MatchOut`<`M`>>
| [`AsyncErrOf`](#asyncerrof)<`MatchOut`<`M`>>>

##### flatTap()

```ts
flatTap<E2>(f): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:851](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L851)

Asynchronous [flatTap](#flattap-5) — 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`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => | [`Result`](#result)<`unknown`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `E2`>> & `ReturnAnAsyncResultNotAPromise` |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): AsyncResult<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:968](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L968)

Asynchronous [flatTapErrCases](#flattaperrcases-5) — the
error-channel mirror of `flatTap`. `f` may return a `Result` **or** an
`AsyncResult`; its `Ok` value is discarded, an `Err`/`Defect` from `f`
threads through, and if `f` throws — or a branch returns the injected
`defect(cause)` marker, the expression-position form of a throw — the result
is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`< | [`Result`](#result)<`unknown`, `E2`> | [`Awaitable`](#awaitable)<[`Result`](#result)<`unknown`, `E2`>> & `ReturnAnAsyncResultNotAPromise`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E` | `E2`>

##### get()

```ts
get(this): Promise<T>;
```

Defined in: [packages/core/src/types.ts:1017](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1017)

Asynchronous [get](#get-5). Compiles only when the
error channel is empty (`this: AsyncResult<T, never>`); the returned promise
rejects on a `Defect` (rethrowing its cause).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`AsyncResult`](#asyncresult)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`Promise`<`T`>

##### getErr()

```ts
getErr(this): Promise<E>;
```

Defined in: [packages/core/src/types.ts:1027](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1027)

Asynchronous [getErr](#geterr-5). Compiles only when
the success channel is empty (`this: AsyncResult<never, E>`); the returned
promise rejects on a `Defect` (rethrowing its cause).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`AsyncResult`](#asyncresult)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`Promise`<`E`>

##### getOr()

```ts
getOr<U>(fallback): Promise<T | U>;
```

Defined in: [packages/core/src/types.ts:1033](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1033)

Asynchronous [getOr](#getor-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fallback` | `U` |

###### Returns

`Promise`<`T` | `U`>

##### getOrElse()

```ts
getOrElse<U>(f): Promise<T | U>;
```

Defined in: [packages/core/src/types.ts:1035](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1035)

Asynchronous [getOrElse](#getorelse-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`error`) => `U` |

###### Returns

`Promise`<`T` | `U`>

##### getOrNull()

```ts
getOrNull(): Promise<T | null>;
```

Defined in: [packages/core/src/types.ts:1037](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1037)

Asynchronous [getOrNull](#getornull-5).

###### Returns

`Promise`<`T` | `null`>

##### getOrThrow()

```ts
getOrThrow(this): Promise<T>;
```

Defined in: [packages/core/src/types.ts:1046](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1046)

Asynchronous [getOrThrow](#getorthrow-5) — the returned
promise **rejects** with the modeled error on `Err` (or the original cause
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`).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`AsyncResult`](#asyncresult)<`T`, `E`> |

###### Returns

`Promise`<`T`>

##### getOrUndefined()

```ts
getOrUndefined(): Promise<T | undefined>;
```

Defined in: [packages/core/src/types.ts:1039](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1039)

Asynchronous [getOrUndefined](#getorundefined-5).

###### Returns

`Promise`<`T` | `undefined`>

##### let()

```ts
let<K, U>(name, f): AsyncResult<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:874](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L874)

Asynchronous [let](#let-5) (do-notation). `f` returns a
plain value, bound under `name`. An async callback is rejected at compile
time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `K` |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> |

###### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

##### map()

```ts
map<U>(f): AsyncResult<U, E>;
```

Defined in: [packages/core/src/types.ts:816](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L816)

Asynchronous [map](#map-5): transforms the success value
with `f`. `f` is synchronous; a throw becomes a `Defect`. An async callback
is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> |

###### Returns

[`AsyncResult`](#asyncresult)<`U`, `E`>

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): AsyncResult<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:904](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L904)

Asynchronous [mapErrCases](#maperrcases-5) — the same exhaustive
[ErrMatcher](#errmatcher) form; the combinator calls `.exhaustive()`. Branches are
synchronous — an `async` branch is a compile error, as on the sync surface.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

##### match()

```ts
match<ROk, RDefect, M>(cases): Promise<ROk | RDefect | MatchOut<M>>;
```

Defined in: [packages/core/src/types.ts:1007](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1007)

Asynchronous [match](#match-5). Handlers are synchronous
(the `errCases` handler returns an exhaustive [ErrMatcher](#errmatcher) builder, no
`defect` helper); resolves to a `Promise` of the folded value.

###### Type Parameters

| Type Parameter |
| ------ |
| `ROk` |
| `RDefect` |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } |
| `cases.defect` | (`cause`) => `RDefect` |
| `cases.errCases` | (`matcher`) => `M` |
| `cases.ok` | (`value`) => `ROk` |

###### Returns

`Promise`<`ROk` | `RDefect` | `MatchOut`<`M`>>

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): AsyncResult<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:981](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L981)

Asynchronous [recoverDefect](#recoverdefect-5). `f` may
return a `Result` or an `AsyncResult`.

###### Type Parameters

| Type Parameter |
| ------ |
| `U` |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`cause`) => | [`Result`](#result)<`U`, `E2`> | [`AsyncResult`](#asyncresult)<`U`, `E2`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T` | `U`, `E` | `E2`>

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): AsyncResult<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:933](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L933)

Asynchronous [recoverErrCases](#recovererrcases-5) — the same
exhaustive [ErrMatcher](#errmatcher) form. Branches are synchronous; a throw
becomes a `Defect`.

###### Type Parameters

| Type Parameter |
| ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `T` | `E`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

##### tap()

```ts
tap<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:844](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L844)

Asynchronous [tap](#tap-5). `f` is synchronous; a throw
becomes a `Defect`. An async callback is rejected at compile time
([NotThenable](#notthenable)) — and so is a returned `AsyncResult` (it is
awaitable). Beware the near-miss: *calling* an `AsyncResult`-returning
effect inside the callback without returning it compiles and leaves the
effect floating — fire-and-forget, never awaited, its `Err`/`Defect`
unobserved. If the effect returns a `Result`/`AsyncResult`, use
[flatTap](#flattap-4).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

##### tapDefect()

```ts
tapDefect<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:990](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L990)

Asynchronous [tapDefect](#tapdefect-5). 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 ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

##### tapErrCases()

```ts
tapErrCases<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:952](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L952)

Asynchronous [tapErrCases](#taperrcases-5). `f` is synchronous; if it
throws — or a branch returns the injected `defect(cause)` marker, the
expression-position form of a throw — the result is a `Defect` whose cause
is an `AggregateError` of `[thrown, original failure]` — observing a failure
never destroys it. An
async branch is rejected at compile time ([NotThenable](#notthenable) on the
builder output) — other branch results are discarded, so a rejected
`Promise` would float unobserved. The
[tap](#tap-4) fire-and-forget caveat applies here
too — a failable effect belongs in
[flatTapErrCases](#flattaperrcases-4).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

##### tapFailure()

```ts
tapFailure<R>(f): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:1000](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L1000)

Asynchronous [tapFailure](#tapfailure-5) — the
cross-channel observer. `f` receives the narrowed failure variant
([FailureView](#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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> |

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

***

### ResultMethods

```ts
type ResultMethods<T, E> = object;
```

Defined in: [packages/core/src/types.ts:181](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L181)

The fluent method surface every [Result](#result-1) variant carries — the
combinators (`map`, `flatMap`, `mapErrCases`, `match`, `get`, …), documented one
per entry below. Factored out so the three variants ([OkView](#okview),
[ErrView](#errview), [DefectView](#defectview)) can each intersect it; [AsyncResult](#asyncresult-1)
mirrors this surface with async signatures.

#### Remarks

This type exists to **document** the surface and to power narrowing — not to be
authored against. You obtain it by holding a `Result` (or `AsyncResult`), never
by implementing your own `Result`-like; treat it as read-only reference.

#### Extended by

* [`DefectView`](#defectview)
* [`ErrView`](#errview)
* [`OkView`](#okview)

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |
| `E` | the modeled error type. |

#### Methods

##### as()

```ts
as<U>(value): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:288](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L288)

Replace the success value with a constant `value`.

Runs only on `Ok`; `Err` and `Defect` pass through.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the replacement value type. |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `U` |

###### Returns

[`Result`](#result)<`U`, `E`>

##### bind()

```ts
bind<K, U, E2>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E | E2>;
```

Defined in: [packages/core/src/types.ts:261](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L261)

Do-notation: run `f` for a `Result` and **bind its value** under `name` in
an accumulating object scope.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the bound value is stored under. |
| `U` | the bound value type. |
| `E2` | the error type `f` may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => [`Result`](#result)<`U`, `E2`> | produces a `Result` from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E` | `E2`>

###### Remarks

Begin a chain with [Do](#do) (an empty object scope) and grow it step by
step. `f` receives the scope accumulated so far and returns a `Result`; on
`Ok` the value is added as `{ ...scope, [name]: value }`, on `Err`/`Defect`
the chain short-circuits. Errors union (`E | E2`). A throw becomes a
`Defect` — as does calling `bind` on a non-object or non-plain scope (e.g.
`Ok(5).bind`, or a class instance whose getters the merge would drop), which
is misuse: the scope is always a plain object inside a real `Do()` chain.
(`let` is the pure-value counterpart.)

##### discard()

```ts
discard(): Result<void, E>;
```

Defined in: [packages/core/src/types.ts:297](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L297)

Drop the success value, collapsing the success type to `void`.

The named form of `map(() => undefined)`. Runs only on `Ok` (the value is
replaced with `undefined`); `Err` and `Defect` pass through. Unlike
`as(undefined)` — which produces `Result<undefined, E>` — the success type
is `void`: the value's story ends here.

###### Returns

[`Result`](#result)<`void`, `E`>

##### ensure()

###### Call Signature

```ts
ensure<U, E2>(predicate, onFail): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:332](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L332)

Validate the success value — keep the `Ok` when `predicate` holds,
otherwise fail into the **modeled** channel with `Err(onFail(value))`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the refined success type (type-guard form). |
| `E2` | the error type `onFail` produces. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `predicate` | (`value`) => `value is U` | the check; a type guard refines `T` to `U`. |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | maps the failing value to the modeled error. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

###### Remarks

The named form of `flatMap((v) => (p(v) ? Ok(v) : Err(e)))`. With a
**type-guard** predicate (`(v): v is U`) the success type is **refined** to
`U` on the way through (this overload). Runs only on `Ok` — a passing value
flows through as the *same* `Ok`; `Err` and `Defect` pass through
untouched. A throw in `predicate` or `onFail` becomes a `Defect`.

Both callbacks are synchronous: an async `onFail` is rejected at compile
time ([NotThenable](#notthenable)), and an async predicate does not type-check
either — its `Promise<boolean>` is not a `boolean` (and, being truthy,
would have silently always passed).

###### Example

```ts
// boolean form: gate a value
Ok(-1).ensure((n) => n > 0, (n) => `negative: ${n}`); // Err("negative: -1")

// type-guard form: refine the success type
declare const r: Result<string | number, "e">;
const s = r.ensure(
  (v): v is string => typeof v === "string",
  () => "not_a_string" as const,
); // Result<string, "e" | "not_a_string">
```

###### Call Signature

```ts
ensure<E2>(predicate, onFail): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:340](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L340)

Boolean form of [ensure](#ensure-5) — validates without
refining, keeping the success type `T`.

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `predicate` | (`value`) => `boolean` |
| `onFail` | (`value`) => `E2` & [`NotThenable`](#notthenable)<`E2`> |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

##### flatMap()

```ts
flatMap<U, E2>(f): Result<U, E | E2>;
```

Defined in: [packages/core/src/types.ts:204](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L204)

Sequence a dependent, `Result`-returning step (monadic bind).

Runs `f` only on `Ok`; `Err` and `Defect` pass through. The error channels
combine, widening to `E | E2`. If `f` throws, the throw becomes a `Defect`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the success type of the next step. |
| `E2` | the error type the next step may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`U`, `E2`> | produces the next `Result` from the current success value. |

###### Returns

[`Result`](#result)<`U`, `E` | `E2`>

##### flatMapErrCases()

```ts
flatMapErrCases<M>(f): Result<T | OkOf<MatchOut<M>>, ErrOf<MatchOut<M>>>;
```

Defined in: [packages/core/src/types.ts:397](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L397)

Sequence from an `Err` by producing another `Result` — the error-channel
mirror of [flatMap](#flatmap-5), **matching the error
exhaustively** ([ErrMatcher](#errmatcher); the combinator calls `.exhaustive()`).

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.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `unknown`> | `Defect`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a fallback `Result`. |

###### Returns

[`Result`](#result)<`T` | [`OkOf`](#okof)<`MatchOut`<`M`>>, [`ErrOf`](#errof)<`MatchOut`<`M`>>>

##### flatTap()

```ts
flatTap<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:240](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L240)

Run a **failable** side effect on the success value, keeping the original
value but threading the effect's error.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E2` | the error type the effect may introduce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => [`Result`](#result)<`unknown`, `E2`> | the failable side effect; its `Ok` value is ignored. |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

This is to [tap](#tap-5) what
[flatMap](#flatmap-5) is to [map](#map-5):
`f` returns a `Result`, but its **success value is discarded** — on success
the original value flows through (`Result<T, E | E2>`), while an `Err` (or
`Defect`) from `f` short-circuits. Runs only on `Ok`; `Err` and `Defect` pass
through. If `f` throws, the throw becomes a `Defect`. Use it for a validation
or write whose *result* matters but whose *value* you don't need.

##### flatTapErrCases()

```ts
flatTapErrCases<E2>(f): Result<T, E | E2>;
```

Defined in: [packages/core/src/types.ts:478](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L478)

Run a **failable** side effect on the error, keeping the original error but
threading the effect's own error — **matched exhaustively**
([ErrMatcher](#errmatcher)).

###### Type Parameters

| Type Parameter |
| ------ |
| `E2` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<[`Result`](#result)<`unknown`, `E2`>> | builds the match; each branch is a failable effect (its `Ok` is ignored). |

###### Returns

[`Result`](#result)<`T`, `E` | `E2`>

###### Remarks

The error-channel mirror of [flatTap](#flattap-5): 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-state `Result` **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). A branch returning the injected `defect(cause)` marker —
reachable under a `returnType` pin — follows the *throw* rule, since it is
the lint-clean, expression-position form of one.

##### get()

```ts
get(this): T;
```

Defined in: [packages/core/src/types.ts:583](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L583)

Extract the success value.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? [`Result`](#result)<`T`, `never`> : `"unthrown: get() needs an empty error channel (E = never) — handle the Err first with recoverErrCases / match / flatMapErrCases, or use getOr / getOrElse / getOrNull / getOrUndefined"` |

###### Returns

`T`

the `Ok` value.

###### Remarks

Compiles only when the error channel is empty (`E = never`) — eliminate
modeled errors first (`match` / `recoverErrCases` / `flatMapErrCases`), or reach for the
`getOr` / `getOrElse` / `getOrNull` / `getOrUndefined` family (which
recover an `Err`). The gate is a `this` type that becomes an explanatory
string when `E` is not `never`, so the compile error names the fix.

`E = never` empties only the **modeled** error channel — a `Defect` can
still be present, and `get()` **rethrows its original cause** (it
*panics*); `Result<T, never>` does not mean `get()` cannot throw.

##### getErr()

```ts
getErr(this): E;
```

Defined in: [packages/core/src/types.ts:601](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L601)

Extract the modeled error.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`T`] *extends* \[`never`] ? [`Result`](#result)<`never`, `E`> : `"unthrown: getErr() needs an empty success channel (T = never) — narrow with isErr() first, or fold with match"` |

###### Returns

`E`

the `Err` value.

###### Remarks

Compiles only when the success channel is empty (`T = never`) — eliminate
the success case first. `T = never` is rarely the case in practice (a
`Result` you hold usually still has a success type), so to inspect an
error prefer an `isErr()` guard or, in tests, `@unthrown/vitest`'s
`toBeErrWith`. A `Defect` still **rethrows its original cause** (a defect is
a bug, not an absent value), so this does not mean `getErr()` can't throw.

##### getOr()

```ts
getOr<U>(fallback): T | U;
```

Defined in: [packages/core/src/types.ts:614](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L614)

The success value, or `fallback` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fallback` | `U` | returned when the result is an `Err` (may be a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect` — a Defect is a bug, not an absent value, so
it is never silently replaced.

##### getOrElse()

```ts
getOrElse<U>(f): T | U;
```

Defined in: [packages/core/src/types.ts:622](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L622)

The success value, or `f(error)` on `Err`.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the fallback type (may differ from `T`; the return widens to `T | U`). |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`error`) => `U` | lazily computes the fallback from the error (may return a different type; the return widens to `T | U`). |

###### Returns

`T` | `U`

###### Throws

Re-throws on a `Defect`.

##### getOrNull()

```ts
getOrNull(): T | null;
```

Defined in: [packages/core/src/types.ts:628](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L628)

The success value, or `null` on `Err`.

###### Returns

`T` | `null`

###### Throws

Re-throws on a `Defect`.

##### getOrThrow()

```ts
getOrThrow(this): T;
```

Defined in: [packages/core/src/types.ts:666](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L666)

The success value, or **throw** the modeled error on `Err`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `this` | \[`E`] *extends* \[`never`] ? `"unthrown: getOrThrow is unnecessary here — the Err channel is empty (E = never), so there is nothing to throw. Use get() instead."` : [`Result`](#result)<`T`, `E`> |

###### Returns

`T`

the `Ok` value.

###### Remarks

A deliberate escape hatch off the errors-as-values model — it **throws the
`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:
[recoverErrCases](#recovererrcases-5) empties `E`, so
[get](#get-5) compiles and a case routed to the injected
`defect(...)` panics with its original cause — with every case still named.
[match](#match-5) and
[flatMapErrCases](#flatmaperrcases-5) 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 [get](#get-5): 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.

###### Throws

the modeled `error` on `Err`; re-throws the original `cause` on a
`Defect` (a panic, like the rest of the `getOr…` family).

##### getOrUndefined()

```ts
getOrUndefined(): T | undefined;
```

Defined in: [packages/core/src/types.ts:634](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L634)

The success value, or `undefined` on `Err`.

###### Returns

`T` | `undefined`

###### Throws

Re-throws on a `Defect`.

##### isDefect()

```ts
isDefect(): this is DefectView<T, E>;
```

Defined in: [packages/core/src/types.ts:677](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L677)

Whether this result is a `Defect` — narrows `this` to its [DefectView](#defectview) on `true`.

###### Returns

`this is DefectView<T, E>`

##### isErr()

```ts
isErr(): this is ErrView<E, T>;
```

Defined in: [packages/core/src/types.ts:675](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L675)

Whether this result is `Err` — narrows `this` to its [ErrView](#errview) on `true`.

###### Returns

`this is ErrView<E, T>`

##### isOk()

```ts
isOk(): this is OkView<T, E>;
```

Defined in: [packages/core/src/types.ts:673](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L673)

Whether this result is `Ok` — narrows `this` to its [OkView](#okview) on `true`.

###### Returns

`this is OkView<T, E>`

##### let()

```ts
let<K, U>(name, f): Result<{ [K in string | number | symbol]: (Omit<T, K> & { readonly [P in string]: U })[K] }, E>;
```

Defined in: [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L280)

Do-notation: run `f` for a **plain value** and bind it under `name` in the
accumulating object scope. The pure-value counterpart of [bind](#bind-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `K` *extends* `string` | the key the value is stored under. |
| `U` | the value type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `K` | the scope key. |
| `f` | (`scope`) => `U` & [`NotThenable`](#notthenable)<`U`> | computes a value from the accumulated scope. |

###### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: (Omit\<T, K> & { readonly \[P in string]: U })\[K] }, `E`>

###### Remarks

`f` receives the scope and returns a value (not a `Result`); it is added as
`{ ...scope, [name]: value }`. Runs only on `Ok`; `Err`/`Defect` pass
through. A throw becomes a `Defect`. An async callback is rejected at
compile time ([NotThenable](#notthenable)).

##### map()

```ts
map<U>(f): Result<U, E>;
```

Defined in: [packages/core/src/types.ts:193](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L193)

Transform the success value with `f`.

Runs `f` only on `Ok`; `Err` and `Defect` pass through untouched. If `f`
throws, the thrown value is captured as a `Defect`.

An async callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | the mapped success type. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `U` & [`NotThenable`](#notthenable)<`U`> | maps the current success value to a new one. |

###### Returns

[`Result`](#result)<`U`, `E`>

##### mapErrCases()

```ts
mapErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T, Exclude<MatchOut<M>, Defect>>;
```

Defined in: [packages/core/src/types.ts:379](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L379)

Transform the modeled error by **matching it exhaustively**.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match over the error (returns the un-terminated builder). |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T`, `Exclude`<`MatchOut`<`M`>, `Defect`>>

###### Remarks

The callback receives `match(error)` (an [ErrMatcher](#errmatcher)) and the
injected `defect` helper. Chain `.with(pattern, handler)` and **return the
un-terminated builder** — `mapErrCases` 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`. Branches are
**synchronous**: an `async` branch is a compile error (its `Promise` would
land in `E` un-triaged), and a thenable slipped past the types becomes a
`Defect`.

**Name every case.** Match on anything the matcher supports — `_tag`,
`code`, structural shape, guards — and group the cases that share a handler
with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
hatch**, not the default: it makes any match exhaustive, so it also absorbs
every case `E` grows later. Two uses are sanctioned — a helper generic in
`E`, where no arm list can prove exhaustiveness against an unresolved type
parameter, and an `E` that is a single type rather than a union of cases
(see [P](#p) for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
its `recommended` preset) flags the rest.

##### match()

```ts
match<ROk, RDefect, M>(cases): ROk | RDefect | MatchOut<M>;
```

Defined in: [packages/core/src/types.ts:562](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L562)

Exhaustively fold all three runtime states into a single value.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `ROk` | the `ok` handler return type. |
| `RDefect` | the `defect` handler return type. |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the `errCases` handler returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cases` | { `defect`: (`cause`) => `RDefect`; `errCases`: (`matcher`) => `M`; `ok`: (`value`) => `ROk`; } | the `ok`/`defect` handlers plus the `errCases` matcher builder. |
| `cases.defect` | (`cause`) => `RDefect` | - |
| `cases.errCases` | (`matcher`) => `M` | - |
| `cases.ok` | (`value`) => `ROk` | - |

###### Returns

`ROk` | `RDefect` | `MatchOut`<`M`>

###### 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`.

The `errCases` handler does not take a single blanket callback: it receives
`match(error)` (an [ErrMatcher](#errmatcher)) and **matches the error exhaustively**,
exactly like the error combinators — which is why the key carries the same
`…Cases` suffix. 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).
Folding at the edge names every case too — `.with(P._, …)` is the wildcard
escape hatch, not the default. 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(…)`.)

##### recoverDefect()

```ts
recoverDefect<U, E2>(f): Result<T | U, E | E2>;
```

Defined in: [packages/core/src/types.ts:498](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L498)

Recover from a `Defect` — the **only** combinator that can touch one.

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `U` | a success type the recovery may produce. |
| `E2` | an error type the recovery may produce. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => [`Result`](#result)<`U`, `E2`> | maps the Defect's unknown cause to a recovering `Result`. |

###### Returns

[`Result`](#result)<`T` | `U`, `E` | `E2`>

###### Remarks

Runs `f` only when a `Defect` is present, re-entering the modeled world by
returning a `Result` (an `Ok` or a fresh `Err`). `Ok` and `Err` pass
through. Recovering a Defect should be rare: usually you let it bubble to
the edge. If `f` throws, the throw becomes a new `Defect`.

##### recoverErrCases()

```ts
recoverErrCases<M>(f, ..._asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases): Result<T | Exclude<MatchOut<M>, Defect>, never>;
```

Defined in: [packages/core/src/types.ts:421](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L421)

Recover from an `Err` by producing a success value, emptying the error
channel — **matching the error exhaustively** ([ErrMatcher](#errmatcher)). Pairs
with [recoverDefect](#recoverdefect-5).

###### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `M` *extends* `ExhaustiveMatch`<`unknown`> | the exhaustive builder the callback returns. |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `M` | builds the match; each branch produces a success value. |
| ...`_asyncBranchBanned_liftWithFromPromiseThenFlatMapErrCases` | `SyncBranches`<`MatchOut`<`M`>, `T` | `E`> | compile-time only; never pass it. Empty for synchronous branches; an **async** branch demands this impossible argument, so the call fails to compile (its name is the fix). |

###### Returns

[`Result`](#result)<`T` | `Exclude`<`MatchOut`<`M`>, `Defect`>, `never`>

###### Remarks

The result type is `Result<T | U, never>`, but `never` describes only the
**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. Branches are **synchronous**: an
`async` branch is a compile error, and a thenable slipped past the types
becomes a `Defect`.

##### tap()

```ts
tap<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:223](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L223)

Run a side effect on the success value and pass the `Result` through
unchanged.

Runs only on `Ok`. If `f` throws, the throw becomes a `Defect`. An async
callback is rejected at compile time ([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`value`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f`'s return value is **ignored** — a `Result` returned by the effect
compiles but is discarded, `Err` and all. If the effect can fail, sequence
it instead of tapping it: a `Result`-returning effect goes in
[flatTap](#flattap-5); an `AsyncResult`-returning effect
cannot be sequenced from the sync surface — lift the chain with
[toAsync](#toasync-3) and use the async
[flatTap](#flattap-4) (which accepts both).

##### tapDefect()

```ts
tapDefect<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:508](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L508)

Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
`Defect` through unchanged. 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
([NotThenable](#notthenable)).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`cause`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the unknown cause. |

###### Returns

[`Result`](#result)<`T`, `E`>

##### tapErrCases()

```ts
tapErrCases<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L450)

Run a side effect on the error — **matched exhaustively** ([ErrMatcher](#errmatcher))
— and pass the `Result` through unchanged.

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`matcher`, `defect`) => `ExhaustiveMatch`<`R` & [`NotThenable`](#notthenable)<`R`>> | builds the match; branch returns are ignored, bar `defect(cause)`. |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

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, and like them it wants every case named — `.with(P._, …)`
remains the wildcard escape hatch. If a branch throws, the
result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
failure]` — observing a failure never destroys it. An **async branch is
rejected at compile time** ([NotThenable](#notthenable) on the builder output):
because the branch results are discarded, a returned `Promise` would float
unobserved and its rejection would vanish. The one branch return that is
**not** discarded is the injected `defect(cause)` marker: it is the
lint-clean, expression-position form of a `throw`, so it follows the throw
rule above (an `AggregateError` of `[the branch's cause, original
failure]`), never a silent no-op. A failable
`Result`-returning effect belongs in
[flatTapErrCases](#flattaperrcases-5).

##### tapFailure()

```ts
tapFailure<R>(f): Result<T, E>;
```

Defined in: [packages/core/src/types.ts:534](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L534)

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 [tapErrCases](#taperrcases-5) and
[tapDefect](#tapdefect-5).

###### Type Parameters

| Type Parameter |
| ------ |
| `R` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `f` | (`failure`) => `R` & [`NotThenable`](#notthenable)<`R`> | the side effect over the failure variant (its return value is ignored). |

###### Returns

[`Result`](#result)<`T`, `E`>

###### Remarks

`f` receives the narrowed **failure variant** ([FailureView](#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
[recoverErrCases](#recovererrcases-5) /
[recoverDefect](#recoverdefect-5) (deliberately separate
acts) or [match](#match-5) 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 ([NotThenable](#notthenable)).

##### toAsync()

```ts
toAsync(): AsyncResult<T, E>;
```

Defined in: [packages/core/src/types.ts:680](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/types.ts#L680)

Lift this synchronous `Result` into an [AsyncResult](#asyncresult-1).

###### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

## Constructors

### P

```ts
const P: Readonly<{
  _: UniversalPattern;
  instanceOf: <C>(cls) => PatternMatcher<InstanceType<C>>;
  tag: <Tag>(value) => object;
  when: <G>(guard) => PatternMatcher<G>;
}>;
```

Defined in: [packages/core/src/matcher.ts:542](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L542)

The pattern namespace (unthrown's own; the former ts-pattern `P`):

* `P._` — the universal catch-all, and an **escape hatch** rather
  than the default: matching the error channel means naming its cases, so
  reach for this only where they cannot be named. Matches anything, and
  (because its phantom type is `unknown`) makes the builder provably
  exhaustive even when the matched input is an unresolved type parameter.
  Two situations are legitimate: a **helper generic in `E`**, where no arm
  list can prove exhaustiveness against an unresolved type parameter; and an
  **`E` that is a single type**, not a union of cases (a validator's issues
  array, say), where one arm *is* the enumeration. `@unthrown/oxlint`'s
  `no-catch-all-pattern` (in its `recommended` preset) flags every other use;
  keep the deliberate ones behind a targeted `oxlint-disable` saying which of
  the two it is.
* `P.tag<const Tag extends string>(value: Tag): { _tag: Tag }` — the
  `{ _tag: t }` object pattern, matching any value whose `_tag` equals `t` (a
  `TaggedError`, or any `_tag`-discriminated member) and narrowing the
  branch's parameter to that variant, payload included. The workhorse of the
  error channel: `matcher.with(P.tag("NotFound"), (e) => …)`. It composes like
  any other pattern — in a grouped arm
  (`.with(P.tag("A"), P.tag("B"), handler)`).
* `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
  instance type (for union members that are not tagged, e.g. a third-party
  error class). **Exhaustiveness here is structural, the check is not:**
  two classes with the same shape (`class A extends Error {}`,
  `class B extends Error {}`) are one type to the compiler, so a match
  naming only `A` compiles as exhaustive while a `B` fails `instanceof A`
  at runtime and becomes a `Defect`. Give each class a distinguishing field
  (a `readonly kind = "A"` literal) or use `TaggedError`, and the missing
  arm is a compile error again.
* `P.when(guard)` — an arbitrary type-guard predicate. Also the way to match
  a primitive shape (`P.when((v): v is string => typeof v === "string")`),
  and grouping patterns under one handler is what a `.with(a, b, handler)`
  arm already does.

#### Example

```ts
import { P, TaggedError, type Result } from "unthrown";

class NotFound extends TaggedError("NotFound")<{ id: string }> {}
class Conflict extends TaggedError("Conflict") {}
class VendorTimeout extends Error {
  readonly afterMs = 30_000;
}

declare const r: Result<string, NotFound | Conflict | VendorTimeout | "rate_limited">;
const status = r.match({
  ok: () => 200,
  errCases: (matcher) =>
    matcher
      .with(P.tag("NotFound"), () => 404) // a TaggedError, narrowed with its payload
      .with(P.tag("Conflict"), () => 409)
      .with(P.instanceOf(VendorTimeout), (e) => (e.afterMs > 10_000 ? 504 : 503))
      .with(
        P.when((v): v is "rate_limited" => v === "rate_limited"),
        () => 429,
      ),
  defect: () => 500,
});
```

***

### Err()

```ts
function Err<E>(error): Result<never, E>;
```

Defined in: [packages/core/src/constructors.ts:61](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L61)

Construct a failed [Result](#result-1) carrying a **modeled** error.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E` | the modeled error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error` | `E` | the domain error to wrap. |

#### Returns

[`Result`](#result)<`never`, `E`>

#### Example

```ts
import { Err } from "unthrown";

Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
Err("not_found").getErr(); // => "not_found"
```

***

### ErrAsync()

```ts
function ErrAsync<E>(error): AsyncResult<never, E>;
```

Defined in: [packages/core/src/constructors.ts:133](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L133)

Construct a failed [AsyncResult](#asyncresult-1) carrying a **modeled** error — the
pre-lifted form of [Err](#err), sparing you `Err(error).toAsync()`.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `E` | the modeled error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error` | `E` | the domain error to wrap. |

#### Returns

[`AsyncResult`](#asyncresult)<`never`, `E`>

#### Remarks

The error-channel mirror of [OkAsync](#okasync); see it for the naming and the
`AsyncResult.Err` companion alias.

#### Example

```ts
import { ErrAsync } from "unthrown";

ErrAsync("not_found"); // AsyncResult<never, string>
```

***

### match()

```ts
function match<E>(value): Matcher<E, E, never>;
```

Defined in: [packages/core/src/matcher.ts:464](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L464)

Begin a match over `value`. Chain `.with(pattern, …patterns, handler)` arms;
terminate with `.exhaustive()` — or return the un-terminated builder to an
unthrown error combinator / `match({ errCases })`, which runs it for you.

#### Type Parameters

| Type Parameter |
| ------ |
| `E` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `E` |

#### Returns

[`Matcher`](#matcher)<`E`, `E`, `never`>

#### Remarks

This is unthrown's own matcher (the former ts-pattern re-export): the same
call-site shape, with exhaustiveness computed by plain `Exclude` over the
builder's `Remaining` parameter. Name every case of the input union; the
`P._` catch-all is the escape hatch, and is provably exhaustive even over an
unresolved generic input — one of the two cases it is irreplaceable for (see
[P](#p)).

#### Example

```ts
import { match, type Result } from "unthrown";

// Matching a whole Result natively — every variant named, `.exhaustive()` last:
declare const r: Result<number, "odd" | "negative">;
const label = match(r)
  .with({ tag: "Ok" }, (ok) => `got ${ok.value}`)
  .with({ tag: "Err" }, (err) => `failed: ${err.error}`)
  .with({ tag: "Defect" }, () => "bug")
  .exhaustive();

// Inside a combinator, return the un-terminated builder — it runs `.exhaustive()`:
const reason = r.mapErrCases((matcher) =>
  matcher.with("odd", () => "not even" as const).with("negative", () => "below zero" as const),
); // Result<number, "not even" | "below zero">
```

***

### Ok()

#### Call Signature

```ts
function Ok(): Result<void, never>;
```

Defined in: [packages/core/src/constructors.ts:20](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L20)

Construct a successful `void` [Result](#result-1) — `Result<void, never>` —
sparing you `Ok(undefined)` and typing the success channel `void`, not
`undefined`.

##### Returns

[`Result`](#result)<`void`, `never`>

##### Example

```ts
import { Ok } from "unthrown";

Ok(); // => a void success: Result<void, never>
```

#### Call Signature

```ts
function Ok<T>(value): Result<T, never>;
```

Defined in: [packages/core/src/constructors.ts:37](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L37)

Construct a successful [Result](#result-1).

##### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `T` | the success value to wrap. |

##### Returns

[`Result`](#result)<`T`, `never`>

##### Example

```ts
import { Ok } from "unthrown";

Ok(2).map((n) => n + 1); // => Ok(3)
Ok(42).get(); // => 42
```

***

### OkAsync()

#### Call Signature

```ts
function OkAsync(): AsyncResult<void, never>;
```

Defined in: [packages/core/src/constructors.ts:79](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L79)

Construct a successful `void` [AsyncResult](#asyncresult-1) — `AsyncResult<void, never>`
— the pre-lifted form of the no-arg [Ok](#ok), sparing you
`Ok(undefined).toAsync()`.

##### Returns

[`AsyncResult`](#asyncresult)<`void`, `never`>

##### Example

```ts
import { OkAsync } from "unthrown";

OkAsync(); // => a void success: AsyncResult<void, never>
```

#### Call Signature

```ts
function OkAsync<T>(value): AsyncResult<T, never>;
```

Defined in: [packages/core/src/constructors.ts:106](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L106)

Construct a successful [AsyncResult](#asyncresult-1) from a pure value — the pre-lifted
form of [Ok](#ok), sparing you `Ok(value).toAsync()`.

##### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the success value type. |

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `T` | the success value to wrap. |

##### Returns

[`AsyncResult`](#asyncresult)<`T`, `never`>

##### Remarks

Reach for this on the synchronous/early branch of an `AsyncResult`-returning
function, so both branches share one return type without a trailing
`.toAsync()`. Named with the `Async` suffix the async free functions carry
(`allAsync`, `allFromDictAsync`); the [AsyncResult](#asyncresult-1) companion aliases it
as `AsyncResult.Ok` (the namespace already says "async", so the suffix drops).

##### Example

```ts
import { OkAsync, type AsyncResult } from "unthrown";

function loadItems(ids: string[]): AsyncResult<Item[], never> {
  if (ids.length === 0) return OkAsync([]); // no more Ok([]).toAsync()
  return itemRepository.load(ids);
}
```

## Interop

### fromExecutor()

```ts
function fromExecutor<T, E>(executor): AsyncResult<T, E>;
```

Defined in: [packages/core/src/interop.ts:351](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L351)

Build an [AsyncResult](#asyncresult-1) from a callback-style API — this library's
answer to `new Promise((resolve, reject) => …)`.

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `T` | `never` | the success type. |
| `E` | `never` | the modeled error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `executor` | (`settle`, `defect`) => `void` | runs immediately; receives the settler and the `defect` helper. |

#### Returns

[`AsyncResult`](#asyncresult)<`T`, `E`>

#### Remarks

The settler takes a **`Result`**, not a value-or-reason pair: the caller names
the variant, so no `unknown` can enter `E` and there is no `qualify` to pass.
For a failure that is *not* modeled, settle the injected `defect` helper's
marker — the same injection `qualify` receives, and the only way to reach the
defect channel from inside an asynchronous callback (a `throw` there runs in
its own turn, long after the executor body returned).

`T` and `E` cannot be inferred from the body, since `settle` is a parameter.
Supply them explicitly, or let them flow from an annotated target. Absent
either, both default to `never` (Thesis #3: no path may produce `unknown` in
`E`) — so an unannotated call is a compile error at the `settle(...)` call
site, not a silently-`unknown` channel.

An executor that never settles yields an `AsyncResult` that never resolves —
the one hazard [fromPromise](#frompromise) does not have, and identical to
`new Promise`.

#### Example

```ts
import { fromExecutor, Err, Ok } from "unthrown";

const listen = (port: number) =>
  fromExecutor<Server, PortInUse>((settle, defect) => {
    server.once("error", (cause) =>
      isAddrInUse(cause) ? settle(Err(new PortInUse(port))) : settle(defect(cause)),
    );
    server.listen(port, () => settle(Ok(server)));
  });
```

***

### fromNullable()

```ts
function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
```

Defined in: [packages/core/src/interop.ts:51](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L51)

Bridge a nullable value into a [Result](#result-1): absence becomes a **modeled**
`Err`. The sanctioned alternative to an `Option` type.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the (nullable) value type. |
| `E` | the error produced when the value is absent. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `T` | `null` | `undefined` | the possibly-absent value. |
| `onAbsent` | () => `E` | lazily produces the error for the absent case. |

#### Returns

[`Result`](#result)<`NonNullable`<`T`>, `E`>

#### Remarks

`null` and `undefined` map to `Err(onAbsent())`; any other value (including
falsy ones like `0`, `""`, `false`) maps to `Ok`.

#### Example

```ts
import { fromNullable } from "unthrown";

const map = new Map([["a", 1]]);
fromNullable(map.get("a"), () => "absent").getOr(0); // => 1
fromNullable(map.get("z"), () => "absent"); // => Err("absent")
fromNullable(0, () => "absent").getOr(-1); // => 0 (falsy but present)
```

***

### fromPromise()

```ts
function fromPromise<T, R>(
   promise, 
   qualify, 
   ..._guard
): AsyncResult<T, Exclude<R, Defect>>;
```

Defined in: [packages/core/src/interop.ts:227](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L227)

Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult-1), forcing
every rejection to be triaged.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the resolved value type. |
| `R` | `qualify`'s return type; the modeled error `E` is `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted). |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `promise` | `Promise`<`T`> | (() => `Promise`<`T`>) | the promise, or a thunk returning one. |
| `qualify` | (`cause`, `defect`) => `R` | triages a rejection `cause` into a modeled `E`, or marks it unmodeled by returning `defect(cause)` (the helper passed as its second arg). |
| ...`_guard` | \[`Extract`<`R`, `PromiseLike`<`unknown`>>] *extends* \[`never`] ? \[] : \[`"unthrown: qualify must be synchronous — its Promise would land in E un-triaged"`] | compile-time only; never pass it. The phantom rest-tuple that enforces "qualify is synchronous": an `async` qualify makes this demand an impossible extra argument (whose type spells out the error), while a synchronous one leaves it empty. Encoded here — not on `qualify`'s return type — so `T`'s inference from `promise` is undisturbed. |

#### Returns

[`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, `Defect`>>

#### Remarks

`qualify` **must** map each rejection cause into a modeled error `E` or a
`Defect` (via the injected `defect` helper, its second argument). The returned
`AsyncResult`'s internal promise never rejects; `await`-ing it always yields a
`Result`. A throw inside `qualify` is itself a `Defect`. `qualify` is
**synchronous**: an `async` qualify is rejected at compile time
([NotThenable](#notthenable)), and a thenable slipped past the types at runtime
becomes a `Defect` (never an `Err(Promise)`), its orphaned rejection silenced.

The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
`qualify` that returns *only* `defect(cause)` yields `E = never`; when every
rejection is a Defect, prefer [fromSafePromise](#fromsafepromise).

#### Example

```ts
import { fromPromise } from "unthrown";

// A rejection with a NotFoundError becomes a modeled `Err`; anything else a Defect.
const user = await fromPromise(fetchUser(id), (cause, defect) =>
  cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
);

if (user.isOk()) user.value; // => the fetched user
// when fetchUser rejects with NotFoundError: user is Err("not_found")
```

***

### fromSafePromise()

```ts
function fromSafePromise<T>(promise): AsyncResult<T, never>;
```

Defined in: [packages/core/src/interop.ts:284](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L284)

Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
becomes a `Defect`.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `T` | the resolved value type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `promise` | `Promise`<`T`> | (() => `Promise`<`T`>) | the promise, or a thunk returning one. |

#### Returns

[`AsyncResult`](#asyncresult)<`T`, `never`>

#### Remarks

Use this only when a rejection genuinely indicates a bug rather than an
anticipated outcome — the error channel is `never`, so there is nothing to
triage. (`await`-ing still yields a `Result`; it never throws.) The
synchronous counterpart is [fromSafeThrowable](#fromsafethrowable).

#### Example

```ts
import { fromSafePromise } from "unthrown";

(await fromSafePromise(Promise.resolve(3))).get(); // => 3
// a rejection becomes a Defect (never a modeled Err):
await fromSafePromise(Promise.reject(new Error("boom"))); // => Defect(Error("boom"))
```

***

### fromSafeThrowable()

```ts
function fromSafeThrowable<A, T>(fn): (...args) => Result<T, never>;
```

Defined in: [packages/core/src/interop.ts:167](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L167)

Wrap a throwing synchronous function asserted **not** to fail in any modeled
way: any throw becomes a `Defect`.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `A` *extends* `unknown`\[] | the wrapped function's argument tuple. |
| `T` | the wrapped function's return type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fn` | (...`args`) => `T` | the throwing function to wrap. |

#### Returns

a function with the same arguments returning `Result<T, never>`.

(...`args`) => [`Result`](#result)<`T`, `never`>

#### Remarks

The synchronous counterpart of [fromSafePromise](#fromsafepromise). Use it only when a
throw genuinely indicates a bug rather than an anticipated outcome — the
error channel is `never`, so there is nothing to triage; there is no
`qualify`. When some throws *are* anticipated, reach for
[fromThrowable](#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 [fromSafePromise](#fromsafepromise) to wrap async work.

#### Example

```ts
import { fromSafeThrowable } from "unthrown";

// A decode failure here is a bug (the row came from our own schema), so
// every throw is a defect — no throwaway `(cause, defect) => defect(cause)`.
const decode = fromSafeThrowable((row: Row) => userSchema.parse(row));

decode(row); // => Result<User, never> — a throw becomes a Defect
```

***

### fromThrowable()

```ts
function fromThrowable<A, T, R>(fn, qualify): (...args) => Result<T, Exclude<R, Defect>>;
```

Defined in: [packages/core/src/interop.ts:108](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L108)

Wrap a throwing synchronous function so it returns a [Result](#result-1) instead of
throwing.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `A` *extends* `unknown`\[] | the wrapped function's argument tuple. |
| `T` | the wrapped function's return type. |
| `R` | `qualify`'s return type; the modeled error `E` is `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted). |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fn` | (...`args`) => `T` | the throwing function to wrap. |
| `qualify` | (`cause`, `defect`) => `R` & [`NotThenable`](#notthenable)<`R`> | 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>`.

(...`args`) => [`Result`](#result)<`T`, `Exclude`<`R`, `Defect`>>

#### Remarks

`qualify` **must** triage every thrown cause into a modeled error `E` or a
`Defect` (via the injected `defect` helper, its second argument) — there is no
path that leaves `unknown` in `E`. A throw inside `qualify` itself is treated
as a `Defect`. `qualify` is **synchronous**: an `async` qualify is rejected at
compile time ([NotThenable](#notthenable)) — its `Promise` would land in `E` un-triaged
— and a thenable slipped past the types at runtime becomes a `Defect` (never
an `Err(Promise)`), its orphaned rejection silenced.

`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 [fromPromise](#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
out-of-band and must not pollute the error channel); reach for
[fromSafeThrowable](#fromsafethrowable) when every throw is a Defect.

#### Example

```ts
import { fromThrowable } from "unthrown";

// Model the parse failure as an `Err`, everything unexpected as a `Defect`.
const parse = fromThrowable(
  (text: string) => JSON.parse(text) as unknown,
  (cause, defect) =>
    cause instanceof SyntaxError ? ("invalid_json" as const) : defect(cause),
);

parse('{"ok":true}').getOr(null); // => { ok: true }
parse("nope"); // => Err("invalid_json")
```

## Do-notation

### Do()

```ts
function Do(): Result<{
}, never>;
```

Defined in: [packages/core/src/do.ts:48](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/do.ts#L48)

Start a do-notation chain with an empty object scope, grown step by step with
`bind` (for `Result`-returning steps) and `let` (for pure values).

#### Returns

[`Result`](#result)<{
}, `never`>

#### Remarks

Capitalised because `do` is a reserved word. Each step receives the scope
accumulated so far; the error types union across `bind`s, and a throw in any
step becomes a `Defect`. To go asynchronous, lift the chain with `toAsync()`
(then a `bind` may return an `AsyncResult`).

#### Examples

```ts
import { Do, Ok } from "unthrown";

const result = Do()
  .bind("user", () => findUser(id)) // Result<User, NotFound>
  .bind("org", ({ user }) => findOrg(user.orgId)) // Result<Org, NotFound>
  .let("label", ({ user, org }) => `${user.name} @ ${org.name}`)
  .map(({ user, org, label }) => render(user, org, label));
// Result<View, NotFound>
```

```ts
import { Do, Ok, Err } from "unthrown";

// Ok path — the scope accumulates:
Do()
  .bind("a", () => Ok(2))
  .let("b", ({ a }) => a * 10)
  .map(({ a, b }) => a + b); // => Ok(22)

// Err path — the first Err short-circuits the rest:
Do()
  .bind("a", () => Err("boom"))
  .let("b", ({ a }) => a); // => Err("boom")
```

***

### DoAsync()

```ts
function DoAsync(): AsyncResult<{
}, never>;
```

Defined in: [packages/core/src/do.ts:76](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/do.ts#L76)

Start an **asynchronous** do-notation chain with an empty object scope — the
pre-lifted form of [Do](#do), sparing you `Do().toAsync()`.

#### Returns

[`AsyncResult`](#asyncresult)<{
}, `never`>

#### Remarks

From here a `bind` may return a `Result` **or** an `AsyncResult`; the scope
accumulates exactly as in a sync [Do](#do) chain, and a throw in any step
becomes a `Defect`. Named with the `Async` suffix the async free functions
carry (`OkAsync`, `allAsync`); the [AsyncResult](#asyncresult-1) companion aliases it as
`AsyncResult.Do` (the namespace already says "async", so the suffix drops).

#### Example

```ts
import { DoAsync, Ok } from "unthrown";

const result = await DoAsync()
  .bind("user", () => findUser(id)) // AsyncResult<User, NotFound>
  .bind("plan", ({ user }) => Ok(user.plan)) // a sync Result is accepted too
  .let("label", ({ user, plan }) => `${user.name} on ${plan}`);
// Result<{ user: User; plan: Plan; label: string }, NotFound>
```

## Guards

### isDefect()

```ts
function isDefect<T, E>(r): r is DefectView<T, E>;
```

Defined in: [packages/core/src/constructors.ts:204](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L204)

Type guard: narrow a [Result](#result-1) to its `Defect` variant, exposing `.cause`.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |
| `E` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Result`](#result)<`T`, `E`> |

#### Returns

`r is DefectView<T, E>`

`true` when `r` is a `Defect`.

#### Remarks

A `Defect` has no public constructor — it only arises at a boundary (e.g. a
callback throwing inside a combinator). This guard is how you detect one.

#### Example

```ts
import { isDefect, Ok } from "unthrown";

// A throw inside a combinator is captured as a Defect:
const r = Ok(1).map(() => {
  throw new Error("boom");
});
isDefect(r); // => true
isDefect(Ok(1)); // => false

if (isDefect(r)) r.cause; // unknown, narrowed
```

***

### isErr()

```ts
function isErr<T, E>(r): r is ErrView<E, T>;
```

Defined in: [packages/core/src/constructors.ts:176](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L176)

Type guard: narrow a [Result](#result-1) to its `Err` variant, exposing `.error`.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |
| `E` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Result`](#result)<`T`, `E`> |

#### Returns

`r is ErrView<E, T>`

`true` when `r` is `Err`.

#### Example

```ts
import { isErr, Ok, Err, type Result } from "unthrown";

isErr(Err("boom")); // => true
isErr(Ok(1)); // => false

declare const r: Result<number, string>;
if (isErr(r)) r.error; // string, narrowed
```

***

### isOk()

```ts
function isOk<T, E>(r): r is OkView<T, E>;
```

Defined in: [packages/core/src/constructors.ts:155](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/constructors.ts#L155)

Type guard: narrow a [Result](#result-1) to its `Ok` variant, exposing `.value`.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |
| `E` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Result`](#result)<`T`, `E`> |

#### Returns

`r is OkView<T, E>`

`true` when `r` is `Ok`.

#### Example

```ts
import { isOk, Ok, Err, type Result } from "unthrown";

isOk(Ok(1)); // => true
isOk(Err("boom")); // => false

declare const r: Result<number, string>;
if (isOk(r)) r.value; // number, narrowed
```

***

### isResult()

```ts
function isResult(x): x is Result<unknown, unknown>;
```

Defined in: [packages/core/src/core.ts:504](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/core.ts#L504)

Type guard: is `x` a [Result](#result-1) (any of `Ok` / `Err` / `Defect`)?

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `x` | `unknown` |

#### Returns

`x is Result<unknown, unknown>`

`true` when `x` is a `Result` produced by this library.

#### Remarks

Unlike [isOk](#isok-4) / [isErr](#iserr-4) / [isDefect](#isdefect-4), which narrow a value
already known to be a `Result`, this narrows from `unknown` — useful at an
untyped boundary. It checks the value carries the `Result` prototype
(`instanceof` first, falling back to the `Symbol.for("unthrown.Result")`
brand the prototype carries — so a `Result` built by **another copy** of
unthrown, e.g. the CJS and ESM builds loaded side by side, is still
recognised). A look-alike plain object (`{ tag: "Ok" }`) carries neither and
is **not** matched; nor is a forgery built on the real prototype whose `tag` or
payload is a getter (both must be own data properties). An `AsyncResult` is not a `Result` and returns `false`.

#### Example

```ts
import { isResult, Ok, P } from "unthrown";

isResult(Ok(1)); // => true
isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
isResult(Ok(1).toAsync()); // => false (an AsyncResult is not a Result)

const x: unknown = Ok(1);
if (isResult(x))
  // `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,
  });
```

## Tagged errors

### TaggedError()

```ts
function TaggedError<Tag>(tag, options?): TaggedErrorConstructor<Tag>;
```

Defined in: [packages/core/src/tagged.ts:110](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/tagged.ts#L110)

Build a base class for a tagged error — a class extending `Error` with a
`_tag` string discriminant, in the style of Effect's `Data.TaggedError`.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `Tag` *extends* `string` | the string literal discriminant. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tag` | `Tag` | the discriminant value; also the default error `name`. |
| `options?` | { `name?`: `string`; } | optional overrides. `options.name` sets `Error.name` independently of `tag` (defaults to `tag`). |
| `options.name?` | `string` | - |

#### Returns

[`TaggedErrorConstructor`](#taggederrorconstructor)<`Tag`>

#### Remarks

Extend the returned class to declare a concrete error. Supply the payload with
an instantiation expression; omit it for a payload-less error. The `message`
is **not** a payload field — it is the human string owned by `Error`, not
structured data, so it is reserved. Define it once per subclass the standard
way, `override message = "…"` (it may interpolate the payload via `this`,
which the base populates before the subclass field initialiser runs); a
payload `message` is rejected at compile time, so contextual detail lives in
typed fields, never baked into per-call prose. The `_tag` always reflects
`tag` and cannot be overridden by the payload. `name` is likewise reserved —
it is the display label (set it with `options.name`); a payload `name` is
rejected at compile time (and excluded from the instance type), so it can't
shadow `Error.name`. `stack` is reserved the same way — it is `Error`'s
trace, and even an untyped payload `stack` cannot clobber the real one.
`cause` is deliberately **not** reserved: `Error.cause` is typed `unknown`,
so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
*narrowing* structured field.

The matching half of the convention is `P.tag(t)` — the pattern constructor on
the `P` namespace, which builds the `{ _tag: t }` pattern this factory's `_tag`
is selected by (there is no standalone `tag` export).

`_tag` is the discriminant matched by `P.tag` in the error combinators
(`result.mapErrCases((matcher) => matcher.with(P.tag("NotFound"), …))`) and in
`match`'s `errCases` handler; `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`:

```ts
class RetryableError extends TaggedError("@my-lib/RetryableError", {
  name: "RetryableError",
}) {
  override message = "operation failed; safe to retry";
}

const e = new RetryableError();
e._tag;    // "@my-lib/RetryableError" — namespaced discriminant
e.name;    // "RetryableError"          — clean display name
e.message; // "operation failed; safe to retry" — the standard Error.message
```

#### Example

```ts
class NotFound extends TaggedError("NotFound") {}
class HttpError extends TaggedError("HttpError")<{ status: number }> {}

new NotFound()._tag; // => "NotFound"
new HttpError({ status: 500 }).status; // => 500
```

## Aggregate

### all()

```ts
function all<Rs>(results): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
```

Defined in: [packages/core/src/interop.ts:729](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L729)

Collect a tuple/array of [Result](#result-1)s into a single `Result` of all their
success values.

#### Type Parameters

| Type Parameter |
| ------ |
| `Rs` *extends* readonly [`Result`](#result)<`unknown`, `unknown`>\[] |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `results` | readonly \[`Rs`] |

#### Returns

[`Result`](#result)<`AllOk`<`Rs`, { \[K in string | number | symbol]: OkOf\<Rs\[K]> }>, [`ErrOf`](#errof)<`Rs`\[`number`]>>

#### Remarks

Short-circuits on the **first** `Err` (later entries are not inspected for
their error); any `Defect` present **dominates**, winning even over an earlier
`Err`. A **fixed tuple** keeps its positional types — `all([Ok(1), Ok("a")])`
is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
use [allFromDict](#allfromdict). To report **every** `Err` instead of only the first,
use [validateAll](#validateall).

#### Example

```ts
import { all, Ok, Err } from "unthrown";

all([Ok(1), Ok("a"), Ok(true)]).get(); // => [1, "a", true] (typed [number, string, boolean])
all([Ok(1), Err("e"), Ok(3)]); // => Err("e") (short-circuits on the first Err)
```

***

### allAsync()

```ts
function allAsync<Rs>(results): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
```

Defined in: [packages/core/src/interop.ts:793](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L793)

The asynchronous counterpart of [all](#all): combine a tuple/array of
[AsyncResult](#asyncresult-1)s into one `AsyncResult` of all their success values.

#### Type Parameters

| Type Parameter |
| ------ |
| `Rs` *extends* readonly [`AsyncResult`](#asyncresult)<`unknown`, `unknown`>\[] |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `results` | readonly \[`Rs`] |

#### Returns

[`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, { \[K in string | number | symbol]: AsyncOkOf\<Rs\[K]> }>, [`AsyncErrOf`](#asyncerrof)<`Rs`\[`number`]>>

#### Remarks

The inputs are resolved **concurrently** (order preserved); the resolved
`Result`s are then folded with the same rules as [all](#all) — first `Err`
short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
internal promise never rejects. For a **record**, use [allFromDictAsync](#allfromdictasync);
to report **every** `Err`, use [validateAllAsync](#validateallasync).

#### Example

```ts
import { allAsync, fromSafePromise } from "unthrown";

const both = allAsync([
  fromSafePromise(Promise.resolve(1)),
  fromSafePromise(Promise.resolve(2)),
]);
(await both).get(); // => [1, 2]
```

***

### allFromDict()

```ts
function allFromDict<R>(results): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
```

Defined in: [packages/core/src/interop.ts:760](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L760)

Collect a **record** of [Result](#result-1)s into a single `Result` of a record of
their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
`Result<{ a: A; b: B }, E>`. The named counterpart of [all](#all), for
parallel work you'd rather not tuple.

#### Type Parameters

| Type Parameter |
| ------ |
| `R` *extends* `ResultRecord` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `results` | `R` |

#### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: OkOf\<R\[K]> }, [`ErrOf`](#errof)<`R`\[keyof `R`]>>

#### Remarks

Same folding rules as [all](#all): first `Err` short-circuits, any `Defect`
dominates. This is **not** error accumulation — for that, reach for
[validateAllFromDict](#validateallfromdict), which accumulates every `Err` and folds them into
one modeled error.

#### Example

```ts
import { allFromDict, Ok, Err } from "unthrown";

allFromDict({ id: Ok(1), name: Ok("ada") }).get(); // => { id: 1, name: "ada" }
allFromDict({ id: Ok(1), name: Err("missing") }); // => Err("missing")
```

***

### allFromDictAsync()

```ts
function allFromDictAsync<R>(results): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
```

Defined in: [packages/core/src/interop.ts:828](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L828)

The asynchronous counterpart of [allFromDict](#allfromdict): combine a record of
[AsyncResult](#asyncresult-1)s into one `AsyncResult` of a record of their values.

#### Type Parameters

| Type Parameter |
| ------ |
| `R` *extends* `AsyncResultRecord` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `results` | `R` |

#### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: AsyncOkOf\<R\[K]> }, [`AsyncErrOf`](#asyncerrof)<`R`\[keyof `R`]>>

#### Remarks

Resolved concurrently (order preserved), folded with the [all](#all) rules,
and the internal promise never rejects. To report **every** `Err`, use
[validateAllFromDictAsync](#validateallfromdictasync).

#### Example

```ts
import { allFromDictAsync, fromSafePromise } from "unthrown";

const both = allFromDictAsync({
  a: fromSafePromise(Promise.resolve(1)),
  b: fromSafePromise(Promise.resolve("x")),
});
(await both).get(); // => { a: 1, b: "x" }
```

***

### validateAll()

```ts
function validateAll<Rs, E2>(results, merge): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, E2>;
```

Defined in: [packages/core/src/interop.ts:894](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L894)

Collect a tuple/array of [Result](#result-1)s, **accumulating every** `Err` and
merging them into a single modeled error — the accumulating counterpart of
[all](#all).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `Rs` *extends* readonly [`Result`](#result)<`unknown`, `unknown`>\[] | the tuple/array of input `Result` types. |
| `E2` | the merged error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `results` | readonly \[`Rs`] | the results to collect. |
| `merge` | (`errors`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | folds the collected errors into one modeled error. |

#### Returns

[`Result`](#result)<`AllOk`<`Rs`, { \[K in string | number | symbol]: OkOf\<Rs\[K]> }>, `E2`>

#### Remarks

Same success channel as [all](#all): a **fixed tuple** keeps its positional
types, a **dynamic array** collapses to `Result<T[], E2>`. The difference is
the error channel — instead of the first `Err` winning, every `Err` is
collected in input order and handed to `merge`, whose return becomes the
modeled error.

`merge` receives a **non-empty** list, so it is total: it is called only when
at least one `Err` was collected. It is **not** called when every element is
`Ok`, nor when a `Defect` is present.

Any `Defect` still **dominates** — it wins over the accumulated errors, which
are discarded and never reach `merge`. A defect means something in this batch
failed in a way nobody modeled, so the violations computed alongside it are
not trustworthy. An out-of-contract non-`Result` element becomes a
`TypeError`-caused `Defect` the same way, and a throw inside `merge` becomes
a `Defect` too.

`merge` must be **synchronous** — an `async` one is a compile error
([NotThenable](#notthenable)), since a `Promise` in `E` is an unqualified rejection.

For **schema-shaped** input (a request body, a form), reach for
`@unthrown/standard-schema`'s `fromSchema` instead — a validator already
hands you every issue as the modeled error. `validateAll` is for independent
checks you wrote yourself. For a **record** keyed by name, use
[validateAllFromDict](#validateallfromdict).

#### Example

```ts
import { validateAll, Ok, Err } from "unthrown";

// every Err is collected, not just the first
validateAll([Ok(1), Err("stock"), Err("credit")], (errors) => errors.join(" and "));
// => Err("stock and credit")

// all-Ok keeps the positional tuple; `merge` never runs
validateAll([Ok(1), Ok("a")], (errors) => errors.join());
// => Ok([1, "a"]) typed Result<[number, string], string>
```

***

### validateAllAsync()

```ts
function validateAllAsync<Rs, E2>(results, merge): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, E2>;
```

Defined in: [packages/core/src/interop.ts:979](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L979)

The asynchronous counterpart of [validateAll](#validateall): collect a tuple/array of
[AsyncResult](#asyncresult-1)s, accumulating every `Err` into one merged error.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `Rs` *extends* readonly [`AsyncResult`](#asyncresult)<`unknown`, `unknown`>\[] | the tuple/array of input `AsyncResult` types. |
| `E2` | the merged error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `results` | readonly \[`Rs`] | the async results to collect. |
| `merge` | (`errors`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | folds the collected errors into one modeled error. |

#### Returns

[`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, { \[K in string | number | symbol]: AsyncOkOf\<Rs\[K]> }>, `E2`>

#### Remarks

Every [validateAll](#validateall) rule holds, with the inputs resolved
**concurrently** (order preserved) — as with [allAsync](#allasync), no work is
short-circuited either way; the fail-fast/accumulating split is purely which
errors get reported. The internal promise never rejects: an out-of-contract
rejecting thenable becomes a dominating `Defect`. `merge` stays synchronous
here too — this is exactly where its rejection would land unqualified in `E`.
For a **record**, use [validateAllFromDictAsync](#validateallfromdictasync).

#### Example

```ts
import { validateAllAsync, OkAsync, ErrAsync } from "unthrown";

const checked = validateAllAsync(
  [OkAsync(1), ErrAsync("stock"), ErrAsync("credit")],
  (errors) => errors.join(" and "),
);
// (await checked) => Err("stock and credit")
```

***

### validateAllFromDict()

```ts
function validateAllFromDict<R, E2>(results, merge): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, E2>;
```

Defined in: [packages/core/src/interop.ts:939](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L939)

Collect a **record** of [Result](#result-1)s, accumulating every `Err` — the
accumulating counterpart of [allFromDict](#allfromdict), and the named counterpart of
[validateAll](#validateall).

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` *extends* `ResultRecord` | the record of input `Result` types. |
| `E2` | the merged error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `results` | `R` | the results to collect, keyed by name. |
| `merge` | (`entries`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | folds the collected `[key, error]` entries into one error. |

#### Returns

[`Result`](#result)<{ \[K in string | number | symbol]: OkOf\<R\[K]> }, `E2`>

#### Remarks

`merge` receives a non-empty list of **`[key, error]` entries**, correlated
per key: `{ a: Result<A, E1>; b: Result<B, E2> }` yields
`["a", E1] | ["b", E2]`, so a `switch` on the key narrows the error and an
impossible pairing does not typecheck. That is what keeps two checks sharing
one error type distinguishable. Entries come in key order — `Object.keys`
order, then enumerable symbol keys (a symbol key is folded like any other).

Every other rule matches [validateAll](#validateall): any `Defect` dominates and
discards the accumulated errors, a throw in `merge` becomes a `Defect`, and
`merge` must be synchronous.

#### Example

```ts
import { validateAllFromDict, Ok, Err } from "unthrown";

validateAllFromDict(
  { vatRate: Err("out of range"), currency: Ok("EUR"), dueDate: Err("past") },
  (entries) => entries.map(([key, error]) => `${key}: ${error}`).join("; "),
);
// => Err("vatRate: out of range; dueDate: past")
```

***

### validateAllFromDictAsync()

```ts
function validateAllFromDictAsync<R, E2>(results, merge): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, E2>;
```

Defined in: [packages/core/src/interop.ts:1016](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/interop.ts#L1016)

The asynchronous counterpart of [validateAllFromDict](#validateallfromdict): collect a record
of [AsyncResult](#asyncresult-1)s, accumulating every `Err` into one merged error.

#### Type Parameters

| Type Parameter | Description |
| ------ | ------ |
| `R` *extends* `AsyncResultRecord` | the record of input `AsyncResult` types. |
| `E2` | the merged error type. |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `results` | `R` | the async results to collect, keyed by name. |
| `merge` | (`entries`) => `E2` & [`NotThenable`](#notthenable)<`E2`> | folds the collected `[key, error]` entries into one error. |

#### Returns

[`AsyncResult`](#asyncresult)<{ \[K in string | number | symbol]: AsyncOkOf\<R\[K]> }, `E2`>

#### Remarks

The [validateAllFromDict](#validateallfromdict) rules, over inputs resolved concurrently as
in [validateAllAsync](#validateallasync).

#### Example

```ts
import { validateAllFromDictAsync, OkAsync, ErrAsync } from "unthrown";

const checked = validateAllFromDictAsync(
  { stock: ErrAsync("none left"), credit: OkAsync(500) },
  (entries) => entries.map(([key, error]) => `${key}: ${error}`).join("; "),
);
// (await checked) => Err("stock: none left")
```

## Errors

### GetError

Defined in: [packages/core/src/core.ts:64](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/core.ts#L64)

Thrown by a [Result](#result-1)'s `get` / `getErr` when the assertion is
wrong on a *modeled* result — `get()` on an `Err`, or `getErr()` on an
`Ok`.

#### Remarks

The offending value is exposed two ways: the typed [GetError.error](#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 a `GetError`: its original cause is
re-thrown (with its original stack) instead.

`get()` and `getErr()` are type-gated (`this: Result<T, never>` /
`Result<never, E>`), so the wrong-variant branch that throws this is
unreachable through well-typed code — it remains only as a defensive guard
against unsound runtime misuse (e.g. an `as` cast past the gate).

#### Extends

* `Error`

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
| `E` | `unknown` | the type of the [GetError.error](#error) it carries. |

#### Constructors

##### Constructor

```ts
new GetError<E>(error): GetError<E>;
```

Defined in: [packages/core/src/core.ts:70](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/core.ts#L70)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `error` | `E` |

###### Returns

[`GetError`](#geterror)<`E`>

###### Overrides

```ts
Error.constructor
```

#### Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `cause?` | `public` | `unknown` | - | `Error.cause` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24 |
|  `error` | `readonly` | `E` | The offending value: the `Err` error for `get()`, or the `Ok` value for `getErr()`. | - | [packages/core/src/core.ts:69](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/core.ts#L69) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured *after* the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:67 |

#### Methods

##### captureStackTrace()

```ts
static captureStackTrace(targetObject, constructorOpt?): void;
```

Defined in: node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:51

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

###### Returns

`void`

###### Inherited from

```ts
Error.captureStackTrace
```

##### prepareStackTrace()

```ts
static prepareStackTrace(err, stackTraces): any;
```

Defined in: node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:55

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

###### Returns

`any`

###### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

###### Inherited from

```ts
Error.prepareStackTrace
```

***

### NonExhaustiveError

Defined in: [packages/core/src/matcher.ts:296](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L296)

Thrown by `.run()` / `.exhaustive()` when no arm matched the value. For
well-typed callers the match is exhaustive by construction, so this is only
reachable by a value that slipped past the types (a widened cast, a raw-JS
caller); inside the error combinators the throw-to-defect net converts it to
a `Defect`, and at the `match` edge it surfaces (a genuinely unmodeled value
is a bug).

#### Example

```ts
import { match, NonExhaustiveError } from "unthrown";

// A value typed "a" | "b" that is really "c" (a cast, a raw-JS caller):
const rogue = "c" as "a" | "b";
try {
  match(rogue)
    .with("a", () => 1)
    .with("b", () => 2)
    .exhaustive();
} catch (error) {
  error instanceof NonExhaustiveError; // => true
  (error as NonExhaustiveError).input; // => "c"
}
```

#### Extends

* `Error`

#### Constructors

##### Constructor

```ts
new NonExhaustiveError(input): NonExhaustiveError;
```

Defined in: [packages/core/src/matcher.ts:299](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L299)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `unknown` |

###### Returns

[`NonExhaustiveError`](#nonexhaustiveerror)

###### Overrides

```ts
Error.constructor
```

#### Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `cause?` | `public` | `unknown` | - | `Error.cause` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24 |
|  `input` | `readonly` | `unknown` | The value no arm matched. | - | [packages/core/src/matcher.ts:298](https://github.com/btravstack/unthrown/blob/c3fdcf7870bbb87a3ed74f4cc521fde8030cac54/packages/core/src/matcher.ts#L298) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured *after* the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:67 |

#### Methods

##### captureStackTrace()

```ts
static captureStackTrace(targetObject, constructorOpt?): void;
```

Defined in: node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:51

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

###### Returns

`void`

###### Inherited from

```ts
Error.captureStackTrace
```

##### prepareStackTrace()

```ts
static prepareStackTrace(err, stackTraces): any;
```

Defined in: node\_modules/.pnpm/@types+node@26.5.1/node\_modules/@types/node/globals.d.ts:55

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

###### Returns

`any`

###### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

###### Inherited from

```ts
Error.prepareStackTrace
```