@onrails/result 0.2.0 → 0.3.0

package/DESIGN.md

@@ -10,7 +10,7 @@ type Result<T, E> =
   | { readonly _tag: "Err"; readonly error: E };
 ```
 
-- Default API: dual-form module functions — every transform accepts either shape:
+- Default API: dual-form module functions — every transform accepts either shape. The arity dispatch is owned by one internal combinator (`src/internal/dual.ts`, twin in `@onrails/maybe`); `test/dual.spec.ts` property-tests `f(r, x) ≡ f(x)(r)` for every transform:
 
   ```ts
   map(result, fn);    // data-first
@@ -25,7 +25,7 @@ type Result<T, E> =
 - `tap` / `tapErr` observe a track without changing the carried value.
 - `recover` binds the error track and may return a failed workflow back to success.
 - `pipe(value, ...fns)` is the variadic value-first pipe (up to 9 steps); `flow(...fns)` is the variadic point-free composition in `@onrails/result/pipe`.
-- Optional dot-chaining via `fluent(r)` / `fluentAsync(ra)` in `@onrails/result/fluent`.
+- Optional dot-chaining via `fluent(r)` / `fluentAsync(ra)` in `@onrails/result/fluent`. Mirrors every instance-appropriate core transform; `test/parity.spec.ts` enforces the mirror (both directions) across core, fluent, and the neverthrow compat shim.
 
 ## Sync / async interop
 
@@ -62,24 +62,18 @@ type RailwayOutput<T, E, M extends RailwayMode> =
   M extends "async" ? ResultAsync<T, E> : Result<T, E>;
 ```
 
-Use `Railway` when named context removes nesting or positional tuple plumbing. Prefer `asyncAfter`, `fromResult`, or direct `flatMap` for one- or two-step flows.
+Use `Railway` when named context removes nesting or positional tuple plumbing. Prefer `asyncAfter`, `fromResult`, or direct `flatMap` for one- or two-step flows. Reusable steps are plain functions of the context (`(ctx) => Result` / `(ctx) => ResultAsync`) plugged in via `.fromResult` / `.fromAsync`.
 
-`railway(input, ...steps)` is the functional companion for reusable workflow steps. Step factories: `parseWith(parser, onThrow).as(key)`, `fromSyncNamed`, `fromResultNamed`, `fromPromiseNamed`, `fromAsyncNamed`, `deriveNamed`, `requireNamed`, `parallelNamed`, `select`.
+Internally the runtime state tag (`"sync" | "async"`) mirrors the phantom `M`; the private `step`/`out` helpers are the only places that re-link the two.
 
 ## Combining results
 
-- `combine` / `combineTuple` — sync, first-Err wins.
-- `ResultAsync.combineTuple` — async, sequential, first-Err in input order.
-- `parallelTupleAsync` — async, concurrent (branches overlap), first-Err in input order.
-- `ResultAsync.combine` — homogeneous async collection.
-
-## Validation
+One module (`collections.ts`), one naming matrix — short-circuit vs accumulate × array vs tuple:
 
-`@onrails/result/validation` is a separate surface for accumulated independent failures (vs. railway short-circuit).
-
-- `validateAll(results, join)` — combine errors via a join function.
-- `validateAllArray(results)` — collect all errors into a readonly array.
-- `validateTupleArray(results)` — same for heterogeneous tuple shapes.
+- `combine` / `combineTuple` — sync, first-Err wins.
+- `validateAll` / `validateTuple` — accumulate independent failures; optional `combineErrors` fold, default collects a `readonly E[]`.
+- `ResultAsync.combine` / `ResultAsync.combineTuple` — async, sequential, first-Err in input order.
+- `ResultAsync.combineTupleParallel` — async, concurrent (branches overlap), first-Err in input order.
 
 Use `flatMap` for dependent checks where later checks need earlier successful values.
 
@@ -95,11 +89,9 @@ Use `flatMap` for dependent checks where later checks need earlier successful va
 | `@onrails/result` | Core: dual-form map/flatMap/match, variadic `pipe`, sync collection, async surface, lift helpers, generator sugar |
 | `@onrails/result/fluent` | Dot-style chains |
 | `@onrails/result/extra` | Error-type utilities |
-| `@onrails/result/interop` | Promise/ResultAsync boundary helpers |
 | `@onrails/result/pipe` | Variadic `flow` for point-free composition |
-| `@onrails/result/railway` | Named workflow builder and reusable step factories |
+| `@onrails/result/railway` | Named workflow builder |
 | `@onrails/result/try-gen` | Sync generator-style `Result` sugar |
-| `@onrails/result/validation` | Independent validation with accumulated failures |
 | `@onrails/result/compat/neverthrow` | Migration shim — class-shaped surface for incremental migration off neverthrow |
 
 ## Type tests

package/README.md

@@ -11,26 +11,17 @@ bun add @onrails/result
 ## Quick start (value-first — best inference)
 
 ```ts
