ripthrow 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sir Cesarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# ripthrow
+
+**Zero-dependency, type-safe error handling for TypeScript.**
+
+`ripthrow` is a lightweight library inspired by Rust's `Result` type and the proposed ECMAScript `?=` operator. It allows you to handle success and failure in a structured way, avoiding `try/catch` blocks and making error states explicit in your types.
+
+## Features
+
+- **Type-Safe:** Full TypeScript support with robust type inference.
+- **Functional API:** Chain operations with `map`, `andThen`, and `orElse`.
+- **Safe Wrappers:** Convert throwing functions and Promises into `Result` types easily.
+- **No Dependencies:** Extremely small footprint.
+- **Documentation:** Built-in JSDoc with examples and a complete Wiki.
+
+## Installation
+
+```bash
+bun add github:MechanicalLabs/ripthrow
+```
+
+## Quick Start
+
+### Explicit errors with `Ok` and `Err`
+
+Functions return `Result`, making failure paths visible in the type signature:
+
+```typescript
+import { Ok, Err, match, type Result } from "ripthrow";
+
+function getUser(id: string): Result<{ id: string; name: string }, string> {
+  if (!id) {
+     return Err("ID is required");
+  }
+
+  return Ok({ id, name: "Alice" });
+}
+
+const result = getUser("123");
+
+match(result, {
+  ok: (user) => console.log(user.name),
+  err: (msg) => console.error(`getUser function failed: ${msg}`),
+});
+```
+
+### Wrap throwing code with `safe`
+
+`safe` catches exceptions and returns a `Result` — no `try/catch`:
+
+```typescript
+import { safe, build } from "ripthrow";
+
+const raw = '{"valid": true}';
+
+const isValid = build(safe(() => JSON.parse(raw)))
+  .map((data: any) => data.valid)
+  .unwrapOr(false);
+
+console.log(isValid); // true
+```
+
+## Why ripthrow?
+
+Handling errors with exceptions can lead to "hidden" control flows. `ripthrow` forces you to acknowledge potential failures, leading to more resilient applications. Whether you are parsing JSON, fetching data, or performing complex logic, `ripthrow` ensures your error handling is as clean as your success path.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ripthrow",
+  "module": "src/index.ts",
+  "version": "2.0.0",
+  "description": "Zero-overhead, type-safe error handling for TypeScript.",
+  "keywords": [
+    "result",
+    "error-handling",
+    "typescript",
+    "functional",
+    "type-safe"
+  ],
+  "author": "Sir Cesarium",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MechanicalLabs/ripthrow.git"
+  },
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@biomejs/biome": "2.4.14",
+    "@types/bun": "latest",
+    "@types/node": "^25.6.1",
+    "knip": "^6.12.1",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "knip": "knip",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "docs": "typedoc"
+  }
+}

package/src/consumers/index.ts

@@ -0,0 +1,3 @@
+export { match } from "./match";
+export { unwrap } from "./unwrap";
+export { unwrapOr } from "./unwrap-or";

package/src/consumers/match.ts

@@ -0,0 +1,34 @@
+import type { Result } from "../types";
+
+/**
+ * Matches a Result against different handlers for Ok and Err cases.
+ * This pattern forces handling both success and failure states, similar to Rust's match.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @template R The type of the return value from the handlers.
+ * @param result The Result to match.
+ * @param handlers An object with `ok` and `err` functions.
+ * @returns The result of the appropriate handler.
+ *
+ * @category Consumers
+ * @see unwrapOr
+ * @example
+ * const output = match(res, {
+ *   ok: (val) => `Success: ${val}`,
+ *   err: (err) => `Failure: ${err}`
+ * });
+ */
+export function match<T, E, R>(
+  result: Result<T, E>,
+  handlers: {
+    ok: (value: T) => R;
+    err: (error: E) => R;
+  },
+): R {
+  if (result.ok) {
+    return handlers.ok(result.value);
+  }
+
+  return handlers.err(result.error);
+}

package/src/consumers/unwrap-or.ts

@@ -0,0 +1,24 @@
+import type { Result } from "../types";
+
+/**
+ * Unwraps a Result, returning the contained value if it's Ok, or a default value if it's Err.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to unwrap.
+ * @param defaultValue The value to return if the Result is an Err.
+ * @returns The contained value if Ok, otherwise the default value.
+ *
+ * @category Consumers
+ * @see match
+ * @example
+ * const res = Err("error");
+ * const val = unwrapOr(res, "default"); // "default"
+ */
+export function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T {
+  if (result.ok) {
+    return result.value;
+  }
+
+  return defaultValue;
+}

package/src/consumers/unwrap.ts

