unthrown 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,663 @@
+//#region src/types.d.ts
+/**
+ * The method surface every {@link Result} variant carries. Factored out so the
+ * three variants ({@link OkView}, {@link ErrView}, {@link DefectView}) can each
+ * intersect it. Not part of the public API on its own.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the modeled error type.
+ * @internal
+ */
+type ResultMethods<T, E> = {
+  /**
+   * 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`.
+   *
+   * @typeParam U - the mapped success type.
+   * @param f - maps the current success value to a new one.
+   */
+  map<U>(f: (value: T) => U): Result$1<U, E>;
+  /**
+   * 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`.
+   *
+   * @typeParam U - the success type of the next step.
+   * @typeParam E2 - the error type the next step may introduce.
+   * @param f - produces the next `Result` from the current success value.
+   */
+  flatMap<U, E2>(f: (value: T) => Result$1<U, E2>): Result$1<U, E | E2>;
+  /**
+   * 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`.
+   *
+   * @param f - the side effect (its return value is ignored).
+   */
+  tap(f: (value: T) => void): Result$1<T, E>;
+  /**
+   * Replace the success value with a constant `value`.
+   *
+   * Runs only on `Ok`; `Err` and `Defect` pass through.
+   *
+   * @typeParam U - the replacement value type.
+   */
+  as<U>(value: U): Result$1<U, E>;
+  /**
+   * Transform the modeled error with `f`.
+   *
+   * Runs `f` only on `Err`; `Ok` passes through and a `Defect` is **never**
+   * touched. If `f` throws, the throw becomes a `Defect`.
+   *
+   * @typeParam E2 - the mapped error type.
+   * @param f - maps the current error to a new one.
+   */
+  mapErr<E2>(f: (error: E) => E2): Result$1<T, E2>;
+  /**
+   * Recover from an `Err` by producing another `Result`.
+   *
+   * Runs `f` only on `Err`; `Ok` and `Defect` pass through. If `f` throws, the
+   * throw becomes a `Defect`.
+   *
+   * @typeParam U - an alternative success type `f` may produce.
+   * @typeParam E2 - the error type `f` may produce instead.
+   * @param f - produces a fallback `Result` from the current error.
+   */
+  orElse<U, E2>(f: (error: E) => Result$1<U, E2>): Result$1<T | U, E2>;
+  /**
+   * Recover from an `Err` by producing a success value, emptying the error
+   * channel.
+   *
+   * @remarks
+   * The result type is `Result<T | U, never>`, but `never` describes only the
+   * **error** channel — a `Defect` can still be present at runtime, so do not
+   * read `never` as "total". Runs `f` only on `Err`; `Ok` and `Defect` pass
+   * through. If `f` throws, the throw becomes a `Defect`.
+   *
+   * @typeParam U - the recovered success type.
+   * @param f - produces a success value from the current error.
+   */
+  recover<U>(f: (error: E) => U): Result$1<T | U, never>;
+  /**
+   * Run a side effect on the error and pass the `Result` through unchanged.
+   *
+   * Runs only on `Err`. If `f` throws, the throw becomes a `Defect`.
+   *
+   * @param f - the side effect (its return value is ignored).
+   */
+  tapErr(f: (error: E) => void): Result$1<T, E>;
+  /**
+   * Recover from a `Defect` — the **only** combinator that can touch one.
+   *
+   * @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`.
+   *
+   * @typeParam U - a success type the recovery may produce.
+   * @typeParam E2 - an error type the recovery may produce.
+   * @param f - maps the defect's unknown cause to a recovering `Result`.
+   */
+  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2>): Result$1<T | U, E | E2>;
+  /**
+   * Run a side effect on a present `Defect`'s cause (e.g. logging) and pass the
+   * `Defect` through unchanged.
+   *
+   * @param f - the side effect over the unknown cause.
+   */
+  tapDefect(f: (cause: unknown) => void): Result$1<T, E>;
+  /**
+   * Exhaustively fold all three runtime states into a single value of type `R`.
+   *
+   * @remarks
+   * Exactly one handler runs. Together with the throw-to-defect guarantee, this
+   * is typically the single place a pipeline is handled at the edge — mapping
+   * `ok`/`err`/`defect` to (for example) 2xx / 4xx / 5xx with no `try`/`catch`.
+   * (For richer matching, a `Result` is also a discriminated union — branch on
+   * its `tag` property, e.g. with `ts-pattern`.)
+   *
+   * @typeParam R - the folded result type.
+   * @param cases - one handler per channel.
+   */
+  match<R>(cases: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+    defect: (cause: unknown) => R;
+  }): R;
+  /**
+   * Extract the success value.
+   *
+   * @returns the `Ok` value.
+   * @throws On `Err`, an {@link UnwrapError} carrying the error. On a `Defect`,
+   * re-throws the **original cause** with its original stack, so an unhandled
+   * defect surfaces at the global handler as the real failure.
+   */
+  unwrap(): T;
+  /**
+   * Extract the modeled error.
+   *
+   * @returns the `Err` value.
+   * @throws On `Ok`, an {@link UnwrapError} carrying the value. On a `Defect`,
+   * re-throws the original cause.
+   */
+  unwrapErr(): E;
+  /**
+   * The success value, or `fallback` on `Err`.
+   *
+   * @param fallback - returned when the result is an `Err`.
+   * @throws Re-throws on a `Defect` — a defect is a bug, not an absent value, so
+   * it is never silently replaced.
+   */
+  unwrapOr(fallback: T): T;
+  /**
+   * The success value, or `f(error)` on `Err`.
+   *
+   * @param f - lazily computes the fallback from the error.
+   * @throws Re-throws on a `Defect`.
+   */
+  unwrapOrElse(f: (error: E) => T): T;
+  /**
+   * The success value, or `null` on `Err`.
+   *
+   * @throws Re-throws on a `Defect`.
+   */
+  getOrNull(): T | null;
+  /**
+   * The success value, or `undefined` on `Err`.
+   *
+   * @throws Re-throws on a `Defect`.
+   */
+  getOrUndefined(): T | undefined; /** Whether this result is `Ok`. */
+  isOk(): boolean; /** Whether this result is `Err`. */
+  isErr(): boolean; /** Whether this result is a `Defect`. */
+  isDefect(): boolean; /** Lift this synchronous `Result` into an {@link AsyncResult}. */
+  toAsync(): AsyncResult<T, E>;
+};
+/** The `Ok` variant of a {@link Result}: a success carrying a `value`. */
+type OkView<T, E = never> = ResultMethods<T, E> & {
+  readonly tag: "Ok";
+  readonly value: T;
+};
+/** The `Err` variant of a {@link Result}: a modeled failure carrying an `error`. */
+type ErrView<E, T = never> = ResultMethods<T, E> & {
+  readonly tag: "Err";
+  readonly error: E;
+};
+/** The `Defect` variant of a {@link Result}: an unmodeled failure carrying a `cause`. */
+type DefectView<T = never, E = never> = ResultMethods<T, E> & {
+  readonly tag: "Defect";
+  readonly cause: unknown;
+};
+/**
+ * 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`.
+ *
+ * @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
+ * `ts-pattern`'s `match(...).with({ tag: "Ok" }, …).exhaustive()`), *and* it
+ * carries the full method surface ({@link ResultMethods}) for fluent chaining.
+ * Either way, the payload (`value`/`error`/`cause`) is only reachable after you
+ * narrow — so "check before you access" still holds.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the modeled error type (only anticipated domain failures).
+ *
+ * @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}`,
+ *   err: (e) => `failed: ${e}`,
+ *   defect: (cause) => `bug: ${String(cause)}`,
+ * });
+ * ```
+ */
+type Result$1<T, E> = OkView<T, E> | ErrView<E, T> | DefectView<T, E>;
+/**
+ * A success-only thenable: awaitable, but deliberately **not** a full
+ * `PromiseLike`.
+ *
+ * @remarks
+ * An {@link AsyncResult}'s internal promise never rejects, so `await`-ing one
+ * always yields a {@link 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`).
+ *
+ * @typeParam T - the value `await` resolves to.
+ */
+type Awaitable<T> = {
+  then<R = T>(onfulfilled?: ((value: T) => R | PromiseLike<R>) | null): PromiseLike<R>;
+};
+/**
+ * The asynchronous counterpart of {@link Result}: an awaitable wrapper with the
+ * same method surface, collapsing to a `Result<T, E>` when `await`-ed.
+ *
+ * @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
+ * {@link 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)`.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the modeled error type.
+ */
+type AsyncResult<T, E> = Awaitable<Result$1<T, E>> & {
+  /** Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. */map<U>(f: (value: T) => U): AsyncResult<U, E>;
+  /**
+   * Asynchronous `flatMap`. `f` may return a `Result` **or** an `AsyncResult`
+   * (never a raw `Promise`); a throw becomes a `Defect`.
+   */
+  flatMap<U, E2>(f: (value: T) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<U, E | E2>; /** Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. */
+  tap(f: (value: T) => void): AsyncResult<T, E>; /** Asynchronous `as`. */
+  as<U>(value: U): AsyncResult<U, E>; /** Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. */
+  mapErr<E2>(f: (error: E) => E2): AsyncResult<T, E2>; /** Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. */
+  orElse<U, E2>(f: (error: E) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<T | U, E2>; /** Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. */
+  recover<U>(f: (error: E) => U): AsyncResult<T | U, never>; /** Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. */
+  tapErr(f: (error: E) => void): AsyncResult<T, E>; /** Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. */
+  recoverDefect<U, E2>(f: (cause: unknown) => Result$1<U, E2> | AsyncResult<U, E2>): AsyncResult<T | U, E | E2>; /** Asynchronous `tapDefect`. */
+  tapDefect(f: (cause: unknown) => void): AsyncResult<T, E>; /** Asynchronous `match`. Handlers are synchronous; resolves to `R`. */
+  match<R>(cases: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+    defect: (cause: unknown) => R;
+  }): Promise<R>; /** Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. */
+  unwrap(): Promise<T>; /** Asynchronous `unwrapErr`. */
+  unwrapErr(): Promise<E>; /** Asynchronous `unwrapOr`. */
+  unwrapOr(fallback: T): Promise<T>; /** Asynchronous `unwrapOrElse`. */
+  unwrapOrElse(f: (error: E) => T): Promise<T>; /** Asynchronous `getOrNull`. */
+  getOrNull(): Promise<T | null>; /** Asynchronous `getOrUndefined`. */
+  getOrUndefined(): Promise<T | undefined>;
+};
+/**
+ * Extract the success type `T` from a `Result`.
+ *
+ * @typeParam R - the `Result` type to inspect.
+ */
+type OkOf<R> = R extends {
+  readonly tag: "Ok";
+  readonly value: infer T;
+} ? T : never;
+/**
+ * Extract the error type `E` from a `Result`.
+ *
+ * @typeParam R - the `Result` type to inspect.
+ */
+type ErrOf<R> = R extends {
+  readonly tag: "Err";
+  readonly error: infer E;
+} ? E : never;
+//#endregion
+//#region src/constructors.d.ts
+/**
+ * Construct a successful {@link Result}.
+ *
+ * @typeParam T - the success value type.
+ * @param value - the success value to wrap.
+ *
+ * @example
+ * ```ts
+ * import { ok } from "unthrown";
+ * ok(42).unwrap(); // 42
+ * ```
+ */
+declare function ok<T>(value: T): Result$1<T, never>;
+/**
+ * Construct a failed {@link Result} carrying a **modeled** error.
+ *
+ * @typeParam E - the modeled error type.
+ * @param error - the domain error to wrap.
+ *
+ * @example
+ * ```ts
+ * import { err } from "unthrown";
+ * err("not_found").unwrapErr(); // "not_found"
+ * ```
+ */
+declare function err<E>(error: E): Result$1<never, E>;
+/**
+ * Type guard: narrow a {@link Result} to its `Ok` variant, exposing `.value`.
+ *
+ * @returns `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
+ * ```
+ */
+declare function isOk<T, E>(r: Result$1<T, E>): r is OkView<T, E>;
+/**
+ * Type guard: narrow a {@link Result} to its `Err` variant, exposing `.error`.
+ *
+ * @returns `true` when `r` is `Err`.
+ */
+declare function isErr<T, E>(r: Result$1<T, E>): r is ErrView<E, T>;
+/**
+ * Type guard: narrow a {@link Result} to its `Defect` variant, exposing `.cause`.
+ *
+ * @returns `true` when `r` is a `Defect`.
+ */
+declare function isDefect<T, E>(r: Result$1<T, E>): r is DefectView<T, E>;
+//#endregion
+//#region src/core.d.ts
+/**
+ * Thrown by a {@link 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.
+ *
+ * @typeParam E - the type of the {@link UnwrapError.error} it carries.
+ */
+declare class UnwrapError<E = unknown> extends Error {
+  /**
+   * The offending value: the `Err` error for `unwrap()`, or the `Ok` value for
+   * `unwrapErr()`.
+   */
+  readonly error: E;
+  constructor(error: E);
+}
+//#endregion
+//#region src/defect.d.ts
+declare const DEFECT: unique symbol;
+/**
+ * The marker a `qualify` function returns to triage a cause as **unexpected**.
+ *
+ * @remarks
+ * `qualify` (passed to {@link fromPromise} / {@link fromThrowable}) returns
+ * `E | Defect`: either a modeled domain error, or a `Defect` produced by
+ * {@link defect} to say "this failure is not modeled". A `Defect` is opaque —
+ * it carries the original cause for the boundary to convert into the third
+ * runtime state of a `Result`.
+ */
+type Defect = {
+  readonly [DEFECT]: true;
+  readonly cause: unknown;
+};
+/**
+ * Wrap a cause as a {@link Defect} — the value you return from a `qualify`
+ * function when a failure is **not** a modeled domain error.
+ *
+ * @param cause - the original thrown/rejected value.
+ * @returns an opaque defect marker carrying `cause`.
+ *
+ * @example
+ * ```ts
+ * import { fromPromise, defect } from "unthrown";
+ *
+ * const user = fromPromise(fetchUser(id), (cause) =>
+ *   cause instanceof NotFoundError ? cause : defect(cause),
+ * );
+ * ```
+ */
+declare function defect(cause: unknown): Defect;
+//#endregion
+//#region src/interop.d.ts
+/**
+ * Bridge a nullable value into a {@link Result}: absence becomes a **modeled**
+ * `Err`. The sanctioned alternative to an `Option` type.
+ *
+ * @remarks
+ * `null` and `undefined` map to `err(onAbsent())`; any other value (including
+ * falsy ones like `0`, `""`, `false`) maps to `Ok`.
+ *
+ * @typeParam T - the (nullable) value type.
+ * @typeParam E - the error produced when the value is absent.
+ * @param value - the possibly-absent value.
+ * @param onAbsent - lazily produces the error for the absent case.
+ *
+ * @example
+ * ```ts
+ * import { fromNullable } from "unthrown";
+ * fromNullable(map.get(key), () => "missing").unwrap();
+ * ```
+ */
+declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E): Result$1<NonNullable<T>, E>;
+/**
+ * Wrap a throwing synchronous function so it returns a {@link Result} instead of
+ * throwing.
+ *
+ * @remarks
+ * `qualify` **must** triage every thrown cause into a modeled error `E` or a
+ * {@link Defect} (via {@link defect}) — there is no path that leaves `unknown`
+ * in `E`. A throw inside `qualify` itself is treated as a `Defect`.
+ *
+ * @typeParam A - the wrapped function's argument tuple.
+ * @typeParam T - the wrapped function's return type.
+ * @typeParam E - the modeled error type.
+ * @param fn - the throwing function to wrap.
+ * @param qualify - triages a thrown cause into `E` or a `Defect`.
+ * @returns a function with the same arguments returning `Result<T, E>`.
+ *
+ * @example
+ * ```ts
+ * import { fromThrowable, defect } from "unthrown";
+ * const parse = fromThrowable(JSON.parse, (cause) => defect(cause));
+ * parse("{}").unwrap();
+ * ```
+ */
+declare function fromThrowable<A extends unknown[], T, E>(fn: (...args: A) => T, qualify: (cause: unknown) => E | Defect): (...args: A) => Result$1<T, E>;
+/**
+ * Wrap a `Promise` (or a thunk producing one) as an {@link AsyncResult}, forcing
+ * every rejection to be triaged.
+ *
+ * @remarks
+ * `qualify` **must** map each rejection cause into a modeled error `E` or a
+ * {@link Defect}. The returned `AsyncResult`'s internal promise never rejects;
+ * `await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
+ * `Defect`.
+ *
+ * @typeParam T - the resolved value type.
+ * @typeParam E - the modeled error type.
+ * @param promise - the promise, or a thunk returning one.
+ * @param qualify - triages a rejection cause into `E` or 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),
+ * );
+ * ```
+ */
+declare function fromPromise<T, E>(promise: Promise<T> | (() => Promise<T>), qualify: (cause: unknown) => E | Defect): AsyncResult<T, E>;
+/**
+ * Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
+ * becomes a `Defect`.
+ *
+ * @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.)
+ *
+ * @typeParam T - the resolved value type.
+ * @param promise - the promise, or a thunk returning one.
+ */
+declare function fromSafePromise<T>(promise: Promise<T> | (() => Promise<T>)): AsyncResult<T, never>;
+/**
+ * Collect a tuple of {@link Result}s into a single `Result` of the tuple of
+ * success values.
+ *
+ * @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], …>`.
+ *
+ * @typeParam Rs - the tuple of input `Result` types.
+ * @param results - the results to combine.
+ *
+ * @example
+ * ```ts
+ * import { all, ok } from "unthrown";
+ * all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true]
+ * ```
+ */
+declare function all<Rs extends readonly Result$1<unknown, unknown>[]>(results: readonly [...Rs]): Result$1<{ [K in keyof Rs]: OkOf<Rs[K]> }, ErrOf<Rs[number]>>;
+//#endregion
+//#region src/facade.d.ts
+/**
+ * Companion object grouping the standalone entry points under a single,
+ * discoverable namespace: {@link Result.ok}, {@link Result.err},
+ * {@link Result.defect}, {@link Result.fromNullable}, {@link Result.fromThrowable},
+ * {@link Result.fromPromise}, {@link Result.fromSafePromise}, {@link Result.all},
+ * {@link Result.isOk}, {@link Result.isErr}, {@link Result.isDefect}.
+ *
+ * @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
+ * {@link Result} share one name (the companion-object pattern).
+ *
+ * @example
+ * ```ts
+ * import { Result } from "unthrown";
+ * Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
+ * ```
+ */
+declare const Result: {
+  readonly ok: typeof ok;
+  readonly err: typeof err;
+  readonly defect: typeof defect;
+  readonly fromNullable: typeof fromNullable;
+  readonly fromThrowable: typeof fromThrowable;
+  readonly fromPromise: typeof fromPromise;
+  readonly fromSafePromise: typeof fromSafePromise;
+  readonly all: typeof all;
+  readonly isOk: typeof isOk;
+  readonly isErr: typeof isErr;
+  readonly isDefect: typeof isDefect;
+};
+type Result<T, E> = Result$1<T, E>;
+//#endregion
+//#region src/tagged.d.ts
+type Props = Record<string, unknown>;
+/**
+ * The instance shape produced by a {@link TaggedError} class: an `Error` plus a
+ * `_tag` discriminant and the (readonly) payload fields.
+ *
+ * @typeParam Tag - the string literal discriminant.
+ * @typeParam A - the payload object type.
+ */
+type TaggedErrorInstance<Tag extends string, A extends Props> = Error & Readonly<A> & {
+  readonly _tag: Tag;
+};
+/**
+ * The class constructor returned by {@link TaggedError}. Generic in its payload:
+ * apply it with an instantiation expression at the `extends` site.
+ *
+ * @remarks
+ * When the payload is empty, the constructor takes **no** arguments (the
+ * `keyof A extends never ? void : A` trick); otherwise it takes the payload.
+ *
+ * @typeParam Tag - the string literal discriminant.
+ */
+type TaggedErrorConstructor<Tag extends string> = {
+  new <A extends Props = {}>(args: keyof A extends never ? void : A): TaggedErrorInstance<Tag, A>;
+};
+/**
+ * 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`.
+ *
+ * @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.
+ *
+ * @typeParam Tag - the string literal discriminant.
+ * @param tag - the discriminant value, also used as the error `name`.
+ *
+ * @example
+ * ```ts
+ * class NotFound extends TaggedError("NotFound") {}
+ * class HttpError extends TaggedError("HttpError")<{ status: number }> {}
+ *
+ * new NotFound()._tag; // "NotFound"
+ * new HttpError({ status: 500 }).status; // 500
+ * ```
+ */
+declare function TaggedError<Tag extends string>(tag: Tag): TaggedErrorConstructor<Tag>;
+/**
+ * The handler object {@link matchTags} requires: a branch per error tag, plus
+ * `Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
+ * enforced by the type, with no `.exhaustive()` to forget.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the tagged error union.
+ * @typeParam R - the folded result type.
+ */
+type TagHandlers<T, E extends {
+  _tag: string;
+}, R> = {
+  Ok: (value: T) => R;
+  Defect: (cause: unknown) => R;
+} & { [K in E["_tag"]]: (error: Extract<E, {
+  _tag: K;
+}>) => R };
+/**
+ * Exhaustively fold a {@link Result} (or {@link AsyncResult}) whose error type is
+ * a tagged union, dispatching each error to the handler matching its `_tag`.
+ *
+ * @remarks
+ * The `handlers` object must provide `Ok`, `Defect`, and exactly one function
+ * per error tag; each tag's handler receives the narrowed error variant. A
+ * missing tag is a compile error. For an `AsyncResult`, the fold resolves to a
+ * `Promise<R>`.
+ *
+ * @typeParam T - the success value type.
+ * @typeParam E - the tagged error union (`E extends { _tag: string }`).
+ * @typeParam R - the folded result type.
+ * @param result - the result to fold.
+ * @param handlers - one branch per channel/tag.
+ *
+ * @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}`,
+ * });
+ * ```
+ */
+declare function matchTags<T, E extends {
+  _tag: string;
+}, R>(result: Result$1<T, E>, handlers: TagHandlers<T, E, R>): R;
+declare function matchTags<T, E extends {
+  _tag: string;
+}, R>(result: AsyncResult<T, E>, handlers: TagHandlers<T, E, R>): Promise<R>;
+//#endregion
+export { type AsyncResult, type Awaitable, type Defect, type DefectView, type ErrOf, type ErrView, type OkOf, type OkView, Result, type TagHandlers, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, UnwrapError, all, defect, err, fromNullable, fromPromise, fromSafePromise, fromThrowable, isDefect, isErr, isOk, matchTags, ok };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/constructors.ts","../src/core.ts","../src/defect.ts","../src/interop.ts","../src/facade.ts","../src/tagged.ts"],"mappings":"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"}