-import {
-  asyncAfter,
-  err,
-  flatMapResult,
-  fromAsync,
-  mapResult,
-  match,
-  ok,
-  trySync,
-} from "@onrails/result";
+import { err, flatMap, match, ok, trySync } from "@onrails/result";
 
 const parse = trySync(
   (raw: string) => JSON.parse(raw),
   (e) => ({ kind: "parse" as const, message: String(e) }),
 );
 
-const pipeline = flatMapResult(parse('{"v":1}'), (data) => ok(data.v));
+const pipeline = flatMap(parse('{"v":1}'), (data) => ok(data.v));
 ```
 
-Long chains: `fluent()` from `@onrails/result/fluent` or `flatMapResult` (not curried `flatMap`) for TS inference.
+Every transform is dual-form: data-first `flatMap(r, fn)` (best inference) or curried `flatMap(fn)(r)` for `pipe`/`flow`. Long chains: `fluent()` from `@onrails/result/fluent`.
 
 For worked examples of multi-step pipelines, parser builders, validator ladders, and parallel sub-workflows see [RECIPES.md](./RECIPES.md).
 
@@ -43,9 +34,9 @@ For worked examples of multi-step pipelines, parser builders, validator ladders,
 | Long sync chain, value-first        | `pipe(r, map(...), flatMap(...), ...)`                              |
 | Long sync chain, dot-style preferred | `fluent(r)` from `@onrails/result/fluent`                          |
 | Reusable composed function          | `flow(...)` from `@onrails/result/pipe`                             |
-| Several named sync/async steps     | `Railway.*` (fluent) or `railway(...)` (functional, reusable steps)  |
+| Several named sync/async steps     | `Railway.*` builder from `@onrails/result/railway`                   |
 | Linear sync with early-return feel | `tryGen` + `$` from `@onrails/result/try-gen`                        |
-| Independent validations, accumulated failures | `validateAll` / `validateTuple` from `@onrails/result/validation` |
+| Independent validations, accumulated failures | `validateAll` / `validateTuple` from `@onrails/result` |
 | Sync → async lift, keep error type | `fromResult`, `asyncAfter` (do **not** use `fromAsync` here)         |
 | `Promise<Result<…>>` boundary lift | `fromAsync` / `tryAsync`                                             |
 
@@ -164,7 +155,7 @@ const out = tryGen(() => {
 });
 ```
 
-Use `ResultAsync.combineTuple` (or `parallelTupleAsync` when branches should overlap) when combining heterogeneous async results and destructuring the result:
+Use `ResultAsync.combineTuple` (or `ResultAsync.combineTupleParallel` when branches should overlap) when combining heterogeneous async results and destructuring the result:
 
 ```ts
 import { ResultAsync } from "@onrails/result";
@@ -206,53 +197,18 @@ Sync-only workflows return `Result<T, E>`. The first `fromPromise`, `fromAsync`,
 
 Use lower-level helpers (`asyncAfter`, `fromResult`, `flatMapResult`) for one or two steps where a builder would add ceremony.
 
-## `railway(...)` — reusable workflow steps
-
-Use lowercase `railway(...)` when the steps should be named once and reused across workflows:
+To share steps across workflows, extract plain functions of the context and plug them in via `.fromResult` / `.fromAsync`:
 
 ```ts
