unthrown 0.1.0

package/docs/index.md

@@ -0,0 +1,1163 @@
+**unthrown**
+
+***
+
+# unthrown
+
+## Classes
+
+### UnwrapError
+
+Defined in: [packages/core/src/core.ts:29](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/core.ts#L29)
+
+Thrown by a [Result](#result)'s `unwrap` / `unwrapErr` when the assertion is
+wrong on a *modeled* result — `unwrap()` on an `Err`, or `unwrapErr()` on an
+`Ok`.
+
+#### Remarks
+
+A `Defect` is never wrapped in an `UnwrapError`: its original cause is
+re-thrown (with its original stack) instead.
+
+#### Extends
+
+- `Error`
+
+#### Type Parameters
+
+| Type Parameter | Default type | Description |
+| ------ | ------ | ------ |
+| `E` | `unknown` | the type of the [UnwrapError.error](#error) it carries. |
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new UnwrapError<E>(error): UnwrapError<E>;
+```
+
+Defined in: [packages/core/src/core.ts:35](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/core.ts#L35)
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `error` | `E` |
+
+###### Returns
+
+[`UnwrapError`](#unwraperror)&lt;`E`&gt;
+
+###### Overrides
+
+```ts
+Error.constructor
+```
+
+#### Properties
+
+| Property | Modifier | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ | ------ |
+| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24 |
+| <a id="error"></a> `error` | `readonly` | `E` | The offending value: the `Err` error for `unwrap()`, or the `Ok` value for `unwrapErr()`. | - | [packages/core/src/core.ts:34](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/core.ts#L34) |
+| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075 |
+| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074 |
+| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
+| <a id="stacktracelimit"></a> `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@24.13.2/node\_modules/@types/node/globals.d.ts:68 |
+
+#### Methods
+
+##### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: node\_modules/.pnpm/@types+node@24.13.2/node\_modules/@types/node/globals.d.ts:52
+
+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@24.13.2/node\_modules/@types/node/globals.d.ts:56
+
+###### 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
+```
+
+## Type Aliases
+
+### AsyncResult
+
+```ts
+type AsyncResult<T, E> = Awaitable<Result<T, E>> & object;
+```
+
+Defined in: [packages/core/src/types.ts:278](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L278)
+
+The asynchronous counterpart of [Result](#result): an awaitable wrapper with the
+same method surface, collapsing to a `Result<T, E>` when `await`-ed.
+
+#### Type Declaration
+
+| Name | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| `as()` | (`value`) => [`AsyncResult`](#asyncresult)&lt;`U`, `E`&gt; | Asynchronous `as`. | [packages/core/src/types.ts:289](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L289) |
+| `flatMap()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`U`, `E` \| `E2`&gt; | Asynchronous `flatMap`. `f` may return a `Result` **or** an `AsyncResult` (never a raw `Promise`); a throw becomes a `Defect`. | [packages/core/src/types.ts:285](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L285) |
+| `getOrNull()` | () => `Promise`&lt;`T` \| `null`&gt; | Asynchronous `getOrNull`. | [packages/core/src/types.ts:322](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L322) |
+| `getOrUndefined()` | () => `Promise`&lt;`T` \| `undefined`&gt; | Asynchronous `getOrUndefined`. | [packages/core/src/types.ts:324](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L324) |
+| `map()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`U`, `E`&gt; | Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L280) |
+| `mapErr()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T`, `E2`&gt; | Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:292](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L292) |
+| `match()` | (`cases`) => `Promise`&lt;`R`&gt; | Asynchronous `match`. Handlers are synchronous; resolves to `R`. | [packages/core/src/types.ts:308](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L308) |
+| `orElse()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T` \| `U`, `E2`&gt; | Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:294](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L294) |
+| `recover()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T` \| `U`, `never`&gt; | Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:296](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L296) |
+| `recoverDefect()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T` \| `U`, `E` \| `E2`&gt; | Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:301](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L301) |
+| `tap()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt; | Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:287](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L287) |
+| `tapDefect()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt; | Asynchronous `tapDefect`. | [packages/core/src/types.ts:305](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L305) |
+| `tapErr()` | (`f`) => [`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt; | Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:298](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L298) |
+| `unwrap()` | () => `Promise`&lt;`T`&gt; | Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. | [packages/core/src/types.ts:314](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L314) |
+| `unwrapErr()` | () => `Promise`&lt;`E`&gt; | Asynchronous `unwrapErr`. | [packages/core/src/types.ts:316](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L316) |
+| `unwrapOr()` | (`fallback`) => `Promise`&lt;`T`&gt; | Asynchronous `unwrapOr`. | [packages/core/src/types.ts:318](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L318) |
+| `unwrapOrElse()` | (`f`) => `Promise`&lt;`T`&gt; | Asynchronous `unwrapOrElse`. | [packages/core/src/types.ts:320](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L320) |
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the success value type. |
+| `E` | the modeled error type. |
+
+#### 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 (`unwrap`, …) return promises; the binds
+(`flatMap`, `orElse`, `recoverDefect`) additionally accept an `AsyncResult`.
+
+To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
+
+***
+
+### Awaitable
+
+```ts
+type Awaitable<T> = object;
+```
+
+Defined in: [packages/core/src/types.ts:256](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L256)
+
+A success-only thenable: awaitable, but deliberately **not** a full
+`PromiseLike`.
+
+#### Remarks
+
+An [AsyncResult](#asyncresult)'s internal promise never rejects, so `await`-ing one
+always yields a [Result](#result) 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); the narrowing simply keeps it from
+being treated as a raw promise (e.g. dropped into `Promise.all`).
+
+#### 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:257](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L257)
+
+###### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `R` | `T` |
+
+###### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `onfulfilled?` | ((`value`) => `R` \| `PromiseLike`&lt;`R`&gt;) \| `null` |
+
+###### Returns
+
+`PromiseLike`&lt;`R`&gt;
+
+***
+
+### Defect
+
+```ts
+type Defect = object;
+```
+
+Defined in: [packages/core/src/defect.ts:15](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/defect.ts#L15)
+
+The marker a `qualify` function returns to triage a cause as **unexpected**.
+
+#### Remarks
+
+`qualify` (passed to [fromPromise](#frompromise) / [fromThrowable](#fromthrowable)) returns
+`E | Defect`: either a modeled domain error, or a `Defect` produced by
+[defect](#defect-2) to say "this failure is not modeled". A `Defect` is opaque —
+it carries the original cause for the boundary to convert into the third
+runtime state of a `Result`.
+
+#### Properties
+
+| Property | Modifier | Type | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/defect.ts#L16) |
+| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/defect.ts#L17) |
+
+***
+
+### DefectView
+
+```ts
+type DefectView<T, E> = ResultMethods<T, E> & object;
+```
+
+Defined in: [packages/core/src/types.ts:199](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L199)
+
+The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `cause`.
+
+#### Type Declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| `cause` | `unknown` | [packages/core/src/types.ts:201](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L201) |
+| `tag` | `"Defect"` | [packages/core/src/types.ts:200](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L200) |
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` | `never` |
+| `E` | `never` |
+
+***
+
+### ErrOf
+
+```ts
+type ErrOf<R> = R extends object ? E : never;
+```
+
+Defined in: [packages/core/src/types.ts:338](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L338)
+
+Extract the error type `E` from a `Result`.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `R` | the `Result` type to inspect. |
+
+***
+
+### ErrView
+
+```ts
+type ErrView<E, T> = ResultMethods<T, E> & object;
+```
+
+Defined in: [packages/core/src/types.ts:194](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L194)
+
+The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
+
+#### Type Declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| `error` | `E` | [packages/core/src/types.ts:196](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L196) |
+| `tag` | `"Err"` | [packages/core/src/types.ts:195](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L195) |
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `E` | - |
+| `T` | `never` |
+
+***
+
+### OkOf
+
+```ts
+type OkOf<R> = R extends object ? T : never;
+```
+
+Defined in: [packages/core/src/types.ts:332](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L332)
+
+Extract the success type `T` from a `Result`.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `R` | the `Result` type to inspect. |
+
+***
+
+### OkView
+
+```ts
+type OkView<T, E> = ResultMethods<T, E> & object;
+```
+
+Defined in: [packages/core/src/types.ts:189](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L189)
+
+The `Ok` variant of a [Result](#result): a success carrying a `value`.
+
+#### Type Declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| `tag` | `"Ok"` | [packages/core/src/types.ts:190](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L190) |
+| `value` | `T` | [packages/core/src/types.ts:191](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/types.ts#L191) |
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` | - |
+| `E` | `never` |
+
+***
+
+### Result
+
+```ts
+type Result<T, E> = ResultType<T, E>;
+```
+
+Defined in: [packages/core/src/facade.ts:31](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L31)
+
+Companion object grouping the standalone entry points under a single,
+discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
+[Result.defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
+[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
+[Result.isOk](#property-isok), [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect).
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `E` |
+
+#### 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).
+
+#### Example
+
+```ts
+import { Result } from "unthrown";
+Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
+```
+
+***
+
+### TaggedErrorConstructor
+
+```ts
+type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
+```
+
+Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L28)
+
+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` |
+
+#### Returns
+
+[`TaggedErrorInstance`](#taggederrorinstance)&lt;`Tag`, `A`&gt;
+
+#### Remarks
+
+When the payload is empty, the constructor takes **no** arguments (the
+`keyof A extends never ? void : A` trick); otherwise it takes the payload.
+
+***
+
+### TaggedErrorInstance
+
+```ts
+type TaggedErrorInstance<Tag, A> = Error & Readonly<A> & object;
+```
+
+Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L15)
+
+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:16](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L16) |
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `Tag` *extends* `string` | the string literal discriminant. |
+| `A` *extends* `Props` | the payload object type. |
+
+***
+
+### TagHandlers
+
+```ts
+type TagHandlers<T, E, R> = object & { [K in E["_tag"]]: (error: Extract<E, { _tag: K }>) => R };
+```
+
+Defined in: [packages/core/src/tagged.ts:81](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L81)
+
+The handler object [matchTags](#matchtags) requires: a branch per error tag, plus
+`Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
+enforced by the type, with no `.exhaustive()` to forget.
+
+#### Type Declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:83](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L83) |
+| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:82](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L82) |
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the success value type. |
+| `E` *extends* `object` | the tagged error union. |
+| `R` | the folded result type. |
+
+## Variables
+
+### Result
+
+```ts
+const Result: object;
+```
+
+Defined in: [packages/core/src/facade.ts:31](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L31)
+
+Companion object grouping the standalone entry points under a single,
+discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
+[Result.defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
+[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
+[Result.isOk](#property-isok), [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect).
+
+#### Type Declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| <a id="property-all"></a> `all()` | &lt;`Rs`&gt;(`results`) => `Result`&lt;\{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}, [`ErrOf`](#errof)&lt;`Rs`\[`number`\]&gt;&gt; | [packages/core/src/facade.ts:39](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L39) |
+| <a id="property-defect"></a> `defect()` | (`cause`) => [`Defect`](#defect) | [packages/core/src/facade.ts:34](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L34) |
+| <a id="property-err"></a> `err()` | &lt;`E`&gt;(`error`) => `Result`&lt;`never`, `E`&gt; | [packages/core/src/facade.ts:33](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L33) |
+| <a id="property-fromnullable"></a> `fromNullable()` | &lt;`T`, `E`&gt;(`value`, `onAbsent`) => `Result`&lt;`NonNullable`&lt;`T`&gt;, `E`&gt; | [packages/core/src/facade.ts:35](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L35) |
+| <a id="property-frompromise"></a> `fromPromise()` | &lt;`T`, `E`&gt;(`promise`, `qualify`) => [`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt; | [packages/core/src/facade.ts:37](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L37) |
+| <a id="property-fromsafepromise"></a> `fromSafePromise()` | &lt;`T`&gt;(`promise`) => [`AsyncResult`](#asyncresult)&lt;`T`, `never`&gt; | [packages/core/src/facade.ts:38](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L38) |
+| <a id="property-fromthrowable"></a> `fromThrowable()` | &lt;`A`, `T`, `E`&gt;(`fn`, `qualify`) => (...`args`) => `Result`&lt;`T`, `E`&gt; | [packages/core/src/facade.ts:36](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L36) |
+| <a id="property-isdefect"></a> `isDefect()` | &lt;`T`, `E`&gt;(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:42](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L42) |
+| <a id="property-iserr"></a> `isErr()` | &lt;`T`, `E`&gt;(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:41](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L41) |
+| <a id="property-isok"></a> `isOk()` | &lt;`T`, `E`&gt;(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:40](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L40) |
+| <a id="property-ok"></a> `ok()` | &lt;`T`&gt;(`value`) => `Result`&lt;`T`, `never`&gt; | [packages/core/src/facade.ts:32](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/facade.ts#L32) |
+
+#### 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).
+
+#### Example
+
+```ts
+import { Result } from "unthrown";
+Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
+```
+
+## Functions
+
+### all()
+
+```ts
+function all<Rs>(results): Result<{ [K in string | number | symbol]: OkOf<Rs[K]> }, ErrOf<Rs[number]>>;
+```
+
+Defined in: [packages/core/src/interop.ts:162](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/interop.ts#L162)
+
+Collect a tuple of [Result](#result)s into a single `Result` of the tuple of
+success values.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `Rs` *extends* readonly `Result`&lt;`unknown`, `unknown`&gt;[] | the tuple of input `Result` types. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `results` | readonly \[`Rs`\] | the results to combine. |
+
+#### Returns
+
+`Result`&lt;\{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}, [`ErrOf`](#errof)&lt;`Rs`\[`number`\]&gt;&gt;
+
+#### 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`. Positional types are preserved, so `all([ok(1), ok("a")])` is
+`Result<[number, string], …>`.
+
+#### Example
+
+```ts
+import { all, ok } from "unthrown";
+all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true]
+```
+
+***
+
+### defect()
+
+```ts
+function defect(cause): Defect;
+```
+
+Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/defect.ts#L36)
+
+Wrap a cause as a [Defect](#defect) — the value you return from a `qualify`
+function when a failure is **not** a modeled domain error.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `cause` | `unknown` | the original thrown/rejected value. |
+
+#### Returns
+
+[`Defect`](#defect)
+
+an opaque defect marker carrying `cause`.
+
+#### Example
+
+```ts
+import { fromPromise, defect } from "unthrown";
+
+const user = fromPromise(fetchUser(id), (cause) =>
+  cause instanceof NotFoundError ? cause : defect(cause),
+);
+```
+
+***
+
+### err()
+
+```ts
+function err<E>(error): Result<never, E>;
+```
+
+Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/constructors.ts#L34)
+
+Construct a failed [Result](#result) 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`&lt;`never`, `E`&gt;
+
+#### Example
+
+```ts
+import { err } from "unthrown";
+err("not_found").unwrapErr(); // "not_found"
+```
+
+***
+
+### fromNullable()
+
+```ts
+function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
+```
+
+Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/interop.ts#L29)
+
+Bridge a nullable value into a [Result](#result): 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`&lt;`NonNullable`&lt;`T`&gt;, `E`&gt;
+
+#### 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";
+fromNullable(map.get(key), () => "missing").unwrap();
+```
+
+***
+
+### fromPromise()
+
+```ts
+function fromPromise<T, E>(promise, qualify): AsyncResult<T, E>;
+```
+
+Defined in: [packages/core/src/interop.ts:95](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/interop.ts#L95)
+
+Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult), forcing
+every rejection to be triaged.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the resolved value type. |
+| `E` | the modeled error type. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `promise` | `Promise`&lt;`T`&gt; \| (() => `Promise`&lt;`T`&gt;) | the promise, or a thunk returning one. |
+| `qualify` | (`cause`) => [`Defect`](#defect) \| `E` | triages a rejection cause into `E` or a `Defect`. |
+
+#### Returns
+
+[`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt;
+
+#### Remarks
+
+`qualify` **must** map each rejection cause into a modeled error `E` or a
+[Defect](#defect). The returned `AsyncResult`'s internal promise never rejects;
+`await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
+`Defect`.
+
+#### Example
+
+```ts
+import { fromPromise, defect } from "unthrown";
+const user = await fromPromise(fetchUser(id), (cause) =>
+  cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
+);
+```
+
+***
+
+### fromSafePromise()
+
+```ts
+function fromSafePromise<T>(promise): AsyncResult<T, never>;
+```
+
+Defined in: [packages/core/src/interop.ts:119](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/interop.ts#L119)
+
+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`&lt;`T`&gt; \| (() => `Promise`&lt;`T`&gt;) | the promise, or a thunk returning one. |
+
+#### Returns
+
+[`AsyncResult`](#asyncresult)&lt;`T`, `never`&gt;
+
+#### 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.)
+
+***
+
+### fromThrowable()
+
+```ts
+function fromThrowable<A, T, E>(fn, qualify): (...args) => Result<T, E>;
+```
+
+Defined in: [packages/core/src/interop.ts:59](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/interop.ts#L59)
+
+Wrap a throwing synchronous function so it returns a [Result](#result) instead of
+throwing.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `A` *extends* `unknown`[] | the wrapped function's argument tuple. |
+| `T` | the wrapped function's return type. |
+| `E` | the modeled error type. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `fn` | (...`args`) => `T` | the throwing function to wrap. |
+| `qualify` | (`cause`) => [`Defect`](#defect) \| `E` | triages a thrown cause into `E` or a `Defect`. |
+
+#### Returns
+
+a function with the same arguments returning `Result<T, E>`.
+
+(...`args`) => `Result`&lt;`T`, `E`&gt;
+
+#### Remarks
+
+`qualify` **must** triage every thrown cause into a modeled error `E` or a
+[Defect](#defect) (via [defect](#defect-2)) — there is no path that leaves `unknown`
+in `E`. A throw inside `qualify` itself is treated as a `Defect`.
+
+#### Example
+
+```ts
+import { fromThrowable, defect } from "unthrown";
+const parse = fromThrowable(JSON.parse, (cause) => defect(cause));
+parse("{}").unwrap();
+```
+
+***
+
+### isDefect()
+
+```ts
+function isDefect<T, E>(r): r is DefectView<T, E>;
+```
+
+Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/constructors.ts#L66)
+
+Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause`.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `E` |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `r` | `Result`&lt;`T`, `E`&gt; |
+
+#### Returns
+
+`r is DefectView<T, E>`
+
+`true` when `r` is a `Defect`.
+
+***
+
+### isErr()
+
+```ts
+function isErr<T, E>(r): r is ErrView<E, T>;
+```
+
+Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/constructors.ts#L58)
+
+Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `E` |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `r` | `Result`&lt;`T`, `E`&gt; |
+
+#### Returns
+
+`r is ErrView<E, T>`
+
+`true` when `r` is `Err`.
+
+***
+
+### isOk()
+
+```ts
+function isOk<T, E>(r): r is OkView<T, E>;
+```
+
+Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/constructors.ts#L50)
+
+Type guard: narrow a [Result](#result) to its `Ok` variant, exposing `.value`.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+| `E` |
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `r` | `Result`&lt;`T`, `E`&gt; |
+
+#### Returns
+
+`r is OkView<T, E>`
+
+`true` when `r` is `Ok`.
+
+#### Example
+
+```ts
+import { isOk, type Result } from "unthrown";
+declare const r: Result<number, string>;
+if (isOk(r)) r.value; // number, narrowed
+```
+
+***
+
+### matchTags()
+
+#### Call Signature
+
+```ts
+function matchTags<T, E, R>(result, handlers): R;
+```
+
+Defined in: [packages/core/src/tagged.ts:116](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L116)
+
+Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
+a tagged union, dispatching each error to the handler matching its `_tag`.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the success value type. |
+| `E` *extends* `object` | the tagged error union (`E extends { _tag: string }`). |
+| `R` | the folded result type. |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `result` | `Result`&lt;`T`, `E`&gt; | the result to fold. |
+| `handlers` | [`TagHandlers`](#taghandlers)&lt;`T`, `E`, `R`&gt; | one branch per channel/tag. |
+
+##### Returns
+
+`R`
+
+##### Remarks
+
+The `handlers` object must provide `Ok`, `Defect`, and exactly one function
+per error tag; each tag's handler receives the narrowed error variant. A
+missing tag is a compile error. For an `AsyncResult`, the fold resolves to a
+`Promise<R>`.
+
+##### Example
+
+```ts
+class NotFound extends TaggedError("NotFound") {}
+class Forbidden extends TaggedError("Forbidden")<{ user: string }> {}
+
+declare const r: Result<number, NotFound | Forbidden>;
+matchTags(r, {
+  Ok: (n) => `got ${n}`,
+  Defect: (cause) => `bug: ${String(cause)}`,
+  NotFound: () => "404",
+  Forbidden: (e) => `403 for ${e.user}`,
+});
+```
+
+#### Call Signature
+
+```ts
+function matchTags<T, E, R>(result, handlers): Promise<R>;
+```
+
+Defined in: [packages/core/src/tagged.ts:120](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L120)
+
+Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
+a tagged union, dispatching each error to the handler matching its `_tag`.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the success value type. |
+| `E` *extends* `object` | the tagged error union (`E extends { _tag: string }`). |
+| `R` | the folded result type. |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `result` | [`AsyncResult`](#asyncresult)&lt;`T`, `E`&gt; | the result to fold. |
+| `handlers` | [`TagHandlers`](#taghandlers)&lt;`T`, `E`, `R`&gt; | one branch per channel/tag. |
+
+##### Returns
+
+`Promise`&lt;`R`&gt;
+
+##### Remarks
+
+The `handlers` object must provide `Ok`, `Defect`, and exactly one function
+per error tag; each tag's handler receives the narrowed error variant. A
+missing tag is a compile error. For an `AsyncResult`, the fold resolves to a
+`Promise<R>`.
+
+##### Example
+
+```ts
+class NotFound extends TaggedError("NotFound") {}
+class Forbidden extends TaggedError("Forbidden")<{ user: string }> {}
+
+declare const r: Result<number, NotFound | Forbidden>;
+matchTags(r, {
+  Ok: (n) => `got ${n}`,
+  Defect: (cause) => `bug: ${String(cause)}`,
+  NotFound: () => "404",
+  Forbidden: (e) => `403 for ${e.user}`,
+});
+```
+
+***
+
+### ok()
+
+```ts
+function ok<T>(value): Result<T, never>;
+```
+
+Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/constructors.ts#L18)
+
+Construct a successful [Result](#result).
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | the success value type. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `T` | the success value to wrap. |
+
+#### Returns
+
+`Result`&lt;`T`, `never`&gt;
+
+#### Example
+
+```ts
+import { ok } from "unthrown";
+ok(42).unwrap(); // 42
+```
+
+***
+
+### TaggedError()
+
+```ts
+function TaggedError<Tag>(tag): TaggedErrorConstructor<Tag>;
+```
+
+Defined in: [packages/core/src/tagged.ts:54](https://github.com/btravstack/unthrown/blob/4553631adb8280ef7c869dfae5bdb13be762095c/packages/core/src/tagged.ts#L54)
+
+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 used as the error `name`. |
+
+#### Returns
+
+[`TaggedErrorConstructor`](#taggederrorconstructor)&lt;`Tag`&gt;
+
+#### Remarks
+
+Extend the returned class to declare a concrete error. Supply the payload with
+an instantiation expression; omit it for a payload-less error. A `message`
+field in the payload is forwarded to `Error`. The `_tag` always reflects
+`tag` and cannot be overridden by the payload.
+
+#### Example
+
+```ts
+class NotFound extends TaggedError("NotFound") {}
+class HttpError extends TaggedError("HttpError")<{ status: number }> {}
+
+new NotFound()._tag; // "NotFound"
+new HttpError({ status: 500 }).status; // 500
+```