@onrails/result 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,123 @@
-export { R as ResultAsync, e as errAsync, f as fromPromise, a as fromSafePromise, o as okAsync, p as parallelTupleAsync, s as sequenceTupleAsync, t as tryAsync } from './async-DKISqIBc.js';
+import { R as ResultAsync } from './async-1fIhfzFu.js';
+import { R as Result, E as Err, O as Ok } from './types-BQ9vv0nD.js';
+export { U as UnexpectedError } from './types-BQ9vv0nD.js';
 export { InferErr, InferOk, asyncAfter, fromAsync, fromResult } from './interop.js';
 export { flow } from './pipe.js';
-import { R as Result, E as Err, O as Ok } from './types-C2Dp1d5J.js';
-export { U as UnexpectedError } from './types-C2Dp1d5J.js';
 export { $, tryGen, yieldResult } from './try-gen.js';
 
+/**
+ * Lifts a value into an `Ok` async result.
+ *
+ * @example
+ * ```ts
+ * const r = okAsync(42);                  // ResultAsync<number, never>
+ * ```
+ */
+declare const okAsync: typeof ResultAsync.ok;
+/**
+ * Lifts a value into an `Err` async result.
+ *
+ * @example
+ * ```ts
+ * const r = errAsync({ kind: "not_found" as const });
+ * ```
+ */
+declare const errAsync: typeof ResultAsync.err;
+/**
+ * Wraps a `PromiseLike<T>` into a {@link ResultAsync}. Reject reasons go
+ * through `onReject` to become typed `Err`s; success becomes `Ok<T>`.
+ *
+ * @example
+ * ```ts
+ * const body = fromPromise(
+ *   fetch(url).then((r) => r.text()),
+ *   (e): NetworkError => ({ kind: "network", cause: String(e) }),
+ * );
+ * ```
+ */
+declare const fromPromise: typeof ResultAsync.fromPromise;
+/**
+ * Wraps a `PromiseLike<T>` that **never rejects** into {@link ResultAsync}.
+ * Skips the `onReject` mapper. Use only when the promise is provably safe.
+ */
+declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
+/**
+ * Heterogeneous async tuple combine — branches overlap in wall-clock time.
+ * Returns the first `Err` in **input** order (not completion order).
+ *
+ * @example
+ * ```ts
+ * const combined = parallelTupleAsync([
+ *   loadProfile(id),
+ *   loadMetrics(id),
+ *   loadFlags(id),
+ * ] as const);
+ * // ResultAsync<readonly [Profile, Metrics, Flags], …>
+ * ```
+ */
+declare const parallelTupleAsync: typeof ResultAsync.combineTupleParallel;
+/**
+ * Convenience wrapper over {@link fromPromise} with default `Error`
+ * normalization. Call without `onReject` to get `ResultAsync<T, Error>`,
+ * or pass a custom mapper for a typed error.
+ *
+ * @example
+ * ```ts
+ * // Default: rejection → Err(Error)
+ * const a = tryAsync(db.users.insert(row));
+ *
+ * // Custom: typed error
+ * const b = tryAsync(db.users.insert(row), (e): DbError => ({
+ *   kind: "db",
+ *   cause: e,
+ * }));
+ * ```
+ */
+declare function tryAsync<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
+declare function tryAsync<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
+
+/**
+ * Combines a homogeneous array of results into a single result holding an
+ * array of the `Ok` values, in input order. Short-circuits on the first `Err`
+ * (first failure wins). For heterogeneous tuples that preserve per-index
+ * types, use {@link combineTuple}.
+ *
+ * @example
+ * ```ts
+ * combine([ok(1), ok(2)]);        // Ok([1, 2])
+ * combine([ok(1), err("e")]);     // Err("e")
+ * ```
+ */
+declare const combine: <T, E>(results: readonly Result<T, E>[]) => Result<T[], E>;
+/**
+ * Heterogeneous tuple combine — like {@link combine} but preserves each
+ * branch's `Ok` type by position, so the result destructures type-safely.
+ * Short-circuits on the first `Err` in input order (neverthrow-style).
+ *
+ * @example
+ * ```ts
+ * const r = combineTuple([ok(1), ok("x")] as const);
+ * // Result<readonly [number, string], never>
+ * if (isOk(r)) {
+ *   const [n, s] = r.value;   // typed per position
+ * }
+ * ```
+ */
+declare const combineTuple: <const R extends readonly Result<unknown, unknown>[]>(results: R) => CombineTuple<R>;
+type _OkValue<R> = R extends {
+    _tag: "Ok";
+    readonly value: infer T;
+} ? T : never;
+type _ErrValue<R> = R extends {
+    _tag: "Err";
+    readonly error: infer E;
+} ? E : never;
+type CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<{
+    [K in keyof R]: _OkValue<R[K]>;
+}, {
+    [K in keyof R]: _ErrValue<R[K]>;
+}[number]>;
+
 /**
  * Lifts a value into the success track.
  *
@@ -47,11 +160,6 @@ declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T, E>;
  * ```
  */
 declare const isErr: <T, E>(result: Result<T, E>) => result is Err<T, E>;
