Structural & behavioral patterns

Names for common code shapes

A design pattern is a name for a shape of code that shows up again and again. Patterns are not rules. You don't have to use them in every file. They give a team short words for common jobs, such as:

• "This function wraps another one and adds a log line."
• "This function turns another company's data into our shape."
• "This action can be undone."

The table below compares the four structural patterns. Read each row as: the pattern, what it does, and one small example from this lesson.

Some nearby patterns have their own lessons:

• Factories and modules are in creational patterns.
• Events that many listeners can hear are in observer & pub/sub.
• Reducers and stores come next, in state management.
• How to lay out a whole project is in app architecture.

A decorator wraps a function or an object and adds a little extra work around it. The original code doesn't change. A function that wraps another function like this is a higher-order function: it takes a function and gives back a new one. Some common decorators:

• withLogging(fn) prints a line each time fn is called.
• withRetry(fn) calls fn again when it fails.
• memoize(fn) remembers earlier answers, so fn doesn't run twice for the same input.

The memoization lesson goes deeper on remembering answers. The decorators lesson covers the @decorator syntax, a newer JavaScript feature for classes. This section is about the pattern, which works with plain functions.

function withTax(fn) {
  return (price) => Math.round(fn(price) * 1.1);
}
const priceWithTax = withTax((price) => price);
console.log(priceWithTax(10));

Line 1 takes a function, fn. Line 2 gives back a new function. The new function calls fn, multiplies the result by 1.1 to add 10% tax, and rounds it with Math.round. The rounding is needed because 10 * 1.1 is really 11.000000000000002 in JavaScript. Line 4 wraps a function that just returns the price it gets. Line 5 prints 11.

One warning: if you wrap a method that uses this, the wrapper must pass this along. Otherwise the method loses its object.

1function withLogging(fn) {2  return function logged(...args) {3    console.log("calling " + fn.name + "(" + args.join(", ") + ")");4    const result = fn(...args);5    console.log("returned " + result);6    return result;7  };8}9 10function withMemo(fn) {11  const cache = new Map();12  return function memoized(value) {13    if (cache.has(value)) return cache.get(value);14    const result = fn(value);15    cache.set(value, result);16    return result;17  };18}19 20function priceWithTax(price) {21  return Number((price * 1.1).toFixed(2));22}23 24const loggedPrice = withLogging(withMemo(priceWithTax));25console.log(loggedPrice(20));26console.log(loggedPrice(20));

Read it in parts:

• Lines 1–8: withLogging gives back a new function, logged. It prints the call, calls the original on line 4, then prints the result.
• Lines 10–18: withMemo makes a cache on line 11. A cache is a store of earlier answers; here it is a Map from each input to its answer. If the input is already there, line 13 returns the saved answer. If not, line 14 calls the original and line 15 saves the answer. The cache stays alive between calls because memoized is a closure: a function that keeps the variables around it.
• Lines 20–22: priceWithTax is the original function. It adds 10% tax and rounds to two decimal places.
• Line 24 wraps it twice. A call goes through logged first, then memoized, then priceWithTax.
• Lines 25 and 26 call it twice with 20. Each call prints calling memoized(20), returned 22, and 22. The log says memoized because that is the name of the function withLogging wraps.

You can wrap an object the same way. The wrapper object has the same methods. Each method calls the original object's method and adds some extra work, such as timing or a permission check.

A proxy is different. It is a stand-in: an object that sits in front of another object, called the target. Code talks to the proxy, and the proxy decides what happens with each read and write. You can write a proxy as a plain object, or use JavaScript's built-in Proxy together with Reflect.

const user = { name: "Asha" };
const safeUser = new Proxy(user, {
  get(target, key) { return key in target ? target[key] : "unknown"; },
});
console.log(safeUser.name, safeUser.role);

Line 1 makes the target, user. Line 2 puts a Proxy in front of it. Line 3 is a trap: a function the proxy runs when code reads a property. If the target has the property, the trap returns it. If not, it returns "unknown". So line 5 prints Asha unknown, and user itself doesn't change.

Each trap is one more step between your code and the object, so errors are harder to trace. If you don't need to catch reads and writes, a plain function is simpler.

