@onrails/result 0.1.2 → 0.1.4

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);
@@ -64,18 +118,17 @@ const saveOrder = (rawJson: string) =>
     flatMap((u) => (u.active ? ok(u) : err({ kind: "inactive" as const }))),
     mapErr((e) => ({ kind: "input" as const, cause: e })),
     tap((u) => log.info({ msg: "validated", userId: u.id })),
-    (validated) =>
-      asyncAfter(validated, (u) =>
-        tryAsync(
-          db.orders.insert({ userId: u.id, items: u.cart }),
-          (e): DbError => ({ kind: "db", cause: e }),
-        ),
+    asyncAfter((u) =>
+      tryAsync(
+        db.orders.insert({ userId: u.id, items: u.cart }),
+        (e): DbError => ({ kind: "db", cause: e }),
       ),
+    ),
   );
 // ResultAsync<OrderRow, { kind: "input"; cause: ... } | DbError>
 ```
 
-The last step isn't perfectly point-free because `asyncAfter` is value-first by design (it takes the sync Result, then the async bridge). That's fine — `pipe` slots arbitrary `(prev) => next` functions, point-free or not.
+`asyncAfter` is dual-form like the rest of the core API: the data-last call `asyncAfter((u) => ...)` is the sync→async bridge that drops straight into `pipe`. The final step stays point-free — `pipe` feeds the upstream `Result` into the curried bridge automatically.
 
 ---
 
@@ -167,7 +220,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 +234,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.
@@ -252,12 +305,10 @@ const fetchWithBackoff = (url: string) =>
   pipe(
     url,
     fetchSync,                                                            // Result<Body, NetworkError | RateLimit | Fatal>
-    recover((e: NetworkError | RateLimit | Fatal) => {
-      if (e.kind === "network" && e.retryable) return fetchSync(url);
-      if (e.kind === "rate_limit") return err(e);   // bubble up — caller schedules retry
-      if (e.kind === "fatal") return err(e);        // unrecoverable
-      return err(e);
-    }),
+    recover((e: NetworkError | RateLimit | Fatal) =>
+      // only retryable network errors do work; everything else bubbles up
+      e.kind === "network" && e.retryable ? fetchSync(url) : err(e),
+    ),
   );
 // Result<Body, NetworkError | RateLimit | Fatal>
 ```
@@ -301,7 +352,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 +406,73 @@ 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>
+```
+
+The middle step can't go point-free: `profile` is reused across both the `flatMap` and the inner `map`. When a value is referenced by two or more async steps, this nested-closure shape is the cost of staying in `flow`. If it gets deeper, drop to the [`tryGen` escape hatch](#7-trygen-escape-hatch-for-branchy-logic) (Tier 3) and rejoin the pipe.
+
+---
+
+## 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, parseNamed, 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,
+    parseNamed("id", IdSchema, toError),
+    fromPromiseNamed(
+      "profile",
+      ({ id }: IdContext) => fetchProfile(id),
+      toError,
+    ),
+    deriveNamed("title", ({ profile }: ProfileContext) =>
+      profile.name.toUpperCase(),
+    ),
+    select(({ title }: TitleContext) => ({ title })),
+  );
+```
+
+Every step now reads name-first (`parseNamed("id", …)`, `fromPromiseNamed("profile", …)`, `deriveNamed("title", …)`) so the field names line up at the left edge. `parseWith(schema).as("id")` remains for the fluent trailing-name style.
+
+---
+
 ## 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/$.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+// src/result.ts
+var err = (error) => ({
+  _tag: "Err",
+  error
+});
+var isErr = (result) => result._tag === "Err";
+
+// src/try-gen.ts
+var ErrSignal = class {
+  constructor(error) {
+    this.error = error;
+  }
+  error;
+  _tag = "ErrSignal";
+};
+var yieldResult = (result) => {
+  if (isErr(result)) {
+    throw new ErrSignal(result.error);
+  }
+  return result.value;
+};
+var $ = yieldResult;
+var tryGen = (fn) => {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof ErrSignal) {
+      return err(error.error);
+    }
+    throw error;
+  }
+};
+
+exports.$ = $;
+exports.tryGen = tryGen;
+exports.yieldResult = yieldResult;
+//# sourceMappingURL=$.cjs.map
+//# sourceMappingURL=$.cjs.map

