@onrails/result 0.1.4 → 0.3.0

package/skills/result-composition/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: result-composition
+description: Primitive composition patterns for `@onrails/result` and `@onrails/maybe` — dual-form transforms, variadic `pipe`, variadic `flow`, point-free pipelines, the closure ladder. Use when writing or refactoring TypeScript that composes `Result` / `Maybe` transforms, when nesting `flatMap` calls feels noisy, when a reusable composed function would be cleaner than a wrapped expression, or when a user asks about "pipe", "flow", "compose", "point-free", "data-last", "dual-form", "curried Result", "tacit", "Ramda-style", or "nested flatMap". Do NOT use for full named-step service workflows — see the `railway-do-notation` skill for the workflow-builder layer above this one.
+---
+
+# Primitive composition in `@onrails/result`
+
+This skill covers how to compose `Result` / `Maybe` transforms at the primitive layer — before reaching for a workflow builder. The dual-form API + variadic `pipe` / `flow` give you Ramda-shape point-free composition with full TS inference.
+
+For named multi-step service workflows (Drizzle ETL, parallel enrichment, required nullable fields), escalate to the **`railway-do-notation`** skill.
+
+For worked examples of the patterns below, see [`packages/result/RECIPES.md`](../../RECIPES.md).
+
+## The dual-form contract
+
+Every transform in `@onrails/result` and `@onrails/maybe` accepts **two call shapes**:
+
+```ts
+map(result, fn);   // data-first — best inference for one-shot inline calls
+map(fn)(result);   // data-last (curried) — feeds pipe(...) and flow(...)
+```
+
+Arity at the call site picks the overload. Same applies to `mapErr`, `bimap`, `flatMap`, `recover`, `tap`, `tapErr`, `match`, and the sync→async bridge `asyncAfter` (`asyncAfter(result, fn)` data-first, `asyncAfter(fn)` data-last).
+
+`match` and `bimap` use 3-args data-first, 2-args curried:
+
+```ts
+match(result, onOk, onErr);          // data-first
+match(onOk, onErr)(result);          // data-last
+```
+
+## Decision tree
+
+Use the smallest tool that makes the code clear:
+
+| Shape | Reach for |
+|-------|-----------|
+| One-shot inline transform | `map(r, fn)` — data-first; TS infers `T` from `r` |
+| 3+ sequential steps from a starting value | `pipe(value, map(fn), flatMap(g), ...)` |
+| Defining a reusable composed function | `flow(map(fn), flatMap(g), ...)` returning `(value) => Result<…>` |
+| Method-chain in expression position | `r.map(fn).flatMap(g)` on `ResultAsync` (class method) |
+| 4+ named domain steps, mixed sync/async, nullable DB rows | **stop — use `railway-do-notation` skill** |
+
+## `pipe` vs `flow` — the only difference
+
+```ts
+pipe(value, f, g, h)   === h(g(f(value)));   // value applied immediately
+flow(f, g, h)(value)   === h(g(f(value)));   // returns a reusable function
+pipe(x, ...fns) === flow(...fns)(x);         // formal identity
+```
+
+Both are **left-to-right** (like Ramda's `R.pipe`, fp-ts `flow`, Effect `flow`). Not right-to-left `compose`.
+
+Use `pipe` when you have the starting value at the call site. Use `flow` when you want to define a function once and apply it later.
+
+## The closure ladder
+
+The decision between `flow`, `pipe`, and an outer HOF wrapper depends on **what each step needs to read**:
+
+| Step needs to read… | Shape |
+|---------------------|-------|
+| Nothing from outside the carrier value | `flow(step1, step2, ...)` — pure point-free |
+| Per-call configuration that doesn't change with the data | `(cfg) => flow(step1(cfg), step2(cfg), ...)` — outer HOF closes over config |
+| The original entry value mid-pipeline (e.g. retry coordinate) | `(input) => pipe(input, step1, step2, ...)` — closure over input, use `pipe` |
+
+Each row up adds one closure layer. Picking the right row keeps the code as point-free as the actual data flow allows — no more, no less.
+
+## Layer 1 — Direct dual-form calls
+
+For one or two transforms, just call the dual-form fn directly:
+
+```ts
+import { map, flatMap, ok, err } from "@onrails/result";
+
+const trimmed = map(parsedConfig, (cfg) => cfg.name.trim());
+const validated = flatMap(trimmed, (name) =>
+  name.length > 0 ? ok(name) : err({ kind: "empty" as const }),
+);
+```
+
+This is already clear. Don't wrap two calls in a `pipe` just to be consistent.
+
+## Layer 2 — Variadic `pipe`
+
+Reach for `pipe(value, ...fns)` when:
+
+- 3+ sequential steps starting from a known value
+- the chain reads top-to-bottom with each line doing one obvious thing
+- intermediate results don't need to be named
+
+```ts
+import { pipe, map, flatMap, recover, tap } from "@onrails/result";
+
+const greeting = pipe(
+  parseConfig(raw),
+  map((cfg) => cfg.user),
+  flatMap((u) => (u.name ? ok(u.name) : err({ kind: "empty" as const }))),
+  recover((e) => (e.kind === "empty" ? ok("anon") : err(e))),
+  tap((name) => log.info({ msg: "resolved", name })),
+);
+// Result<string, ParseError>
+```
+
+`asyncAfter` is dual-form too — its data-last call is the sync→async bridge that drops straight into `pipe`, so the step stays point-free:
+
+```ts
+pipe(
+  validated,
+  asyncAfter((v) => tryAsync(persist(v))),   // Result → ResultAsync, point-free
+);
+```
+
+And `pipe` still slots arbitrary `(prev) => next` lambdas when a step is genuinely one-off and has no curried form:
+
+```ts
+pipe(
+  parseConfig(raw),
+  map((cfg) => cfg.users),
+  (r) => r.map((users) => users.slice(0, 10)),   // ad-hoc reshape, no point-free gain
+);
+```
+
+Don't fight the railway — reach for the data-last form when it exists; embed a plain lambda only when the step is truly bespoke.
+
+## Layer 3 — Variadic `flow`
+
+Use `flow(...fns)` to **define reusable composed functions** without mentioning the data:
+
+```ts
+import { flow } from "@onrails/result/pipe";
+import { flatMap, map, type Result } from "@onrails/result";
+
+// Result-track mini-pipeline — takes raw, returns Result.
+const parseAndValidate = flow(parseJson, flatMap(validateSchema));
+
+// Value-track mini-pipeline — takes Ok value, returns Result. Lifted by `flatMap`.
+const enrichAndPersist = flow(addTimestamp, persist);
+
+// flow is associative — flow(flow(a, b), c) === flow(a, b, c).
+const ingest = flow(parseAndValidate, flatMap(enrichAndPersist));
+// (raw: string) => Result<Saved, ParseError | SchemaError | DbError>
+```
+
+`flow` shines when the same composition is reused across call sites, or when naming the mini-pipeline (`parseAndValidate`) clarifies intent.
+
+## Layer 4 — Strategy-parametrised flows (HOF + `flow`)
+
+When a step needs configuration that doesn't change per-call, take it on an outer factory. Inner `flow` stays point-free over the data:
+
+```ts
+import { flow } from "@onrails/result/pipe";
+import { map, recover, ok, err } from "@onrails/result";
+
+type FetchConfig = {
+  readonly fallback?: Body;
+  readonly rethrow: (e: FetchError) => boolean;
+};
+
+const fetchWith = (cfg: FetchConfig) =>
+  flow(
+    fetchSync,
+    recover((e: FetchError) =>
+      cfg.rethrow(e) || !cfg.fallback ? err(e) : ok(cfg.fallback),
+    ),
+    map((body: Body) => body.byteLength),
+  );
+
+const fetchOrEmpty = fetchWith({ fallback: emptyBody, rethrow: (e) => e.kind === "fatal" });
+// (url: string) => Result<number, FetchError>
+```
+
+The outer fn captures *what varies between definitions*; the inner `flow` captures *what varies per-call*. Same shape as recipe #10 in `RECIPES.md`.
+
+## Anti-patterns
+
+### 1. Compose direction confusion
+
+`flow` is **left-to-right**. The first fn is the entry point, not the last:
+
+```ts
+// Right:
+flow(fetchSync, recover(handler));   // (url) => recover(handler)(fetchSync(url))
+
+// Wrong (Ramda compose habit):
+flow(recover(handler), fetchSync);   // recover called first with `url`, type-fails
+```
+
+If you want right-to-left `compose`, build it on top in one line — but in practice, just use `flow` and read top-to-bottom.
+
+### 2. Closure-over-input in `flow`
+
+`flow(...)` has no lexical access to the eventual call argument. If a step needs to reference the entry value (e.g. retry with the original URL inside `recover`), you must wrap `flow` in a function-of-input:
+
+```ts
+// Wrong — `url` is undefined in the recover closure:
+const fetchWithBackoff = flow(
+  fetchSync,
+  recover((e) => fetchSync(url)),   // `url` is not in scope
+);
+
+// Right — wrap so recover closes over the outer parameter:
+const fetchWithBackoff = (url: string) =>
+  pipe(
+    url,
+    fetchSync,
+    recover((e) => fetchSync(url)),
+  );
+```
+
+Decide via the closure ladder above: any step that looks back at the original input forces row 3 (wrap in `(input) => pipe(input, ...)`).
+
+### 3. Point-free where a step needs the same value three times
+
+When one intermediate value is referenced multiple times in branchy logic, `flatMap` chains start carrying ambient state and reading inverted. Drop into `tryGen` — `$(result)` unwraps the Ok value or short-circuits the whole block with the first Err (Rust's `?` for sync code).
+
+```ts
+import { tryGen, $ } from "@onrails/result/try-gen";
+```
+
+**a) Linear unwrap — same value reused downstream.** The point-free version would thread `user` through every closure; `$` names it once.
+
+```ts
+const ingest = (raw: string) =>
+  pipe(
+    raw,
+    parseUser,
+    (validated) =>
+      tryGen(() => {
+        const user = $(validated);                 // unwrap or short-circuit
+        const enriched = $(enrichWithAcl(user));    // reads user
+        const persisted = $(persistSync(enriched));
+        return ok({ user: persisted, at: Date.now() });
+      }),
+    mapErr((e) => ({ kind: "ingest" as const, cause: e })),
+  );
+```
+
+**b) Branch on an unwrapped value — early `return err(...)`.** This is the case `flatMap` reads worst: a guard between two unwraps.
+
+```ts
+const authorize = (req: Request, postId: string) =>
+  tryGen(() => {
+    const user = $(authenticate(req));
+    const post = $(fetchPost(postId));
+    if (post.authorId !== user.id && !user.isAdmin) {
+      return err({ kind: "forbidden" as const });   // early exit, no nesting
+    }
+    return ok(post);
+  });
+// Result<Post, AuthError | FetchError | { kind: "forbidden" }>
+```
+
+**c) Conditional unwrap — `$` inside a branch.** Only the taken branch unwraps; the error union still accumulates both sides.
+
+```ts
+const resolve = (raw: string, opts: { strict: boolean }) =>
+  tryGen(() => {
+    const cfg = $(parseConfig(raw));
+    const name = cfg.name ?? (opts.strict ? $(err({ kind: "missing" as const })) : "anon");
+    return ok({ ...cfg, name });
+  });
+```
+
+**d) Loop with `$` — accumulate or bail on first failure.** A `for` loop with `$` is far clearer than `combine` + manual reduce when each iteration depends on the last.
+
+```ts
+const applyAll = (state: State, steps: readonly Step[]) =>
+  tryGen(() => {
+    let acc = state;
+    for (const step of steps) {
+      acc = $(applyStep(acc, step));   // first Err aborts the loop + the block
+    }
+    return ok(acc);
+  });
+```
+
+`tryGen` is a sync island. Use it when:
+
+- the same value is referenced 3+ times
+- conditional branching makes the `flatMap` chain feel inverted
+- you want `?`-style early returns without method-chaining
+- a `Result`-returning loop body must bail on first failure
+
+### 4. Inference noise mid-chain
+
+If a `pipe` accumulates two or more `as const` casts between steps, TS is telling you the carrier type is fighting back. Either:
+
+- annotate the carrier type explicitly with a typed intermediate variable, or
+- revert that step to a named one-shot and continue the pipe after it.
+
+Point-free should reduce noise, not add it.
+
+## When to escalate
+
+When you find yourself reaching for **any** of:
+
+- named context carrying values forward across many steps
+- mixed sync + async boundaries with `fromResult` / `asyncAfter` plumbing on every line
+- nullable Drizzle rows that must become required values
+- independent async branches that should run in parallel and merge by name
+
+…**stop and switch to the `railway-do-notation` skill**. `Railway.*` is designed for that territory and will read better than any amount of `pipe`/`flow` plumbing.
+
+## When NOT to go point-free
+
+`flow` and `pipe` are tools, not goals. Pipelines should read top-to-bottom with each step doing one obvious thing. Reach for `pipe` when:
+
+- 3+ sequential steps
+- each step has a clear *what*, not a clever *how*
+- errors compose cleanly via `mapErr` / `recover`
+
+Avoid point-free when:
+
+- the pipeline branches on the value mid-flight in non-obvious ways — use `tryGen` or escalate to `Railway`
+- a single step needs three different references to the same intermediate value — name it with `flatMap((x) => { ... })` and stop pretending it's anonymous
+- TypeScript inference gets noisy (multiple `as const` casts mid-chain) — annotate or revert
+
+The dual-form API lets you mix both styles freely: start point-free, drop to a named step when clarity beats compression.
+
+## See also
+
+- [`packages/result/RECIPES.md`](../../RECIPES.md) — 13 worked recipes covering parser builders, ETL pipelines, strategy-parametrised flows, validator ladders, Maybe → Result crossings, parallel sub-workflows, `tryGen` escape hatches, async pipelines, and Railway workflow pipelines.
+- [`railway-do-notation`](../railway-do-notation/SKILL.md) — workflow-builder layer above this one. Use when named context wins over positional plumbing.