1const stock = { notebook: 3 };2 3const guardedStock = {4  get(name) {5    return name in stock ? stock[name] : 0;6  },7  set(name, value) {8    if (value < 0) throw new Error("Stock cannot be negative");9    stock[name] = value;10  },11};12 13guardedStock.set("pen", 2);14console.log(guardedStock.get("pen"));15console.log(guardedStock.get("missing"));16 17const settings = new Proxy({ theme: "dark" }, {18  get(target, key, receiver) {19    console.log("read " + String(key));20    return Reflect.get(target, key, receiver);21  },22  set(target, key, value, receiver) {23    if (key === "theme" && !["dark", "light"].includes(value)) {24      throw new Error("Unsupported theme");25    }26    return Reflect.set(target, key, value, receiver);27  },28});29 30console.log(settings.theme);31settings.theme = "light";32console.log(settings.theme);

Read it in three parts:

• Lines 3–11 are a plain stand-in object. Its get returns 0 for an item that isn't in stock. Its set throws an error for a number below 0. Line 14 prints 2, and line 15 prints 0 for "missing", because line 13 added 2 pens and nothing called "missing".
• Lines 17–28 use the built-in Proxy. The get trap prints read theme on every read (line 19). The set trap on line 22 throws for any theme other than "dark" or "light". Line 26 calls Reflect.set, which does the normal write. Reflect has one function for each normal object action, so a trap can do its check and then hand the action back.
• Line 30 prints read theme and dark. Line 31 changes the theme. Line 32 prints read theme and light.

Proxies are good for checking new values, logging, loading data only when it is first read, and controlling who can change what. If a plain function call does the job, use that. It is easier to debug.

An API is the set of functions and data shapes that one piece of code offers to others. Data from outside your app often comes in a shape you don't want. It might come from a weather service, a payment company, or an old library. An adapter is a small function that turns that outside shape into your app's own shape.

The adapter sits at the boundary: the place where outside data enters your app. Then the rest of your app never sees the outside shape. If the outside shape changes, only the adapter changes.

function adaptUser(user) {
  return { name: user.full_name, admin: user.role === "admin" };
}
console.log(adaptUser({ full_name: "Asha", role: "admin" }));

The outside data calls the name full_name. Your app wants name. Line 2 copies the name across. It also turns the text "admin" into the true-or-false value admin: true. Line 4 prints { name: 'Asha', admin: true }. This happens once, at the boundary, not in every part of the app that shows a profile.

1function fromWeatherApiA(response) {2  return { city: response.city, celsius: response.tempC };3}4 5function fromWeatherApiB(response) {6  return {7    city: response.location.name,8    celsius: Math.round((response.current.tempF - 32) * 5 / 9),9  };10}11 12function readLegacyProfile(id, callback) {13  callback(null, { id, name: "Ada" });14}15 16function profilePromise(id) {17  return new Promise((resolve, reject) => {18    readLegacyProfile(id, (error, profile) => {19      if (error) reject(error);20      else resolve(profile);21    });22  });23}24 25const reports = [26  fromWeatherApiA({ city: "Chennai", tempC: 31 }),27  fromWeatherApiB({ location: { name: "London" }, current: { tempF: 59 } }),28];29 30console.log(reports.map((report) => report.city + ":" + report.celsius).join(" | "));31profilePromise(7).then((profile) => console.log(profile.name));

Read it in parts:

• Lines 1–3 and 5–10 read two different weather shapes. Service A gives tempC, in Celsius. Service B gives tempF, in Fahrenheit, inside other objects. Both adapters return the same shape: { city, celsius }.
• Lines 25–28 run both adapters. Line 30 prints Chennai:31 | London:15, because 59°F is 15°C.
• Lines 12–14 are an old function that takes a callback: a function it calls when it is done. Lines 16–23 adapt it so it returns a promise instead: an object that will hold the result once it arrives. Line 31 prints Ada.

Now callers can use .then() or await instead of a callback. The promisification and async/await lessons go deeper.

A facade is one simple function in front of a subsystem: a group of parts that must be called in several steps. The rest of your app calls the facade. It doesn't need to know the steps or their order.

const kitchen = {
  boil() { return "boiled"; },
  pour() { return "tea"; },
};
const makeTea = () => { kitchen.boil(); return kitchen.pour(); };
console.log(makeTea());

Lines 1–4 are the subsystem: a kitchen with two steps. Line 5 is the facade. makeTea() boils, then pours, and returns what pour() gives back. Line 6 prints tea. The caller only knows makeTea().

A facade isn't worth it for a single step that only one place uses. It helps when several parts of the app need the same steps in the same order.