package/dist/$.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/result.ts","../src/try-gen.ts"],"names":[],"mappings":";;;AA2BO,IAAM,GAAA,GAAM,CAAyB,KAAA,MAA4B;AAAA,EACtE,IAAA,EAAM,KAAA;AAAA,EACN;AACF,CAAA,CAAA;AAwBO,IAAM,KAAA,GAAQ,CAAO,MAAA,KAA8C,MAAA,CAAO,IAAA,KAAS,KAAA;;;AClD1F,IAAM,YAAN,MAAmB;AAAA,EAEjB,YAAqB,KAAA,EAAU;AAAV,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AAAA,EAAW;AAAA,EAAX,KAAA;AAAA,EADZ,IAAA,GAAO,WAAA;AAElB,CAAA;AAMO,IAAM,WAAA,GAAc,CAAO,MAAA,KAA4B;AAC5D,EAAA,IAAI,KAAA,CAAM,MAAM,CAAA,EAAG;AACjB,IAAA,MAAM,IAAI,SAAA,CAAU,MAAA,CAAO,KAAK,CAAA;AAAA,EAClC;AACA,EAAA,OAAO,MAAA,CAAO,KAAA;AAChB;AAEO,IAAM,CAAA,GAAI;AAcV,IAAM,MAAA,GAAS,CAAO,EAAA,KAAyC;AACpE,EAAA,IAAI;AACF,IAAA,OAAO,EAAA,EAAG;AAAA,EACZ,SAAS,KAAA,EAAO;AACd,IAAA,IAAI,iBAAiB,SAAA,EAAW;AAC9B,MAAA,OAAO,GAAA,CAAI,MAAM,KAAK,CAAA;AAAA,IACxB;AACA,IAAA,MAAM,KAAA;AAAA,EACR;AACF","file":"$.cjs","sourcesContent":["import type { Err, Ok, Result } from \"./types.js\";\n\nexport type { Err, Ok, Result } from \"./types.js\";\n\n/**\n * Lifts a value into the success track.\n *\n * @example\n * ```ts\n * const r = ok(42);                          // Result<number, never>\n * const typed: Result<number, \"parse\"> = ok(1);\n * ```\n */\nexport const ok = <T, E = never>(value: T): Result<T, E> => ({\n  _tag: \"Ok\",\n  value,\n});\n\n/**\n * Lifts a value into the error track.\n *\n * @example\n * ```ts\n * const r = err({ kind: \"parse\", message: \"bad json\" });\n * // Result<never, { kind: \"parse\"; message: string }>\n * ```\n */\nexport const err = <T = never, E = unknown>(error: E): Result<T, E> => ({\n  _tag: \"Err\",\n  error,\n});\n\n/**\n * Type-narrowing predicate: returns `true` when the result is `Ok`.\n *\n * @example\n * ```ts\n * if (isOk(r)) {\n *   console.log(r.value);    // narrowed to Ok branch\n * }\n * ```\n */\nexport const isOk = <T, E>(result: Result<T, E>): result is Ok<T, E> => result._tag === \"Ok\";\n\n/**\n * Type-narrowing predicate: returns `true` when the result is `Err`.\n *\n * @example\n * ```ts\n * if (isErr(r)) {\n *   metrics.inc(\"error\", { kind: r.error.kind });\n * }\n * ```\n */\nexport const isErr = <T, E>(result: Result<T, E>): result is Err<T, E> => result._tag === \"Err\";\n\n/**\n * Fantasy Land `of` — alias of {@link ok}.\n * @deprecated Use {@link ok} instead.\n */\nexport const of = ok;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Dual-form helpers — each export accepts either shape:\n//   data-first: `map(result, fn)`\n//   curried:    `map(fn)(result)`\n// Arity at the call site selects the overload.\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst mapImpl = <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 * Transform the `Ok` value, passing `Err` through unchanged. Dual-form:\n * call data-first or curried (for use with {@link pipe}).\n *\n * @example\n * ```ts\n * map(ok(2), (n) => n * 3);          // Ok 6 — data-first\n * pipe(ok(\"x\"), map((s) => s.length));// Ok 1 — curried\n * ```\n */\nexport function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;\nexport function map<T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Result<U, E>;\nexport function map(\n  ...args: [Result<unknown, unknown>, (value: unknown) => unknown] | [(value: unknown) => unknown]\n): unknown {\n  if (args.length === 2) return mapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => mapImpl(result, fn);\n}\n\nconst mapErrImpl = <T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> =>\n  isErr(result) ? err(fn(result.error)) : ok(result.value);\n\n/**\n * Transform the `Err` value, passing `Ok` through unchanged. Useful for\n * unifying heterogeneous failure types into one app-level union.\n *\n * @example\n * ```ts\n * type AppError = { kind: \"http\"; status: number } | { kind: \"parse\" };\n * pipe(\n *   fetchSync(url),                                     // Result<Body, { status: number }>\n *   mapErr((e): AppError => ({ kind: \"http\", status: e.status })),\n * );\n * ```\n */\nexport function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;\nexport function mapErr<E, F>(fn: (error: E) => F): <T>(result: Result<T, E>) => Result<T, F>;\nexport function mapErr(\n  ...args: [Result<unknown, unknown>, (error: unknown) => unknown] | [(error: unknown) => unknown]\n): unknown {\n  if (args.length === 2) return mapErrImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => mapErrImpl(result, fn);\n}\n\nconst bimapImpl = <T, U, E, F>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): Result<U, F> => (isOk(result) ? ok(onOk(result.value)) : err(onErr(result.error)));\n\n/**\n * Transform both tracks at once — `Ok` via `onOk`, `Err` via `onErr`.\n * Equivalent to `mapErr(onErr)(map(onOk)(result))` but in one pass.\n *\n * @example\n * ```ts\n * bimap(parsed, (cfg) => cfg.name, (e) => ({ kind: \"input\", cause: e }));\n * ```\n */\nexport function bimap<T, U, E, F>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): Result<U, F>;\nexport function bimap<T, U, E, F>(\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): (result: Result<T, E>) => Result<U, F>;\nexport function bimap(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => unknown, (error: unknown) => unknown]\n    | [(value: unknown) => unknown, (error: unknown) => unknown]\n): unknown {\n  if (args.length === 3) return bimapImpl(args[0], args[1], args[2]);\n  const [onOk, onErr] = args;\n  return (result: Result<unknown, unknown>) => bimapImpl(result, onOk, onErr);\n}\n\nconst flatMapImpl = <T, U, E, F>(\n  result: Result<T, E>,\n  fn: (value: T) => Result<U, F>,\n): Result<U, E | F> => (isOk(result) ? fn(result.value) : err(result.error));\n\n/**\n * Canonical bind (Fantasy Land `chain`). Chains a Result-returning step,\n * widening the error union to `E | F`. Short-circuits on `Err`.\n *\n * @example\n * ```ts\n * flatMap(parseInput(raw), (data) =>\n *   data.id != null ? ok(data) : err({ kind: \"missing_id\" as const }),\n * );\n * // Result<Data, ParseError | { kind: \"missing_id\" }>\n * ```\n */\nexport function flatMap<T, U, E, F>(\n  result: Result<T, E>,\n  fn: (value: T) => Result<U, F>,\n): Result<U, E | F>;\nexport function flatMap<T, U, F>(\n  fn: (value: T) => Result<U, F>,\n): <E>(result: Result<T, E>) => Result<U, E | F>;\nexport function flatMap(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => Result<unknown, unknown>]\n    | [(value: unknown) => Result<unknown, unknown>]\n): unknown {\n  if (args.length === 2) return flatMapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => flatMapImpl(result, fn);\n}\n\nconst recoverImpl = <T, E, F>(\n  result: Result<T, E>,\n  fn: (error: E) => Result<T, F>,\n): Result<T, F> => (isErr(result) ? fn(result.error) : ok(result.value));\n\n/**\n * Error-track bind — runs `fn` only when the result is `Err`, allowing\n * a failed workflow to recover to `Ok` or remap the failure. Mirror of\n * {@link flatMap} on the error channel.\n *\n * @example\n * ```ts\n * recover(networkResult, (e) =>\n *   e.kind === \"rate_limit\" ? ok(cachedBody) : err(e),\n * );\n * ```\n */\nexport function recover<T, E, F>(\n  result: Result<T, E>,\n  fn: (error: E) => Result<T, F>,\n): Result<T, F>;\nexport function recover<T, E, F>(\n  fn: (error: E) => Result<T, F>,\n): (result: Result<T, E>) => Result<T, F>;\nexport function recover(\n  ...args:\n    | [Result<unknown, unknown>, (error: unknown) => Result<unknown, unknown>]\n    | [(error: unknown) => Result<unknown, unknown>]\n): unknown {\n  if (args.length === 2) return recoverImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => recoverImpl(result, fn);\n}\n\nconst tapImpl = <T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E> => {\n  if (isOk(result)) fn(result.value);\n  return result;\n};\n\n/**\n * Observe the `Ok` value for side effects (logging, metrics) without\n * changing the carried value. Passes `Err` through untouched.\n *\n * @example\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   tap((cfg) => log.info({ msg: \"parsed\", name: cfg.name })),\n *   flatMap(validate),\n * );\n * ```\n */\nexport function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;\nexport function tap<T>(fn: (value: T) => void): <E>(result: Result<T, E>) => Result<T, E>;\nexport function tap(\n  ...args: [Result<unknown, unknown>, (value: unknown) => void] | [(value: unknown) => void]\n): unknown {\n  if (args.length === 2) return tapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => tapImpl(result, fn);\n}\n\nconst tapErrImpl = <T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E> => {\n  if (isErr(result)) fn(result.error);\n  return result;\n};\n\n/**\n * Observe the `Err` value for side effects (logging, metrics) without\n * changing the carried error. Passes `Ok` through untouched.\n *\n * @example\n * ```ts\n * pipe(\n *   loadUser(id),\n *   tapErr((e) => metrics.inc(\"user.load.fail\", { kind: e.kind })),\n * );\n * ```\n */\nexport function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;\nexport function tapErr<E>(fn: (error: E) => void): <T>(result: Result<T, E>) => Result<T, E>;\nexport function tapErr(\n  ...args: [Result<unknown, unknown>, (error: unknown) => void] | [(error: unknown) => void]\n): unknown {\n  if (args.length === 2) return tapErrImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => tapErrImpl(result, fn);\n}\n\nconst matchImpl = <T, E, U>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): U => (isOk(result) ? onOk(result.value) : onErr(result.error));\n\n/**\n * Terminal collapse — fold both tracks into a single value. Dual-form:\n * 3-args data-first, 2-args curried for {@link pipe}. Returns whatever\n * the handlers return.\n *\n * For files that also import `match` from `ts-pattern`, the\n * collision-free alias {@link matchResult} is identical.\n *\n * @example\n * ```ts\n * const html = match(parsed, (cfg) => render(cfg), (e) => renderError(e));\n * ```\n */\nexport function match<T, E, U>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): U;\nexport function match<T, E, U>(\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): (result: Result<T, E>) => U;\nexport function match(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => unknown, (error: unknown) => unknown]\n    | [(value: unknown) => unknown, (error: unknown) => unknown]\n): unknown {\n  if (args.length === 3) return matchImpl(args[0], args[1], args[2]);\n  const [onOk, onErr] = args;\n  return (result: Result<unknown, unknown>) => matchImpl(result, onOk, onErr);\n}\n\n/**\n * Collision-free alias for files that also import `match` from ts-pattern.\n * @deprecated Namespace import carriers (e.g., `import * as R from \"@onrails/result\"`) and use canonical {@link match} instead.\n */\nexport const matchResult = match;\n\n/**\n * Curried collapse with named slots — escape valve when positional `match`\n * order is unclear at the call site (e.g. when both handlers return the same\n * type and a transposed `match(r, onErr, onOk)` would silently compile).\n * @deprecated Use curried {@link match}(onOk, onErr)(result) instead.\n */\nexport const fold =\n  <T, E, U>(handlers: { readonly ok: (value: T) => U; readonly err: (error: E) => U }) =>\n  (result: Result<T, E>): U =>\n    matchImpl(result, handlers.ok, handlers.err);\n\n/**\n * Returns the `Ok` value, or `defaultValue` when the result is `Err`.\n *\n * @example\n * ```ts\n * unwrapOr(parsedSetting, \"default-value\");\n * ```\n */\nexport const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T =>\n  isOk(result) ? result.value : defaultValue;\n\n/**\n * Test/assert helper — throws the original Err value when called on Err.\n *\n * @throws when the result is Err — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.\n * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.\n */\nexport function unwrapOk<T, E>(result: Result<T, E>): T {\n  if (isErr(result)) throw result.error;\n  return result.value;\n}\n\n/**\n * Test/assert helper — throws TypeError when called on Ok.\n *\n * @throws when the result is Ok — assertion-tier; allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.\n */\nexport function unwrapErr<T, E>(result: Result<T, E>): E {\n  if (isOk(result)) throw new TypeError(\"unwrapErr called on Ok\");\n  return result.error;\n}\n\n/** Wrap a throwing sync function — neverthrow `Result.fromThrowable` */\nexport function trySync<A extends readonly unknown[], T, E>(\n  fn: (...args: A) => T,\n  onThrow: (error: unknown) => E,\n): (...args: A) => Result<T, E>;\nexport function trySync<F extends (...args: never) => unknown, E>(\n  fn: F,\n  onThrow: (error: unknown) => E,\n): (...args: Parameters<F>) => Result<ReturnType<F>, E>;\nexport function trySync(\n  fn: (...args: never) => unknown,\n  onThrow: (error: unknown) => unknown,\n): (...args: never) => Result<unknown, unknown> {\n  return (...args: never) => {\n    try {\n      return ok(fn(...args));\n    } catch (error) {\n      return err(onThrow(error));\n    }\n  };\n}\n\n/** First failure wins; otherwise collects values in order */\nexport const combine = <T, E>(results: readonly Result<T, E>[]): Result<T[], E> => {\n  const values: T[] = [];\n  for (const result of results) {\n    if (isErr(result)) return err(result.error);\n    values.push(result.value);\n  }\n  return ok(values);\n};\n\n/** Tuple-preserving combine (neverthrow-style) */\nexport const combineTuple = <const R extends readonly Result<unknown, unknown>[]>(\n  results: R,\n): CombineTuple<R> =>\n  // Runtime identical to combine; the cast restores per-index tuple types.\n  combine(results as readonly Result<unknown, unknown>[]) as CombineTuple<R>;\n\ntype _OkValue<R> = R extends { _tag: \"Ok\"; readonly value: infer T } ? T : never;\ntype _ErrValue<R> = R extends { _tag: \"Err\"; readonly error: infer E } ? E : never;\n\ntype CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<\n  { [K in keyof R]: _OkValue<R[K]> },\n  { [K in keyof R]: _ErrValue<R[K]> }[number]\n>;\n\n/**\n * Variadic value-first pipe — threads `value` through up to nine unary fns.\n *\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   map((cfg) => cfg.name),\n *   flatMap((name) => name ? ok(name) : err({ kind: \"empty\" })),\n *   tap(log),\n * );\n * ```\n */\nexport function pipe<A>(value: A): A;\nexport function pipe<A, B>(value: A, ab: (a: A) => B): B;\nexport function pipe<A, B, C>(value: A, ab: (a: A) => B, bc: (b: B) => C): C;\nexport function pipe<A, B, C, D>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;\nexport function pipe<A, B, C, D, E>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n): E;\nexport function pipe<A, B, C, D, E, F>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n): F;\nexport function pipe<A, B, C, D, E, F, G>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n): G;\nexport function pipe<A, B, C, D, E, F, G, H>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n  gh: (g: G) => H,\n): H;\nexport function pipe<A, B, C, D, E, F, G, H, I>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n  gh: (g: G) => H,\n  hi: (h: H) => I,\n): I;\nexport function pipe(value: unknown, ...fns: ReadonlyArray<(x: unknown) => unknown>): unknown {\n  let acc = value;\n  for (const fn of fns) {\n    acc = fn(acc);\n  }\n  return acc;\n}\n","import { err, isErr } from \"./result.js\";\nimport type { Result } from \"./types.js\";\n\n/** Internal control-flow signal — not part of public error types */\nclass ErrSignal<E> {\n  readonly _tag = \"ErrSignal\" as const;\n  constructor(readonly error: E) {}\n}\n\n/**\n * Unwrap a {@link Result} inside {@link tryGen} (Rust `?` for sync code).\n * Prefer {@link flatMap} / {@link fluent} for long pipelines.\n */\nexport const yieldResult = <T, E>(result: Result<T, E>): T => {\n  if (isErr(result)) {\n    throw new ErrSignal(result.error);\n  }\n  return result.value;\n};\n\nexport const $ = yieldResult;\n\n/**\n * Run a block that uses {@link yieldResult}; returns the final `Result` or the first Err.\n *\n * @example\n * ```ts\n * const out = tryGen(() => {\n *   const a = $(parseA());\n *   const b = $(parseB());\n *   return ok(a + b);\n * });\n * ```\n */\nexport const tryGen = <T, E>(fn: () => Result<T, E>): Result<T, E> => {\n  try {\n    return fn();\n  } catch (error) {\n    if (error instanceof ErrSignal) {\n      return err(error.error);\n    }\n    throw error;\n  }\n};\n"]}

