@onrails/result 0.3.1 → 0.4.1

package/DESIGN.md

@@ -21,12 +21,13 @@ type Result<T, E> =
 
 - `flatMap` is the canonical bind and widens error types (`E | F`).
 - `match` is the canonical terminal collapse — positional, dual-form.
-- For files that also import `match` from `ts-pattern`, dissolve the collision with a namespace import (`import * as R from "@onrails/result"` → `R.match`).
+- House style: `import * as R from "@onrails/result"`. `R.` autocompletes the full surface (data-first's one ergonomic debit) and sidesteps name collisions — most commonly `match` from `ts-pattern` or `@onrails/pattern` (`R.match` next to `P.matchTag`).
 - `of` is the Fantasy Land `pure` alias of `ok`, mirrored by `ResultAsync.of` (`Maybe.of` follows in RFC 0002); `show(r)` prints `Ok(…)` / `Err(…)` for logs (fluent's `toString` delegates to it).
 - `tap` / `tapErr` observe a track without changing the carried value.
 - `recover` binds the error track and may return a failed workflow back to success.
 - `pipe(value, ...fns)` is the variadic value-first pipe (up to 9 steps); `flow(...fns)` is the variadic point-free composition in `@onrails/result/pipe`.
-- Optional dot-chaining via `fluent(r)` / `fluentAsync(ra)` in `@onrails/result/fluent`. Mirrors every instance-appropriate core transform; `test/parity.spec.ts` enforces the mirror (both directions) across core, fluent, and the neverthrow compat shim.
+- Optional dot-chaining via `fluent(r)` in `@onrails/result/fluent`. Mirrors every instance-appropriate core transform; `test/parity.spec.ts` enforces the mirror (both directions) across core, fluent, and the neverthrow compat shim. `ResultAsync` is already fluent (its methods return `ResultAsync`) — no `fluentAsync` wrapper; wrapping it would just be a one-line delegate to itself.
+- The fluent wrapper stays local: `fluent(r)` opens and a terminal (`toResult`/`toString`/`match`/`unwrapOr`) closes within one expression — it's a closure over data, not data, so it must never be a return type, an exported binding, a stored field, or an argument to a serialize/`postMessage`/cache call. `@onrails/eslint-plugin` and `@onrails/biome-plugin` enforce this via `fluent-stays-local` (RFC 0002 §9).
 
 ## Sync / async interop
 
@@ -39,7 +40,7 @@ Two distinct lift paths:
 
 ```ts
 asyncAfter(
-  trySync(() => Schema.parse(input), toError)(),
+  trySync(() => Schema.parse(input), toError),
   (value) => tryAsync(save(value)),
 );
 ```

package/README.md

@@ -11,9 +11,13 @@ bun add @onrails/result
 ## Quick start (value-first — best inference)
 
 ```ts
-import { err, flatMap, match, ok, trySync } from "@onrails/result";
+import { err, flatMap, fromThrowable, match, ok, trySync } from "@onrails/result";
 
-const parse = trySync(
+// Run it now — the sync mirror of `tryAsync`.
+const parsed = trySync(() => JSON.parse(raw));           // Result<unknown, Error>
+
+// Or lift the throwing function once and reuse it.
+const parse = fromThrowable(
   (raw: string) => JSON.parse(raw),
   (e) => ({ kind: "parse" as const, message: String(e) }),
 );
@@ -21,24 +25,56 @@ const parse = trySync(
 const pipeline = flatMap(parse('{"v":1}'), (data) => ok(data.v));
 ```
 
-Every transform is dual-form: data-first `flatMap(r, fn)` (best inference) or curried `flatMap(fn)(r)` for `pipe`/`flow`. Long chains: `fluent()` from `@onrails/result/fluent`.
-
 For worked examples of multi-step pipelines, parser builders, validator ladders, and parallel sub-workflows see [RECIPES.md](./RECIPES.md).
 
-## When to use what
+## The default path
+
+Two forms cover almost everything. Learn these; treat the rest of this README as reference for the cases they do not fit.
+
+| Sync  | data-first module functions — `flatMap(r, fn)`, `map`, `match` |
+| ----- | -------------------------------------------------------------- |
+| Async | `ResultAsync` dot-chaining — `ra.flatMap(fn).map(fn).match(…)`  |
+
+```ts
+// sync
+const name = match(
+  flatMap(parseConfig(raw), (cfg) => (cfg.name ? ok(cfg.name) : err({ kind: "missing" }))),
+  (n) => n,
+  (e) => `<${e.kind}>`,
+);
+
+// async — `.flatMap` also accepts a plain sync `Result`, so no manual lifting
+const count = await loadUser(id).flatMap(loadOrders).map((os) => os.length).unwrapOr(0);
+```
+
+Data-first gives the best inference, and `ResultAsync.flatMap` takes either carrier, so mixed sync/async chains need no lift step.
+
+## Other syntaxes (opt-in)
+
+Same operations, different shape. Reach for one only when it removes real nesting or naming pain — none of them unlock behavior the default path lacks.
 
 | Shape                              | Reach for                                                            |
 | ---------------------------------- | -------------------------------------------------------------------- |
-| One or two sync steps              | `flatMapResult`, `mapResult`, `match`                                |
-| One or two async steps             | `ResultAsync.flatMap`, `asyncAfter`                                  |
 | Long sync chain, value-first        | `pipe(r, map(...), flatMap(...), ...)`                              |
+| Long async chain, value-first      | `pipe(ra, RA.map(...), RA.flatMap(...))` from `@onrails/result/async` |
 | Long sync chain, dot-style preferred | `fluent(r)` from `@onrails/result/fluent`                          |
 | Reusable composed function          | `flow(...)` from `@onrails/result/pipe`                             |
 | Several named sync/async steps     | `Railway.*` builder from `@onrails/result/railway`                   |
 | Linear sync with early-return feel | `tryGen` + `$` from `@onrails/result/try-gen`                        |
+
+Every transform is dual-form: data-first `flatMap(r, fn)` or curried `flatMap(fn)(r)` for `pipe` / `flow`.
+
+## Boundaries and collections
+
+These are not alternative syntaxes — they are the entry points into the railway.
+
+| Shape                              | Reach for                                                            |
+| ---------------------------------- | -------------------------------------------------------------------- |
 | Independent validations, accumulated failures | `validateAll` / `validateTuple` from `@onrails/result` |
 | Sync → async lift, keep error type | `fromResult`, `asyncAfter` (do **not** use `fromAsync` here)         |
 | `Promise<Result<…>>` boundary lift | `fromAsync` / `tryAsync`                                             |
+| Throwing sync call, run it now     | `trySync(() => f())` — mirrors `tryAsync(promise)`                   |
+| Throwing sync function, reusable   | `fromThrowable(f, onThrow)` — neverthrow's `Result.fromThrowable`    |
 
 Rule of thumb: pick the smallest tool that removes nesting. Reach for `Railway` only when named context replaces positional tuple plumbing.
 
@@ -60,7 +96,7 @@ Use `asyncAfter` for the common "validate synchronously, then run async IO" shap
 import { asyncAfter, tryAsync, trySync } from "@onrails/result";
 
 return asyncAfter(
-  trySync(() => ArtifactSchema.parse(artifact), toError)(),
+  trySync(() => ArtifactSchema.parse(artifact), toError),
   (validated) =>
     tryAsync(
       getDb()
@@ -94,6 +130,36 @@ type BotError =
 
 Helpers: `@onrails/result/extra` — `hasKind`, `mapErrKind`, `declareErrors`, `UnionErrors`, `AccumulateErrors`.
 
+### Literals stay narrow
+
+`ok` and `err` lock an inline literal instead of widening it, so a tagged error keeps its `kind` without `as const`:
+
+```ts
+err({ kind: "not_found", id });   // Result<never, { readonly kind: "not_found"; readonly id: string }>
+ok("ready");                      // Result<"ready", never>
+```
+
+Locking is inference-only — a value that already has a type is left alone (`ok(name)` where `name: string` is still `Result<string, never>`), and an array literal payload stays assignable to a mutable array (`ok([1, 2])` satisfies `Result<number[], E>`).
+
+Pass **both** type arguments to opt out. Generic code that has to produce `Result<T, E>` for an unresolved `T` needs that form:
+
+```ts
+const lift = <T, E>(value: T): Result<T, E> => ok<T, E>(value);
+```
+
+### Naming the error channel
+
+One explicit type argument on `err` names the **error**:
+
+```ts
+type AppError = { kind: "parse" } | { kind: "io" };
+
+err<AppError>({ kind: "io" });          // Result<never, AppError>
+err<number, AppError>({ kind: "io" });  // Result<number, AppError> — neverthrow's T, E order
+```
+
+The two-argument form keeps neverthrow's order. `errAsync` / `ResultAsync.err` behave the same way.
+
 ## Async interop — `fromAsync`
 
 Lift `async` handlers that return `Result` without leaking `Promise<Result<…>>`:
@@ -132,6 +198,20 @@ import { match } from "ts-pattern";
 R.match(result, onOk, onErr);
 ```
 
+For an object-form, self-labelling fold, use `matchTag` from [`@onrails/pattern`](../pattern/README.md) — it dispatches on `_tag` and requires one branch per tag, so the branches read as names instead of argument positions:
+
+```ts
+import { matchTag } from "@onrails/pattern";
+
+const label = (r: Result<number, string>) =>
+  matchTag(r, {
+    Ok: (v) => `ok:${v.value}`,    // v: Ok<number>  — the member, not the payload
+    Err: (e) => `err:${e.error}`,  // e: Err<string>
+  });
+```
+
+Note the difference: `match` hands each branch the *payload*, `matchTag` hands it the narrowed *member*.
+
 `unwrapOk` and `unwrapErr` are test/assertion helpers. Prefer `match`, `isOk`, or `isErr` in production control flow.
 
 ```ts
@@ -163,7 +243,7 @@ import { ResultAsync } from "@onrails/result";
 const combined = ResultAsync.combineTuple([
   loadSettings(),
   loadModelCatalog(),
-] as const);
+]);
 
 const dto = combined.map(([settings, catalog]) =>
   buildDto(settings, catalog),
@@ -172,6 +252,25 @@ const dto = combined.map(([settings, catalog]) =>
 
 When TS only infers the first error in a generator-style flow, use `declareErrors<E1 | E2>()` from `/extra`.
 
+## Async pipelines — `@onrails/result/async`
+
+`ResultAsync` is a class, so dot-chaining is always available and stays the shortest form for a one-off chain. When you want the sync side's *other* two syntaxes on the async carrier — value-first `pipe`, or point-free `flow` — import the data-last twins as a namespace:
+
+```ts
+import * as RA from "@onrails/result/async";
+import { pipe } from "@onrails/result";
+import { flow } from "@onrails/result/pipe";
+
+// value-first
+pipe(loadUser(id), RA.flatMap(loadOrders), RA.map((os) => os.length));
+// ResultAsync<number, NotFound | DbError>
+
+// reusable point-free pipeline — no value yet
+const orderCount = flow(loadUser, RA.flatMap(loadOrders), RA.map((os) => os.length));
+```
+
+Every `ResultAsync` method has a twin here — `map`, `mapErr`, `bimap`, `flatMap`, `recover`, `tap`, `tapErr`, `match`, `unwrapOr` — each in both data-first and curried form. The terminals (`match`, `unwrapOr`) resolve to a plain `Promise`, ending the pipeline.
+
 ## `Railway` — named service workflows
 
 Use `Railway` from `@onrails/result/railway` when a service workflow has several named sync/async steps and would otherwise need manual context-carrying objects:
@@ -195,7 +294,15 @@ const summary = Railway.fromSync("profileId", () => ProfileIdSchema.parse(id), t
 
 Sync-only workflows return `Result<T, E>`. The first `fromPromise`, `fromAsync`, or `parallel` step upgrades the output to `ResultAsync<T, E>`.
 
-Use lower-level helpers (`asyncAfter`, `fromResult`, `flatMapResult`) for one or two steps where a builder would add ceremony.
+Step keys must be unique. Reusing one is a compile error naming the offending key — previously it overwrote at runtime while the type silently collapsed to `never`:
+
+```ts
+Railway.empty()
+  .derive("x", () => 1)
+  .derive("x", () => "two");   // ✗ key "x" already exists in the workflow context
+```
+
+Use lower-level helpers (`asyncAfter`, `fromResult`, `flatMap`) for one or two steps where a builder would add ceremony.
 
 To share steps across workflows, extract plain functions of the context and plug them in via `.fromResult` / `.fromAsync`:
 
@@ -211,6 +318,8 @@ const summary = Railway.fromSync("profileId", () => ProfileIdSchema.parse(id), t
 
 ## Pipe
 
+`pipe` and `flow` both live in `@onrails/result/pipe`; `pipe` is also re-exported from the package root.
+
 ```ts
 import { pipe } from "@onrails/result";
 import { flow } from "@onrails/result/pipe";
@@ -233,10 +342,53 @@ const parseUserName = flow(
 parseUserName(raw);
 ```
 
+Both cap at **12 steps**. That cap is deliberate: a single recursive variadic signature would remove it, but it cannot give each step a contextual type from the previous step's output, so lambda parameters degrade to `unknown` (`map((cfg) => cfg.user)` stops inferring). Longer chains nest — `pipe(pipe(v, ...), ...)` — or factor a segment into a named `flow`.
+
 ## ESLint
 
 `@onrails/eslint-plugin` — warns on `Promise<Result<…>>` and `_unsafeUnwrap*`.
 
+## Breaking changes
+
+### `ok` / `err` lock inline literals
+
+Inline literals no longer widen: `ok("a")` is `Result<"a", never>` and `err({ kind: "io" })` carries `{ readonly kind: "io" }`. Annotated values are unaffected. Two call shapes need a change:
+
+```ts
+// generic code — pass both type arguments to opt out of locking
+const lift = <T, E>(value: T): Result<T, E> => ok<T, E>(value);
+
+// a type-level assertion that expected the widened type
+expectType<TypeEqual<typeof ok(1), Result<number, never>>>(true);  // before
+expectType<TypeEqual<typeof value, Result<1, never>>>(true);       // after
+```
+
+### One type argument on `err` now names the error
+
+`err<AppError>(e)` used to set the *`Ok`* parameter and leave the error at `unknown`. It now returns `Result<never, AppError>`. Call sites that meant the old reading fail to compile; use `err<AppError, unknown>(e)` to restore it, or drop the argument and let inference lock the literal. The compat shim (`@onrails/result/compat/neverthrow`) is unchanged.
+
+### `trySync` is now eager; the lazy form is `fromThrowable`
+
+`trySync` used to lift a throwing *function* and return a wrapper, while
+`tryAsync` took a *value* and ran immediately — same prefix, opposite contract.
+The two now agree, and the lifting form takes neverthrow's own name.
+
+```ts
+// before
+const parse = trySync(JSON.parse, toErr);
+parse(raw);
+trySync(() => Schema.parse(input), toErr)();   // note the trailing ()
+
+// after
+const parse = fromThrowable(JSON.parse, toErr);
+parse(raw);
+trySync(() => Schema.parse(input), toErr);     // runs now, returns Result
+trySync(() => Schema.parse(input));            // Result<T, Error> — onThrow optional
+```
+
+Mechanical migration: rename `trySync` → `fromThrowable` everywhere, then drop
+the trailing `()` on any call site that immediately invoked the wrapper.
+
 ## Migration from neverthrow
 
 See [@onrails/codemod](../codemod/README.md) for the automated codemod, and the **Compat surface** notes below.
@@ -250,7 +402,7 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 - `Result` / `ResultAsync` are class-shaped (`CompatResult` / `CompatResultAsync`).
 - `await ra` resolves to a `CompatResult<T, E>` (thenable), so `.isOk()`, `.value`, `.error`, `.match()`, `.unwrapOr()` all work without an extra `.resolve()` call.
 - `andThen` / `chain` / `flatMap` / `orElse` accept any of `CompatResultAsync` / `ResultAsync` / `CompatResult` / tagged `Result` returns and union the error type.
-- Supported: `andThen`, `asyncAndThen`, `chain`, `flatMap`, `flatMapResult`, `andThenResult`, `map`, `mapErr`, `orElse`, `match`, `unwrapOr`, `isOk`, `isErr`, `andTee`, `orTee`, `Result.combine`, `Result.fromThrowable`, `ResultAsync.combine`, `ResultAsync.fromPromise`, `ResultAsync.fromSafePromise`, `ResultAsync.fromThrowable`, `_unsafeUnwrap` / `_unsafeUnwrapErr`.
+- Supported: `andThen`, `asyncAndThen`, `chain`, `flatMap`, `map`, `mapErr`, `orElse`, `match`, `unwrapOr`, `isOk`, `isErr`, `andTee`, `orTee`, `Result.combine`, `Result.fromThrowable`, `ResultAsync.combine`, `ResultAsync.fromPromise`, `ResultAsync.fromSafePromise`, `ResultAsync.fromThrowable`, `_unsafeUnwrap` / `_unsafeUnwrapErr`.
 - Treat the compat surface as a migration step, not the destination — once a package migrates, switch its imports to `@onrails/result` and `@onrails/result/fluent`.
 
 ## Subpaths
@@ -258,9 +410,10 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 | Path | Contents |
 |------|----------|
 | `@onrails/result` | Core + interop exports |
-| `@onrails/result/fluent` | `fluent()`, `fluentAsync()` |
+| `@onrails/result/async` | Data-last twins of the `ResultAsync` methods (for `pipe` / `flow`) |
+| `@onrails/result/fluent` | `fluent()` |
 | `@onrails/result/extra` | Error-type utilities |
-| `@onrails/result/pipe` | `flow` (variadic point-free composition) |
+| `@onrails/result/pipe` | `pipe` (value-first) and `flow` (point-free), up to 12 steps |
 | `@onrails/result/railway` | `Railway` named-context workflow builder |
 | `@onrails/result/try-gen` | `tryGen`, `yieldResult`, `$` |
 | `@onrails/result/compat/neverthrow` | Migration shim |

package/RECIPES.md

@@ -81,15 +81,17 @@ Define a parser factory once, instantiate per schema.
 
 ```ts
 import { flow } from "@onrails/result/pipe";
-import { flatMap, trySync, type Result } from "@onrails/result";
+import { flatMap, fromThrowable, type Result } from "@onrails/result";
 
 type ParseError = { kind: "parse"; message: string };
 type SchemaError = { kind: "schema"; field: string };
 
 const parseJsonWith = <T>(schema: { parse: (x: unknown) => T }) =>
   flow(
-    trySync(JSON.parse, (e): ParseError => ({ kind: "parse", message: String(e) })),
-    flatMap(trySync(schema.parse, (e): SchemaError => ({ kind: "schema", field: String(e) }))),
+    fromThrowable(JSON.parse, (e): ParseError => ({ kind: "parse", message: String(e) })),
+    flatMap(
+      fromThrowable(schema.parse, (e): SchemaError => ({ kind: "schema", field: String(e) })),
+    ),
   );
 
 const parseUser = parseJsonWith(UserSchema);
@@ -208,7 +210,7 @@ const buildSummary = (userId: string) =>
       loadProfile(userId),                                                // ResultAsync<Profile, ProfileError>
       loadRecentMetrics(userId),                                          // ResultAsync<Metrics, MetricsError>
       loadFeatureFlags(userId),                                           // ResultAsync<Flags,   never>
-    ] as const),
+    ]),
     (combined) =>
       combined.map(([profile, metrics, flags]) => ({
         userId,

package/dist/async-fns.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+// 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)
+);
+
+exports.bimap = bimap;
+exports.flatMap = flatMap;
+exports.map = map;
+exports.mapErr = mapErr;
+exports.match = match;
+exports.recover = recover;
+exports.tap = tap;
+exports.tapErr = tapErr;
+exports.unwrapOr = unwrapOr;
+//# sourceMappingURL=async-fns.cjs.map
+//# sourceMappingURL=async-fns.cjs.map

package/dist/async-fns.cjs.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.cjs","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-fns.d.cts

@@ -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 {};