1function createMediaFacade(video, analytics) {2  return {3    play(title) {4      video.load(title);5      video.setVolume(0.7);6      analytics.track("play:" + title);7      return video.start();8    },9  };10}11 12const video = {13  load(title) { console.log("load " + title); },14  setVolume(level) { console.log("volume " + level); },15  start() { return "playing"; },16};17const analytics = { track(event) { console.log("track " + event); } };18 19const media = createMediaFacade(video, analytics);20console.log(media.play("intro"));

createMediaFacade gets a video player and an analytics tool: code that counts what users do. Its play method on line 3 does four steps:

1. Line 4 loads the video.
2. Line 5 sets the volume.
3. Line 6 records the play.
4. Line 7 starts the video and returns "playing".

Line 19 builds the facade. Line 20 is the one call the rest of the app makes. It prints load intro, volume 0.7, track play:intro, and then playing.

The steps inside can change later without changing any caller. A fetch helper is often a facade too: one call that adds login headers, reads the JSON, and turns failures into clear error messages.

A strategy is one of several functions that do the same job in different ways. They all take the same input and give back the same kind of result. You keep them in one object, each under a name, and pick one by its name while the program runs.

This can replace a long switch statement or a long if/else chain. Shipping prices, discounts, sorting, and formatting are common examples.

const formatters = {
  upper: (name) => name.toUpperCase(),
  lower: (name) => name.toLowerCase(),
};
console.log(formatters.upper("Asha"));

Both functions take a name and return text. Line 5 picks upper and prints ASHA. If there are only two or three choices that never change, a plain if is often clearer.

1const shippingStrategies = {2  standard(cart) {3    return cart.subtotal >= 75 ? 0 : 7;4  },5  express(cart) {6    return 12 + cart.items * 2;7  },8  pickup() {9    return 0;10  },11};12 13function quoteShipping(cart, strategyName) {14  return shippingStrategies[strategyName](cart);15}16 17const cart = { subtotal: 80, items: 2 };18console.log(quoteShipping(cart, "standard"));19console.log(quoteShipping(cart, "express"));20console.log(quoteShipping(cart, "pickup"));

Try each button. Lines 1–11 hold the three shipping functions. Line 14 picks one by its name, with shippingStrategies[strategyName], and calls it with the cart. For this cart:

• standard is 0, because the total, 80, is at least 75.
• express is 16: 12, plus 2 for each of the 2 items.
• pickup is always 0.

The caller only passes a cart and a name. To add overnight shipping, you add one more function to the object. You don't edit quoteShipping. A strategy is worth it when the choices grow, come from settings, or need their own tests.

A command is an object that stands for one action. It has two methods:

• execute() does the action.
• undo() reverses it.

A history manager keeps commands in two stacks. A stack is a list where you add to the end and take from the end, like a pile of plates. The manager doesn't need to know what each command does. It only calls execute() and undo(). Text editors, drawing apps, task queues, and activity logs use this shape.

const todo = { done: false };
const complete = {
  execute() { todo.done = true; },
  undo() { todo.done = false; },
};
complete.execute();
console.log(todo.done);

Line 1 is a to-do item that is not done yet. Lines 2–5 are the command. Line 6 runs it, so line 7 prints true. Calling complete.undo() would set it back to false.

Each command must know exactly how to reverse its own work. The editor below adds text at the end, so its undo removes the same number of characters from the end. That only works because nothing else changes the text in between. Real editors save a copy of the old text, or a full reverse step, for bigger edits.

1function createEditor(initialText = "") {Run2  let text = initialText;3  return {4    getText: () => text,5    insert: (value) => { text += value; },6    removeEnd: (count) => { text = text.slice(0, -count); },7  };8}9 10function insertText(editor, value) {11  return {12    execute() { editor.insert(value); },13    undo() { editor.removeEnd(value.length); },14    label: "insert " + JSON.stringify(value),15  };16}17 18function createCommandManager() {19  const undoStack = [];20  const redoStack = [];21  return {22    run(command) {23      command.execute();24      undoStack.push(command);25      redoStack.length = 0;26    },27    undo() {28      const command = undoStack.pop();29      if (!command) return;30      command.undo();31      redoStack.push(command);32    },33    redo() {34      const command = redoStack.pop();35      if (!command) return;36      command.execute();37      undoStack.push(command);38    },39    counts: () => ({ undo: undoStack.length, redo: redoStack.length }),40  };41}42 43const editor = createEditor("Hi");44const history = createCommandManager();45history.run(insertText(editor, "!"));46console.log(editor.getText(), JSON.stringify(history.counts()));47history.undo();48console.log(editor.getText(), JSON.stringify(history.counts()));49history.redo();50console.log(editor.getText(), JSON.stringify(history.counts()));51history.undo();52history.run(insertText(editor, "?"));53console.log(editor.getText(), JSON.stringify(history.counts()));