-import {
-  deriveNamed,
-  fromPromiseNamed,
-  parallelNamed,
-  parseWith,
-  railway,
-  requireNamed,
-  select,
-} from "@onrails/result/railway";
-
-const parseProfileId = parseWith(ProfileIdSchema, toError).as("profileId");
-
-const loadProfileRow = fromPromiseNamed(
-  "row",
-  ({ profileId }) => loadProfileRowById(profileId),
-  toError,
-);
-
-const requireProfile = requireNamed("profile", "row", ({ profileId }) =>
-  new Error(`Profile not found: ${profileId}`),
-);
-
-const loadSummaryInputs = parallelNamed({
-  recentArtifacts: ({ profile }) => loadRecentArtifacts(profile.id),
-  jobMetrics: ({ profile }) => loadJobMetrics(profile.id),
-});
+const loadProfileRow = ({ profileId }: { profileId: string }) =>
+  tryAsync(loadProfileRowById(profileId), toError);
 
-const summary = railway(
-  id,
-  parseProfileId,
-  loadProfileRow,
-  requireProfile,
-  deriveNamed("normalized", ({ profile }) => normalizeProfile(profile)),
-  loadSummaryInputs,
-  select(({ normalized, recentArtifacts, jobMetrics }) =>
-    toProfileSummary({ normalized, recentArtifacts, jobMetrics }),
-  ),
-);
+const summary = Railway.fromSync("profileId", () => ProfileIdSchema.parse(id), toError)
+  .fromAsync("row", loadProfileRow)
+  .require("profile", "row", ({ profileId }) => new Error(`Profile not found: ${profileId}`))
+  .select(({ profile }) => toProfileSummary(profile));
 ```
 
-`railway(input, ...steps)` starts from `{ input }`. `parseWith(...).as(key)` is the usual first step for raw input. The final output is still mode-aware: sync-only steps return `Result`, while async steps return `ResultAsync`.
-
 ## Pipe
 
 ```ts
@@ -304,9 +260,8 @@ import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result
 | `@onrails/result` | Core + interop exports |
 | `@onrails/result/fluent` | `fluent()`, `fluentAsync()` |
 | `@onrails/result/extra` | Error-type utilities |
-| `@onrails/result/interop` | `fromAsync`, `fromResult`, `asyncAfter` |
 | `@onrails/result/pipe` | `flow` (variadic point-free composition) |
-| `@onrails/result/railway` | `Railway`, `railway`, named workflow helpers |
+| `@onrails/result/railway` | `Railway` named-context workflow builder |
 | `@onrails/result/try-gen` | `tryGen`, `yieldResult`, `$` |
 | `@onrails/result/compat/neverthrow` | Migration shim |
 

package/RECIPES.md

@@ -20,7 +20,7 @@ To keep codebases readable and consistent, follow the four-tier decision guideli
 | **1** | 1–2 steps, linear | direct data-first calls or method chains |
 | **2** | 3+ steps, linear | `pipe` or `flow` |
 | **3** | branchy, value reused | `tryGen` escape hatch |
-| **4** | 4+ named steps, mixed IO | `Railway` or `railway()` steps |
+| **4** | 4+ named steps, mixed IO | `Railway` builder |
 
 `/fluent` is documented as app-edge sugar only — never in library or service internals.
 
