@onrails/result 0.1.3 → 0.2.0

package/DESIGN.md

@@ -21,7 +21,7 @@ type Result<T, E> =
 
 - `flatMap` is the canonical bind and widens error types (`E | F`).
 - `match` is the canonical terminal collapse — positional, dual-form.
-- `fold({ ok, err })(result)` is the curried named-slot escape valve when positional `match` order is ambiguous at the call site.
+- For files that also import `match` from `ts-pattern`, dissolve the collision with a namespace import (`import * as R from "@onrails/result"` → `R.match`).
 - `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`.
@@ -69,7 +69,7 @@ Use `Railway` when named context removes nesting or positional tuple plumbing. P
 ## Combining results
 
 - `combine` / `combineTuple` — sync, first-Err wins.
-- `sequenceTupleAsync` — async, sequential, first-Err in input order.
+- `ResultAsync.combineTuple` — async, sequential, first-Err in input order.
 - `parallelTupleAsync` — async, concurrent (branches overlap), first-Err in input order.
 - `ResultAsync.combine` — homogeneous async collection.
 

package/README.md

@@ -141,9 +141,6 @@ 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

package/RECIPES.md

@@ -118,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.
 
 ---
 
@@ -306,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>
 ```
@@ -434,6 +431,8 @@ const loadSummary = flow(
 // (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)
@@ -441,7 +440,7 @@ const loadSummary = flow(
 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 { railway, parseNamed, fromPromiseNamed, deriveNamed, select } from "@onrails/result/railway";
 import { type ResultAsync } from "@onrails/result";
 
 type Dashboard = { title: string };
@@ -457,7 +456,7 @@ declare const toError: (e: unknown) => Error;
 const loadDashboard = (rawId: unknown): ResultAsync<Dashboard, Error> =>
   railway(
     rawId,
-    parseWith(IdSchema, toError).as("id"),
+    parseNamed("id", IdSchema, toError),
     fromPromiseNamed(
       "profile",
       ({ id }: IdContext) => fetchProfile(id),
@@ -470,6 +469,8 @@ const loadDashboard = (rawId: unknown): ResultAsync<Dashboard, Error> =>
   );
 ```
 
