@onrails/result 0.1.2 → 0.1.3

package/DESIGN.md

@@ -96,7 +96,6 @@ Use `flatMap` for dependent checks where later checks need earlier successful va
 | `@onrails/result/fluent` | Dot-style chains |
 | `@onrails/result/extra` | Error-type utilities |
 | `@onrails/result/interop` | Promise/ResultAsync boundary helpers |
-| `@onrails/result/mcp` | MCP / HTTP boundary helpers |
 | `@onrails/result/pipe` | Variadic `flow` for point-free composition |
 | `@onrails/result/railway` | Named workflow builder and reusable step factories |
 | `@onrails/result/try-gen` | Sync generator-style `Result` sugar |

package/README.md

@@ -132,13 +132,18 @@ else console.error(r.error);
 
 ## Match and unwrap helpers
 
-`matchResult` is an alias for `match` for files that also import `match` from `ts-pattern`:
+`match` is the canonical positional fold. If a file imports `match` from `@onrails/pattern` or `ts-pattern`, resolve the collision by using namespace imports:
 
 ```ts
-import { matchResult } from "@onrails/result";
+import * as R from "@onrails/result";
 import { match } from "ts-pattern";
+
+R.match(result, onOk, onErr);
 ```
 
+> [!NOTE]
+> `matchResult` is deprecated and will be removed in the next major version.
+
 `unwrapOk` and `unwrapErr` are test/assertion helpers. Prefer `match`, `isOk`, or `isErr` in production control flow.
 
 ```ts
@@ -147,17 +152,6 @@ import { unwrapOk } from "@onrails/result";
 expect(unwrapOk(parseConfig(raw))).toEqual(expected);
 ```
 
-## MCP / HTTP boundaries
-
-```ts
-import { toToolResponseAsync, unwrapFetchResultAsync } from "@onrails/result/mcp";
-
-const ra = unwrapFetchResultAsync(
-  client.GET("/tokens/{id}"),
-  ({ error, response }) => new PrintrApiError(response.status, detail),
-);
-return toToolResponseAsync(ra);
-```
 
 ## `tryGen` — sync `?`
 
@@ -173,12 +167,12 @@ const out = tryGen(() => {
 });
 ```
 
-Use `sequenceTupleAsync` (or `parallelTupleAsync` when branches should overlap) when combining heterogeneous async results and destructuring the result:
+Use `ResultAsync.combineTuple` (or `parallelTupleAsync` when branches should overlap) when combining heterogeneous async results and destructuring the result:
 
 ```ts
-import { sequenceTupleAsync } from "@onrails/result";
+import { ResultAsync } from "@onrails/result";
 
