@onrails/result 0.4.0 → 0.4.2

package/dist/async-fns.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `@onrails/result/async` — data-last twins of the {@link ResultAsync} methods,
+ * so an async railway composes with `pipe` / `flow` the same way a sync one does.
+ *
+ * `ResultAsync` is a class, so dot-chaining is always available and remains the
+ * shortest form for a one-off chain. Reach for this module when you want the
+ * sync side's other two syntaxes on the async carrier:
+ *
+ * ```ts
+ * import * as RA from "@onrails/result/async";
+ * import { pipe } from "@onrails/result";
+ * import { flow } from "@onrails/result/pipe";
+ *
+ * // value-first pipe
+ * pipe(loadUser(id), RA.flatMap(loadOrders), RA.map((os) => os.length));
+ *
+ * // reusable point-free pipeline — no value yet
+ * const orderCount = flow(loadUser, RA.flatMap(loadOrders), RA.map((os) => os.length));
+ * ```
+ *
+ * Every export mirrors one `ResultAsync` method exactly, in both forms:
+ * data-first (`RA.map(ra, fn)`) and curried (`RA.map(fn)`). Import as a
+ * namespace — the names deliberately match the sync core, and `test/parity.spec.ts`
+ * enforces that the mirror stays complete.
+ */
+import type { ResultAsync } from "./async.js";
+import type { Result } from "./types.js";
+/** A step may hand back either carrier; the async one absorbs a sync `Result`. */
+type Step<U, F> = ResultAsync<U, F> | Result<U, F>;
+/**
+ * Transforms the `Ok` value, passing `Err` through unchanged.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), map((u) => u.name));   // ResultAsync<string, LoadError>
+ * ```
+ */
+export declare const map: {
+    <T, U, E>(ra: ResultAsync<T, E>, fn: (value: T) => U): ResultAsync<U, E>;
+    <T, U>(fn: (value: T) => U): <E>(ra: ResultAsync<T, E>) => ResultAsync<U, E>;
+};
+/**
+ * Transforms the `Err` value, passing `Ok` through unchanged — useful for
+ * unifying heterogeneous failures into one app-level union.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), mapErr((e): AppError => ({ kind: "load", cause: e })));
+ * ```
+ */
+export declare const mapErr: {
+    <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => F): ResultAsync<T, F>;
+    <E, F>(fn: (error: E) => F): <T>(ra: ResultAsync<T, E>) => ResultAsync<T, F>;
+};
+/**
+ * Transforms both tracks in one step. Exactly one of `onOk` / `onErr` runs.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), bimap(toDto, (e): AppError => ({ kind: "load", cause: e })));
+ * ```
+ */
+export declare const bimap: {
+    <T, U, E, F>(ra: ResultAsync<T, E>, onOk: (value: T) => U, onErr: (error: E) => F): ResultAsync<U, F>;
+    <T, U, E, F>(onOk: (value: T) => U, onErr: (error: E) => F): (ra: ResultAsync<T, E>) => ResultAsync<U, F>;
+};
+/**
+ * Canonical bind — chains a step returning a `ResultAsync` or a sync `Result`,
+ * short-circuiting on `Err`. Error types accumulate (`E | F`).
+ *
+ * @example
+ * ```ts
+ * pipe(authenticate(req), flatMap((user) => loadProfile(user.id)));
+ * ```
+ */
+export declare const flatMap: {
+    <T, U, E, F>(ra: ResultAsync<T, E>, fn: (value: T) => Step<U, F>): ResultAsync<U, E | F>;
+    <T, U, F>(fn: (value: T) => Step<U, F>): <E>(ra: ResultAsync<T, E>) => ResultAsync<U, E | F>;
+};
+/**
+ * Error-track bind — runs `fn` only on `Err`, letting a failed workflow
+ * recover to `Ok` or remap the failure.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), recover((e) => (e === "notFound" ? okAsync(guest) : errAsync(e))));
+ * ```
+ */
+export declare const recover: {
+    <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => Step<T, F>): ResultAsync<T, F>;
+    <T, E, F>(fn: (error: E) => Step<T, F>): (ra: ResultAsync<T, E>) => ResultAsync<T, F>;
+};
+/**
+ * Observes the `Ok` value for side effects without changing it.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), tap((u) => log.info({ msg: "loaded", id: u.id })));
+ * ```
+ */
+export declare const tap: {
+    <T, E>(ra: ResultAsync<T, E>, fn: (value: T) => void): ResultAsync<T, E>;
+    <T>(fn: (value: T) => void): <E>(ra: ResultAsync<T, E>) => ResultAsync<T, E>;
+};
+/**
+ * Observes the `Err` value for side effects without changing it.
+ *
+ * @example
+ * ```ts
+ * pipe(loadUser(id), tapErr((e) => metrics.inc("user.load.fail", { kind: e.kind })));
+ * ```
+ */
+export declare const tapErr: {
+    <T, E>(ra: ResultAsync<T, E>, fn: (error: E) => void): ResultAsync<T, E>;
+    <E>(fn: (error: E) => void): <T>(ra: ResultAsync<T, E>) => ResultAsync<T, E>;
+};
+/**
+ * Terminal collapse — folds both tracks into a single awaited value, settling
+ * the carrier exactly once. Ends the pipeline, so it returns a plain `Promise`.
+ *
+ * @example
+ * ```ts
+ * const status = await pipe(save(row), match(() => 200, (e) => (e.kind === "conflict" ? 409 : 500)));
+ * ```
+ */
+export declare const match: {
+    <T, E, U1, U2 = U1>(ra: ResultAsync<T, E>, onOk: (value: T) => U1, onErr: (error: E) => U2): Promise<U1 | U2>;
+    <T, E, U1, U2 = U1>(onOk: (value: T) => U1, onErr: (error: E) => U2): (ra: ResultAsync<T, E>) => Promise<U1 | U2>;
+};
+/**
+ * Terminal — resolves to the `Ok` value, or `defaultValue` on `Err`. The
+ * fallback may differ from `T`; the result widens to `T | U`.
+ *
+ * @example
+ * ```ts
+ * const profile = await pipe(loadProfile(id), unwrapOr(guestProfile));
+ * ```
+ */
+export declare const unwrapOr: {
+    <T, E, U>(ra: ResultAsync<T, E>, defaultValue: U): Promise<T | U>;
+    <U>(defaultValue: U): <T, E>(ra: ResultAsync<T, E>) => Promise<T | U>;
+};
+export {};

