@onrails/result 0.1.4 → 0.2.0

package/dist/railway.js

@@ -69,9 +69,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 {
@@ -81,12 +104,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);
@@ -94,14 +134,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 = [];
@@ -115,6 +183,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
@@ -123,18 +208,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();
@@ -151,16 +273,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();
@@ -171,9 +305,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();
@@ -183,6 +335,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();
@@ -192,28 +353,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();
@@ -300,10 +482,7 @@ var Railway = class _Railway {
         return new _Railway({ mode: "sync", result: err(current.error) });
       }
       const next = fn(current.value);
-      if (isErr(next)) {
-        return new _Railway({ mode: "sync", result: err(next.error) });
-      }
-      return new _Railway({
+      return isErr(next) ? new _Railway({ mode: "sync", result: err(next.error) }) : new _Railway({
         mode: "sync",
         result: ok(addField(current.value, key, next.value))
       });