@@ -197,14 +197,14 @@ const requireOrder = requireRow(orderCache.get);
 Three independent async loads overlap in wall-clock time; downstream `.map` reshapes the tuple.
 
 ```ts
-import { pipe, parallelTupleAsync } from "@onrails/result";
+import { pipe, ResultAsync } from "@onrails/result";
 
 type ProfileError = { kind: "profile"; cause: unknown };
 type MetricsError = { kind: "metrics"; cause: unknown };
 
 const buildSummary = (userId: string) =>
   pipe(
-    parallelTupleAsync([
+    ResultAsync.combineTupleParallel([
       loadProfile(userId),                                                // ResultAsync<Profile, ProfileError>
       loadRecentMetrics(userId),                                          // ResultAsync<Metrics, MetricsError>
       loadFeatureFlags(userId),                                           // ResultAsync<Flags,   never>
@@ -220,7 +220,7 @@ const buildSummary = (userId: string) =>
 // ResultAsync<Summary, ProfileError | MetricsError>
 ```
 
-`parallelTupleAsync` preserves tuple positions, so destructuring stays type-safe. Use static `ResultAsync.combineTuple` if branches must run left-to-right.
+`ResultAsync.combineTupleParallel` preserves tuple positions, so destructuring stays type-safe. Use static `ResultAsync.combineTuple` if branches must run left-to-right.
 
 ---
 
@@ -435,41 +435,28 @@ The middle step can't go point-free: `profile` is reused across both the `flatMa
 
 ---
 
-## 13. Functional Railway pipelines (`railway` + named steps)
+## 13. Railway workflow pipelines (named-context builder)
 
-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`.
+Use the `Railway` builder from `@onrails/result/railway` to build a multi-step async pipeline with named context fields. If any step is async, the entire pipeline resolves to a `ResultAsync`.
 
 ```ts
-import { railway, parseNamed, fromPromiseNamed, deriveNamed, select } from "@onrails/result/railway";
+import { Railway } from "@onrails/result/railway";
 import { type ResultAsync } from "@onrails/result";
 
 type Dashboard = { title: string };
 
-type IdContext = { readonly id: string };
-type ProfileContext = { readonly profile: Profile };
-type TitleContext = { readonly title: string };
-
 declare const IdSchema: { parse: (x: unknown) => string };
 declare const fetchProfile: (id: string) => Promise<Profile>;
 declare const toError: (e: unknown) => Error;
 
 const loadDashboard = (rawId: unknown): ResultAsync<Dashboard, Error> =>