package/dist/async-fns.js

@@ -0,0 +1,42 @@
+// src/internal/dual.ts
+var dual = (arity, body) => {
+  const run = body;
+  const dispatcher = (...args) => args.length >= arity ? run(...args) : (self) => run(self, ...args);
+  return dispatcher;
+};
+
+// src/async-fns.ts
+var map = dual(2, (ra, fn) => ra.map(fn));
+var mapErr = dual(
+  2,
+  (ra, fn) => ra.mapErr(fn)
+);
+var bimap = dual(
+  3,
+  (ra, onOk, onErr) => ra.bimap(onOk, onErr)
+);
+var flatMap = dual(
+  2,
+  (ra, fn) => ra.flatMap(fn)
+);
+var recover = dual(
+  2,
+  (ra, fn) => ra.recover(fn)
+);
+var tap = dual(2, (ra, fn) => ra.tap(fn));
+var tapErr = dual(
+  2,
+  (ra, fn) => ra.tapErr(fn)
+);
+var match = dual(
+  3,
+  (ra, onOk, onErr) => ra.match(onOk, onErr)
+);
+var unwrapOr = dual(
+  2,
+  (ra, defaultValue) => ra.unwrapOr(defaultValue)
+);
+
+export { bimap, flatMap, map, mapErr, match, recover, tap, tapErr, unwrapOr };
+//# sourceMappingURL=async-fns.js.map
+//# sourceMappingURL=async-fns.js.map