-/**
- * Fantasy Land `of` — alias of {@link ok}.
- * @deprecated Use {@link ok} instead.
- */
-declare const of: <T, E = never>(value: T) => Result<T, E>;
 /**
  * Transform the `Ok` value, passing `Err` through unchanged. Dual-form:
  * call data-first or curried (for use with {@link pipe}).
@@ -152,8 +260,9 @@ declare function tapErr<E>(fn: (error: E) => void): <T>(result: Result<T, E>) =>
  * 3-args data-first, 2-args curried for {@link pipe}. Returns whatever
  * the handlers return.
  *
- * For files that also import `match` from `ts-pattern`, the
- * collision-free alias {@link matchResult} is identical.
+ * For files that also import `match` from `ts-pattern`, use a namespace
+ * import (`import * as R from "@onrails/result"` → `R.match`) to dissolve
+ * the collision.
  *
  * @example
  * ```ts
@@ -162,21 +271,6 @@ declare function tapErr<E>(fn: (error: E) => void): <T>(result: Result<T, E>) =>
  */
 declare function match<T, E, U>(result: Result<T, E>, onOk: (value: T) => U, onErr: (error: E) => U): U;
 declare function match<T, E, U>(onOk: (value: T) => U, onErr: (error: E) => U): (result: Result<T, E>) => U;
-/**
- * Collision-free alias for files that also import `match` from ts-pattern.
- * @deprecated Namespace import carriers (e.g., `import * as R from "@onrails/result"`) and use canonical {@link match} instead.
- */
-declare const matchResult: typeof match;
-/**
- * Curried collapse with named slots — escape valve when positional `match`
- * order is unclear at the call site (e.g. when both handlers return the same
- * type and a transposed `match(r, onErr, onOk)` would silently compile).
- * @deprecated Use curried {@link match}(onOk, onErr)(result) instead.
- */
-declare const fold: <T, E, U>(handlers: {
-    readonly ok: (value: T) => U;
-    readonly err: (error: E) => U;
-}) => (result: Result<T, E>) => U;
 /**
  * Returns the `Ok` value, or `defaultValue` when the result is `Err`.
  *
@@ -187,46 +281,75 @@ declare const fold: <T, E, U>(handlers: {
  */
 declare const unwrapOr: <T, E>(result: Result<T, E>, defaultValue: T) => T;
 /**
- * Test/assert helper — throws the original Err value when called on Err.
+ * Test/assert helper — returns the `Ok` value, or **throws the original `Err`
+ * value** when called on an `Err`. This is the assertion tier (RFC 0001 §4):
+ * intended for `*.spec.ts` / `*.test.ts`, where throwing fails the test loudly.
+ * In business logic prefer {@link match} or {@link unwrapOr}; the lint plugins
+ * flag `unwrapOk` outside test files.
+ *
+ * @returns the unwrapped `Ok` value
+ * @throws the carried `Err` value when the result is `Err`
  *
- * @throws when the result is Err — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.
- * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ * @example
+ * ```ts
+ * // in a *.spec.ts
+ * expect(unwrapOk(ok(5))).toBe(5);
+ * expect(() => unwrapOk(err(error))).toThrow(error);
+ * ```
  */
 declare function unwrapOk<T, E>(result: Result<T, E>): T;
 /**
- * Test/assert helper — throws TypeError when called on Ok.
+ * Test/assert helper — returns the `Err` value, or **throws a `TypeError`**
+ * when called on an `Ok`. Mirror of {@link unwrapOk} on the error track and
+ * part of the same assertion tier (RFC 0001 §4): intended for `*.spec.ts` /
+ * `*.test.ts`. Prefer {@link match} / {@link unwrapOr} in business logic; the
+ * lint plugins flag `unwrapErr` outside test files.
  *
- * @throws when the result is Ok — assertion-tier; allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.
+ * @returns the unwrapped `Err` value
+ * @throws `TypeError` when the result is `Ok`
+ *
+ * @example
+ * ```ts
+ * // in a *.spec.ts
+ * expect(unwrapErr(err("x"))).toBe("x");
+ * expect(() => unwrapErr(ok(5))).toThrow(TypeError);
+ * ```
  */
 declare function unwrapErr<T, E>(result: Result<T, E>): E;