Step through the whole history:

1. Line 45 runs a command that adds !. The text is Hi!.
2. Line 47 undoes it. The command moves from undoStack to redoStack.
3. Line 49 redoes it. The command moves back.
4. Line 51 undoes it again.
5. Line 52 runs a new command that adds ?. The text is Hi?.

The main rule is on line 25: a new command empties the redo stack. Once the user makes a new edit, the old ! belongs to a path they left, so it can't be redone.

Middleware is a chain of functions that each do part of the work on one request. Each function gets two things:

• a context object, shared by the whole chain, that holds the request's data;
• next(), a function that runs the rest of the chain.

Code before next() runs on the way in. Code after next() runs on the way out, once the rest of the chain is done. Express and Koa, two Node.js server libraries, use this idea. So does Redux, a library for app data, for its own middleware.

const log = [];
const withLabel = (next) => { log.push("before"); next(); log.push("after"); };
withLabel(() => log.push("work"));
console.log(log.join(" > "));

Line 2 is a wrapper. It pushes before, calls next(), then pushes after. Line 3 calls it and passes the main work as next. Line 4 prints before > work > after.

Real middleware also needs a plan for errors. It should also stop a function from calling next() twice, because that would run the rest of the chain twice.

1function compose(middleware) {2  return (context) => {3    let index = -1;4    function dispatch(i) {5      if (i <= index) throw new Error("next() called twice");6      index = i;7      const fn = middleware[i];8      if (!fn) return;9      return fn(context, () => dispatch(i + 1));10    }11    dispatch(0);12    return context.log;13  };14}15 16const stack = [17  (ctx, next) => { ctx.log.push("auth before"); next(); ctx.log.push("auth after"); },18  (ctx, next) => { ctx.log.push("timing before"); next(); ctx.log.push("timing after"); },19  (ctx) => { ctx.log.push("handler"); },20];21 22const app = compose(stack);23console.log(app({ log: [] }).join(" -> "));

The runner is a function called compose. It keeps a counter, index, for the last middleware it ran. If a function calls next() twice, line 5 throws an error. Line 9 calls the current middleware and hands it a next that runs the one after it.

The async version below changes one thing: next() returns a promise, and each middleware waits for it with await.

1function composeAsync(middleware) {Run2  return async (context) => {3    let index = -1;4    async function dispatch(i) {5      if (i <= index) throw new Error("next() called twice");6      index = i;7      const fn = middleware[i];8      if (!fn) return;9      await fn(context, () => dispatch(i + 1));10    }11    await dispatch(0);12    return context.log;13  };14}15 16const stack = [17  async (ctx, next) => {18    ctx.log.push("auth before");19    await next();20    ctx.log.push("auth after");21  },22  async (ctx, next) => {23    ctx.log.push("timing before");24    await next();25    ctx.log.push("timing after");26  },27  async (ctx) => {28    ctx.log.push("handler");29  },30];31 32async function main() {33  const app = composeAsync(stack);34  const log = await app({ log: [] });35  console.log(log.join(" -> "));36}37main();

Because of await next(), the order is like the layers of an onion. Auth starts on the outside. Timing starts inside it. The handler is the middle. Then timing finishes, and auth finishes last.

Choosing a pattern without extra code

Patterns often mix. A decorator may use a closure. A proxy may keep a cache. A facade may call adapters. That is normal. Pick the name that best explains the job of the code you are writing.

The table below says when each pattern is worth it. Read each row as: the pattern, how often it pays off, and the job that calls for it.

1const examples = [2  "withRetry(fetchJson)",3  "new Proxy(settings, traps)",4  "fromWeatherApiB(response)",5  "shippingStrategies.express(cart)",6  "history.run(insertText(editor, '!'))",7  "await logger(ctx, next)",8];9 10console.log(examples.length);

Each text in this list is a call you met in this lesson. Line 10 prints 6, the number of calls. Now sort the same calls by the job they do.

Three more patterns are worth knowing by name:

