- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Functional Design Idioms
- Pipeline Composition
On this page
Composing Pipelines Idiomatically
Published on August 8, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
A pipeline earns its keep when every stage reads as one clear, nameable transformation, laid out so the whole sequence can be scanned top to bottom without backtracking. Getting the mechanics of |> right is only the first step; writing pipelines that stay readable as a codebase grows is a matter of formatting convention, knowing when to break a long chain apart, and handling the specific situations — side effects, functions that can fail — that don't compose through a plain pipeline as cleanly as ordinary transformations do.
Formatting a Pipeline Across Multiple Lines
Once a pipeline has more than one or two stages, putting each stage on its own line, with the |> operators aligned underneath the value they're threading through, makes the sequence far easier to scan than cramming it onto a single line:
let clean_usernames names =
names
|> List.map String.trim
|> List.map String.lowercase_ascii
|> List.filter (fun s -> String.length s > 0)
|> List.sort_uniq String.compare
Read top to bottom, this says exactly what it does: trim whitespace, lowercase everything, drop empty strings, then sort and deduplicate. Each line answers one question — "what happens to the data at this step?" — and the vertical alignment makes it visually obvious that all four operations belong to the same sequential pipeline, rather than four unrelated statements that happen to sit near each other.
Knowing When a Pipeline Has Grown Too Long
A pipeline that keeps accumulating stages eventually stops being easy to take in at a glance, and piling on more |> lines isn't the fix at that point — breaking the computation into named, intermediate steps is. Consider a pipeline that's grown past the point of comfortable readability:
let process_report data =
data
|> List.filter (fun r -> r.status = Active)
|> List.map (fun r -> { r with amount = r.amount *. 1.08 })
|> List.sort (fun a b -> compare b.amount a.amount)
|> List.filteri (fun i _ -> i < 10)
|> List.map (fun r -> Printf.sprintf "%s: %.2f" r.name r.amount)
Splitting this into named pieces gives each stage of the computation its own identity, and often its own type annotation, which documents intent directly rather than leaving a reader to infer it from an anonymous lambda buried mid-chain:
let active_only data = List.filter (fun r -> r.status = Active) data
let apply_tax data = List.map (fun r -> { r with amount = r.amount *. 1.08 }) data
let top_ten data =
data
|> List.sort (fun a b -> compare b.amount a.amount)
|> List.filteri (fun i _ -> i < 10)
let format_line r = Printf.sprintf "%s: %.2f" r.name r.amount
let process_report data =
data
|> active_only
|> apply_tax
|> top_ten
|> List.map format_line
process_report itself is now short enough to read as a genuine summary of the whole computation, and each named helper can be tested, reused, or reasoned about entirely on its own. Roughly three or four stages is a reasonable point to start asking whether a pipeline would communicate its intent more clearly broken apart this way — there's no fixed rule, but a pipeline that no longer fits comfortably on one screen, or whose individual stages are hard to describe in a few words, is usually a pipeline that's grown past what a single flat chain should be doing.
Keep Inline Steps Short
A stage written inline as an anonymous function is fine as long as it stays genuinely short and self-explanatory — List.filter (fun x -> x > 0) reads clearly without needing a name. Once a single stage's logic grows past a short, obvious one-liner, giving it a name (as active_only and apply_tax were given above) usually communicates more than leaving an increasingly elaborate lambda sitting directly inside the pipeline. The pipeline's job is to communicate sequence; a named helper's job is to communicate what a given step actually does — mixing both concerns into one long anonymous function inside a |> chain tends to blur both jobs at once.
Inspecting a Value Mid-Pipeline Without Breaking It
A common temptation while debugging a pipeline is to insert a Printf.printf call to inspect an intermediate value — but a plain print statement doesn't fit into a pipeline cleanly, since it returns unit, not the value that needs to keep flowing to the next stage. Fun.tap solves this directly: it runs a function purely for its side effect and then returns its argument completely unchanged, letting a pipeline stage exist purely for inspection without disrupting the data flowing through it.
let clean_usernames names =
names
|> List.map String.trim
|> Fun.tap (fun l -> Printf.printf "after trim: %d items\n%!" (List.length l))
|> List.map String.lowercase_ascii
|> List.filter (fun s -> String.length s > 0)
The inserted Fun.tap line prints diagnostic information and then hands the exact same list straight on to the next stage — nothing about the pipeline's actual behavior changes, which makes it just as easy to remove again once debugging is finished, without needing to restructure anything around it.
Pipelines and Functions That Can Fail
A plain |> chain assumes every stage takes an ordinary value and returns an ordinary value of some type. The moment a stage instead returns something wrapped — an option or a result, to represent an operation that might fail — a plain pipeline stops composing as simply, since the next stage generally expects an unwrapped value, not the wrapper itself:
let sanitize input =
input
|> String.trim
|> int_of_string_opt (* now produces an int option, not an int *)
Chaining a further transformation onto this int option result isn't as simple as adding another |> line the way the earlier examples were, since none of the ordinary List or String functions know what to do with a value that might be absent. This is a genuinely different composition problem from the one plain pipelines solve, with its own dedicated idioms for chaining fallible steps together cleanly.
Key Takeaways
- Formatting a multi-stage pipeline with one
|>stage per line, aligned under the piped value, makes the sequence scannable top to bottom. - A pipeline that's grown past roughly three or four stages, or whose individual steps are hard to summarize briefly, usually communicates better broken into named, reusable helper functions.
- Short, self-explanatory transformations are fine written inline as anonymous functions; logic complex enough to need its own explanation is usually clearer given its own name.
Fun.taplets a pipeline stage run purely for a side effect, such as debugging output, without disturbing the value being passed on to the next stage.- A plain
|>chain assumes every stage returns an ordinary, unwrapped value; once a stage can fail and returns anoptionorresultinstead, chaining the rest of the pipeline calls for different, dedicated composition idioms.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Immutability-First Design
Next
Option/Result-Based Error Handling
- Formatting a Pipeline Across Multiple Lines
- Knowing When a Pipeline Has Grown Too Long
- Keep Inline Steps Short
- Inspecting a Value Mid-Pipeline Without Breaking It
- Pipelines and Functions That Can Fail
- Key Takeaways