-/** Wrap a throwing sync function — neverthrow `Result.fromThrowable` */
+/**
+ * Wraps a throwing sync function, returning a function that produces a
+ * {@link Result} instead of throwing. Thrown errors pass through `onThrow` to
+ * become a typed `Err`; a normal return becomes `Ok`. The neverthrow analogue
+ * is `Result.fromThrowable`.
+ *
+ * @param fn - the throwing function to wrap
+ * @param onThrow - maps a thrown value to the `Err` channel
+ * @returns a function with `fn`'s parameters that returns `Result<ReturnType, E>`
+ *
+ * @example
+ * ```ts
+ * type ParseError = { kind: "parse"; message: string };
+ * const parse = trySync(
+ *   JSON.parse,
+ *   (e): ParseError => ({ kind: "parse", message: String(e) }),
+ * );
+ * parse("{}");      // Ok({})
+ * parse("nope");    // Err({ kind: "parse", … })
+ * ```
+ */
 declare function trySync<A extends readonly unknown[], T, E>(fn: (...args: A) => T, onThrow: (error: unknown) => E): (...args: A) => Result<T, E>;
 declare function trySync<F extends (...args: never) => unknown, E>(fn: F, onThrow: (error: unknown) => E): (...args: Parameters<F>) => Result<ReturnType<F>, E>;