+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

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;AAmBO,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// 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`, use a namespace\n * import (`import * as R from \"@onrails/result\"` → `R.match`) to dissolve\n * the collision.\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 * 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 — returns the `Ok` value, or **throws the original `Err`\n * value** when called on an `Err`. This is the assertion tier (RFC 0001 §4):\n * intended for `*.spec.ts` / `*.test.ts`, where throwing fails the test loudly.\n * In business logic prefer {@link match} or {@link unwrapOr}; the lint plugins\n * flag `unwrapOk` outside test files.\n *\n * @returns the unwrapped `Ok` value\n * @throws the carried `Err` value when the result is `Err`\n *\n * @example\n * ```ts\n * // in a *.spec.ts\n * expect(unwrapOk(ok(5))).toBe(5);\n * expect(() => unwrapOk(err(error))).toThrow(error);\n * ```\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 — returns the `Err` value, or **throws a `TypeError`**\n * when called on an `Ok`. Mirror of {@link unwrapOk} on the error track and\n * part of the same assertion tier (RFC 0001 §4): intended for `*.spec.ts` /\n * `*.test.ts`. Prefer {@link match} / {@link unwrapOr} in business logic; the\n * lint plugins flag `unwrapErr` outside test files.\n *\n * @returns the unwrapped `Err` value\n * @throws `TypeError` when the result is `Ok`\n *\n * @example\n * ```ts\n * // in a *.spec.ts\n * expect(unwrapErr(err(\"x\"))).toBe(\"x\");\n * expect(() => unwrapErr(ok(5))).toThrow(TypeError);\n * ```\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/**\n * Wraps a throwing sync function, returning a function that produces a\n * {@link Result} instead of throwing. Thrown errors pass through `onThrow` to\n * become a typed `Err`; a normal return becomes `Ok`. The neverthrow analogue\n * is `Result.fromThrowable`.\n *\n * @param fn - the throwing function to wrap\n * @param onThrow - maps a thrown value to the `Err` channel\n * @returns a function with `fn`'s parameters that returns `Result<ReturnType, E>`\n *\n * @example\n * ```ts\n * type ParseError = { kind: \"parse\"; message: string };\n * const parse = trySync(\n *   JSON.parse,\n *   (e): ParseError => ({ kind: \"parse\", message: String(e) }),\n * );\n * parse(\"{}\");      // Ok({})\n * parse(\"nope\");    // Err({ kind: \"parse\", … })\n * ```\n */\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/**\n * Variadic value-first pipe — threads `value` through up to nine unary fns,\n * left-to-right. Use {@link pipe} when you already have a starting value;\n * use {@link flow} to define a reusable composed function with no value yet.\n *\n * @example\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   map((cfg) => cfg.name),\n *   flatMap((name) => (name ? ok(name) : err({ kind: \"empty\" as const }))),\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 * Unwraps a {@link Result} inside a {@link tryGen} block — the sync analogue of\n * Rust's `?` operator. On `Ok` it returns the value; on `Err` it short-circuits\n * the enclosing `tryGen`, which returns that `Err`. Only valid inside `tryGen`;\n * prefer {@link flatMap} / `pipe` for long pipelines.\n *\n * @returns the unwrapped `Ok` value\n *\n * @example\n * ```ts\n * const out = tryGen(() => {\n *   const a = yieldResult(parseA());   // unwrap or short-circuit\n *   const b = yieldResult(parseB());\n *   return ok(a + b);\n * });\n * ```\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\n/**\n * Terse alias of {@link yieldResult} (mirrors Rust's `?`), for compact\n * {@link tryGen} blocks.\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 $ = 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;AAmBO,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// 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`, use a namespace\n * import (`import * as R from \"@onrails/result\"` → `R.match`) to dissolve\n * the collision.\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 * 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 — returns the `Ok` value, or **throws the original `Err`\n * value** when called on an `Err`. This is the assertion tier (RFC 0001 §4):\n * intended for `*.spec.ts` / `*.test.ts`, where throwing fails the test loudly.\n * In business logic prefer {@link match} or {@link unwrapOr}; the lint plugins\n * flag `unwrapOk` outside test files.\n *\n * @returns the unwrapped `Ok` value\n * @throws the carried `Err` value when the result is `Err`\n *\n * @example\n * ```ts\n * // in a *.spec.ts\n * expect(unwrapOk(ok(5))).toBe(5);\n * expect(() => unwrapOk(err(error))).toThrow(error);\n * ```\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 — returns the `Err` value, or **throws a `TypeError`**\n * when called on an `Ok`. Mirror of {@link unwrapOk} on the error track and\n * part of the same assertion tier (RFC 0001 §4): intended for `*.spec.ts` /\n * `*.test.ts`. Prefer {@link match} / {@link unwrapOr} in business logic; the\n * lint plugins flag `unwrapErr` outside test files.\n *\n * @returns the unwrapped `Err` value\n * @throws `TypeError` when the result is `Ok`\n *\n * @example\n * ```ts\n * // in a *.spec.ts\n * expect(unwrapErr(err(\"x\"))).toBe(\"x\");\n * expect(() => unwrapErr(ok(5))).toThrow(TypeError);\n * ```\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/**\n * Wraps a throwing sync function, returning a function that produces a\n * {@link Result} instead of throwing. Thrown errors pass through `onThrow` to\n * become a typed `Err`; a normal return becomes `Ok`. The neverthrow analogue\n * is `Result.fromThrowable`.\n *\n * @param fn - the throwing function to wrap\n * @param onThrow - maps a thrown value to the `Err` channel\n * @returns a function with `fn`'s parameters that returns `Result<ReturnType, E>`\n *\n * @example\n * ```ts\n * type ParseError = { kind: \"parse\"; message: string };\n * const parse = trySync(\n *   JSON.parse,\n *   (e): ParseError => ({ kind: \"parse\", message: String(e) }),\n * );\n * parse(\"{}\");      // Ok({})\n * parse(\"nope\");    // Err({ kind: \"parse\", … })\n * ```\n */\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/**\n * Variadic value-first pipe — threads `value` through up to nine unary fns,\n * left-to-right. Use {@link pipe} when you already have a starting value;\n * use {@link flow} to define a reusable composed function with no value yet.\n *\n * @example\n * ```ts\n * pipe(\n *   parseConfig(raw),\n *   map((cfg) => cfg.name),\n *   flatMap((name) => (name ? ok(name) : err({ kind: \"empty\" as const }))),\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 * Unwraps a {@link Result} inside a {@link tryGen} block — the sync analogue of\n * Rust's `?` operator. On `Ok` it returns the value; on `Err` it short-circuits\n * the enclosing `tryGen`, which returns that `Err`. Only valid inside `tryGen`;\n * prefer {@link flatMap} / `pipe` for long pipelines.\n *\n * @returns the unwrapped `Ok` value\n *\n * @example\n * ```ts\n * const out = tryGen(() => {\n *   const a = yieldResult(parseA());   // unwrap or short-circuit\n *   const b = yieldResult(parseB());\n *   return ok(a + b);\n * });\n * ```\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\n/**\n * Terse alias of {@link yieldResult} (mirrors Rust's `?`), for compact\n * {@link tryGen} blocks.\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 $ = 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-BQ9vv0nD.cjs';