-  railway(
-    rawId,
-    parseNamed("id", IdSchema, toError),
-    fromPromiseNamed(
-      "profile",
-      ({ id }: IdContext) => fetchProfile(id),
-      toError,
-    ),
-    deriveNamed("title", ({ profile }: ProfileContext) =>
-      profile.name.toUpperCase(),
-    ),
-    select(({ title }: TitleContext) => ({ title })),
-  );
+  Railway.fromSync("id", () => IdSchema.parse(rawId), toError)
+    .fromPromise("profile", ({ id }) => fetchProfile(id), toError)
+    .derive("title", ({ profile }) => profile.name.toUpperCase())
+    .select(({ title }) => ({ title }));
 ```
 
-Every step now reads name-first (`parseNamed("id", …)`, `fromPromiseNamed("profile", …)`, `deriveNamed("title", …)`) so the field names line up at the left edge. `parseWith(schema).as("id")` remains for the fluent trailing-name style.
+Every step reads name-first (`fromSync("id", …)`, `fromPromise("profile", …)`, `derive("title", …)`) so the field names line up at the left edge, and each step's callback sees the fully-typed context accumulated so far — no manual context annotations needed.
 
 ---
 

package/dist/{async-u8U5P2EH.d.cts → async-BR3AX0ck.d.cts}

@@ -1,12 +1,51 @@
 import { R as Result, U as UnexpectedError } from './types-BQ9vv0nD.cjs';
 
+/**
+ * @onrails/result internal — the single payload-extraction pair.
+ *
+ * `InferOk` / `InferErr` pull the success/error type out of a {@link Result}
+ * (tagged union) or a {@link ResultAsync} (class carrier), resolving to
+ * `never` for anything else. Every module that needs to extract a payload
+ * type imports from here; do not redeclare local copies.
+ *
+ * Internal only: not listed in package.json `exports` or tsup entries.
+ * The package index re-exports the pair under the same names.
+ */
+
+/**
+ * Extracts the `Ok` value type from a {@link Result} or {@link ResultAsync},
+ * resolving to `never` for any other type.
+ *
+ * @example
+ * ```ts
+ * type T = InferOk<Result<number, string>>;        // number
+ * type U = InferOk<ResultAsync<User, AppError>>;    // User
+ * ```
+ */
+type InferOk<R> = R extends {
+    _tag: "Ok";
+    readonly value: infer T;
+} ? T : R extends ResultAsync<infer T, unknown> ? T : never;
+/**
+ * Extracts the `Err` error type from a {@link Result} or {@link ResultAsync},
+ * resolving to `never` for any other type. Mirror of {@link InferOk}.
+ *
+ * @example
+ * ```ts
+ * type E = InferErr<Result<number, string>>;        // string
+ * type F = InferErr<ResultAsync<User, AppError>>;    // AppError
+ * ```
+ */
+type InferErr<R> = R extends {
+    _tag: "Err";
+    readonly error: infer E;
+} ? E : R extends ResultAsync<unknown, infer E> ? E : never;
+
 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]: InferOk<R[K]>;
 }, {
-    [K in keyof R]: AsyncErr<R[K]>;
+    [K in keyof R]: InferErr<R[K]>;
 }[number]>;
 /**
  * Async railway carrier. Wraps a deferred `Promise<Result<T, E>>` and exposes
@@ -103,12 +142,13 @@ declare class ResultAsync<T, E> {
     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}.
+     * {@link ResultAsync}. A thrown defect is routed through `onDefect`,
+     * defaulting to {@link UnexpectedError}. The `Ok` value passes through
+     * verbatim — even when it happens to be Result-shaped.
      *
      * @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`
+     * @see {@link fromAsync} from `@onrails/result`
      */
     static fromResultPromise<T, E>(promise: Promise<Result<T, E>>, onDefect?: (error: unknown) => E | UnexpectedError): ResultAsync<T, E | UnexpectedError>;
     /**
@@ -171,7 +211,7 @@ declare class ResultAsync<T, E> {
      *
      * @example
      * ```ts
-     * load(id).mapErr((e): AppError => ({ kind: "load", cause: e }));
+     * load(id).mapErr((e): AppError => ({ kind: "load", cause: e })); // ResultAsync<T, AppError>
      * ```
      */
     mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
@@ -186,21 +226,17 @@ declare class ResultAsync<T, E> {
      *   .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>;
+    flatMap<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F>): ResultAsync<U, E | F>;
     /**
      * neverthrow-compat alias of {@link flatMap}. Kept as the documented compat
-     * tier; prefer `flatMap` in new code.
+     * tier; prefer {@link 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>;
+    andThen<U, F = E>(fn: (value: T) => ResultAsync<U, F> | 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
@@ -208,13 +244,13 @@ declare class ResultAsync<T, E> {
      *
      * @example
      * ```ts
-     * loadFromCache(id).recover(() => loadFromOrigin(id));
+     * loadFromCache(id).recover(() => loadFromOrigin(id)); // ResultAsync<T, F>
      * ```
      */
     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.