-/** First failure wins; otherwise collects values in order */
-declare const combine: <T, E>(results: readonly Result<T, E>[]) => Result<T[], E>;
-/** Tuple-preserving combine (neverthrow-style) */
-declare const combineTuple: <const R extends readonly Result<unknown, unknown>[]>(results: R) => CombineTuple<R>;
-type _OkValue<R> = R extends {
-    _tag: "Ok";
-    readonly value: infer T;
-} ? T : never;
-type _ErrValue<R> = R extends {
-    _tag: "Err";
-    readonly error: infer E;
-} ? E : never;
-type CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<{
-    [K in keyof R]: _OkValue<R[K]>;
-}, {
-    [K in keyof R]: _ErrValue<R[K]>;
-}[number]>;
 /**
- * Variadic value-first pipe — threads `value` through up to nine unary fns.
+ * Variadic value-first pipe — threads `value` through up to nine unary fns,
+ * left-to-right. Use {@link pipe} when you already have a starting value;
+ * use {@link flow} to define a reusable composed function with no value yet.
  *
+ * @example
  * ```ts
  * pipe(
  *   parseConfig(raw),
  *   map((cfg) => cfg.name),
- *   flatMap((name) => name ? ok(name) : err({ kind: "empty" })),
+ *   flatMap((name) => (name ? ok(name) : err({ kind: "empty" as const }))),
  *   tap(log),
  * );
  * ```
@@ -241,4 +364,4 @@ declare function pipe<A, B, C, D, E, F, G>(value: A, ab: (a: A) => B, bc: (b: B)
 declare function pipe<A, B, C, D, E, F, G, H>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): H;
 declare function pipe<A, B, C, D, E, F, G, H, I>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): I;
 
-export { Err, Ok, Result, bimap, combine, combineTuple, err, flatMap, fold, isErr, isOk, map, mapErr, match, matchResult, of, ok, pipe, recover, tap, tapErr, trySync, unwrapErr, unwrapOk, unwrapOr };
+export { Err, Ok, Result, ResultAsync, bimap, combine, combineTuple, err, errAsync, flatMap, fromPromise, fromSafePromise, isErr, isOk, map, mapErr, match, ok, okAsync, parallelTupleAsync, pipe, recover, tap, tapErr, tryAsync, trySync, unwrapErr, unwrapOk, unwrapOr };

package/dist/index.js

@@ -9,7 +9,6 @@ var err = (error) => ({
 });
 var isOk = (result) => result._tag === "Ok";
 var isErr = (result) => result._tag === "Err";
-var of = ok;
 var mapImpl = (result, fn) => isOk(result) ? ok(fn(result.value)) : err(result.error);
 function map(...args) {
   if (args.length === 2) return mapImpl(args[0], args[1]);
@@ -64,8 +63,6 @@ function match(...args) {
   const [onOk, onErr] = args;
   return (result) => matchImpl(result, onOk, onErr);
 }
-var matchResult = match;
-var fold = (handlers) => (result) => matchImpl(result, handlers.ok, handlers.err);
 var unwrapOr = (result, defaultValue) => isOk(result) ? result.value : defaultValue;
 function unwrapOk(result) {
   if (isErr(result)) throw result.error;
@@ -84,18 +81,6 @@ function trySync(fn, onThrow) {
     }
   };
 }
-var combine = (results) => {
-  const values = [];
-  for (const result of results) {
-    if (isErr(result)) return err(result.error);
-    values.push(result.value);
-  }
-  return ok(values);
-};
-var combineTuple = (results) => (
-  // Runtime identical to combine; the cast restores per-index tuple types.
-  combine(results)
-);
 function pipe(value, ...fns) {
   let acc = value;
   for (const fn of fns) {
@@ -142,9 +127,32 @@ var ResultAsync = class _ResultAsync {
   }
   run;
   promise = null;
+  /**
+   * Lifts an already-settled sync {@link Result} into a {@link ResultAsync}.
+   *
+   * @example
+   * ```ts
+   * const ra = ResultAsync.fromResult(ok(42));   // ResultAsync<number, never>
+   * ```
+   */
   static fromResult(result) {
     return new _ResultAsync(async () => result);
   }