package/dist/$.cjs

@@ -1,40 +0,0 @@
-'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

@@ -1 +0,0 @@
-{"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

@@ -1,36 +0,0 @@
-// 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

@@ -1 +0,0 @@
-{"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

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

package/dist/_.d.ts

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

package/dist/async-CH8Cs8KE.d.cts

@@ -1,161 +0,0 @@
-import { R as Result, U as UnexpectedError } from './types-C2Dp1d5J.cjs';
-
-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 result — public API never exposes `Promise<Result<…>>` directly;
- * await via `.resolve()` or `.match()`.
- */
-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>;
-    static fromSafePromise<T, E = never>(promise: PromiseLike<T>): ResultAsync<T, E>;
-    /**
-     * Defers work until {@link resolve}. Unlike {@link fromPromise}, nothing runs
-     * until the `ResultAsync` is resolved (e.g. by `combineTuple` / `combineTupleParallel`).
-     */
-    static defer<T, E>(fn: () => Promise<Result<T, E>>): ResultAsync<T, E>;
-    static ok<T>(value: T): ResultAsync<T, never>;
-    static ok<T, E>(value: T): ResultAsync<T, E>;
-    static err<T = never, E = unknown>(error: E): ResultAsync<T, E>;
-    /** @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>;
-    static combine<T, E>(results: readonly ResultAsync<T, E>[]): ResultAsync<T[], E>;
-    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.
-     */
-    static combineTupleParallel<const R extends readonly ResultAsync<unknown, unknown>[]>(results: R): CombineTupleAsync<R>;
-    map<U>(fn: (value: T) => U): ResultAsync<U, E>;
-    mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
-    flatMap<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F> | {
-        inner: Result<U, F>;
-    }): ResultAsync<U, E | F>;
-    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>;
-    recover<F>(fn: (error: E) => ResultAsync<T, F> | Result<T, F>): ResultAsync<T, F>;
-    orElse<F>(fn: (error: E) => ResultAsync<T, F> | Result<T, F>): ResultAsync<T, F>;
-    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>>;
-    /**
-     * 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>;
-}
-/**
- * Lifts a value into an `Ok` async result.
- *
- * @example
- * ```ts
- * const r = okAsync(42);                  // ResultAsync<number, never>
- * ```
- */
-declare const okAsync: typeof ResultAsync.ok;
-/**
- * Lifts a value into an `Err` async result.
- *
- * @example
- * ```ts
- * const r = errAsync({ kind: "not_found" as const });
- * ```
- */
-declare const errAsync: typeof ResultAsync.err;
-/**
- * Wraps a `PromiseLike<T>` into a {@link ResultAsync}. Reject reasons go
- * through `onReject` to become typed `Err`s; success becomes `Ok<T>`.
- *
- * @example
- * ```ts
- * const body = fromPromise(
- *   fetch(url).then((r) => r.text()),
- *   (e): NetworkError => ({ kind: "network", cause: String(e) }),
- * );
- * ```
- */
-declare const fromPromise: typeof ResultAsync.fromPromise;
-/**
- * Wraps a `PromiseLike<T>` that **never rejects** into {@link ResultAsync}.
- * Skips the `onReject` mapper. Use only when the promise is provably safe.
- */
-declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
-/**
- * Heterogeneous async tuple combine — left-to-right, short-circuit on
- * first `Err` in input order. Preserves tuple positions so destructuring
- * stays type-safe.
- *
- * @example
- * ```ts
- * 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;
-/**
- * Heterogeneous async tuple combine — branches overlap in wall-clock time.
- * Returns the first `Err` in **input** order (not completion order).
- *
- * @example
- * ```ts
- * const combined = parallelTupleAsync([
- *   loadProfile(id),
- *   loadMetrics(id),
- *   loadFlags(id),
- * ] as const);
- * // ResultAsync<readonly [Profile, Metrics, Flags], …>
- * ```
- */
-declare const parallelTupleAsync: typeof ResultAsync.combineTupleParallel;
-/**
- * Convenience wrapper over {@link fromPromise} with default `Error`
- * normalization. Call without `onReject` to get `ResultAsync<T, Error>`,
- * or pass a custom mapper for a typed error.
- *
- * @example
- * ```ts
- * // Default: rejection → Err(Error)
- * const a = tryAsync(db.users.insert(row));
- *
- * // Custom: typed error
- * const b = tryAsync(db.users.insert(row), (e): DbError => ({
- *   kind: "db",
- *   cause: e,
- * }));
- * ```
- */
-declare function tryAsync<T>(promise: PromiseLike<T>): ResultAsync<T, Error>;
-declare function tryAsync<T, E>(promise: PromiseLike<T>, onReject: (error: unknown) => E): ResultAsync<T, E>;
-
-export { ResultAsync as R, fromSafePromise as a, errAsync as e, fromPromise as f, okAsync as o, parallelTupleAsync as p, sequenceTupleAsync as s, tryAsync as t };