+     * tier; prefer {@link recover} in new code.
      *
      * @example
      * ```ts
@@ -287,4 +323,4 @@ declare class ResultAsync<T, E> {
     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 };
+export { type InferErr as I, ResultAsync as R, type InferOk as a };

package/dist/{async-1fIhfzFu.d.ts → async-SZ7BEl0g.d.ts}

@@ -1,12 +1,51 @@
 import { R as Result, U as UnexpectedError } from './types-BQ9vv0nD.js';
 
+/**
+ * @onrails/result internal — the single payload-extraction pair.
+ *
+ * `InferOk` / `InferErr` pull the success/error type out of a {@link Result}
+ * (tagged union) or a {@link ResultAsync} (class carrier), resolving to
+ * `never` for anything else. Every module that needs to extract a payload
+ * type imports from here; do not redeclare local copies.
+ *
+ * Internal only: not listed in package.json `exports` or tsup entries.
+ * The package index re-exports the pair under the same names.
+ */
+
+/**
+ * Extracts the `Ok` value type from a {@link Result} or {@link ResultAsync},
+ * resolving to `never` for any other type.
+ *
+ * @example
+ * ```ts
+ * type T = InferOk<Result<number, string>>;        // number
+ * type U = InferOk<ResultAsync<User, AppError>>;    // User
+ * ```
+ */
+type InferOk<R> = R extends {
+    _tag: "Ok";
+    readonly value: infer T;
+} ? T : R extends ResultAsync<infer T, unknown> ? T : never;
+/**
+ * Extracts the `Err` error type from a {@link Result} or {@link ResultAsync},
+ * resolving to `never` for any other type. Mirror of {@link InferOk}.
+ *
+ * @example
+ * ```ts
+ * type E = InferErr<Result<number, string>>;        // string
+ * type F = InferErr<ResultAsync<User, AppError>>;    // AppError
+ * ```
+ */
+type InferErr<R> = R extends {
+    _tag: "Err";
+    readonly error: infer E;
+} ? E : R extends ResultAsync<unknown, infer E> ? E : never;
+
 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]: InferOk<R[K]>;
 }, {
-    [K in keyof R]: AsyncErr<R[K]>;
+    [K in keyof R]: InferErr<R[K]>;
 }[number]>;
 /**
  * Async railway carrier. Wraps a deferred `Promise<Result<T, E>>` and exposes
@@ -103,12 +142,13 @@ declare class ResultAsync<T, E> {
     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}.
+     * {@link ResultAsync}. A thrown defect is routed through `onDefect`,
+     * defaulting to {@link UnexpectedError}. The `Ok` value passes through
+     * verbatim — even when it happens to be Result-shaped.
      *
      * @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`
+     * @see {@link fromAsync} from `@onrails/result`
      */
     static fromResultPromise<T, E>(promise: Promise<Result<T, E>>, onDefect?: (error: unknown) => E | UnexpectedError): ResultAsync<T, E | UnexpectedError>;
     /**
@@ -171,7 +211,7 @@ declare class ResultAsync<T, E> {
      *
      * @example
      * ```ts
-     * load(id).mapErr((e): AppError => ({ kind: "load", cause: e }));
+     * load(id).mapErr((e): AppError => ({ kind: "load", cause: e })); // ResultAsync<T, AppError>
      * ```
      */
     mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
@@ -186,21 +226,17 @@ declare class ResultAsync<T, E> {
      *   .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>;
+    flatMap<U, F = E>(fn: (value: T) => ResultAsync<U, F> | Result<U, F>): ResultAsync<U, E | F>;
     /**
      * neverthrow-compat alias of {@link flatMap}. Kept as the documented compat
-     * tier; prefer `flatMap` in new code.
+     * tier; prefer {@link 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>;
+    andThen<U, F = E>(fn: (value: T) => ResultAsync<U, F> | 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
@@ -208,13 +244,13 @@ declare class ResultAsync<T, E> {
      *
      * @example
      * ```ts
-     * loadFromCache(id).recover(() => loadFromOrigin(id));
+     * loadFromCache(id).recover(() => loadFromOrigin(id)); // ResultAsync<T, F>
      * ```
      */
     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.
+     * tier; prefer {@link recover} in new code.
      *
      * @example
      * ```ts
@@ -287,4 +323,4 @@ declare class ResultAsync<T, E> {
     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 };
+export { type InferErr as I, ResultAsync as R, type InferOk as a };