+  /**
+   * Wraps a `PromiseLike<T>` that may reject. Rejections pass through `onReject`
+   * to become a typed `Err`; resolution becomes `Ok<T>`.
+   *
+   * @param promise - the promise to wrap
+   * @param onReject - maps a rejection reason to the `Err` channel
+   *
+   * @example
+   * ```ts
+   * const body = ResultAsync.fromPromise(
+   *   fetch(url).then((r) => r.text()),
+   *   (e): NetError => ({ kind: "net", cause: String(e) }),
+   * );
+   * ```
+   */
   static fromPromise(promise, onReject) {
     return new _ResultAsync(async () => {
       try {
@@ -154,12 +162,29 @@ var ResultAsync = class _ResultAsync {
       }
     });
   }
+  /**
+   * Wraps a `PromiseLike<T>` that is **guaranteed not to reject**, skipping the
+   * `onReject` mapper. Use only when rejection is provably impossible.
+   *
+   * @example
+   * ```ts
+   * const now = ResultAsync.fromSafePromise(Promise.resolve(Date.now()));
+   * ```
+   */
   static fromSafePromise(promise) {
     return new _ResultAsync(async () => ok(await promise));
   }
   /**
-   * Defers work until {@link resolve}. Unlike {@link fromPromise}, nothing runs
-   * until the `ResultAsync` is resolved (e.g. by `combineTuple` / `combineTupleParallel`).
+   * Defers work until {@link resolve}. Unlike {@link fromPromise}, the factory
+   * does not run until the `ResultAsync` is resolved (e.g. by `combineTuple` /
+   * `combineTupleParallel`). The factory runs at most once — `resolve` memoizes.
+   *
+   * @example
+   * ```ts
+   * const insert = ResultAsync.defer(() => db.orders.insert(row));
+   * // nothing has run yet
+   * const r = await insert;   // factory runs exactly once here
+   * ```
    */
   static defer(fn) {
     return new _ResultAsync(fn);
@@ -167,14 +192,42 @@ var ResultAsync = class _ResultAsync {
   static ok(value) {
     return new _ResultAsync(async () => ok(value));
   }
+  /**
+   * Lifts an error into an `Err` async result.
+   *
+   * @example
+   * ```ts
+   * const r = ResultAsync.err({ kind: "not_found" as const });
+   * ```
+   */
   static err(error) {
     return new _ResultAsync(async () => err(error));
   }
-  /** @see {@link fromAsync} from `@onrails/result/interop` */
+  /**
+   * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a
+   * {@link ResultAsync}, auto-flattening one level of double-wrapping. A thrown
+   * defect is routed through `onDefect`, defaulting to {@link UnexpectedError}.
+   *
+   * @param promise - a promise that already yields a `Result`
+   * @param onDefect - maps an unexpected throw to the `Err` channel
+   * @see {@link fromAsync} from `@onrails/result/interop`
+   */
   static fromResultPromise(promise, onDefect) {
     const mapDefect = onDefect ?? ((error) => new UnexpectedError("Unexpected async defect", error));
     return new _ResultAsync(() => liftPromiseResult(promise, mapDefect));
   }
+  /**
+   * Combines a homogeneous array of async results into one. Resolves
+   * **sequentially** in input order, short-circuiting on the first `Err`.
+   * For heterogeneous tuples that preserve per-index types, use
+   * {@link combineTuple}; for wall-clock overlap, {@link combineTupleParallel}.
+   *
+   * @example
+   * ```ts
+   * const all = ResultAsync.combine([loadA(), loadB(), loadC()]);
+   * // ResultAsync<Item[], LoadError>
+   * ```
+   */
   static combine(results) {
     return new _ResultAsync(async () => {
       const values = [];
@@ -188,6 +241,23 @@ var ResultAsync = class _ResultAsync {
       return ok(values);
     });
   }
+  /**
+   * Heterogeneous async tuple combine — resolves branches **sequentially**
+   * (left-to-right), returning the first `Err` in input order. Preserves each
+   * branch's `Ok` type by position, so the result destructures type-safely.
+   * This is the canonical sequential async combine (replaces the former
+   * `sequenceTupleAsync`).
+   *
+   * @example
+   * ```ts
+   * const combined = ResultAsync.combineTuple([loadCfg(), loadCatalog()] as const);
+   * // ResultAsync<readonly [Cfg, Catalog], CfgError | CatalogError>
+   * const r = await combined;
+   * if (isOk(r)) {
+   *   const [cfg, catalog] = r.value;  // typed per position
+   * }
+   * ```
+   */
   static combineTuple(results) {
     return _ResultAsync.combine(
       results
@@ -196,18 +266,55 @@ var ResultAsync = class _ResultAsync {
   /**
    * Like {@link combineTuple}, but starts every branch before awaiting (wall-clock
    * parallel for independent IO). On failure, returns the first `Err` in input order.
+   *
+   * @example
+   * ```ts
+   * // independent IO — overlap them
+   * const combined = ResultAsync.combineTupleParallel([
+   *   loadProfile(id),
+   *   loadMetrics(id),
+   * ] as const);
+   * ```
    */
   static combineTupleParallel(results) {
     return new _ResultAsync(
       async () => sequenceSettled(await Promise.all(results.map((ra) => ra.resolve())))
     );
   }
+  /**
+   * Transforms the `Ok` value, passing `Err` through unchanged.
+   *
+   * @example
+   * ```ts
+   * ResultAsync.ok(2).map((n) => n * 3);   // ResultAsync<number> → Ok 6
+   * ```
+   */
   map(fn) {
     return new _ResultAsync(async () => map(await this.resolve(), fn));
   }
+  /**
+   * Transforms the `Err` value, passing `Ok` through unchanged — useful for
+   * unifying heterogeneous failures into one app-level union.
+   *
+   * @example
+   * ```ts
+   * load(id).mapErr((e): AppError => ({ kind: "load", cause: e }));
+   * ```
+   */
   mapErr(fn) {
     return new _ResultAsync(async () => mapErr(await this.resolve(), fn));
   }
+  /**
+   * Canonical bind — chains a step that itself returns a `ResultAsync` or sync
+   * `Result`, short-circuiting on `Err`. Error types accumulate (`E | F`).
+   *
+   * @example
+   * ```ts
+   * authenticate(req)
+   *   .flatMap((user) => loadProfile(user.id))   // ResultAsync
+   *   .flatMap((p) => validate(p));              // sync Result also accepted
+   * ```
+   */
   flatMap(fn) {
     return new _ResultAsync(async () => {
       const first = await this.resolve();
@@ -224,16 +331,28 @@ var ResultAsync = class _ResultAsync {
       return isCompatLike(next) ? next.inner : next;
     });
   }
+  /**
+   * neverthrow-compat alias of {@link flatMap}. Kept as the documented compat
+   * tier; prefer `flatMap` in new code.
+   *
+   * @example
+   * ```ts
+   * authenticate(req).andThen((user) => loadProfile(user.id));
+   * ```
+   */
   andThen(fn) {
     return this.flatMap(fn);
   }
   /**
-   * Alias for {@link flatMap}.
-   * @deprecated Use {@link flatMap} or keep/use compat {@link andThen} instead.
+   * Error-channel bind — runs `fn` only on `Err`, swapping in a recovery
+   * `ResultAsync` or sync `Result`. `Ok` passes through. The mirror of
+   * {@link flatMap} on the error track.
+   *
+   * @example
+   * ```ts
+   * loadFromCache(id).recover(() => loadFromOrigin(id));
+   * ```
    */
-  chain(fn) {
-    return this.flatMap(fn);
-  }
   recover(fn) {
     return new _ResultAsync(async () => {
       const first = await this.resolve();
@@ -244,9 +363,27 @@ var ResultAsync = class _ResultAsync {
       return next instanceof _ResultAsync ? next.resolve() : next;
     });
   }
+  /**
+   * neverthrow-compat alias of {@link recover}. Kept as the documented compat
+   * tier; prefer `recover` in new code.
+   *
+   * @example
+   * ```ts
+   * loadFromCache(id).orElse(() => loadFromOrigin(id));
+   * ```
+   */
   orElse(fn) {
     return this.recover(fn);
   }
+  /**
+   * Runs a side effect on the `Ok` value and passes the result through
+   * unchanged; a no-op on `Err`. Mirrors {@link tapErr}.
+   *
+   * @example
+   * ```ts
+   * saveUser(u).tap((saved) => analytics.track("user_saved", saved.id));
+   * ```
+   */
   tap(fn) {
     return new _ResultAsync(async () => {
       const result = await this.resolve();
@@ -256,6 +393,15 @@ var ResultAsync = class _ResultAsync {
       return result;
     });
   }
+  /**
+   * Runs a side effect on the `Err` value and passes the result through
+   * unchanged; a no-op on `Ok`. The error-track mirror of {@link tap}.
+   *
+   * @example
+   * ```ts
+   * saveUser(u).tapErr((e) => logger.warn("save failed", e));
+   * ```
+   */
   tapErr(fn) {
     return new _ResultAsync(async () => {
       const result = await this.resolve();
@@ -265,28 +411,49 @@ var ResultAsync = class _ResultAsync {
       return result;
     });
   }
-  unwrapOr(defaultValue) {
-    return this.resolve().then((result) => isErr(result) ? defaultValue : result.value);
-  }
   /**
-   * @deprecated Await the ResultAsync and narrow with {@link isOk} — this method
-   * re-executes deferred factories and cannot narrow.
+   * Settles to the `Ok` value, or `defaultValue` if `Err`. Terminal — returns a
+   * plain `Promise`, not a `ResultAsync`.
+   *
+   * @example
+   * ```ts
+   * const profile = await loadProfile(id).unwrapOr(guestProfile);
+   * ```
    */
-  isOk() {
-    return this.resolve().then((result) => !isErr(result));
+  unwrapOr(defaultValue) {
+    return this.resolve().then((result) => isErr(result) ? defaultValue : result.value);
   }
   /**
-   * @deprecated Await the ResultAsync and narrow with {@link isErr} — this method
-   * re-executes deferred factories and cannot narrow.
+   * Terminal collapse — folds both tracks into a single awaited value. Returns
+   * a plain `Promise`, settling the carrier exactly once.
+   *
+   * @param onOk - handles the `Ok` value
+   * @param onErr - handles the `Err` value
+   *
+   * @example
+   * ```ts
+   * const status = await save(row).match(
+   *   () => 200,
+   *   (e) => (e.kind === "conflict" ? 409 : 500),
+   * );
+   * ```
    */
-  isErr() {
-    return this.resolve().then((result) => isErr(result));
-  }
   match(onOk, onErr) {
     return this.resolve().then(
       (result) => isErr(result) ? onErr(result.error) : onOk(result.value)
     );
   }
+  /**
+   * Settles the carrier to a bare sync {@link Result}, memoizing so the
+   * underlying factory runs at most once. Prefer `await ra` (the thenable) or
+   * {@link match} in app code; use `resolve` when you need the tagged union back.
+   *
+   * @example
+   * ```ts
+   * const r = await load(id).resolve();   // Result<Data, LoadError>
+   * if (isOk(r)) use(r.value);
+   * ```
+   */
   resolve() {
     if (!this.promise) {
       this.promise = this.run();
@@ -312,26 +479,42 @@ function isResultLike(v) {
 function isCompatLike(v) {
   return typeof v === "object" && v !== null && "inner" in v && isResultLike(v.inner);
 }
+
+// src/async-lift.ts
 var okAsync = ResultAsync.ok;
 var errAsync = ResultAsync.err;
 var fromPromise = ResultAsync.fromPromise;
 var fromSafePromise = ResultAsync.fromSafePromise;
-var sequenceTupleAsync = ResultAsync.combineTuple;
 var parallelTupleAsync = ResultAsync.combineTupleParallel;
 var toError = (error) => error instanceof Error ? error : new Error(String(error));
 function tryAsync(promise, onReject) {
-  if (onReject) {
-    return ResultAsync.fromPromise(promise, onReject);
-  }
-  return ResultAsync.fromPromise(promise, toError);
+  return onReject ? ResultAsync.fromPromise(promise, onReject) : ResultAsync.fromPromise(promise, toError);
 }
 
+// src/collections.ts
+var combine = (results) => {
+  const values = [];
+  for (const result of results) {
+    if (isErr(result)) return err(result.error);
+    values.push(result.value);
+  }
+  return ok(values);
+};
+var combineTuple = (results) => (
+  // Runtime identical to combine; the cast restores per-index tuple types.
+  combine(results)
+);
+
 // src/interop.ts
 var fromResult = (result) => ResultAsync.fromResult(result);
-var asyncAfter = (result, fn) => fromResult(result).flatMap(fn);
-function fromAsync(fn, onDefect) {
-  return (...args) => ResultAsync.fromResultPromise(fn(...args), onDefect);
+function asyncAfter(resultOrFn, fn) {
+  if (fn === void 0) {
+    const f = resultOrFn;
+    return (result) => fromResult(result).flatMap(f);
+  }
+  return fromResult(resultOrFn).flatMap(fn);
 }
+var fromAsync = (fn, onDefect) => (...args) => ResultAsync.fromResultPromise(fn(...args), onDefect);
 
 // src/pipe.ts
 function flow(first, ...rest) {
@@ -370,6 +553,6 @@ var tryGen = (fn) => {
   }
 };
 
-export { $, ResultAsync, asyncAfter, bimap, combine, combineTuple, err, errAsync, flatMap, flow, fold, fromAsync, fromPromise, fromResult, fromSafePromise, isErr, isOk, map, mapErr, match, matchResult, of, ok, okAsync, parallelTupleAsync, pipe, recover, sequenceTupleAsync, tap, tapErr, tryAsync, tryGen, trySync, unwrapErr, unwrapOk, unwrapOr, yieldResult };
+export { $, ResultAsync, asyncAfter, bimap, combine, combineTuple, err, errAsync, flatMap, flow, fromAsync, fromPromise, fromResult, fromSafePromise, isErr, isOk, map, mapErr, match, ok, okAsync, parallelTupleAsync, pipe, recover, tap, tapErr, tryAsync, tryGen, trySync, unwrapErr, unwrapOk, unwrapOr, yieldResult };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map