• Composite treats one item and a group of items the same way, like a file and a folder.
• Iterator is a standard way to walk through a collection, one item at a time.
• Chain of responsibility passes a request along a line of handlers until one of them handles it. Middleware is a kind of chain where every step shares one context and calls next().

Common mix-ups

• "Decorator means the @decorator syntax." The syntax is one language feature. The pattern is just wrapping, and plain functions can do it.
• "Proxy always means the built-in Proxy." A plain stand-in object is also a proxy when it guards how code reads or changes another object.
• "Adapter and facade mean the same thing." An adapter changes a shape. A facade hides several steps behind one call.
• "A strategy is always better than switch." A short switch is often clearer, until the choices grow or come from settings.
• "Middleware is only for servers." Redux, logging in the browser, feature switches, and analytics can all use the same chain idea.

The table below pairs up patterns that look alike. Read each row as: the two names, one question that tells them apart, and which one to pick.

Practice exercises

function withLogging(fn) {
  return (...args) => {
    const result = fn(...args);
    console.log("result:" + result);
    return result;
  };
}
const shout = withLogging((word) => word.toUpperCase());
console.log(shout("pattern"));

function withLogging(fn) {
  return (...args) => {
    const result = fn(...args);
    console.log("result:" + result);
    return result;
  };
}
const shout = withLogging((word) => word.toUpperCase());
console.log(shout("pattern"));

function adaptPaymentA(response) {
  return { id: response.payment_id, cents: response.amount_cents, ok: response.status === "paid" };
}
const payment = adaptPaymentA({ payment_id: "p1", amount_cents: 1299, status: "paid" });
console.log(payment.id + ":" + payment.cents + ":" + payment.ok);

function adaptPaymentA(response) {
  return { id: response.payment_id, cents: response.amount_cents, ok: response.status === "paid" };
}
const payment = adaptPaymentA({ payment_id: "p1", amount_cents: 1299, status: "paid" });
console.log(payment.id + ":" + payment.cents + ":" + payment.ok);

const discounts = {
  student: (total) => total * 0.8,
  none: (total) => total,
};
console.log(discounts.student(50));

const discounts = {
  student: (total) => total * 0.8,
  none: (total) => total,
};
console.log(discounts.student(50));

function createEditor(text = "") {
  return {
    text,
    insert(value) { this.text += value; },
    removeEnd(count) { this.text = this.text.slice(0, -count); },
  };
}
function insertText(editor, value) {
  return {
    execute() { editor.insert(value); },
    undo() { editor.removeEnd(value.length); },
  };
}
const undo = [];
const redo = [];
const editor = createEditor("A");
const command = insertText(editor, "B");
command.execute();
undo.push(command);
undo.pop().undo();
redo.push(command);
insertText(editor, "?").execute();
redo.length = 0;
console.log(editor.text + " redo=" + redo.length);

function createEditor(text = "") {
  return {
    text,
    insert(value) { this.text += value; },
    removeEnd(count) { this.text = this.text.slice(0, -count); },
  };
}
function insertText(editor, value) {
  return {
    execute() { editor.insert(value); },
    undo() { editor.removeEnd(value.length); },
  };
}
const undo = [];
const redo = [];
const editor = createEditor("A");
const command = insertText(editor, "B");
command.execute();
undo.push(command);
undo.pop().undo();
redo.push(command);
insertText(editor, "?").execute();
redo.length = 0;
console.log(editor.text + " redo=" + redo.length);

const log = [];
const outer = (next) => { log.push("outer before"); next(); log.push("outer after"); };
const inner = (next) => { log.push("inner before"); next(); log.push("inner after"); };
outer(() => inner(() => log.push("handler")));
console.log(log.join(" > "));

const log = [];
const outer = (next) => { log.push("outer before"); next(); log.push("outer after"); };
const inner = (next) => { log.push("inner before"); next(); log.push("inner after"); };
outer(() => inner(() => log.push("handler")));
console.log(log.join(" > "));

Check your understanding

Key takeaways

• A decorator wraps a function or object and adds work around it. A proxy stands in front of an object and guards it.
• An adapter changes outside data into your shape. A facade hides several steps behind one call.
• A strategy is one of several functions, picked by name while the program runs.
• A command is an action object with execute() and undo(), so a history can undo and redo it.
• Middleware is a chain of functions joined by next(). With await next(), the after lines run on the way out.

Next, state management shows how to keep your app's data in one place and change it step by step, with actions and reducers, as the app grows.