package/dist/$.js

@@ -0,0 +1,36 @@
+// src/result.ts
+var err = (error) => ({
+  _tag: "Err",
+  error
+});
+var isErr = (result) => result._tag === "Err";
+
+// src/try-gen.ts
+var ErrSignal = class {
+  constructor(error) {
+    this.error = error;
+  }
+  error;
+  _tag = "ErrSignal";
+};
+var yieldResult = (result) => {
+  if (isErr(result)) {
+    throw new ErrSignal(result.error);
+  }
+  return result.value;
+};
+var $ = yieldResult;
+var tryGen = (fn) => {
+  try {
+    return fn();
+  } catch (error) {
+    if (error instanceof ErrSignal) {
+      return err(error.error);
+    }
+    throw error;
+  }
+};
+
+export { $, tryGen, yieldResult };
+//# sourceMappingURL=$.js.map
+//# sourceMappingURL=$.js.map

package/dist/$.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/result.ts","../src/try-gen.ts"],"names":[],"mappings":";AA2BO,IAAM,GAAA,GAAM,CAAyB,KAAA,MAA4B;AAAA,EACtE,IAAA,EAAM,KAAA;AAAA,EACN;AACF,CAAA,CAAA;AAwBO,IAAM,KAAA,GAAQ,CAAO,MAAA,KAA8C,MAAA,CAAO,IAAA,KAAS,KAAA;;;AClD1F,IAAM,YAAN,MAAmB;AAAA,EAEjB,YAAqB,KAAA,EAAU;AAAV,IAAA,IAAA,CAAA,KAAA,GAAA,KAAA;AAAA,EAAW;AAAA,EAAX,KAAA;AAAA,EADZ,IAAA,GAAO,WAAA;AAElB,CAAA;AAMO,IAAM,WAAA,GAAc,CAAO,MAAA,KAA4B;AAC5D,EAAA,IAAI,KAAA,CAAM,MAAM,CAAA,EAAG;AACjB,IAAA,MAAM,IAAI,SAAA,CAAU,MAAA,CAAO,KAAK,CAAA;AAAA,EAClC;AACA,EAAA,OAAO,MAAA,CAAO,KAAA;AAChB;AAEO,IAAM,CAAA,GAAI;AAcV,IAAM,MAAA,GAAS,CAAO,EAAA,KAAyC;AACpE,EAAA,IAAI;AACF,IAAA,OAAO,EAAA,EAAG;AAAA,EACZ,SAAS,KAAA,EAAO;AACd,IAAA,IAAI,iBAAiB,SAAA,EAAW;AAC9B,MAAA,OAAO,GAAA,CAAI,MAAM,KAAK,CAAA;AAAA,IACxB;AACA,IAAA,MAAM,KAAA;AAAA,EACR;AACF","file":"$.js","sourcesContent":["import type { Err, Ok, Result } from \"./types.js\";\n\nexport type { Err, Ok, Result } from \"./types.js\";\n\n/**\n * Lifts a value into the success track.\n *\n * @example\n * ```ts\n * const r = ok(42);                          // Result<number, never>\n * const typed: Result<number, \"parse\"> = ok(1);\n * ```\n */\nexport const ok = <T, E = never>(value: T): Result<T, E> => ({\n  _tag: \"Ok\",\n  value,\n});\n\n/**\n * Lifts a value into the error track.\n *\n * @example\n * ```ts\n * const r = err({ kind: \"parse\", message: \"bad json\" });\n * // Result<never, { kind: \"parse\"; message: string }>\n * ```\n */\nexport const err = <T = never, E = unknown>(error: E): Result<T, E> => ({\n  _tag: \"Err\",\n  error,\n});\n\n/**\n * Type-narrowing predicate: returns `true` when the result is `Ok`.\n *\n * @example\n * ```ts\n * if (isOk(r)) {\n *   console.log(r.value);    // narrowed to Ok branch\n * }\n * ```\n */\nexport const isOk = <T, E>(result: Result<T, E>): result is Ok<T, E> => result._tag === \"Ok\";\n\n/**\n * Type-narrowing predicate: returns `true` when the result is `Err`.\n *\n * @example\n * ```ts\n * if (isErr(r)) {\n *   metrics.inc(\"error\", { kind: r.error.kind });\n * }\n * ```\n */\nexport const isErr = <T, E>(result: Result<T, E>): result is Err<T, E> => result._tag === \"Err\";\n\n/**\n * Fantasy Land `of` — alias of {@link ok}.\n * @deprecated Use {@link ok} instead.\n */\nexport const of = ok;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Dual-form helpers — each export accepts either shape:\n//   data-first: `map(result, fn)`\n//   curried:    `map(fn)(result)`\n// Arity at the call site selects the overload.\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst mapImpl = <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 * Transform the `Ok` value, passing `Err` through unchanged. Dual-form:\n * call data-first or curried (for use with {@link pipe}).\n *\n * @example\n * ```ts\n * map(ok(2), (n) => n * 3);          // Ok 6 — data-first\n * pipe(ok(\"x\"), map((s) => s.length));// Ok 1 — curried\n * ```\n */\nexport function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;\nexport function map<T, U>(fn: (value: T) => U): <E>(result: Result<T, E>) => Result<U, E>;\nexport function map(\n  ...args: [Result<unknown, unknown>, (value: unknown) => unknown] | [(value: unknown) => unknown]\n): unknown {\n  if (args.length === 2) return mapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => mapImpl(result, fn);\n}\n\nconst mapErrImpl = <T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> =>\n  isErr(result) ? err(fn(result.error)) : ok(result.value);\n\n/**\n * Transform the `Err` value, passing `Ok` through unchanged. Useful for\n * unifying heterogeneous failure types into one app-level union.\n *\n * @example\n * ```ts\n * type AppError = { kind: \"http\"; status: number } | { kind: \"parse\" };\n * pipe(\n *   fetchSync(url),                                     // Result<Body, { status: number }>\n *   mapErr((e): AppError => ({ kind: \"http\", status: e.status })),\n * );\n * ```\n */\nexport function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;\nexport function mapErr<E, F>(fn: (error: E) => F): <T>(result: Result<T, E>) => Result<T, F>;\nexport function mapErr(\n  ...args: [Result<unknown, unknown>, (error: unknown) => unknown] | [(error: unknown) => unknown]\n): unknown {\n  if (args.length === 2) return mapErrImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => mapErrImpl(result, fn);\n}\n\nconst bimapImpl = <T, U, E, F>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): Result<U, F> => (isOk(result) ? ok(onOk(result.value)) : err(onErr(result.error)));\n\n/**\n * Transform both tracks at once — `Ok` via `onOk`, `Err` via `onErr`.\n * Equivalent to `mapErr(onErr)(map(onOk)(result))` but in one pass.\n *\n * @example\n * ```ts\n * bimap(parsed, (cfg) => cfg.name, (e) => ({ kind: \"input\", cause: e }));\n * ```\n */\nexport function bimap<T, U, E, F>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): Result<U, F>;\nexport function bimap<T, U, E, F>(\n  onOk: (value: T) => U,\n  onErr: (error: E) => F,\n): (result: Result<T, E>) => Result<U, F>;\nexport function bimap(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => unknown, (error: unknown) => unknown]\n    | [(value: unknown) => unknown, (error: unknown) => unknown]\n): unknown {\n  if (args.length === 3) return bimapImpl(args[0], args[1], args[2]);\n  const [onOk, onErr] = args;\n  return (result: Result<unknown, unknown>) => bimapImpl(result, onOk, onErr);\n}\n\nconst flatMapImpl = <T, U, E, F>(\n  result: Result<T, E>,\n  fn: (value: T) => Result<U, F>,\n): Result<U, E | F> => (isOk(result) ? fn(result.value) : err(result.error));\n\n/**\n * Canonical bind (Fantasy Land `chain`). Chains a Result-returning step,\n * widening the error union to `E | F`. Short-circuits on `Err`.\n *\n * @example\n * ```ts\n * flatMap(parseInput(raw), (data) =>\n *   data.id != null ? ok(data) : err({ kind: \"missing_id\" as const }),\n * );\n * // Result<Data, ParseError | { kind: \"missing_id\" }>\n * ```\n */\nexport function flatMap<T, U, E, F>(\n  result: Result<T, E>,\n  fn: (value: T) => Result<U, F>,\n): Result<U, E | F>;\nexport function flatMap<T, U, F>(\n  fn: (value: T) => Result<U, F>,\n): <E>(result: Result<T, E>) => Result<U, E | F>;\nexport function flatMap(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => Result<unknown, unknown>]\n    | [(value: unknown) => Result<unknown, unknown>]\n): unknown {\n  if (args.length === 2) return flatMapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => flatMapImpl(result, fn);\n}\n\nconst recoverImpl = <T, E, F>(\n  result: Result<T, E>,\n  fn: (error: E) => Result<T, F>,\n): Result<T, F> => (isErr(result) ? fn(result.error) : ok(result.value));\n\n/**\n * Error-track bind — runs `fn` only when the result is `Err`, allowing\n * a failed workflow to recover to `Ok` or remap the failure. Mirror of\n * {@link flatMap} on the error channel.\n *\n * @example\n * ```ts\n * recover(networkResult, (e) =>\n *   e.kind === \"rate_limit\" ? ok(cachedBody) : err(e),\n * );\n * ```\n */\nexport function recover<T, E, F>(\n  result: Result<T, E>,\n  fn: (error: E) => Result<T, F>,\n): Result<T, F>;\nexport function recover<T, E, F>(\n  fn: (error: E) => Result<T, F>,\n): (result: Result<T, E>) => Result<T, F>;\nexport function recover(\n  ...args:\n    | [Result<unknown, unknown>, (error: unknown) => Result<unknown, unknown>]\n    | [(error: unknown) => Result<unknown, unknown>]\n): unknown {\n  if (args.length === 2) return recoverImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => recoverImpl(result, fn);\n}\n\nconst tapImpl = <T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E> => {\n  if (isOk(result)) fn(result.value);\n  return result;\n};\n\n/**\n * Observe the `Ok` value for side effects (logging, metrics) without\n * changing the carried value. Passes `Err` through untouched.\n *\n * @example\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   tap((cfg) => log.info({ msg: \"parsed\", name: cfg.name })),\n *   flatMap(validate),\n * );\n * ```\n */\nexport function tap<T, E>(result: Result<T, E>, fn: (value: T) => void): Result<T, E>;\nexport function tap<T>(fn: (value: T) => void): <E>(result: Result<T, E>) => Result<T, E>;\nexport function tap(\n  ...args: [Result<unknown, unknown>, (value: unknown) => void] | [(value: unknown) => void]\n): unknown {\n  if (args.length === 2) return tapImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => tapImpl(result, fn);\n}\n\nconst tapErrImpl = <T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E> => {\n  if (isErr(result)) fn(result.error);\n  return result;\n};\n\n/**\n * Observe the `Err` value for side effects (logging, metrics) without\n * changing the carried error. Passes `Ok` through untouched.\n *\n * @example\n * ```ts\n * pipe(\n *   loadUser(id),\n *   tapErr((e) => metrics.inc(\"user.load.fail\", { kind: e.kind })),\n * );\n * ```\n */\nexport function tapErr<T, E>(result: Result<T, E>, fn: (error: E) => void): Result<T, E>;\nexport function tapErr<E>(fn: (error: E) => void): <T>(result: Result<T, E>) => Result<T, E>;\nexport function tapErr(\n  ...args: [Result<unknown, unknown>, (error: unknown) => void] | [(error: unknown) => void]\n): unknown {\n  if (args.length === 2) return tapErrImpl(args[0], args[1]);\n  const fn = args[0];\n  return (result: Result<unknown, unknown>) => tapErrImpl(result, fn);\n}\n\nconst matchImpl = <T, E, U>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): U => (isOk(result) ? onOk(result.value) : onErr(result.error));\n\n/**\n * Terminal collapse — fold both tracks into a single value. Dual-form:\n * 3-args data-first, 2-args curried for {@link pipe}. Returns whatever\n * the handlers return.\n *\n * For files that also import `match` from `ts-pattern`, the\n * collision-free alias {@link matchResult} is identical.\n *\n * @example\n * ```ts\n * const html = match(parsed, (cfg) => render(cfg), (e) => renderError(e));\n * ```\n */\nexport function match<T, E, U>(\n  result: Result<T, E>,\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): U;\nexport function match<T, E, U>(\n  onOk: (value: T) => U,\n  onErr: (error: E) => U,\n): (result: Result<T, E>) => U;\nexport function match(\n  ...args:\n    | [Result<unknown, unknown>, (value: unknown) => unknown, (error: unknown) => unknown]\n    | [(value: unknown) => unknown, (error: unknown) => unknown]\n): unknown {\n  if (args.length === 3) return matchImpl(args[0], args[1], args[2]);\n  const [onOk, onErr] = args;\n  return (result: Result<unknown, unknown>) => matchImpl(result, onOk, onErr);\n}\n\n/**\n * Collision-free alias for files that also import `match` from ts-pattern.\n * @deprecated Namespace import carriers (e.g., `import * as R from \"@onrails/result\"`) and use canonical {@link match} instead.\n */\nexport const matchResult = match;\n\n/**\n * Curried collapse with named slots — escape valve when positional `match`\n * order is unclear at the call site (e.g. when both handlers return the same\n * type and a transposed `match(r, onErr, onOk)` would silently compile).\n * @deprecated Use curried {@link match}(onOk, onErr)(result) instead.\n */\nexport const fold =\n  <T, E, U>(handlers: { readonly ok: (value: T) => U; readonly err: (error: E) => U }) =>\n  (result: Result<T, E>): U =>\n    matchImpl(result, handlers.ok, handlers.err);\n\n/**\n * Returns the `Ok` value, or `defaultValue` when the result is `Err`.\n *\n * @example\n * ```ts\n * unwrapOr(parsedSetting, \"default-value\");\n * ```\n */\nexport const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T =>\n  isOk(result) ? result.value : defaultValue;\n\n/**\n * Test/assert helper — throws the original Err value when called on Err.\n *\n * @throws when the result is Err — assertion-tier; use {@link match} / {@link unwrapOr} in business logic.\n * Allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.\n */\nexport function unwrapOk<T, E>(result: Result<T, E>): T {\n  if (isErr(result)) throw result.error;\n  return result.value;\n}\n\n/**\n * Test/assert helper — throws TypeError when called on Ok.\n *\n * @throws when the result is Ok — assertion-tier; allowed in `*.spec.ts` / `*.test.ts`; flagged elsewhere by the plugins.\n */\nexport function unwrapErr<T, E>(result: Result<T, E>): E {\n  if (isOk(result)) throw new TypeError(\"unwrapErr called on Ok\");\n  return result.error;\n}\n\n/** Wrap a throwing sync function — neverthrow `Result.fromThrowable` */\nexport function trySync<A extends readonly unknown[], T, E>(\n  fn: (...args: A) => T,\n  onThrow: (error: unknown) => E,\n): (...args: A) => Result<T, E>;\nexport function trySync<F extends (...args: never) => unknown, E>(\n  fn: F,\n  onThrow: (error: unknown) => E,\n): (...args: Parameters<F>) => Result<ReturnType<F>, E>;\nexport function trySync(\n  fn: (...args: never) => unknown,\n  onThrow: (error: unknown) => unknown,\n): (...args: never) => Result<unknown, unknown> {\n  return (...args: never) => {\n    try {\n      return ok(fn(...args));\n    } catch (error) {\n      return err(onThrow(error));\n    }\n  };\n}\n\n/** First failure wins; otherwise collects values in order */\nexport const combine = <T, E>(results: readonly Result<T, E>[]): Result<T[], E> => {\n  const values: T[] = [];\n  for (const result of results) {\n    if (isErr(result)) return err(result.error);\n    values.push(result.value);\n  }\n  return ok(values);\n};\n\n/** Tuple-preserving combine (neverthrow-style) */\nexport const combineTuple = <const R extends readonly Result<unknown, unknown>[]>(\n  results: R,\n): CombineTuple<R> =>\n  // Runtime identical to combine; the cast restores per-index tuple types.\n  combine(results as readonly Result<unknown, unknown>[]) as CombineTuple<R>;\n\ntype _OkValue<R> = R extends { _tag: \"Ok\"; readonly value: infer T } ? T : never;\ntype _ErrValue<R> = R extends { _tag: \"Err\"; readonly error: infer E } ? E : never;\n\ntype CombineTuple<R extends readonly Result<unknown, unknown>[]> = Result<\n  { [K in keyof R]: _OkValue<R[K]> },\n  { [K in keyof R]: _ErrValue<R[K]> }[number]\n>;\n\n/**\n * Variadic value-first pipe — threads `value` through up to nine unary fns.\n *\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   map((cfg) => cfg.name),\n *   flatMap((name) => name ? ok(name) : err({ kind: \"empty\" })),\n *   tap(log),\n * );\n * ```\n */\nexport function pipe<A>(value: A): A;\nexport function pipe<A, B>(value: A, ab: (a: A) => B): B;\nexport function pipe<A, B, C>(value: A, ab: (a: A) => B, bc: (b: B) => C): C;\nexport function pipe<A, B, C, D>(value: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;\nexport function pipe<A, B, C, D, E>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n): E;\nexport function pipe<A, B, C, D, E, F>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n): F;\nexport function pipe<A, B, C, D, E, F, G>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n): G;\nexport function pipe<A, B, C, D, E, F, G, H>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n  gh: (g: G) => H,\n): H;\nexport function pipe<A, B, C, D, E, F, G, H, I>(\n  value: A,\n  ab: (a: A) => B,\n  bc: (b: B) => C,\n  cd: (c: C) => D,\n  de: (d: D) => E,\n  ef: (e: E) => F,\n  fg: (f: F) => G,\n  gh: (g: G) => H,\n  hi: (h: H) => I,\n): I;\nexport function pipe(value: unknown, ...fns: ReadonlyArray<(x: unknown) => unknown>): unknown {\n  let acc = value;\n  for (const fn of fns) {\n    acc = fn(acc);\n  }\n  return acc;\n}\n","import { err, isErr } from \"./result.js\";\nimport type { Result } from \"./types.js\";\n\n/** Internal control-flow signal — not part of public error types */\nclass ErrSignal<E> {\n  readonly _tag = \"ErrSignal\" as const;\n  constructor(readonly error: E) {}\n}\n\n/**\n * Unwrap a {@link Result} inside {@link tryGen} (Rust `?` for sync code).\n * Prefer {@link flatMap} / {@link fluent} for long pipelines.\n */\nexport const yieldResult = <T, E>(result: Result<T, E>): T => {\n  if (isErr(result)) {\n    throw new ErrSignal(result.error);\n  }\n  return result.value;\n};\n\nexport const $ = yieldResult;\n\n/**\n * Run a block that uses {@link yieldResult}; returns the final `Result` or the first Err.\n *\n * @example\n * ```ts\n * const out = tryGen(() => {\n *   const a = $(parseA());\n *   const b = $(parseB());\n *   return ok(a + b);\n * });\n * ```\n */\nexport const tryGen = <T, E>(fn: () => Result<T, E>): Result<T, E> => {\n  try {\n    return fn();\n  } catch (error) {\n    if (error instanceof ErrSignal) {\n      return err(error.error);\n    }\n    throw error;\n  }\n};\n"]}

package/dist/_.d.cts

@@ -0,0 +1,2 @@
+export { $, tryGen, yieldResult } from './try-gen.cjs';
+import './types-C2Dp1d5J.cjs';

package/dist/_.d.ts

@@ -0,0 +1,2 @@
+export { $, tryGen, yieldResult } from './try-gen.js';
+import './types-C2Dp1d5J.js';

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;
 /**