package/dist/async-fns.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/dual.ts","../src/async-fns.ts"],"names":[],"mappings":";AA0CO,IAAM,IAAA,GAAO,CAAI,KAAA,EAAe,IAAA,KAA2C;AAMhF,EAAA,MAAM,GAAA,GAAM,IAAA;AACZ,EAAA,MAAM,UAAA,GAAa,CAAA,GAAI,IAAA,KACrB,IAAA,CAAK,UAAU,KAAA,GAAQ,GAAA,CAAI,GAAG,IAAI,IAAI,CAAC,IAAA,KAAkB,GAAA,CAAI,IAAA,EAAM,GAAG,IAAI,CAAA;AAG5E,EAAA,OAAO,UAAA;AACT,CAAA;;;ACbO,IAAM,GAAA,GAGT,KAAK,CAAA,EAAG,CAAU,IAAuB,EAAA,KAA2C,EAAA,CAAG,GAAA,CAAI,EAAE,CAAC;AAW3F,IAAM,MAAA,GAGT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CAAU,EAAA,EAAuB,EAAA,KAA2C,EAAA,CAAG,OAAO,EAAE;AAC1F;AAUO,IAAM,KAAA,GAUT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CACE,EAAA,EACA,IAAA,EACA,UACsB,EAAA,CAAG,KAAA,CAAM,MAAM,KAAK;AAC9C;AAWO,IAAM,OAAA,GAGT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CAAa,EAAA,EAAuB,EAAA,KAClC,EAAA,CAAG,QAAQ,EAAE;AACjB;AAWO,IAAM,OAAA,GAGT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CAAU,EAAA,EAAuB,EAAA,KAC/B,EAAA,CAAG,QAAQ,EAAE;AACjB;AAUO,IAAM,GAAA,GAGT,KAAK,CAAA,EAAG,CAAO,IAAuB,EAAA,KAA8C,EAAA,CAAG,GAAA,CAAI,EAAE,CAAC;AAU3F,IAAM,MAAA,GAGT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CAAO,EAAA,EAAuB,EAAA,KAA8C,EAAA,CAAG,OAAO,EAAE;AAC1F;AAWO,IAAM,KAAA,GAUT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CACE,EAAA,EACA,IAAA,EACA,UACqB,EAAA,CAAG,KAAA,CAAM,MAAM,KAAK;AAC7C;AAWO,IAAM,QAAA,GAGT,IAAA;AAAA,EACF,CAAA;AAAA,EACA,CAAU,EAAA,EAAuB,YAAA,KAAoC,EAAA,CAAG,SAAS,YAAY;AAC/F","file":"async-fns.js","sourcesContent":["/**\n * @onrails/result internal — owning module for the **dual-form idiom**.\n *\n * Every dual-form transform in this package (`map`, `flatMap`, `match`, …)\n * accepts either shape:\n *\n *   data-first: `map(result, fn)`  — full arity, runs immediately\n *   curried:    `map(fn)(result)`  — arity minus the leading `self`, returns\n *                                    a unary function awaiting the data\n *\n * {@link dual} is the single arity dispatcher those transforms derive from;\n * hand-rolled `args.length` checks are not allowed elsewhere.\n *\n * NOTE: a twin copy of this module lives at `packages/maybe/src/internal/dual.ts`\n * — keep the two in sync when editing.\n *\n * Internal only: not listed in package.json `exports` or tsup entries.\n */\n\n/**\n * Derive a dual-form (data-first / curried) function from a single\n * data-first `body`.\n *\n * When called with `args.length >= arity` the wrapper runs `body(...args)`\n * (data-first). With fewer arguments it returns `(self) => body(self, ...args)`\n * — the curried, data-last-`self` form used with `pipe`/`flow`.\n *\n * The public type is supplied entirely by the caller: annotate the exported\n * const with the exact overload set and let `F` be inferred from it.\n *\n * @example\n * ```ts\n * export const map: {\n *   <T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;\n *   <T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Result<U, E>;\n * } = dual(\n *   2,\n *   <T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> =>\n *     isOk(result) ? ok(fn(result.value)) : err(result.error),\n * );\n * ```\n */\nexport const dual = <F>(arity: number, body: (...args: never[]) => unknown): F => {\n  // `(...args: never[]) => unknown` is the top function type, so every typed\n  // body is assignable to the parameter — but it cannot be invoked with\n  // `unknown` arguments. Re-view it through the variadic shape the dispatcher\n  // actually forwards; the constraint is that `body` only ever receives the\n  // arguments the caller's overload annotation admitted.\n  const run = body as (...args: readonly unknown[]) => unknown;\n  const dispatcher = (...args: readonly unknown[]): unknown =>\n    args.length >= arity ? run(...args) : (self: unknown) => run(self, ...args);\n  // The caller's overload annotation on the exported const supplies the real\n  // public type; internally the dispatcher stays `unknown`-typed.\n  return dispatcher as F;\n};\n","/**\n * `@onrails/result/async` — data-last twins of the {@link ResultAsync} methods,\n * so an async railway composes with `pipe` / `flow` the same way a sync one does.\n *\n * `ResultAsync` is a class, so dot-chaining is always available and remains the\n * shortest form for a one-off chain. Reach for this module when you want the\n * sync side's other two syntaxes on the async carrier:\n *\n * ```ts\n * import * as RA from \"@onrails/result/async\";\n * import { pipe } from \"@onrails/result\";\n * import { flow } from \"@onrails/result/pipe\";\n *\n * // value-first pipe\n * pipe(loadUser(id), RA.flatMap(loadOrders), RA.map((os) => os.length));\n *\n * // reusable point-free pipeline — no value yet\n * const orderCount = flow(loadUser, RA.flatMap(loadOrders), RA.map((os) => os.length));\n * ```\n *\n * Every export mirrors one `ResultAsync` method exactly, in both forms:\n * data-first (`RA.map(ra, fn)`) and curried (`RA.map(fn)`). Import as a\n * namespace — the names deliberately match the sync core, and `test/parity.spec.ts`\n * enforces that the mirror stays complete.\n */\n\nimport type { ResultAsync } from \"./async.js\";\nimport { dual } from \"./internal/dual.js\";\nimport type { Result } from \"./types.js\";\n\n/** A step may hand back either carrier; the async one absorbs a sync `Result`. */\ntype Step<U, F> = ResultAsync<U, F> | Result<U, F>;\n\n/**\n * Transforms the `Ok` value, passing `Err` through unchanged.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), map((u) => u.name));   // ResultAsync<string, LoadError>\n * ```\n */\nexport const map: {\n  <T, U, E>(ra: ResultAsync<T, E>, fn: (value: T) => U): ResultAsync<U, E>;\n  <T, U>(fn: (value: T) => U): <E>(ra: ResultAsync<T, E>) => ResultAsync<U, E>;\n} = dual(2, <T, U, E>(ra: ResultAsync<T, E>, fn: (value: T) => U): ResultAsync<U, E> => ra.map(fn));\n\n/**\n * Transforms the `Err` value, passing `Ok` through unchanged — useful for\n * unifying heterogeneous failures into one app-level union.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), mapErr((e): AppError => ({ kind: \"load\", cause: e })));\n * ```\n */\nexport const mapErr: {\n  <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => F): ResultAsync<T, F>;\n  <E, F>(fn: (error: E) => F): <T>(ra: ResultAsync<T, E>) => ResultAsync<T, F>;\n} = dual(\n  2,\n  <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => F): ResultAsync<T, F> => ra.mapErr(fn),\n);\n\n/**\n * Transforms both tracks in one step. Exactly one of `onOk` / `onErr` runs.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), bimap(toDto, (e): AppError => ({ kind: \"load\", cause: e })));\n * ```\n */\nexport const bimap: {\n  <T, U, E, F>(\n    ra: ResultAsync<T, E>,\n    onOk: (value: T) => U,\n    onErr: (error: E) => F,\n  ): ResultAsync<U, F>;\n  <T, U, E, F>(\n    onOk: (value: T) => U,\n    onErr: (error: E) => F,\n  ): (ra: ResultAsync<T, E>) => ResultAsync<U, F>;\n} = dual(\n  3,\n  <T, U, E, F>(\n    ra: ResultAsync<T, E>,\n    onOk: (value: T) => U,\n    onErr: (error: E) => F,\n  ): ResultAsync<U, F> => ra.bimap(onOk, onErr),\n);\n\n/**\n * Canonical bind — chains a step returning a `ResultAsync` or a sync `Result`,\n * short-circuiting on `Err`. Error types accumulate (`E | F`).\n *\n * @example\n * ```ts\n * pipe(authenticate(req), flatMap((user) => loadProfile(user.id)));\n * ```\n */\nexport const flatMap: {\n  <T, U, E, F>(ra: ResultAsync<T, E>, fn: (value: T) => Step<U, F>): ResultAsync<U, E | F>;\n  <T, U, F>(fn: (value: T) => Step<U, F>): <E>(ra: ResultAsync<T, E>) => ResultAsync<U, E | F>;\n} = dual(\n  2,\n  <T, U, E, F>(ra: ResultAsync<T, E>, fn: (value: T) => Step<U, F>): ResultAsync<U, E | F> =>\n    ra.flatMap(fn),\n);\n\n/**\n * Error-track bind — runs `fn` only on `Err`, letting a failed workflow\n * recover to `Ok` or remap the failure.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), recover((e) => (e === \"notFound\" ? okAsync(guest) : errAsync(e))));\n * ```\n */\nexport const recover: {\n  <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => Step<T, F>): ResultAsync<T, F>;\n  <T, E, F>(fn: (error: E) => Step<T, F>): (ra: ResultAsync<T, E>) => ResultAsync<T, F>;\n} = dual(\n  2,\n  <T, E, F>(ra: ResultAsync<T, E>, fn: (error: E) => Step<T, F>): ResultAsync<T, F> =>\n    ra.recover(fn),\n);\n\n/**\n * Observes the `Ok` value for side effects without changing it.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), tap((u) => log.info({ msg: \"loaded\", id: u.id })));\n * ```\n */\nexport const tap: {\n  <T, E>(ra: ResultAsync<T, E>, fn: (value: T) => void): ResultAsync<T, E>;\n  <T>(fn: (value: T) => void): <E>(ra: ResultAsync<T, E>) => ResultAsync<T, E>;\n} = dual(2, <T, E>(ra: ResultAsync<T, E>, fn: (value: T) => void): ResultAsync<T, E> => ra.tap(fn));\n\n/**\n * Observes the `Err` value for side effects without changing it.\n *\n * @example\n * ```ts\n * pipe(loadUser(id), tapErr((e) => metrics.inc(\"user.load.fail\", { kind: e.kind })));\n * ```\n */\nexport const tapErr: {\n  <T, E>(ra: ResultAsync<T, E>, fn: (error: E) => void): ResultAsync<T, E>;\n  <E>(fn: (error: E) => void): <T>(ra: ResultAsync<T, E>) => ResultAsync<T, E>;\n} = dual(\n  2,\n  <T, E>(ra: ResultAsync<T, E>, fn: (error: E) => void): ResultAsync<T, E> => ra.tapErr(fn),\n);\n\n/**\n * Terminal collapse — folds both tracks into a single awaited value, settling\n * the carrier exactly once. Ends the pipeline, so it returns a plain `Promise`.\n *\n * @example\n * ```ts\n * const status = await pipe(save(row), match(() => 200, (e) => (e.kind === \"conflict\" ? 409 : 500)));\n * ```\n */\nexport const match: {\n  <T, E, U1, U2 = U1>(\n    ra: ResultAsync<T, E>,\n    onOk: (value: T) => U1,\n    onErr: (error: E) => U2,\n  ): Promise<U1 | U2>;\n  <T, E, U1, U2 = U1>(\n    onOk: (value: T) => U1,\n    onErr: (error: E) => U2,\n  ): (ra: ResultAsync<T, E>) => Promise<U1 | U2>;\n} = dual(\n  3,\n  <T, E, U1, U2>(\n    ra: ResultAsync<T, E>,\n    onOk: (value: T) => U1,\n    onErr: (error: E) => U2,\n  ): Promise<U1 | U2> => ra.match(onOk, onErr),\n);\n\n/**\n * Terminal — resolves to the `Ok` value, or `defaultValue` on `Err`. The\n * fallback may differ from `T`; the result widens to `T | U`.\n *\n * @example\n * ```ts\n * const profile = await pipe(loadProfile(id), unwrapOr(guestProfile));\n * ```\n */\nexport const unwrapOr: {\n  <T, E, U>(ra: ResultAsync<T, E>, defaultValue: U): Promise<T | U>;\n  <U>(defaultValue: U): <T, E>(ra: ResultAsync<T, E>) => Promise<T | U>;\n} = dual(\n  2,\n  <T, E, U>(ra: ResultAsync<T, E>, defaultValue: U): Promise<T | U> => ra.unwrapOr(defaultValue),\n);\n"]}

package/dist/async-lift.d.cts

@@ -0,0 +1,109 @@
+/**
+ * @onrails/result — THE lift module. Every "value → {@link ResultAsync}"
+ * entry point is defined exactly once, here: `okAsync`, `errAsync`,
+ * `fromPromise`, `fromSafePromise`, `fromResult`, `fromAsync`, `asyncAfter`,
+ * `tryAsync`.
+ */
+import { ResultAsync } from "./async.js";
+import type { InferErr, InferOk } from "./internal/infer.js";
+import type { Result, UnexpectedError } from "./types.js";
+/**
+ * Lifts a value into an `Ok` async result.
+ *
+ * @example
+ * ```ts
+ * const r = okAsync(42);   // ResultAsync<42, never> — literal locked
+ * ```
+ */
+export declare const okAsync: typeof ResultAsync.ok;
+/**
+ * Lifts a value into an `Err` async result.
+ *
+ * @example
+ * ```ts
+ * const r = errAsync({ kind: "not_found" as const });
+ * ```
+ */
+export 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) }),
+ * );
+ * ```
+ */
+export 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.
+ */
+export declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
+/**
+ * Lifts an already-settled sync {@link Result} into a {@link ResultAsync}, so
+ * it can be chained alongside async steps in a railway.
+ *
+ * @example
+ * ```ts
+ * const ra = fromResult(ok(1));            // ResultAsync<number, never>
+ * await fromResult(err(error)).resolve();  // Err(error)
+ * ```
+ */
+export declare const fromResult: typeof ResultAsync.fromResult;
+/**
+ * Bind a sync {@link Result} into an async step without widening defects.
+ * Dual-form: data-first for one-shots, data-last (curried) for `pipe`/`flow`.
+ *
+ * @example
+ * ```ts
+ * asyncAfter(result, (u) => tryAsync(db.insert(u), toErr)); // data-first
+ * asyncAfter((u) => tryAsync(db.insert(u), toErr));         // data-last
+ * ```
+ */
+export declare const asyncAfter: {
+    <T, U, E, F>(result: Result<T, E>, fn: (value: T) => ResultAsync<U, F>): ResultAsync<U, E | F>;
+    <T, U, F>(fn: (value: T) => ResultAsync<U, F>): <E>(result: Result<T, E>) => ResultAsync<U, E | F>;
+};
+type AnyResult = Result<unknown, unknown>;
+/**
+ * Lifts a `(...args) => Promise<Result<T, E>>` function (typical of interop or
+ * boundary code) into one returning `(...args) => ResultAsync<T, E>`. Expected
+ * `Err`s pass through; an unexpected promise rejection (a defect) is routed via
+ * `onDefect`, defaulting to {@link UnexpectedError} and widening the error union.
+ *
+ * @param fn - a function returning a promise that already yields a `Result`
+ * @param onDefect - maps an unexpected rejection to the `Err` channel
+ *
+ * @example
+ * ```ts
+ * const loadUser = fromAsync(
+ *   (id: string): Promise<Result<User, NotFound>> => api.getUser(id),
+ * );
+ * const ra = loadUser("u1");   // ResultAsync<User, NotFound | UnexpectedError>
+ * ```
+ */
+export declare const fromAsync: <A extends readonly unknown[], R extends AnyResult>(fn: (...args: A) => Promise<R>, onDefect?: (error: unknown) => InferErr<R> | UnexpectedError) => ((...args: A) => ResultAsync<InferOk<R>, InferErr<R> | UnexpectedError>);
+/**
+ * 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,
+ * }));
+ * ```
+ */
+export declare function tryAsync<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
+export declare function tryAsync<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
+export {};

