Composition & pipelines

Chain small functions into bigger ones

Code is easier to read when each function does one small job. One function trims a string. Another checks a form. Another adds up a total. Composition is a way to join small functions like these into one bigger function, without writing calls inside calls inside calls.

This lesson uses three ideas from earlier lessons: higher-order functions (functions that take or return functions), pure functions, and currying. In this lesson you will:

• build two small helpers, compose and pipe;
• shape your own helpers so they fit together;
• look at the values in the middle of a chain with tap;
• chain functions that have to wait, like network requests;
• read the planned |> syntax, which JavaScript does not have yet.

const trim = (text) => text.trim();
const titleCase = (text) => text[0].toUpperCase() + text.slice(1);
const pipe = (...fns) => (input) =>
  fns.reduce((value, fn) => fn(value), input);
const formatTea = pipe(trim, titleCase);

console.log(formatTea("  tea  "));

Both functions here are unary. That means they take one input and return one output. In plain words, line by line:

1. Line 1: trim removes the spaces at the start and end of a string.
2. Line 2: titleCase turns the first letter into a capital letter.
3. Lines 3–4: pipe joins functions together. You'll build it step by step below.
4. Line 5: formatTea runs trim first, then titleCase.
5. Line 7: prints Tea, because titleCase gets the text after it was trimmed.

There are four ways to write a chain of steps. Read each row of the table as: "when I write this, the steps run in this direction."

One rule holds for the whole lesson: each stage takes one value and returns the next value. A stage can break this rule. It might change data outside itself, throw an error, or return the wrong thing. Then the pipeline is harder to trust.

Thinking in steps helps when something goes wrong. You can ask two questions:

• Which stage got the wrong input?
• Which stage gave the wrong output to the next stage?

The rest of the lesson shows how to answer both questions in code.

compose is a helper that joins functions. The name comes from math. compose(square, increment, double)(3) means the same as square(increment(double(3))). The innermost call, double(3), runs first. So compose runs the functions from right to left. Many beginners read it in the wrong direction at first.

const trim = (text) => text.trim();
const titleCase = (text) => text[0].toUpperCase() + text.slice(1);
const pipe = (...fns) => (input) =>
  fns.reduce((value, fn) => fn(value), input);
const formatTea = pipe(trim, titleCase);

console.log(formatTea("  tea  "));

This example works because trim and titleCase have the same shape: one input, one output. A function that needs two different inputs can't go straight into this pipeline. First you must do one of two things:

• fill in one input ahead of time, with currying;
• or wrap the call in a new function that takes just one input.

1const double = (value) => value * 2;Run2const increment = (value) => value + 1;3const square = (value) => value * value;4 5function compose(...fns) {6  return (input) => {7    return fns.reduceRight((value, fn) => fn(value), input);8  };9}10 11const transform = compose(square, increment, double);12console.log(transform(3));

pipe runs the other way. The value starts on the left. It goes through the functions in the order you wrote them. Many teams prefer pipe for page code and data cleanup, because it reads like a recipe, from first step to last.

1const trim = (text) => text.trim();Run2const lower = (text) => text.toLowerCase();3const dash = (text) => text.replaceAll(" ", "-");4 5function pipe(...fns) {6  return (input) => {7    return fns.reduce((value, fn) => fn(value), input);8  };9}10 11const toSlug = pipe(trim, lower, dash);12console.log(toSlug("  Composition Lesson  "));

Building them with reduce and reduceRight

Inside, each helper is one call to reduce. reduce walks through an array and keeps a running result. That running result is called the accumulator. Here the accumulator is not a sum. It is the value moving through the chain. On each turn, reduce calls one function with the value and keeps what it returns.

1. pipe uses reduce. It starts at the first function in the array and moves forward.
2. compose uses reduceRight. It starts at the last function in the array and moves backward.
3. The starting accumulator is the input. Without it, the first function would not get the original data.

The two step-throughs above run the lesson's real code. Go back and replay them until the order feels natural: compose starts on the right, and pipe starts on the left.

const pipe = (...fns) => (input) =>
  fns.reduce((value, fn) => fn(value), input);

