@onrails/result 0.1.0

package/DESIGN.md

@@ -0,0 +1,119 @@
+# @onrails/result — design
+
+Typed `Result` / `ResultAsync` for railway-oriented TypeScript. Tagged unions, tree-shakeable, neverthrow-compat shim available.
+
+## Runtime model
+
+```ts
+type Result<T, E> =
+  | { readonly _tag: "Ok"; readonly value: T }
+  | { readonly _tag: "Err"; readonly error: E };
+```
+
+- Default API: dual-form module functions — every transform accepts either shape:
+
+  ```ts
+  map(result, fn);    // data-first
+  map(fn)(result);    // curried
+  ```
+
+  Dual functions: `map`, `mapErr`, `bimap`, `flatMap`, `recover`, `tap`, `tapErr`, `match`.
+
+- `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.
+- `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`.
+
+## Sync / async interop
+
+Two distinct lift paths:
+
+- `fromResult(result)` — already-known sync `Result<T, E>`. Cannot defect, so returns `ResultAsync<T, E>` without widening.
+- `fromAsync(fn)` / `ResultAsync.fromResultPromise(promise)` — `Promise<Result<T, E>>` boundary. The promise can reject outside the `Result` channel, so the error widens with `UnexpectedError` unless a custom defect mapper is supplied.
+
+`asyncAfter(result, fn)` bridges sync validation into async IO:
+
+```ts
+asyncAfter(
+  trySync(() => Schema.parse(input), toError)(),
+  (value) => tryAsync(save(value)),
+);
+```
+
+`tryAsync(promise, onReject?)` wraps Promise boundaries with default `Error` normalization.
+
+## Railway workflows
+
+`Railway<C, E, M>` (`@onrails/result/railway`) is a named-context builder for service-layer ETL.
+
+- `Railway.fromSync`, `.fromResult`, `.derive` preserve sync mode.
+- `.fromPromise`, `.fromAsync`, `.parallel` upgrade to async mode.
+- `.require(key, source, onMissing)` converts a nullable context field into a required non-null field.
+- `.parallel(record)` runs independent `ResultAsync` branches concurrently and merges named outputs back into context. On multiple failures, the first `Err` in record iteration order wins.
+- `.select(fn)` projects the final context.
+
+Return type is mode-aware:
+
+```ts
+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.
+
+`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`.
+
+## Combining results
+
+- `combine` / `combineTuple` — sync, first-Err wins.
+- `sequenceTupleAsync` — async, sequential, first-Err in input order.
+- `parallelTupleAsync` — async, concurrent (branches overlap), first-Err in input order.
+- `ResultAsync.combine` — homogeneous async collection.
+
+## Validation
+
+`@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.
+
+Use `flatMap` for dependent checks where later checks need earlier successful values.
+
+## Errors
+
+- `E` is fully generic on the core package.
+- `@onrails/result/extra` — `errOf`, `unionErrors`, `mapErrKind`, `declareErrors`, `AccumulateErrors` for discriminated unions.
+
+## Exports
+
+| Subpath | Purpose |
+|---------|---------|
+| `@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/mcp` | MCP / HTTP boundary helpers |
+| `@onrails/result/pipe` | Variadic `flow` for point-free composition |
+| `@onrails/result/railway` | Named workflow builder and reusable step factories |
+| `@onrails/result/try-gen` | Sync generator-style `Result` sugar |
+| `@onrails/result/validation` | Independent validation with accumulated failures |
+| `@onrails/result/compat/neverthrow` | Migration shim — class-shaped surface for incremental migration off neverthrow |
+
+## Type tests
+
+`test/types.spec.ts` — `ts-expect` (`expectType` + `TypeEqual`).
+
+## v1.0 gate
+
+- bun tests: core ops, FL functor/monad laws (sync), neverthrow-compat fixtures.
+- README with tagged-error guidance.
+- **Not** in v1.0: npm publish.
+
+## Deferred
+
+- npm publish visibility.
+- `ap` / `alt` / error `Semigroup`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan R. Soares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# @onrails/result
+
+Tagged `Result` / `ResultAsync` for railway-oriented TypeScript. Pure tagged unions, neverthrow-shaped compat shim, FL-friendly.
+
+## Install (local — pre-publish)
+
+```bash
+bun add @onrails/result@file:../onrails/packages/result
+```
+
+## Quick start (value-first — best inference)
+
+```ts
+import {
+  asyncAfter,
+  err,
+  flatMapResult,
+  fromAsync,
+  mapResult,
+  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));
+```
+
+Long chains: `fluent()` from `@onrails/result/fluent` or `flatMapResult` (not curried `flatMap`) for TS inference.
+
+For worked examples of multi-step pipelines, parser builders, validator ladders, and parallel sub-workflows see [RECIPES.md](./RECIPES.md).
+
+## When to use what
+
+| Shape                              | Reach for                                                            |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| One or two sync steps              | `flatMapResult`, `mapResult`, `match`                                |
+| One or two async steps             | `ResultAsync.flatMap`, `asyncAfter`                                  |
+| 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)  |
+| Linear sync with early-return feel | `tryGen` + `$` from `@onrails/result/try-gen`                        |
+| Independent validations, accumulated failures | `validateAll` / `validateTuple` from `@onrails/result/validation` |
+| Sync → async lift, keep error type | `fromResult`, `asyncAfter` (do **not** use `fromAsync` here)         |
+| `Promise<Result<…>>` boundary lift | `fromAsync` / `tryAsync`                                             |
+
+Rule of thumb: pick the smallest tool that removes nesting. Reach for `Railway` only when named context replaces positional tuple plumbing.
+
+## Sync → async boundaries
+
+Use `fromResult` when a sync `Result` needs to enter a `ResultAsync` pipeline without widening the error channel:
+
+```ts
+import { fromResult, ok, type Result } from "@onrails/result";
+
+const parsed: Result<number, "parse"> = ok(1);
+const asyncParsed = fromResult(parsed);
+// ResultAsync<number, "parse"> — no UnexpectedError widening
+```
+
+Use `asyncAfter` for the common "validate synchronously, then run async IO" shape:
+
+```ts
+import { asyncAfter, tryAsync, trySync } from "@onrails/result";
+
+return asyncAfter(
+  trySync(() => ArtifactSchema.parse(artifact), toError)(),
+  (validated) =>
+    tryAsync(
+      getDb()
+        .insert(artifacts)
+        .values(validated)
+        .then(() => undefined),
+    ),
+);
+```
+
+Use `tryAsync` for Promise boundaries with default `Error` normalization, or pass a custom rejection mapper:
+
+```ts
+const body = tryAsync(fetch(url).then((res) => res.text()));
+
+const status = tryAsync(fetch(url), (error) => ({
+  kind: "network" as const,
+  message: String(error),
+}));
+```
+
+## Tagged error style
+
+Prefer **tagged objects**, not bare `extends Error` classes — TS collapses structurally identical errors ([#652](https://github.com/supermacro/neverthrow/issues/652)).
+
+```ts
+type BotError =
+  | { kind: "not_found"; id: string }
+  | { kind: "network"; message: string };
+```
+
+Helpers: `@onrails/result/extra` — `hasKind`, `mapErrKind`, `declareErrors`, `UnionErrors`, `AccumulateErrors`.
+
+## Async interop — `fromAsync`
+
+Lift `async` handlers that return `Result` without leaking `Promise<Result<…>>`:
+
+```ts
+import { fromAsync, ok, err } from "@onrails/result";
+
+async function getItem(): Promise<Result<{ id: string }, HttpError>> {
+  if (!user) return err({ kind: "unauthorized" });
+  return ok({ id: "x" });
+}
+
+// Public API: ResultAsync only
+export const getItemAsync = fromAsync(getItem);
+```
+
+
+## Awaitable `ResultAsync`
+
+`ResultAsync` is thenable — `await ra` resolves to a bare tagged-union `Result<T, E>`. Narrow with `isOk(r)` / `isErr(r)` (type predicates) to read `.value` / `.error`.
+
+```ts
+const r = await getItemAsync();
+if (isOk(r)) console.log(r.value.id);
+else console.error(r.error);
+```
+
+## Match and unwrap helpers
+
+`matchResult` is an alias for `match` for files that also import `match` from `ts-pattern`:
+
+```ts
+import { matchResult } from "@onrails/result";
+import { match } from "ts-pattern";
+```
+
+`unwrapOk` and `unwrapErr` are test/assertion helpers. Prefer `match`, `isOk`, or `isErr` in production control flow.
+
+```ts
+import { unwrapOk } from "@onrails/result";
+
+expect(unwrapOk(parseConfig(raw))).toEqual(expected);
+```
+
+## MCP / HTTP boundaries
+
+```ts
+import { toToolResponseAsync, unwrapFetchResultAsync } from "@onrails/result/mcp";
+
+const ra = unwrapFetchResultAsync(
+  client.GET("/tokens/{id}"),
+  ({ error, response }) => new PrintrApiError(response.status, detail),
+);
+return toToolResponseAsync(ra);
+```
+
+## `tryGen` — sync `?`
+
+For short linear sync code:
+
+```ts
+import { $, ok, tryGen } from "@onrails/result";
+
+const out = tryGen(() => {
+  const a = $(parseA());
+  const b = $(parseB());
+  return ok(a + b);
+});
+```
+
+Use `sequenceTupleAsync` (or `parallelTupleAsync` when branches should overlap) when combining heterogeneous async results and destructuring the result:
+
+```ts
+import { sequenceTupleAsync } from "@onrails/result";
+
+const combined = sequenceTupleAsync([
+  loadSettings(),
+  loadModelCatalog(),
+] as const);
+
+const dto = combined.map(([settings, catalog]) =>
+  buildDto(settings, catalog),
+);
+```
+
+When TS only infers the first error in a generator-style flow, use `declareErrors<E1 | E2>()` from `/extra`.
+
+## `Railway` — named service workflows
+
+Use `Railway` from `@onrails/result/railway` when a service workflow has several named sync/async steps and would otherwise need manual context-carrying objects:
+
+```ts
+import { Railway } from "@onrails/result/railway";
+
+const summary = Railway.fromSync("profileId", () => ProfileIdSchema.parse(id), toError)
+  .fromPromise("row", ({ profileId }) => loadProfileRow(profileId), toError)
+  .require("profile", "row", ({ profileId }) => new Error(`Profile not found: ${profileId}`))
+  .derive("normalized", ({ profile }) => normalizeProfile(profile))
+  .fromResult("stats", ({ normalized }) => enrichProfileStats(normalized))
+  .parallel({
+    recentArtifacts: ({ normalized }) => loadRecentArtifacts(normalized.id),
+    jobMetrics: ({ normalized }) => loadJobMetrics(normalized.id),
+  })
+  .select(({ normalized, stats, recentArtifacts, jobMetrics }) =>
+    toProfileSummary({ normalized, stats, recentArtifacts, jobMetrics }),
+  );
+```
+
+Sync-only workflows return `Result<T, E>`. The first `fromPromise`, `fromAsync`, or `parallel` step upgrades the output to `ResultAsync<T, E>`.
+
+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:
+
+```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 summary = railway(
+  id,
+  parseProfileId,
+  loadProfileRow,
+  requireProfile,
+  deriveNamed("normalized", ({ profile }) => normalizeProfile(profile)),
+  loadSummaryInputs,
+  select(({ normalized, recentArtifacts, jobMetrics }) =>
+    toProfileSummary({ normalized, recentArtifacts, jobMetrics }),
+  ),
+);
+```
+
+`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
+import { pipe } from "@onrails/result";
+import { flow } from "@onrails/result/pipe";
+
+// Value-first variadic pipe — threads a starting value through unary steps.
+const name = pipe(
+  parseConfig(raw),
+  map((cfg) => cfg.user),
+  flatMap((u) => (u.name ? ok(u.name) : err({ kind: "missing" }))),
+  recover((e) => (e.kind === "missing" ? ok("anon") : err(e))),
+  tap((n) => log(n)),
+);
+
+// Variadic point-free composition — define a reusable pipeline.
+const parseUserName = flow(
+  (raw: string) => parseConfig(raw),
+  map((cfg) => cfg.user),
+  flatMap((u) => (u.name ? ok(u.name) : err({ kind: "missing" }))),
+);
+parseUserName(raw);
+```
+
+## ESLint
+
+`@onrails/eslint-plugin` — warns on `Promise<Result<…>>` and `_unsafeUnwrap*`.
+
+## Migration from neverthrow
+
+See [@onrails/codemod](../codemod/README.md) for the automated codemod, and the **Compat surface** notes below.
+
+### Compat surface
+
+```ts
+import { ResultAsync, Result, ok, err, okAsync, errAsync } from "@onrails/result/compat/neverthrow";
+```
+
+- `Result` / `ResultAsync` are class-shaped (`CompatResult` / `CompatResultAsync`).
+- `await ra` resolves to a `CompatResult<T, E>` (thenable), so `.isOk()`, `.value`, `.error`, `.match()`, `.unwrapOr()` all work without an extra `.resolve()` call.
+- `andThen` / `chain` / `flatMap` / `orElse` accept any of `CompatResultAsync` / `ResultAsync` / `CompatResult` / tagged `Result` returns and union the error type.
+- Supported: `andThen`, `asyncAndThen`, `chain`, `flatMap`, `flatMapResult`, `andThenResult`, `map`, `mapErr`, `orElse`, `match`, `unwrapOr`, `isOk`, `isErr`, `andTee`, `orTee`, `Result.combine`, `Result.fromThrowable`, `ResultAsync.combine`, `ResultAsync.fromPromise`, `ResultAsync.fromSafePromise`, `ResultAsync.fromThrowable`, `_unsafeUnwrap` / `_unsafeUnwrapErr`.
+- Treat the compat surface as a migration step, not the destination — once a package migrates, switch its imports to `@onrails/result` and `@onrails/result/fluent`.
+
+## Subpaths
+
+| Path | Contents |
+|------|----------|
+| `@onrails/result` | Core + interop exports |
+| `@onrails/result/fluent` | `fluent()`, `fluentAsync()` |
+| `@onrails/result/extra` | Error-type utilities |
+| `@onrails/result/interop` | `fromAsync`, `fromResult`, `asyncAfter` |
+| `@onrails/result/mcp` | MCP / openapi-fetch helpers |
+| `@onrails/result/pipe` | `flow` (variadic point-free composition) |
+| `@onrails/result/railway` | `Railway`, `railway`, named workflow helpers |
+| `@onrails/result/try-gen` | `tryGen`, `yieldResult`, `$` |
+| `@onrails/result/compat/neverthrow` | Migration shim |
+
+See [DESIGN.md](./DESIGN.md).