package/dist/async-lift.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @onrails/result — THE lift module. Every "value → {@link ResultAsync}"
+ * entry point is defined exactly once, here: `okAsync`, `errAsync`,
+ * `fromPromise`, `fromSafePromise`, `fromResult`, `fromAsync`, `asyncAfter`,
+ * `tryAsync`.
+ */
+import { ResultAsync } from "./async.js";
+import type { InferErr, InferOk } from "./internal/infer.js";
+import type { Result, UnexpectedError } from "./types.js";
+/**
+ * Lifts a value into an `Ok` async result.
+ *
+ * @example
+ * ```ts
+ * const r = okAsync(42);   // ResultAsync<42, never> — literal locked
+ * ```
+ */
+export declare const okAsync: typeof ResultAsync.ok;
+/**
+ * Lifts a value into an `Err` async result.
+ *
+ * @example
+ * ```ts
+ * const r = errAsync({ kind: "not_found" as const });
+ * ```
+ */
+export 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) }),
+ * );
+ * ```
+ */
+export 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.
+ */
+export declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
+/**
+ * Lifts an already-settled sync {@link Result} into a {@link ResultAsync}, so
+ * it can be chained alongside async steps in a railway.
+ *
+ * @example
+ * ```ts
+ * const ra = fromResult(ok(1));            // ResultAsync<number, never>
+ * await fromResult(err(error)).resolve();  // Err(error)
+ * ```
+ */
+export declare const fromResult: typeof ResultAsync.fromResult;
+/**
+ * Bind a sync {@link Result} into an async step without widening defects.
+ * Dual-form: data-first for one-shots, data-last (curried) for `pipe`/`flow`.
+ *
+ * @example
+ * ```ts
+ * asyncAfter(result, (u) => tryAsync(db.insert(u), toErr)); // data-first
+ * asyncAfter((u) => tryAsync(db.insert(u), toErr));         // data-last
+ * ```
+ */
+export declare const asyncAfter: {
+    <T, U, E, F>(result: Result<T, E>, fn: (value: T) => ResultAsync<U, F>): ResultAsync<U, E | F>;
+    <T, U, F>(fn: (value: T) => ResultAsync<U, F>): <E>(result: Result<T, E>) => ResultAsync<U, E | F>;
+};
+type AnyResult = Result<unknown, unknown>;
+/**
+ * Lifts a `(...args) => Promise<Result<T, E>>` function (typical of interop or
+ * boundary code) into one returning `(...args) => ResultAsync<T, E>`. Expected
+ * `Err`s pass through; an unexpected promise rejection (a defect) is routed via
+ * `onDefect`, defaulting to {@link UnexpectedError} and widening the error union.
+ *
+ * @param fn - a function returning a promise that already yields a `Result`
+ * @param onDefect - maps an unexpected rejection to the `Err` channel
+ *
+ * @example
+ * ```ts
+ * const loadUser = fromAsync(
+ *   (id: string): Promise<Result<User, NotFound>> => api.getUser(id),
+ * );
+ * const ra = loadUser("u1");   // ResultAsync<User, NotFound | UnexpectedError>
+ * ```
+ */
+export declare const fromAsync: <A extends readonly unknown[], R extends AnyResult>(fn: (...args: A) => Promise<R>, onDefect?: (error: unknown) => InferErr<R> | UnexpectedError) => ((...args: A) => ResultAsync<InferOk<R>, InferErr<R> | UnexpectedError>);
+/**
+ * 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,
+ * }));
+ * ```
+ */
+export declare function tryAsync<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
+export declare function tryAsync<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
+export {};

