--- 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.