@@ -0,0 +1,23 @@
+import type { Result } from "../types";
+
+/**
+ * Unwraps a Result, returning the success value or throwing the error.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to unwrap.
+ * @returns The success value.
+ * @throws The error contained in the Result if it's an Err.
+ *
+ * @category Consumers
+ * @see unwrapOr
+ * @example
+ * const val = unwrap(Ok(42)); // 42
+ * const val = unwrap(Err("failed")); // throws "failed"
+ */
+export function unwrap<T, E>(result: Result<T, E>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw result.error;
+}

package/src/factories/bail.ts

@@ -0,0 +1,17 @@
+import { Report, type ReportOptions } from "../report";
+
+/**
+ * Creates a new Report instance.
+ * Useful for generating structured errors to be wrapped in an Err result.
+ *
+ * @param message The error message.
+ * @param options Additional report options.
+ * @returns A new Report instance.
+ *
+ * @category Factories
+ * @example
+ * return Err(bail("Permission denied", { help: "Check your API token" }));
+ */
+export function bail(message: string, options?: ReportOptions): Report {
+  return new Report(message, options);
+}

package/src/factories/err.ts

@@ -0,0 +1,19 @@
+import type { Result } from "../types";
+
+/**
+ * Constructs an error Result containing the given error.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param error The error to wrap in an Err result.
+ * @returns A failed Result object `{ ok: false, error: E }`.
+ *
+ * @category Factories
+ * @see Ok
+ * @example
+ * const res = Err("Something went wrong");
+ * if (!res.ok) console.error(res.error); // "Something went wrong"
+ */
+export function Err<T, E>(error: E): Result<T, E> {
+  return { ok: false, error };
+}

package/src/factories/index.ts

@@ -0,0 +1,7 @@
+export { bail } from "./bail";
+export { Err } from "./err";
+export { isErr } from "./is-err";
+export { isOk } from "./is-ok";
+export { Ok } from "./ok";
+export { safe } from "./safe";
+export { safeAsync } from "./safe-async";

package/src/factories/is-err.ts

@@ -0,0 +1,19 @@
+import type { Result } from "../types";
+
+/**
+ * A type guard that checks if a Result is an Err.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to check.
+ * @returns `true` if the result is an Err, `false` otherwise.
+ *
+ * @category Factories
+ * @example
+ * if (isErr(res)) {
+ *   console.error(res.error); // res.error is typed as E
+ * }
+ */
+export function isErr<T, E>(result: Result<T, E>): result is { ok: false; error: E } {
+  return !result.ok;
+}

package/src/factories/is-ok.ts

@@ -0,0 +1,19 @@
+import type { Result } from "../types";
+
+/**
+ * A type guard that checks if a Result is an Ok.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to check.
+ * @returns `true` if the result is an Ok, `false` otherwise.
+ *
+ * @category Factories
+ * @example
+ * if (isOk(res)) {
+ *   console.log(res.value); // res.value is typed as T
+ * }
+ */
+export function isOk<T, E>(result: Result<T, E>): result is { ok: true; value: T } {
+  return result.ok;
+}

package/src/factories/ok.ts

@@ -0,0 +1,19 @@
+import type { Result } from "../types";
+
+/**
+ * Constructs a successful Result containing the given value.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param value The value to wrap in an Ok result.
+ * @returns A successful Result object `{ ok: true, value: T }`.
+ *
+ * @category Factories
+ * @see Err
+ * @example
+ * const res = Ok(42);
+ * if (res.ok) console.log(res.value); // 42
+ */
+export function Ok<T = void, E = unknown>(value?: T): Result<T, E> {
+  return { ok: true, value: value as T };
+}

package/src/factories/safe-async.ts

@@ -0,0 +1,28 @@
+import type { Result } from "../types";
+import { Err } from "./err";
+import { Ok } from "./ok";
+
+/**
+ * Converts a Promise into a Result.
+ * If the promise resolves, it returns an Ok result with the data.
+ * If the promise rejects, it captures the reason and returns an Err result.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value. Defaults to Error.
+ * @param promise The Promise to convert.
+ * @returns A Promise resolving to an Ok result with the data, or an Err result with the error.
+ *
+ * @category Factories
+ * @see safe
+ * @example
+ * const res = await safeAsync(fetch("https://api.example.com"));
+ * if (res.ok) console.log(await res.value.json());
+ */
+export async function safeAsync<T, E = Error>(promise: Promise<T>): Promise<Result<T, E>> {
+  try {
+    const data = await promise;
+    return Ok(data);
+  } catch (e) {
+    return Err(e as E);
+  }
+}

package/src/factories/safe.ts