package/dist/{async-Ci6WSL5-.d.ts → async.d.cts}

@@ -1,56 +1,25 @@
-import { R as Result, U as UnexpectedError } from './types-BQ9vv0nD.js';
-
-/**
- * @onrails/result internal — the single payload-extraction pair.
- *
- * `InferOk` / `InferErr` pull the success/error type out of a {@link Result}
- * (tagged union) or a {@link ResultAsync} (class carrier), resolving to
- * `never` for anything else. Every module that needs to extract a payload
- * type imports from here; do not redeclare local copies.
- *
- * Internal only: not listed in package.json `exports` or tsup entries.
- * The package index re-exports the pair under the same names.
- */
-
-/**
- * Extracts the `Ok` value type from a {@link Result} or {@link ResultAsync},
- * resolving to `never` for any other type.
- *
- * @example
- * ```ts
- * type T = InferOk<Result<number, string>>;        // number
- * type U = InferOk<ResultAsync<User, AppError>>;    // User
- * ```
- */
-type InferOk<R> = R extends {
-    _tag: "Ok";
-    readonly value: infer T;
-} ? T : R extends ResultAsync<infer T, unknown> ? T : never;
+import type { InferErr, InferOk } from "./internal/infer.js";
+import type { Payload } from "./internal/payload.js";
+import type { Result } from "./types.js";
+import { UnexpectedError } from "./types.js";
+type PromiseFactory<T, E> = () => Promise<Result<T, E>>;
+type AnyResultAsync = ResultAsync<unknown, unknown>;
 /**
- * Extracts the `Err` error type from a {@link Result} or {@link ResultAsync},
- * resolving to `never` for any other type. Mirror of {@link InferOk}.
- *
- * @example
- * ```ts
- * type E = InferErr<Result<number, string>>;        // string
- * type F = InferErr<ResultAsync<User, AppError>>;    // AppError
- * ```
+ * Mirrors the sync `CombineTuple` in `./collections.ts`: the element check
+ * lives in the RETURN type, never in the parameter constraint. A
+ * `ResultAsync<unknown, unknown>` constraint contextually types the arguments
+ * and widens `okAsync(1)`'s defaulted `E = never` to `unknown`, so call sites
+ * would need hoisted intermediates to keep their error union.
  */