console.log(pipe()(7));
console.log(pipe((value) => value + 1)(7));

Line 4 has no stages, so pipe()(7) gives back the input, 7, unchanged. Line 5 has one stage that adds 1, so the same input becomes 8. This is why reduce needs the input as its starting accumulator.

A stage fits a pipeline most easily when it is unary: one input, one output. But many useful helpers also need a setting:

• a filter needs a test to run on each item;
• a join needs a separator, like ", ";
• a date formatter needs a language.

A data-last helper takes the setting first. It returns a new unary function that waits for the data. A data-first helper takes the data first and the setting second. The table compares the two. Read each row as: "a helper shaped like this is called like this, and this is how it fits in a pipeline."

That is why helper libraries like lodash/fp and Ramda make their helpers data-last and curried. You set up each stage now. Later, pipe passes in the list. The final code can be point-free: you never write a name for the data, such as (items) =>, at each stage.

const getTitle = (lesson) => lesson.title;
const titles = (lessons) => lessons.map(getTitle);
const lessons = [{ title: "Composition" }];

console.log(titles(lessons).join(", "));

Line 1 names the function getTitle. Line 2 names the list lessons. That is not point-free, but titles still works fine as a stage in a pipeline. It is often clearer than a row of nameless functions. Point-free style is a choice, not a rule. Keep a name when it explains the data or makes a mistake easier to find.

1const lessons = [2  { title: "Currying", published: true },3  { title: "Composition", published: true },4  { title: "Memoization", published: false },5];6const includeDrafts = false;7 8const filter = (predicate) => (items) => items.filter(predicate);9const map = (fn) => (items) => items.map(fn);10const join = (separator) => (items) => items.join(separator);11const pipe = (...fns) => (input) =>12  fns.reduce((value, fn) => fn(value), input);13 14const visibleTitles = pipe(15  includeDrafts ? (items) => items : filter((lesson) => lesson.published),16  map((lesson) => lesson.title),17  join(" -> "),18);19 20console.log(visibleTitles(lessons));

Data-last is not better than data-first in every case. Data-first calls are simpler when you already have the data. Data-last calls help when you build stages to reuse before the data arrives.

A pipeline is easy to read when it works. When it breaks, you can't see the values in the middle. A tap helper fixes that. It takes the current value, logs it, and returns the same value unchanged.

1const pipe = (...fns) => (input) =>2  fns.reduce((value, fn) => fn(value), input);3 4const tap = (label) => (value) => {5  const shown = Array.isArray(value) ? value.join(",") : value;6  console.log(label + ":", shown);7  return value;8};9 10const normalize = (text) => text.trim().toLowerCase();11const words = (text) => text.split(/\s+/);12const dropShort = (items) => items.filter((word) => word.length > 3);13 14const keywords = pipe(15  normalize,16  tap("normalized"),17  words,18  tap("words"),19  dropShort,20  tap("filtered"),21);22 23console.log(keywords("  Compose small functions well  ").join("|"));

The return value is what matters. console.log(value) returns undefined. If a stage only calls console.log, the next stage gets undefined. A proper tap returns value after it logs it.

Real page code often has to wait. It loads a cart, adds prices, checks who the user is, and builds a receipt. A function that waits returns a promise: an object that holds a result that will arrive later. A normal pipe would hand the promise itself to the next stage, not the result inside it.

pipeAsync fixes this. Its accumulator is a promise, so each stage waits for the stage before it to finish.

1const pipeAsync = (...fns) => (input) =>2  fns.reduce(3    (promise, fn) => promise.then(fn),4    Promise.resolve(input),5  );6 7const getCart = async (userId) => ({ userId, items: ["notebook", "pen"] });8const addPrices = async (cart) => ({ ...cart, total: 12 });9const formatReceipt = async (cart) => `User ${cart.userId}: $${cart.total}`;10 11async function main() {12  const receipt = await pipeAsync(getCart, addPrices, formatReceipt)(42);13  console.log(receipt);14}15 16main();

The stages still run one after another. Use this when stage two really needs the result of stage one. If two requests don't depend on each other, start them together with Promise.all. Otherwise one request waits for the other for no reason.