@@ -0,0 +1,26 @@
+import type { Result } from "../types";
+import { Err } from "./err";
+import { Ok } from "./ok";
+
+/**
+ * Executes a synchronous function and wraps its return value in an Ok result.
+ * If the function throws an error, it captures it and wraps it in an Err result.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value. Defaults to Error.
+ * @param fn The function to execute.
+ * @returns An Ok result with the return value, or an Err result with the thrown error.
+ *
+ * @category Factories
+ * @see safeAsync
+ * @example
+ * const res = safe(() => JSON.parse('{"valid": true}'));
+ * if (res.ok) console.log(res.value);
+ */
+export function safe<T, E = Error>(fn: () => T): Result<T, E> {
+  try {
+    return Ok(fn());
+  } catch (e) {
+    return Err(e as E);
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * ripthrow: A tiny, type-safe Result type for TypeScript.
+ * Inspired by Rust's Result and the proposed Error Handling Operator (?=).
+ *
+ * This library provides a structured way to handle success and failure
+ * without relying on exceptions, promoting safer and more predictable code.
+ *
+ * @module ripthrow
+ */
+
+export * from "./consumers";
+export * from "./factories";
+export * from "./operators";
+export * from "./pattern";
+export * from "./report";
+export * from "./result-builder";
+export * from "./result-builder-async";
+export type * from "./types";
+export * from "./utils";

package/src/operators/and-then.ts

@@ -0,0 +1,32 @@
+import type { Result } from "../types";
+
+/**
+ * Chains a sequence of operations that may fail, short-circuiting on the first error.
+ * If the Result is an Ok, it applies the function to the value and returns its Result.
+ * If the Result is an Err, it returns the original error without executing the function.
+ *
+ * Also known as `flatMap` or `bind` in other functional contexts.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @template R The type of the new success value.
+ * @param result The initial Result.
+ * @param fn The function to apply to the success value if it's Ok.
+ * @returns A new Result representing the chained operation.
+ *
+ * @category Operators
+ * @see map
+ * @example
+ * const res = Ok("user_id");
+ * const user = andThen(res, fetchUser); // fetchUser returns a Result
+ */
+export function andThen<T, E, R>(
+  result: Result<T, E>,
+  fn: (value: T) => Result<R, E>,
+): Result<R, E> {
+  if (result.ok) {
+    return fn(result.value);
+  }
+
+  return result;
+}

package/src/operators/context.ts

@@ -0,0 +1,25 @@
+import { Report } from "../report";
+import type { Result } from "../types/result";
+import { mapErr } from "./map-err";
+
+/**
+ * Attaches context to a Result's error, converting it to a Report if it isn't one already.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to attach context to.
+ * @param message The context message.
+ * @param help An optional help message.
+ * @returns A Result with the same success value or a Report as the error.
+ *
+ * @category Operators
+ * @example
+ * const res = context(safe(() => JSON.parse(data)), "Failed to parse config");
+ */
+export function context<T, E>(
+  result: Result<T, E>,
+  message: string,
+  help?: string,
+): Result<T, Report> {
+  return mapErr(result, (err) => Report.from(err, message, { help }));
+}

package/src/operators/index.ts

@@ -0,0 +1,7 @@
+export { andThen } from "./and-then";
+export { context } from "./context";
+export { map } from "./map";
+export { mapErr } from "./map-err";
+export { orElse } from "./or-else";
+export { tap } from "./tap";
+export { tapErr } from "./tap-err";

package/src/operators/map-err.ts

@@ -0,0 +1,28 @@
+import { Err } from "../factories/err";
+import type { Result } from "../types";
+
+/**
+ * Maps a Result's error value using the provided function, leaving successes unchanged.
+ * If the Result is an Ok, the function is not executed and the original success value is returned.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @template F The type of the new error value.
+ * @param result The Result to map.
+ * @param fn The function to apply to the error value if it's Err.
+ * @returns A new Result with the mapped error value or the original success.
+ *
+ * @category Operators
+ * @see map
+ * @see orElse
+ * @example
+ * const res = Err("not found");
+ * const wrapped = mapErr(res, (e) => new Error(e)); // Err(Error("not found"))
+ */
+export function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {
+  if (!result.ok) {
+    return Err(fn(result.error));
+  }
+
+  return result;
+}

package/src/operators/map.ts

@@ -0,0 +1,28 @@
+import { Ok } from "../factories/ok";
+import type { Result } from "../types";
+
+/**
+ * Maps a Result's success value using the provided function, leaving errors unchanged.
+ * If the Result is an Err, the function is not executed and the original error is returned.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @template R The type of the new success value.
+ * @param result The Result to map.
+ * @param fn The function to apply to the success value if it's Ok.
+ * @returns A new Result with the mapped success value or the original error.
+ *
+ * @category Operators
+ * @see mapErr
+ * @see andThen
+ * @example
+ * const res = Ok(1);
+ * const doubled = map(res, (n) => n * 2); // Ok(2)
+ */
+export function map<T, E, R>(result: Result<T, E>, fn: (value: T) => R): Result<R, E> {
+  if (result.ok) {
+    return Ok(fn(result.value));
+  }
+
+  return result;
+}

package/src/operators/or-else.ts

@@ -0,0 +1,30 @@
+import type { Result } from "../types";
+
+/**
+ * Chains a sequence of operations that may fail, allowing recovery from errors.
+ * If the Result is an Err, it applies the function to the error and returns its Result.
+ * If the Result is an Ok, it returns the original success value without executing the function.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @template F The type of the new error value.
+ * @param result The initial Result.
+ * @param fn The function to apply to the error value if it's Err.
+ * @returns A new Result representing the chained operation with potential recovery.
+ *
+ * @category Operators
+ * @see mapErr
+ * @example
+ * const res = Err("failed");
+ * const recovered = orElse(res, () => Ok("default")); // Ok("default")
+ */
+export function orElse<T, E, F>(
+  result: Result<T, E>,
+  fn: (error: E) => Result<T, F>,
+): Result<T, F> {
+  if (!result.ok) {
+    return fn(result.error);
+  }
+
+  return result;
+}

package/src/operators/tap-err.ts

@@ -0,0 +1,23 @@
+import type { Result } from "../types";
+
+/**
+ * Executes a side effect function if the Result is an Err.
+ * The original Result is returned unchanged.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to tap into.
+ * @param fn The function to execute with the error value.
+ * @returns The original Result unchanged.
+ *
+ * @category Operators
+ * @see tap
+ * @example
+ * safe(() => doSomething()).tapErr(err => logger.error(err))
+ */
+export function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E> {
+  if (!result.ok) {
+    fn(result.error);
+  }
+  return result;
+}

package/src/operators/tap.ts

@@ -0,0 +1,23 @@
+import type { Result } from "../types";
+
+/**
+ * Executes a side effect function if the Result is an Ok.
+ * The original Result is returned unchanged.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param result The Result to tap into.
+ * @param fn The function to execute with the success value.
+ * @returns The original Result unchanged.
+ *
+ * @category Operators
+ * @see tapErr
+ * @example
+ * map(res, val => val + 1).tap(val => console.log(val))
+ */
+export function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E> {
+  if (result.ok) {
+    fn(result.value);
+  }
+  return result;
+}

package/src/pattern.ts

@@ -0,0 +1,157 @@
+// biome-ignore lint/nursery/noExcessiveClassesPerFile: _Error is local inside createError
+import type { Result } from "./types/result";
+
+const $class = Symbol("error-class");
+const noMatch = Symbol("no-match");
+
+interface TypedError<A extends unknown[], N extends string> extends Error {
+  readonly args: A;
+  readonly help?: string;
+  readonly name: N;
+  readonly kind: N;
+}
+
+interface HandlerEntry {
+  execute: (err: unknown) => unknown;
+}
+
+interface ExternalErrFactory<C extends new (...args: never[]) => Error> {
+  (...args: ConstructorParameters<C>): InstanceType<C>;
+  readonly [$class]: C;
+}
+
+interface ErrDefEntry {
+  // biome-ignore lint/suspicious/noExplicitAny: required for Parameters<>
+  message: (...args: any[]) => string;
+  // biome-ignore lint/suspicious/noExplicitAny: required for Parameters<>
+  help?: (...args: any[]) => string;
+}
+
+type ErrDefMap = Record<string, ErrDefEntry>;
+
+declare const exhaustiveCheck: unique symbol;
+type TypedKinds<E> = E extends TypedError<unknown[], infer K> ? K : never;
+type AllTypedKindsHandled<E, Handled extends string> = TypedKinds<E> extends Handled ? true : false;
+
+type ErrorFactories<T extends ErrDefMap> = {
+  [K in keyof T & string]: ErrFactory<Parameters<T[K]["message"]>, K>;
+} & {
+  readonly _type: {
+    [K in keyof T & string]: TypedError<Parameters<T[K]["message"]>, K>;
+  }[keyof T & string];
+};
+
+export function createErrors<T extends ErrDefMap>(defs: T): ErrorFactories<T> {
+  const result: Record<string, ErrFactory<unknown[], string>> = {};
+  for (const [name, def] of Object.entries(defs)) {
+    result[name] = createError(name, def.message, def.help);
+  }
+  return result as unknown as ErrorFactories<T>;
+}
+
+export function createError<A extends unknown[], N extends string>(
+  name: N,
+  message: (...args: A) => string,
+  help?: (...args: A) => string,
+): ErrFactory<A, N> {
+  class _Error extends Error {
+    override readonly name: N;
+    readonly args: A;
+    readonly help: string | undefined;
+    readonly kind: N = name;
+
+    constructor(...args: A) {
+      super(message(...args));
+      this.name = name;
+      this.args = args;
+      if (help) {
+        this.help = help(...args);
+      }
+    }
+  }
+  Object.defineProperty(_Error, "name", { value: name });
+
+  const factory = (...args: A): TypedError<A, N> =>
+    new _Error(...args) as unknown as TypedError<A, N>;
+  Object.defineProperty(factory, $class, { value: _Error });
+  return factory as unknown as ErrFactory<A, N>;
+}
+
+export function wrapError<C extends new (...args: never[]) => Error>(
+  cls: C,
+): ExternalErrFactory<C> {
+  const factory = (...args: ConstructorParameters<C>): Error => new cls(...args);
+  Object.defineProperty(factory, $class, { value: cls });
+  return factory as unknown as ExternalErrFactory<C>;
+}
+
+export class MatchErrBuilder<T, E, R, Handled extends string = never> {
+  private readonly result: Result<T, E>;
+  private readonly handlers: HandlerEntry[] = [];
+
+  constructor(result: Result<T, E>) {
+    this.result = result;
+  }
+
+  on<A extends unknown[], N extends string, HandlerResult>(
+    def: ErrFactory<A, N>,
+    handler: (err: TypedError<A, N>) => HandlerResult,
+  ): MatchErrBuilder<T, E, R | HandlerResult, Handled | N>;
+
+  on<C extends new (...args: never[]) => Error, HandlerResult>(
+    def: ExternalErrFactory<C>,
+    handler: (err: InstanceType<C>) => HandlerResult,
+  ): MatchErrBuilder<T, E, R | HandlerResult, Handled>;
+
+  on(def: unknown, handler: unknown): this {
+    const _class = (def as { readonly [$class]: new (...args: never[]) => Error })[$class];
+    this.handlers.push({
+      execute: (err: unknown) => {
+        if ((err as Error) instanceof _class) {
+          return (handler as (err: unknown) => unknown)(err);
+        }
+        return noMatch;
+      },
+    });
+    return this;
+  }
+
+  otherwise(fallback: (err: E) => R): T | R {
+    return this.execute(fallback);
+  }
+
+  exhaustive(): AllTypedKindsHandled<E, Handled> extends true
+    ? T | R
+    : { readonly [exhaustiveCheck]: typeof exhaustiveCheck } {
+    return this.execute((err) => {
+      throw err;
+    }) as never;
+  }
+
+  private execute(fallback: (err: E) => R): T | R {
+    if (this.result.ok) {
+      return this.result.value;
+    }
+
+    // biome-ignore lint/nursery/useDestructuring: discriminated union prevents destructuring
+    const error = this.result.error;
+
+    for (const entry of this.handlers) {
+      const result = entry.execute(error);
+      if (result !== noMatch) {
+        return result as R;
+      }
+    }
+
+    return fallback(error);
+  }
+}
+
+export function matchErr<T, E>(result: Result<T, E>): MatchErrBuilder<T, E, never, never> {
+  return new MatchErrBuilder(result);
+}
+
+export interface ErrFactory<A extends unknown[], N extends string> {
+  (...args: A): TypedError<A, N>;
+  readonly [$class]: new (...args: A) => TypedError<A, N>;
+}

package/src/report.ts

@@ -0,0 +1,62 @@
+/**
+ * Options for creating a new Report.
+ *
+ * @category Error Handling
+ */
+export interface ReportOptions {
+  /** The underlying cause of the error. */
+  cause?: unknown;
+  /** A helpful message for the user on how to resolve the error. */
+  help?: string | undefined;
+  /** Additional key-value pairs to provide more context. */
+  context?: Record<string, unknown> | undefined;
+}
+
+/**
+ * A structured error class that supports causes, help messages, and context.
+ * Inspired by Rust's `anyhow` or `eyre`.
+ *
+ * @category Error Handling
+ */
+export class Report extends Error {
+  /** A helpful message for the user on how to resolve the error. */
+  readonly help?: string | undefined;
+  /** Additional key-value pairs to provide more context. */
+  readonly context?: Record<string, unknown> | undefined;
+
+  constructor(message: string, options: ReportOptions = {}) {
+    super(message);
+    this.name = "Report";
+    this.help = options.help;
+    this.context = options.context;
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+  }
+
+  /**
+   * Creates a Report from an unknown error.
+   * If the error is already a Report and no new information is provided, it returns it as is.
+   *
+   * @param err The original error.
+   * @param message An optional new message.
+   * @param options Additional options.
+   * @returns A Report instance.
+   */
+  static from(err: unknown, message?: string, options: ReportOptions = {}): Report {
+    if (err instanceof Report && !message && !options.help && !options.context) {
+      return err;
+    }
+
+    let baseMessage: string;
+    if (message) {
+      baseMessage = message;
+    } else if (err instanceof Error) {
+      baseMessage = err.message;
+    } else {
+      baseMessage = String(err);
+    }
+
+    return new Report(baseMessage, { cause: err, ...options });
+  }
+}

package/src/result-builder-async.ts

@@ -0,0 +1,141 @@
+import { match } from "./consumers/match";
+import { unwrap } from "./consumers/unwrap";
+import { unwrapOr } from "./consumers/unwrap-or";
+import { Err } from "./factories/err";
+import { isErr } from "./factories/is-err";
+import { isOk } from "./factories/is-ok";
+import { Ok } from "./factories/ok";
+import { safeAsync } from "./factories/safe-async";
+import { context as contextOp } from "./operators/context";
+import { map } from "./operators/map";
+import { mapErr } from "./operators/map-err";
+import { tap } from "./operators/tap";
+import { tapErr } from "./operators/tap-err";
+import type { Report } from "./report";
+import type { AsyncResult, Result } from "./types/result";
+
+export class AsyncResultBuilder<T, E> {
+  private readonly _promise: AsyncResult<T, E>;
+
+  constructor(promise: AsyncResult<T, E>) {
+    this._promise = promise;
+  }
+
+  static ok<U = void, F = unknown>(value?: U): AsyncResultBuilder<U, F> {
+    return new AsyncResultBuilder(Promise.resolve(Ok(value) as Result<U, F>));
+  }
+
+  static err<U, F>(error: F): AsyncResultBuilder<U, F> {
+    return new AsyncResultBuilder(Promise.resolve(Err(error) as Result<U, F>));
+  }
+
+  static safeAsync<U, F = Error>(promise: Promise<U>): AsyncResultBuilder<U, F> {
+    return new AsyncResultBuilder(safeAsync(promise) as AsyncResult<U, F>);
+  }
+
+  static all<U, F>(results: AsyncResult<U, F>[]): AsyncResultBuilder<U[], F> {
+    return new AsyncResultBuilder(
+      Promise.all(results).then((resolved) => {
+        const values: U[] = [];
+        for (const res of resolved) {
+          if (!res.ok) {
+            return Err(res.error);
+          }
+          values.push(res.value);
+        }
+        return Ok(values);
+      }),
+    );
+  }
+
+  static any<U, F>(results: AsyncResult<U, F>[]): AsyncResultBuilder<U, F> {
+    if (results.length === 0) {
+      return new AsyncResultBuilder(
+        Promise.resolve(Err(new Error("any() called with an empty array") as unknown as F)),
+      );
+    }
+
+    return new AsyncResultBuilder(
+      Promise.all(results).then((resolved) => {
+        let lastErr: F | undefined;
+        for (const res of resolved) {
+          if (res.ok) {
+            return res;
+          }
+          lastErr = res.error;
+        }
+        return Err(lastErr as F);
+      }),
+    );
+  }
+
+  get result(): AsyncResult<T, E> {
+    return this._promise;
+  }
+
+  get isOk(): Promise<boolean> {
+    return this._promise.then(isOk);
+  }
+
+  get isErr(): Promise<boolean> {
+    return this._promise.then(isErr);
+  }
+
+  map<R>(fn: (value: T) => R): AsyncResultBuilder<R, E> {
+    return new AsyncResultBuilder(this._promise.then((r) => map(r, fn)));
+  }
+
+  mapErr<F>(fn: (error: E) => F): AsyncResultBuilder<T, F> {
+    return new AsyncResultBuilder(this._promise.then((r) => mapErr(r, fn)));
+  }
+
+  andThen<R>(fn: (value: T) => Result<R, E> | AsyncResult<R, E>): AsyncResultBuilder<R, E> {
+    return new AsyncResultBuilder(
+      this._promise.then((r) => {
+        if (!r.ok) {
+          return r;
+        }
+        return fn(r.value);
+      }),
+    );
+  }
+
+  orElse<F>(fn: (error: E) => Result<T, F> | AsyncResult<T, F>): AsyncResultBuilder<T, F> {
+    return new AsyncResultBuilder(
+      this._promise.then((r) => {
+        if (r.ok) {
+          return r;
+        }
+        return fn(r.error);
+      }),
+    );
+  }
+
+  tap(fn: (value: T) => void): AsyncResultBuilder<T, E> {
+    return new AsyncResultBuilder(this._promise.then((r) => tap(r, fn)));
+  }
+
+  tapErr(fn: (error: E) => void): AsyncResultBuilder<T, E> {
+    return new AsyncResultBuilder(this._promise.then((r) => tapErr(r, fn)));
+  }
+
+  context(message: string, help?: string): AsyncResultBuilder<T, Report> {
+    return new AsyncResultBuilder(this._promise.then((r) => contextOp(r, message, help)));
+  }
+
+  match<R>(handlers: { ok: (value: T) => R; err: (error: E) => R }): Promise<R> {
+    return this._promise.then((r) => match(r, handlers));
+  }
+
+  unwrapOr(defaultValue: T): Promise<T> {
+    return this._promise.then((r) => unwrapOr(r, defaultValue));
+  }
+
+  unwrap(): Promise<T> {
+    return this._promise.then((r) => unwrap(r));
+  }
+}
+
+export function buildAsync<T, E>(promise: AsyncResult<T, E>): AsyncResultBuilder<T, E> {
+  return new AsyncResultBuilder(promise);
+}

package/src/result-builder.ts

@@ -0,0 +1,193 @@
+import { match } from "./consumers/match";
+import { unwrap } from "./consumers/unwrap";
+import { unwrapOr } from "./consumers/unwrap-or";
+import { isErr } from "./factories/is-err";
+import { isOk } from "./factories/is-ok";
+import { andThen } from "./operators/and-then";
+import { context as contextOp } from "./operators/context";
+import { map } from "./operators/map";
+import { mapErr } from "./operators/map-err";
+import { orElse } from "./operators/or-else";
+import { tap } from "./operators/tap";
+import { tapErr } from "./operators/tap-err";
+import type { Report } from "./report";
+import type { Result } from "./types/result";
+
+/**
+ * A fluent wrapper around the Result type that allows for method chaining.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ *
+ * @category Builder
+ */
+export class ResultBuilder<T, E> {
+  private readonly _result: Result<T, E>;
+
+  constructor(result: Result<T, E>) {
+    this._result = result;
+  }
+
+  /**
+   * Constructs a successful Result wrapped in a ResultBuilder.
+   */
+  static ok<U = void, F = unknown>(value?: U): ResultBuilder<U, F> {
+    return new ResultBuilder({ ok: true, value: value as U });
+  }
+
+  /**
+   * Constructs an error Result wrapped in a ResultBuilder.
+   */
+  static err<U, F>(error: F): ResultBuilder<U, F> {
+    return new ResultBuilder({ ok: false, error });
+  }
+
+  /**
+   * Executes a synchronous function and wraps the result in a ResultBuilder.
+   */
+  static safe<U, F = Error>(fn: () => U): ResultBuilder<U, F> {
+    try {
+      return ResultBuilder.ok(fn());
+    } catch (e) {
+      return ResultBuilder.err(e as F);
+    }
+  }
+
+  /**
+   * Combines multiple Results into a single ResultBuilder.
+   */
+  static all<U, F>(results: Result<U, F>[]): ResultBuilder<U[], F> {
+    const values: U[] = [];
+    for (const res of results) {
+      if (!res.ok) {
+        return ResultBuilder.err(res.error);
+      }
+      values.push(res.value);
+    }
+    return ResultBuilder.ok(values);
+  }
+
+  /**
+   * Returns the first Ok Result from an array wrapped in a ResultBuilder.
+   */
+  static any<U, F>(results: Result<U, F>[]): ResultBuilder<U, F> {
+    if (results.length === 0) {
+      return ResultBuilder.err(new Error("any() called with an empty array") as unknown as F);
+    }
+
+    let lastErr: F | undefined;
+    for (const res of results) {
+      if (res.ok) {
+        return new ResultBuilder(res);
+      }
+      lastErr = res.error;
+    }
+
+    return ResultBuilder.err(lastErr as F);
+  }
+
+  /**
+   * Returns the underlying raw Result type.
+   */
+  get result(): Result<T, E> {
+    return this._result;
+  }
+
+  /**
+   * Returns true if the result is an Ok.
+   */
+  get isOk(): boolean {
+    return isOk(this._result);
+  }
+
+  /**
+   * Returns true if the result is an Err.
+   */
+  get isErr(): boolean {
+    return isErr(this._result);
+  }
+
+  /**
+   * Maps the success value if the result is Ok.
+   */
+  map<R>(fn: (value: T) => R): ResultBuilder<R, E> {
+    return new ResultBuilder(map(this._result, fn));
+  }
+
+  /**
+   * Maps the error value if the result is Err.
+   */
+  mapErr<F>(fn: (error: E) => F): ResultBuilder<T, F> {
+    return new ResultBuilder(mapErr(this._result, fn));
+  }
+
+  /**
+   * Chains another operation that returns a Result.
+   */
+  andThen<R>(fn: (value: T) => Result<R, E>): ResultBuilder<R, E> {
+    return new ResultBuilder(andThen(this._result, fn));
+  }
+
+  /**
+   * Chains another operation that returns a Result if the current result is an Err.
+   */
+  orElse<F>(fn: (error: E) => Result<T, F>): ResultBuilder<T, F> {
+    return new ResultBuilder(orElse(this._result, fn));
+  }
+
+  /**
+   * Executes a side effect if the result is Ok.
+   */
+  tap(fn: (value: T) => void): this {
+    tap(this._result, fn);
+    return this;
+  }
+
+  /**
+   * Executes a side effect if the result is Err.
+   */
+  tapErr(fn: (error: E) => void): this {
+    tapErr(this._result, fn);
+    return this;
+  }
+
+  /**
+   * Matches the result against Ok and Err handlers.
+   */
+  match<R>(handlers: { ok: (value: T) => R; err: (error: E) => R }): R {
+    return match(this._result, handlers);
+  }
+
+  /**
+   * Unwraps the value or returns a default value.
+   */
+  unwrapOr(defaultValue: T): T {
+    return unwrapOr(this._result, defaultValue);
+  }
+
+  /**
+   * Unwraps the value or throws the error.
+   */
+  unwrap(): T {
+    return unwrap(this._result);
+  }
+
+  /**
+   * Attaches context to the error if it exists.
+   */
+  context(message: string, help?: string): ResultBuilder<T, Report> {
+    return new ResultBuilder(contextOp(this._result, message, help));
+  }
+}
+
+/**
+ * Wraps a Result in a ResultBuilder for fluent chaining.
+ *
+ * @param result The Result to wrap.
+ * @returns A ResultBuilder instance.
+ *
+ * @category Builder
+ */
+export function build<T, E>(result: Result<T, E>): ResultBuilder<T, E> {
+  return new ResultBuilder(result);
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export type * from "./result";

package/src/types/result.ts

@@ -0,0 +1,15 @@
+/**
+ * A Result type representing either a success (Ok) or an error (Err).
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ */
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+/**
+ * Represents a Result that is asynchronously resolved.
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ */
+export type AsyncResult<T, E> = Promise<Result<T, E>>;

package/src/utils/all.ts

@@ -0,0 +1,30 @@
+import { Err } from "../factories/err";
+import { Ok } from "../factories/ok";
+import type { Result } from "../types";
+
+/**
+ * Combines multiple Results into a single Result.
+ * If all Results are Ok, returns an Ok with an array of all values.
+ * If any Result is an Err, returns the first Err encountered.
+ *
+ * @template T The type of the success values.
+ * @template E The type of the error value.
+ * @param results An array of Results to combine.
+ * @returns A Result with an array of values or the first error.
+ *
+ * @category Utilities
+ * @see any
+ * @example
+ * const res = all([Ok(1), Ok(2)]); // Ok([1, 2])
+ * const res = all([Ok(1), Err("fail")]); // Err("fail")
+ */
+export function all<T, E>(results: Result<T, E>[]): Result<T[], E> {
+  const values: T[] = [];
+  for (const res of results) {
+    if (!res.ok) {
+      return Err(res.error);
+    }
+    values.push(res.value);
+  }
+  return Ok(values);
+}

package/src/utils/any.ts

@@ -0,0 +1,32 @@
+import { Err } from "../factories/err";
+import type { Result } from "../types";
+
+/**
+ * Returns the first Ok Result from an array of Results.
+ * If all Results are Err, returns the last Err encountered (or a default error if empty).
+ *
+ * @template T The type of the success value.
+ * @template E The type of the error value.
+ * @param results An array of Results to check.
+ * @returns The first Ok result or the last Err.
+ *
+ * @category Utilities
+ * @see all
+ * @example
+ * const res = any([Err("a"), Ok(1), Ok(2)]); // Ok(1)
+ */
+export function any<T, E>(results: Result<T, E>[]): Result<T, E> {
+  if (results.length === 0) {
+    return Err(new Error("any() called with an empty array") as unknown as E);
+  }
+
+  let lastErr: E | undefined;
+  for (const res of results) {
+    if (res.ok) {
+      return res;
+    }
+    lastErr = res.error;
+  }
+
+  return Err(lastErr as E);
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { all } from "./all";
+export { any } from "./any";