-type InferErr<R> = R extends {
-    _tag: "Err";
-    readonly error: infer E;
-} ? E : R extends ResultAsync<unknown, infer E> ? E : never;
-
-type PromiseFactory<T, E> = () => Promise<Result<T, E>>;
-type CombineTupleAsync<R extends readonly ResultAsync<unknown, unknown>[]> = ResultAsync<{
+type CombineTupleAsync<R extends readonly unknown[]> = R[number] extends AnyResultAsync ? ResultAsync<{
     [K in keyof R]: InferOk<R[K]>;
-}, {
-    [K in keyof R]: InferErr<R[K]>;
-}[number]>;
+}, InferErr<R[number]>> : never;
+/** Mirrors `TupleGuard` in `./collections.ts` — see the note there. */
+type AsyncTupleGuard<R extends readonly unknown[]> = R[number] extends AnyResultAsync ? [] : [error: "expected an array of ResultAsync values"];
 /**
  * Async railway carrier. Wraps a deferred `Promise<Result<T, E>>` and exposes
- * the same dual-track transforms as the sync {@link Result} — `map`, `flatMap`,
- * `recover`, `tap`, `match`. The public API never surfaces `Promise<Result<…>>`
+ * the same dual-track transforms as the sync {@link Result} — `map`, `mapErr`,
+ * `bimap`, `flatMap`, `recover`, `tap`, `match`. The public API never surfaces `Promise<Result<…>>`
  * directly: `await` the instance (it is thenable) or call {@link resolve} /
  * {@link match} to settle it.
  *
@@ -69,7 +38,7 @@ type CombineTupleAsync<R extends readonly ResultAsync<unknown, unknown>[]> = Res
  * const r = await user;          // Result<Profile, AppError>
  * ```
  */