package/dist/_.d.ts

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

package/dist/async-1fIhfzFu.d.ts

@@ -0,0 +1,290 @@
+import { R as Result, U as UnexpectedError } from './types-BQ9vv0nD.js';
+
+type PromiseFactory<T, E> = () => Promise<Result<T, E>>;
+type AsyncOk<R> = R extends ResultAsync<infer T, unknown> ? T : never;
+type AsyncErr<R> = R extends ResultAsync<unknown, infer E> ? E : never;
+type CombineTupleAsync<R extends readonly ResultAsync<unknown, unknown>[]> = ResultAsync<{
+    [K in keyof R]: AsyncOk<R[K]>;
+}, {
+    [K in keyof R]: AsyncErr<R[K]>;
+}[number]>;
+/**
+ * Async railway carrier. Wraps a deferred `Promise<Result<T, E>>` and exposes
+ * the same dual-track transforms as the sync {@link Result} — `map`, `flatMap`,
+ * `recover`, `tap`, `match`. The public API never surfaces `Promise<Result<…>>`
+ * directly: `await` the instance (it is thenable) or call {@link resolve} /
+ * {@link match} to settle it.
+ *
+ * Construct via the static factories ({@link ok}, {@link err}, {@link fromPromise},
+ * {@link defer}, …) rather than `new` — the constructor is `protected`.
+ *
+ * @typeParam T - the `Ok` value type
+ * @typeParam E - the `Err` error type
+ *
+ * @example
+ * ```ts
+ * const user = ResultAsync.fromPromise(api.getUser(id), toAppError)
+ *   .map((u) => u.profile)
+ *   .recover(() => ResultAsync.ok(guestProfile));
+ *
+ * const r = await user;          // Result<Profile, AppError>
+ * ```
+ */
+declare class ResultAsync<T, E> {
+    protected readonly run: PromiseFactory<T, E>;
+    private promise;
+    protected constructor(run: PromiseFactory<T, E>);
+    /**
+     * Lifts an already-settled sync {@link Result} into a {@link ResultAsync}.
+     *
+     * @example
+     * ```ts
+     * const ra = ResultAsync.fromResult(ok(42));   // ResultAsync<number, never>
+     * ```
+     */
+    static fromResult<T, E>(result: Result<T, E>): ResultAsync<T, E>;
+    /**
+     * Wraps a `PromiseLike<T>` that may reject. Rejections pass through `onReject`
+     * to become a typed `Err`; resolution becomes `Ok<T>`.
+     *
+     * @param promise - the promise to wrap
+     * @param onReject - maps a rejection reason to the `Err` channel
+     *
+     * @example
+     * ```ts
+     * const body = ResultAsync.fromPromise(
+     *   fetch(url).then((r) => r.text()),
+     *   (e): NetError => ({ kind: "net", cause: String(e) }),
+     * );
+     * ```
+     */
+    static fromPromise<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
+    /**
+     * Wraps a `PromiseLike<T>` that is **guaranteed not to reject**, skipping the
+     * `onReject` mapper. Use only when rejection is provably impossible.
+     *
+     * @example
+     * ```ts
+     * const now = ResultAsync.fromSafePromise(Promise.resolve(Date.now()));
+     * ```
+     */
+    static fromSafePromise<T, E = never>(promise: PromiseLike<T>): ResultAsync<T, E>;
+    /**
+     * Defers work until {@link resolve}. Unlike {@link fromPromise}, the factory
+     * does not run until the `ResultAsync` is resolved (e.g. by `combineTuple` /
+     * `combineTupleParallel`). The factory runs at most once — `resolve` memoizes.
+     *
+     * @example
+     * ```ts
+     * const insert = ResultAsync.defer(() => db.orders.insert(row));
+     * // nothing has run yet
+     * const r = await insert;   // factory runs exactly once here
+     * ```
+     */
+    static defer<T, E>(fn: () => Promise<Result<T, E>>): ResultAsync<T, E>;
+    /**
+     * Lifts a value into an `Ok` async result.
+     *
+     * @example
+     * ```ts
+     * const r = ResultAsync.ok(42);   // ResultAsync<number, never>
+     * ```
+     */
+    static ok<T>(value: T): ResultAsync<T, never>;
+    static ok<T, E>(value: T): ResultAsync<T, E>;
+    /**
+     * Lifts an error into an `Err` async result.
+     *
+     * @example
+     * ```ts
+     * const r = ResultAsync.err({ kind: "not_found" as const });
+     * ```
+     */
+    static err<T = never, E = unknown>(error: E): ResultAsync<T, E>;
+    /**
+     * Lifts an existing `Promise<Result<T, E>>` (e.g. from interop code) into a
+     * {@link ResultAsync}, auto-flattening one level of double-wrapping. A thrown
+     * defect is routed through `onDefect`, defaulting to {@link UnexpectedError}.
+     *
+     * @param promise - a promise that already yields a `Result`
+     * @param onDefect - maps an unexpected throw to the `Err` channel
+     * @see {@link fromAsync} from `@onrails/result/interop`
+     */
+    static fromResultPromise<T, E>(promise: Promise<Result<T, E>>, onDefect?: (error: unknown) => E | UnexpectedError): ResultAsync<T, E | UnexpectedError>;
+    /**
+     * Combines a homogeneous array of async results into one. Resolves
+     * **sequentially** in input order, short-circuiting on the first `Err`.
+     * For heterogeneous tuples that preserve per-index types, use
+     * {@link combineTuple}; for wall-clock overlap, {@link combineTupleParallel}.
+     *
+     * @example
+     * ```ts
+     * const all = ResultAsync.combine([loadA(), loadB(), loadC()]);
+     * // ResultAsync<Item[], LoadError>
+     * ```
+     */
+    static combine<T, E>(results: readonly ResultAsync<T, E>[]): ResultAsync<T[], E>;
+    /**
+     * Heterogeneous async tuple combine — resolves branches **sequentially**
+     * (left-to-right), returning the first `Err` in input order. Preserves each
+     * branch's `Ok` type by position, so the result destructures type-safely.
+     * This is the canonical sequential async combine (replaces the former
+     * `sequenceTupleAsync`).
+     *
+     * @example
+     * ```ts
+     * const combined = ResultAsync.combineTuple([loadCfg(), loadCatalog()] as const);
+     * // ResultAsync<readonly [Cfg, Catalog], CfgError | CatalogError>
+     * const r = await combined;
+     * if (isOk(r)) {
+     *   const [cfg, catalog] = r.value;  // typed per position
+     * }
+     * ```
+     */
+    static combineTuple<const R extends readonly ResultAsync<unknown, unknown>[]>(results: R): CombineTupleAsync<R>;
+    /**
+     * Like {@link combineTuple}, but starts every branch before awaiting (wall-clock
+     * parallel for independent IO). On failure, returns the first `Err` in input order.
+     *
+     * @example
+     * ```ts
+     * // independent IO — overlap them
+     * const combined = ResultAsync.combineTupleParallel([
+     *   loadProfile(id),
+     *   loadMetrics(id),
+     * ] as const);
+     * ```
+     */
+    static combineTupleParallel<const R extends readonly ResultAsync<unknown, unknown>[]>(results: R): CombineTupleAsync<R>;
+    /**
+     * Transforms the `Ok` value, passing `Err` through unchanged.
+     *
+     * @example
+     * ```ts
+     * ResultAsync.ok(2).map((n) => n * 3);   // ResultAsync<number> → Ok 6
+     * ```
+     */
+    map<U>(fn: (value: T) => U): ResultAsync<U, E>;
+    /**
+     * Transforms the `Err` value, passing `Ok` through unchanged — useful for
+     * unifying heterogeneous failures into one app-level union.
+     *
+     * @example
+     * ```ts
+     * load(id).mapErr((e): AppError => ({ kind: "load", cause: e }));
+     * ```
+     */
+    mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
+    /**
+     * Canonical bind — chains a step that itself returns a `ResultAsync` or sync
+     * `Result`, short-circuiting on `Err`. Error types accumulate (`E | F`).
+     *
+     * @example
+     * ```ts
+     * authenticate(req)
+     *   .flatMap((user) => loadProfile(user.id))   // ResultAsync
+     *   .flatMap((p) => validate(p));              // sync Result also accepted
+     * ```
+     */
+    flatMap<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
+        inner: Result<U, F>;
+    }): ResultAsync<U, E | F>;
+    /**
+     * neverthrow-compat alias of {@link flatMap}. Kept as the documented compat
+     * tier; prefer `flatMap` in new code.
+     *
+     * @example
+     * ```ts
+     * authenticate(req).andThen((user) => loadProfile(user.id));
+     * ```
+     */
+    andThen<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
+        inner: Result<U, F>;
+    }): ResultAsync<U, E | F>;
+    /**
+     * Error-channel bind — runs `fn` only on `Err`, swapping in a recovery
+     * `ResultAsync` or sync `Result`. `Ok` passes through. The mirror of
+     * {@link flatMap} on the error track.
+     *
+     * @example
+     * ```ts
+     * loadFromCache(id).recover(() => loadFromOrigin(id));
+     * ```
+     */
+    recover<F>(fn: (error: E) => ResultAsync<T, F> | Result<T, F>): ResultAsync<T, F>;
+    /**
+     * neverthrow-compat alias of {@link recover}. Kept as the documented compat
+     * tier; prefer `recover` in new code.
+     *
+     * @example
+     * ```ts
+     * loadFromCache(id).orElse(() => loadFromOrigin(id));
+     * ```
+     */
+    orElse<F>(fn: (error: E) => ResultAsync<T, F> | Result<T, F>): ResultAsync<T, F>;
+    /**
+     * Runs a side effect on the `Ok` value and passes the result through
+     * unchanged; a no-op on `Err`. Mirrors {@link tapErr}.
+     *
+     * @example
+     * ```ts
+     * saveUser(u).tap((saved) => analytics.track("user_saved", saved.id));
+     * ```
+     */
+    tap(fn: (value: T) => void): ResultAsync<T, E>;
+    /**
+     * Runs a side effect on the `Err` value and passes the result through
+     * unchanged; a no-op on `Ok`. The error-track mirror of {@link tap}.
+     *
+     * @example
+     * ```ts
+     * saveUser(u).tapErr((e) => logger.warn("save failed", e));
+     * ```
+     */
+    tapErr(fn: (error: E) => void): ResultAsync<T, E>;
+    /**
+     * Settles to the `Ok` value, or `defaultValue` if `Err`. Terminal — returns a
+     * plain `Promise`, not a `ResultAsync`.
+     *
+     * @example
+     * ```ts
+     * const profile = await loadProfile(id).unwrapOr(guestProfile);
+     * ```
+     */
+    unwrapOr<U>(defaultValue: U): Promise<T | U>;
+    /**
+     * Terminal collapse — folds both tracks into a single awaited value. Returns
+     * a plain `Promise`, settling the carrier exactly once.
+     *
+     * @param onOk - handles the `Ok` value
+     * @param onErr - handles the `Err` value
+     *
+     * @example
+     * ```ts
+     * const status = await save(row).match(
+     *   () => 200,
+     *   (e) => (e.kind === "conflict" ? 409 : 500),
+     * );
+     * ```
+     */
+    match<U1, U2 = U1>(onOk: (value: T) => U1, onErr: (error: E) => U2): Promise<U1 | U2>;
+    /**
+     * Settles the carrier to a bare sync {@link Result}, memoizing so the
+     * underlying factory runs at most once. Prefer `await ra` (the thenable) or
+     * {@link match} in app code; use `resolve` when you need the tagged union back.
+     *
+     * @example
+     * ```ts
+     * const r = await load(id).resolve();   // Result<Data, LoadError>
+     * if (isOk(r)) use(r.value);
+     * ```
+     */
+    resolve(): Promise<Result<T, E>>;
+    /**
+     * Thenable shim — `await ra` resolves to a bare tagged-union `Result<T, E>`.
+     * Narrow with `isOk(r)` / `isErr(r)` to read `.value` / `.error`.
+     */
+    then<R1 = Result<T, E>, R2 = never>(onfulfilled?: ((value: Result<T, E>) => R1 | PromiseLike<R1>) | undefined | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | undefined | null): Promise<R1 | R2>;
+}
+
+export { ResultAsync as R };