-const combined = sequenceTupleAsync([
+const combined = ResultAsync.combineTuple([
   loadSettings(),
   loadModelCatalog(),
 ] as const);
@@ -314,7 +308,6 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 | `@onrails/result/fluent` | `fluent()`, `fluentAsync()` |
 | `@onrails/result/extra` | Error-type utilities |
 | `@onrails/result/interop` | `fromAsync`, `fromResult`, `asyncAfter` |
-| `@onrails/result/mcp` | MCP / openapi-fetch helpers |
 | `@onrails/result/pipe` | `flow` (variadic point-free composition) |
 | `@onrails/result/railway` | `Railway`, `railway`, named workflow helpers |
 | `@onrails/result/try-gen` | `tryGen`, `yieldResult`, `$` |

package/RECIPES.md

@@ -11,6 +11,68 @@ map(fn)(result);   // curried, data-last — feeds `pipe(...)` and `flow(...)`
 
 See [README.md](./README.md) for the API reference and decision tree.
 
+## Composition Guidelines (The Four Tiers)
+
+To keep codebases readable and consistent, follow the four-tier decision guideline when choosing how to compose operations. Use the simplest pattern that fits your workflow:
+
+| Tier | Use Case | Recommended Pattern |
+| ---- | -------- | ------------------- |
+| **1** | 1–2 steps, linear | direct data-first calls or method chains |
+| **2** | 3+ steps, linear | `pipe` or `flow` |
+| **3** | branchy, value reused | `tryGen` escape hatch |
+| **4** | 4+ named steps, mixed IO | `Railway` or `railway()` steps |
+
+`/fluent` is documented as app-edge sugar only — never in library or service internals.
+
+### Tier 1: 1–2 steps, linear (Direct data-first call or method chain)
+
+```ts
+import { map } from "@onrails/result";
+
+const normalized = map(rawResult, normalize);
+```
+
+### Tier 2: 3+ steps, linear (pipe / flow)
+
+```ts
+import { flow, map, flatMap, recover } from "@onrails/result";
+
+const process = flow(
+  map(normalize),
+  flatMap(validate),
+  recover(fallback)
+);
+```
+
+### Tier 3: Branchy, value reused (tryGen)
+
+```ts
+import { tryGen, $ } from "@onrails/result/try-gen";
+import { ok, err } from "@onrails/result";
+
+const stepResult = tryGen(() => {
+  const user = $(authenticate(req));
+  const post = $(fetchPost(postId));
+  if (post.authorId !== user.id && !user.isAdmin) {
+    return err({ kind: "unauthorized" as const });
+  }
+  return ok(post);
+});
+```
+
+### Tier 4: 4+ named steps, mixed IO (Railway context builder)
+
+```ts
+import { Railway } from "@onrails/result/railway";
+
+const workflow = Railway
+  .fromSync("id", () => IdSchema.parse(raw), toError)
+  .fromPromise("row", ({ id }) => db.profiles.find(id), toError)
+  .require("profile", "row", ({ id }) => ({ kind: "not_found" as const, id }))
+  .derive("normalized", ({ profile }) => normalizeProfile(profile))
+  .select(({ normalized }) => normalized);
+```
+
 ---
 
 ## 1. Reusable parser builder via `flow`
@@ -26,16 +88,8 @@ type SchemaError = { kind: "schema"; field: string };
 
 const parseJsonWith = <T>(schema: { parse: (x: unknown) => T }) =>
   flow(
-    trySync(
-      (raw: string) => JSON.parse(raw),
-      (e): ParseError => ({ kind: "parse", message: String(e) }),
-    ),
-    flatMap((data: unknown) =>
-      trySync(
-        () => schema.parse(data),
-        (e): SchemaError => ({ kind: "schema", field: String(e) }),
-      )(),
-    ),
+    trySync(JSON.parse, (e): ParseError => ({ kind: "parse", message: String(e) })),
+    flatMap(trySync(schema.parse, (e): SchemaError => ({ kind: "schema", field: String(e) }))),
   );
 
 const parseUser = parseJsonWith(UserSchema);
@@ -167,7 +221,7 @@ const buildSummary = (userId: string) =>
 // ResultAsync<Summary, ProfileError | MetricsError>
 ```
 
-`parallelTupleAsync` preserves tuple positions, so destructuring stays type-safe. Use `sequenceTupleAsync` if branches must run left-to-right.
+`parallelTupleAsync` preserves tuple positions, so destructuring stays type-safe. Use static `ResultAsync.combineTuple` if branches must run left-to-right.
 
 ---
 
@@ -181,24 +235,24 @@ import { flatMap, recover, ok, err } from "@onrails/result";
 
 type LengthError = { kind: "len"; min: number };
 type CharsError  = { kind: "chars"; bad: string };
+type TooShortError = { kind: "too_short"; min: number };
 
-const requireMin = (min: number) =>
-  flow((s: string) => (s.length >= min ? ok(s) : err({ kind: "len" as const, min })));
+const requireMin = (min: number) => (s: string) =>
+  s.length >= min ? ok(s) : err({ kind: "len" as const, min });
 
-const requireAscii = flow(
-  (s: string) =>
-    /^[\x20-\x7e]*$/.test(s) ? ok(s) : err({ kind: "chars" as const, bad: s }),
-);
+const requireAscii = (s: string) =>
+  /^[\x20-\x7e]*$/.test(s) ? ok(s) : err({ kind: "chars" as const, bad: s });
 
 const validateUsername = flow(
   (raw: string) => ok(raw.trim()),
   flatMap(requireMin(3)),
   flatMap(requireAscii),
-  recover((e: LengthError | CharsError) =>
-    e.kind === "len" ? err({ kind: "too_short" as const, min: e.min }) : err(e),
+  recover(
+    (e: LengthError | CharsError): Result<string, TooShortError | CharsError> =>
+      e.kind === "len" ? err({ kind: "too_short" as const, min: e.min }) : err(e),
   ),
 );
-// (raw: string) => Result<string, { kind: "too_short"; min: number } | CharsError>
+// (raw: string) => Result<string, TooShortError | CharsError>
 ```
 
 `requireMin(3)` is a curried factory — `flow` strings it into the pipeline alongside `requireAscii`. None of the inner steps mention the value.
@@ -301,7 +355,12 @@ import { map, recover, ok, err, type Result } from "@onrails/result";
 
 type FetchError = { kind: "network" } | { kind: "fatal"; message: string };
 
-const fetchWith = (cfg: { fallback?: Body; rethrow: (e: FetchError) => boolean }) =>
+type FetchConfig = {
+  readonly fallback?: Body;
+  readonly rethrow: (e: FetchError) => boolean;
+};
+
+const fetchWith = (cfg: FetchConfig) =>
   flow(
     fetchSync,
     recover((e: FetchError) =>
@@ -350,6 +409,69 @@ Each sub-flow has a clear purpose; the top-level `ingest` reads as a sentence. E
 
 ---
 
+## 12. Async pipelines via `ResultAsync` composition
+
+When composing functions that return `ResultAsync` values, `flow` chains them by wrapping the async transforms in arrow functions. The resulting pipeline remains point-free over the input.
+
+```ts
+import { flow } from "@onrails/result/pipe";
+import { type ResultAsync } from "@onrails/result";
+
+type Profile = { id: string; name: string };
+type Metrics = { score: number };
+type Summary = { name: string; score: number };
+
+declare const fetchProfile: (id: string) => ResultAsync<Profile, Error>;
+declare const fetchMetrics: (p: Profile) => ResultAsync<Metrics, Error>;
+declare const formatSummary: (p: Profile, m: Metrics) => Summary;
+
+const loadSummary = flow(
+  fetchProfile,
+  (ra) => ra.flatMap((profile) => 
+    fetchMetrics(profile).map((metrics) => formatSummary(profile, metrics))
+  ),
+);
+// (id: string) => ResultAsync<Summary, Error>
+```
+
+---
+
+## 13. Functional Railway pipelines (`railway` + named steps)
+
+Use `railway(input, ...steps)` from `@onrails/result/railway` to build a multi-step async pipeline using point-free reusable step wrappers. If any step is async, the entire pipeline resolves to a `ResultAsync`.
+
+```ts
+import { railway, parseWith, fromPromiseNamed, deriveNamed, select } from "@onrails/result/railway";
+import { type ResultAsync } from "@onrails/result";
+
+type Dashboard = { title: string };
+
+type IdContext = { readonly id: string };
+type ProfileContext = { readonly profile: Profile };
+type TitleContext = { readonly title: string };
+
+declare const IdSchema: { parse: (x: unknown) => string };
+declare const fetchProfile: (id: string) => Promise<Profile>;
+declare const toError: (e: unknown) => Error;
+
+const loadDashboard = (rawId: unknown): ResultAsync<Dashboard, Error> =>
+  railway(
+    rawId,
+    parseWith(IdSchema, toError).as("id"),
+    fromPromiseNamed(
+      "profile",
+      ({ id }: IdContext) => fetchProfile(id),
+      toError,
+    ),
+    deriveNamed("title", ({ profile }: ProfileContext) =>
+      profile.name.toUpperCase(),
+    ),
+    select(({ title }: TitleContext) => ({ title })),
+  );
+```
+
+---
+
 ## When NOT to go point-free
 
 Pipelines should read top-to-bottom and each step should do one obvious thing. Reach for `pipe` when:

package/dist/{async-CCA1yK8q.d.cts → async-CH8Cs8KE.d.cts}

@@ -14,6 +14,7 @@ type CombineTupleAsync<R extends readonly ResultAsync<unknown, unknown>[]> = Res
  */
 declare class ResultAsync<T, E> {
     protected readonly run: PromiseFactory<T, E>;
+    private promise;
     protected constructor(run: PromiseFactory<T, E>);
     static fromResult<T, E>(result: Result<T, E>): ResultAsync<T, E>;
     static fromPromise<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
@@ -43,6 +44,10 @@ declare class ResultAsync<T, E> {
     andThen<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
         inner: Result<U, F>;
     }): ResultAsync<U, E | F>;
+    /**
+     * Alias for {@link flatMap}.
+     * @deprecated Use {@link flatMap} or keep/use compat {@link andThen} instead.
+     */
     chain<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
         inner: Result<U, F>;
     }): ResultAsync<U, E | F>;
@@ -51,7 +56,15 @@ declare class ResultAsync<T, E> {
     tap(fn: (value: T) => void): ResultAsync<T, E>;
     tapErr(fn: (error: E) => void): ResultAsync<T, E>;
     unwrapOr<U>(defaultValue: U): Promise<T | U>;
+    /**
+     * @deprecated Await the ResultAsync and narrow with {@link isOk} — this method
+     * re-executes deferred factories and cannot narrow.
+     */
     isOk(): Promise<boolean>;
+    /**
+     * @deprecated Await the ResultAsync and narrow with {@link isErr} — this method
+     * re-executes deferred factories and cannot narrow.
+     */
     isErr(): Promise<boolean>;
     match<U1, U2 = U1>(onOk: (value: T) => U1, onErr: (error: E) => U2): Promise<U1 | U2>;
     resolve(): Promise<Result<T, E>>;
@@ -107,6 +120,7 @@ declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
  * const combined = sequenceTupleAsync([loadCfg(), loadCatalog()] as const);
  * // ResultAsync<readonly [Cfg, Catalog], CfgError | CatalogError>
  * ```
+ * @deprecated Use static {@link ResultAsync.combineTuple} instead.
  */
 declare const sequenceTupleAsync: typeof ResultAsync.combineTuple;
 /**

package/dist/{async-DH_-dNIo.d.ts → async-DKISqIBc.d.ts}

@@ -14,6 +14,7 @@ type CombineTupleAsync<R extends readonly ResultAsync<unknown, unknown>[]> = Res
  */
 declare class ResultAsync<T, E> {
     protected readonly run: PromiseFactory<T, E>;
+    private promise;
     protected constructor(run: PromiseFactory<T, E>);
     static fromResult<T, E>(result: Result<T, E>): ResultAsync<T, E>;
     static fromPromise<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
@@ -43,6 +44,10 @@ declare class ResultAsync<T, E> {
     andThen<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
         inner: Result<U, F>;
     }): ResultAsync<U, E | F>;
+    /**
+     * Alias for {@link flatMap}.
+     * @deprecated Use {@link flatMap} or keep/use compat {@link andThen} instead.
+     */
     chain<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
         inner: Result<U, F>;
     }): ResultAsync<U, E | F>;
@@ -51,7 +56,15 @@ declare class ResultAsync<T, E> {
     tap(fn: (value: T) => void): ResultAsync<T, E>;
     tapErr(fn: (error: E) => void): ResultAsync<T, E>;
     unwrapOr<U>(defaultValue: U): Promise<T | U>;
+    /**
+     * @deprecated Await the ResultAsync and narrow with {@link isOk} — this method
+     * re-executes deferred factories and cannot narrow.
+     */
     isOk(): Promise<boolean>;
+    /**
+     * @deprecated Await the ResultAsync and narrow with {@link isErr} — this method
+     * re-executes deferred factories and cannot narrow.
+     */
     isErr(): Promise<boolean>;
     match<U1, U2 = U1>(onOk: (value: T) => U1, onErr: (error: E) => U2): Promise<U1 | U2>;
     resolve(): Promise<Result<T, E>>;
@@ -107,6 +120,7 @@ declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
  * const combined = sequenceTupleAsync([loadCfg(), loadCatalog()] as const);
  * // ResultAsync<readonly [Cfg, Catalog], CfgError | CatalogError>
  * ```
+ * @deprecated Use static {@link ResultAsync.combineTuple} instead.
  */
 declare const sequenceTupleAsync: typeof ResultAsync.combineTuple;
 /**

package/dist/compat/neverthrow.cjs

@@ -89,6 +89,7 @@ var ResultAsync = class _ResultAsync {
     this.run = run;
   }
   run;
+  promise = null;
   static fromResult(result) {
     return new _ResultAsync(async () => result);
   }
@@ -150,14 +151,14 @@ var ResultAsync = class _ResultAsync {
     );
   }
   map(fn) {
-    return new _ResultAsync(async () => map(await this.run(), fn));
+    return new _ResultAsync(async () => map(await this.resolve(), fn));
   }
   mapErr(fn) {
-    return new _ResultAsync(async () => mapErr(await this.run(), fn));
+    return new _ResultAsync(async () => mapErr(await this.resolve(), fn));
   }
   flatMap(fn) {
     return new _ResultAsync(async () => {
-      const first = await this.run();
+      const first = await this.resolve();
       if (isErr(first)) {
         return first;
       }
@@ -174,12 +175,16 @@ var ResultAsync = class _ResultAsync {
   andThen(fn) {
     return this.flatMap(fn);
   }
+  /**
+   * Alias for {@link flatMap}.
+   * @deprecated Use {@link flatMap} or keep/use compat {@link andThen} instead.
+   */
   chain(fn) {
     return this.flatMap(fn);
   }
   recover(fn) {
     return new _ResultAsync(async () => {
-      const first = await this.run();
+      const first = await this.resolve();
       if (!isErr(first)) {
         return first;
       }
@@ -192,7 +197,7 @@ var ResultAsync = class _ResultAsync {
   }
   tap(fn) {
     return new _ResultAsync(async () => {
-      const result = await this.run();
+      const result = await this.resolve();
       if (!isErr(result)) {
         fn(result.value);
       }
@@ -201,7 +206,7 @@ var ResultAsync = class _ResultAsync {
   }
   tapErr(fn) {
     return new _ResultAsync(async () => {
-      const result = await this.run();
+      const result = await this.resolve();
       if (isErr(result)) {
         fn(result.error);
       }
@@ -209,19 +214,32 @@ var ResultAsync = class _ResultAsync {
     });
   }
   unwrapOr(defaultValue) {
-    return this.run().then((result) => isErr(result) ? defaultValue : result.value);
+    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.
+   */
   isOk() {
-    return this.run().then((result) => !isErr(result));
+    return this.resolve().then((result) => !isErr(result));
   }
+  /**
+   * @deprecated Await the ResultAsync and narrow with {@link isErr} — this method
+   * re-executes deferred factories and cannot narrow.
+   */
   isErr() {
-    return this.run().then((result) => isErr(result));
+    return this.resolve().then((result) => isErr(result));
   }
   match(onOk, onErr) {
-    return this.run().then((result) => isErr(result) ? onErr(result.error) : onOk(result.value));
+    return this.resolve().then(
+      (result) => isErr(result) ? onErr(result.error) : onOk(result.value)
+    );
   }
   resolve() {
-    return this.run();
+    if (!this.promise) {
+      this.promise = this.run();
+    }
+    return this.promise;
   }
   /**
    * Thenable shim — `await ra` resolves to a bare tagged-union `Result<T, E>`.
@@ -229,7 +247,7 @@ var ResultAsync = class _ResultAsync {
    */
   // biome-ignore lint/suspicious/noThenProperty: makes ResultAsync awaitable
   then(onfulfilled, onrejected) {
-    return this.run().then(
+    return this.resolve().then(
       // Safe: without onfulfilled, R1 stays at its Result<T, E> default.
       (r) => onfulfilled ? onfulfilled(r) : r,
       onrejected ?? void 0