-declare class ResultAsync<T, E> {
+export declare class ResultAsync<T, E> {
     protected readonly run: PromiseFactory<T, E>;
     private promise;
     protected constructor(run: PromiseFactory<T, E>);
@@ -129,13 +98,15 @@ declare class ResultAsync<T, E> {
      * const r = ResultAsync.ok(42);   // ResultAsync<number, never>
      * ```
      */
-    static ok<T>(value: T): ResultAsync<T, never>;
+    static ok<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static ok<const T>(value: T): ResultAsync<T, never>;
     static ok<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Fantasy Land `pure` — alias of {@link ResultAsync.ok}. One lift name
      * shared across the trio (`of` / `Maybe.of` / `ResultAsync.of`).
      */
-    static of<T>(value: T): ResultAsync<T, never>;
+    static of<const T extends Payload[]>(value: T): ResultAsync<T, never>;
+    static of<const T>(value: T): ResultAsync<T, never>;
     static of<T, E>(value: T): ResultAsync<T, E>;
     /**
      * Lifts an error into an `Err` async result.
@@ -145,7 +116,9 @@ declare class ResultAsync<T, E> {
      * const r = ResultAsync.err({ kind: "not_found" as const });
      * ```
      */
-    static err<T = never, E = unknown>(error: E): ResultAsync<T, E>;
+    static err<const E extends Payload[]>(error: E): ResultAsync<never, E>;
+    static err<const E>(error: E): ResultAsync<never, E>;
+    static err<T, E>(error: E): ResultAsync<T, E>;
     /**
      * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a
      * {@link ResultAsync}. A thrown defect is routed through `onDefect`,
@@ -179,7 +152,7 @@ declare class ResultAsync<T, E> {
      *
      * @example
      * ```ts
-     * const combined = ResultAsync.combineTuple([loadCfg(), loadCatalog()] as const);
+     * const combined = ResultAsync.combineTuple([loadCfg(), loadCatalog()]);
      * // ResultAsync<readonly [Cfg, Catalog], CfgError | CatalogError>
      * const r = await combined;
      * if (isOk(r)) {
@@ -187,7 +160,7 @@ declare class ResultAsync<T, E> {
      * }
      * ```
      */
-    static combineTuple<const R extends readonly ResultAsync<unknown, unknown>[]>(results: R): CombineTupleAsync<R>;
+    static combineTuple<const R extends readonly unknown[]>(results: R, ..._guard: AsyncTupleGuard<R>): CombineTupleAsync<R>;
     /**
      * Like {@link combineTuple}, but starts every branch before awaiting (wall-clock
      * parallel for independent IO). On failure, returns the first `Err` in input order.
@@ -198,10 +171,10 @@ declare class ResultAsync<T, E> {
      * const combined = ResultAsync.combineTupleParallel([
      *   loadProfile(id),
      *   loadMetrics(id),
-     * ] as const);
+     * ]);
      * ```
      */
-    static combineTupleParallel<const R extends readonly ResultAsync<unknown, unknown>[]>(results: R): CombineTupleAsync<R>;
+    static combineTupleParallel<const R extends readonly unknown[]>(results: R, ..._guard: AsyncTupleGuard<R>): CombineTupleAsync<R>;
     /**
      * Transforms the `Ok` value, passing `Err` through unchanged.
      *
@@ -221,6 +194,16 @@ declare class ResultAsync<T, E> {
      * ```
      */
     mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
+    /**
+     * Transforms both tracks in one step — the async mirror of the sync
+     * `bimap`. Exactly one of `onOk` / `onErr` runs.
+     *
+     * @example
+     * ```ts
+     * load(id).bimap(toDto, (e): AppError => ({ kind: "load", cause: e }));
+     * ```
+     */
+    bimap<U, F>(onOk: (value: T) => U, onErr: (error: E) => F): ResultAsync<U, F>;
     /**
      * Canonical bind — chains a step that itself returns a `ResultAsync` or sync
      * `Result`, short-circuiting on `Err`. Error types accumulate (`E | F`).
@@ -328,5 +311,9 @@ declare class ResultAsync<T, E> {
      */
     then<R1 = Result<T, E>, R2 = never>(onfulfilled?: ((value: Result<T, E>) => R1 | PromiseLike<R1>) | undefined | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | undefined | null): Promise<R1 | R2>;
 }
-
-export { type InferErr as I, ResultAsync as R, type InferOk as a };
+export {};
+/**
+ * The free-function lift helpers (`okAsync`, `errAsync`, `fromPromise`,
+ * `fromSafePromise`, `fromResult`, `fromAsync`, `asyncAfter`, `tryAsync`)
+ * live in `./async-lift.ts` and are re-exported from the package index.
+ */