const pipeAsync = (...fns) => (input) =>
  fns.reduce((promise, fn) => promise.then(fn), Promise.resolve(input));
const loadCart = async () => ({ total: 0 });
const requireItems = async (cart) => {
  if (cart.total === 0) throw new Error("empty cart");
  return cart;
};

pipeAsync(loadCart, requireItems)(undefined)
  .then(() => "ready")
  .catch((error) => "stopped: " + error.message)
  .then(console.log);

The first stage, loadCart, returns a cart with a total of 0. So line 5 throws an error. An error thrown inside an async function makes its promise reject, which means it fails. Because of that, the .then on line 10 is skipped. Line 11 catches the failure and turns it into the text stopped: empty cart. In a real app, you might let the error reach the page's error handler instead.

You may see |> in blog posts. It is a proposal: a plan for new syntax. TC39, the group that designs JavaScript, is still discussing it. It would let you write pipelines without a helper function.

The official proposal page lists this version, called "Hack-style", at Stage 2. That means it is not finished. It is not part of JavaScript. Node 22 and today's browsers can't run it, unless a tool first rewrites the code.

1const pipe = (...fns) => (input) =>2  fns.reduce((value, fn) => fn(value), input);3 4const slug = pipe(5  (text) => text.trim(),6  (text) => text.toLowerCase(),7  (text) => text.replaceAll(" ", "-"),8)("  Hello Pipeline  ");9 10console.log(slug);

1const slug = "  Hello Pipeline  "2  |> %.trim()3  |> %.toLowerCase()4  |> %.replaceAll(" ", "-");5 6console.log(slug);

The proposal is still worth knowing. It shows what the language wants to make easier: code you read from left to right. Until browsers can run it, any |> example must be marked as not runnable, or shown next to plain JavaScript that does the same thing.

Pipelines work best when each stage is named after what it does for the app: clean up a page address, keep only published lessons, price a cart, check a form, or add request headers. They work badly when every stage is a nameless trick that the reader must puzzle out line by line.

• Formatting: trim text, clean it up, turn it into a web-address-friendly name, and format it for display.
• Checking input: read it, check it, add details, and return a result object.
• Requests: build a URL, add headers, fetch, read the JSON, and turn errors into messages.
• Page state: run pure changes on the data before you save it as the page's state.

const pipe = (...fns) => (input) =>
  fns.reduce((value, fn) => fn(value), input);
const addTax = (cart) => ({ ...cart, total: cart.total * 1.1 });
const formatTotal = (cart) => "$" + cart.total.toFixed(2);
const formatCartTotal = pipe(addTax, formatTotal);

console.log(formatCartTotal({ total: 10 }));

Line 3 makes a new cart object with the tax added. It does not change the cart you passed in. Line 4 turns the final number into text, so formatCartTotal prints $11.00. Line 5 gives the whole pipeline a name, so the line that uses it says what it does.

Common misconceptions

• "compose and pipe are two names for the same thing." Both join functions, but they run in opposite directions.
• "Point-free code is always cleaner." It is clean when the stage names tell the story. It is hard to read when a named variable would explain the data.
• "A plain log can be a pipeline stage." Only if the stage returns the value it got. console.log returns undefined.
• "Async stages work with a normal pipe." A normal pipe passes the promise along as if it were the value. Use pipeAsync, or write the await steps one by one.
• "The pipeline operator is ready, because Babel can read it." Babel is a tool that rewrites new syntax into older JavaScript. A tool that can read |> is not the same as browsers running it.

When a pipeline goes wrong, check these first. Read each row as: "people often think this, but this is what is true."

Follow one value at a time. For questions that ask what code prints, first write down the order the stages run. For questions about |>, ask: is this real JavaScript today, or a plan that still needs a tool to run?

Key takeaways

• compose joins functions from right to left, using reduceRight.
• pipe joins functions from left to right, using reduce.
• Data-last helpers return one-input stages, so you can build pipelines without naming the data.
• tap logs a value and returns it unchanged.
• pipeAsync keeps a promise as its running result, so each stage waits for the one before it.
• The |> pipeline operator is a Stage 2 proposal. You can't run it as JavaScript today.

Up next: Memoization & laziness.