Decorator

The four participants

Every textbook Decorator has the same four roles. In coffee terms:

• Component interface — Coffee, with cost() and description(). This is the shape everyone agrees on; both real coffees and wrappers implement it.
• Concrete Component — Espresso, the plain object at the core of every stack. It answers cost() with its own price and doesn't know wrappers exist.
• Base Decorator — a small abstract class that holds a reference to a wrapped `Coffee` and, by default, just forwards every call to it. Its only job is the plumbing.
• Concrete Decorators — Milk, Mocha, Whip, Caramel. Each extends the base decorator and overrides methods to add its own bit: its price, its name — then delegates inward.

interface Coffee {
  cost(): number;
  description(): string;
}

class Espresso implements Coffee {          // the core
  cost() { return 2.5; }
  description() { return "Espresso"; }
}

abstract class CoffeeDecorator implements Coffee {
  constructor(protected wrapped: Coffee) {} // 🔑 holds what it wraps
  cost() { return this.wrapped.cost(); }    // default: just delegate
  description() { return this.wrapped.description(); }
}

class Milk extends CoffeeDecorator {
  cost() { return this.wrapped.cost() + 0.5; }        // add, then delegate
  description() { return this.wrapped.description() + " + Milk"; }
}

class Whip extends CoffeeDecorator {
  cost() { return this.wrapped.cost() + 0.7; }
  description() { return this.wrapped.description() + " + Whip"; }
}

const order: Coffee = new Whip(new Milk(new Espresso()));
order.cost();          // 3.7  — 2.5 + 0.5 + 0.7
order.description();   // "Espresso + Milk + Whip"

How one cost() call unwinds through the layers

Call cost() on new Whip(new Milk(new Espresso())) and the call travels inward: Whip.cost() asks Milk, Milk.cost() asks Espresso. Then the answers come back out: Espresso returns $2.50, Milk adds $0.50 and returns $3.00, Whip adds $0.70 and returns $3.70. Each layer does one small job on the way back. The caller never sees any of this — it called cost() on a Coffee and got a number.

Why not just subclass? Do the math

With 4 optional add-ons, covering every combination with subclasses means EspressoWithMilk, EspressoWithMilkAndMocha, EspressoWithMilkAndWhip… — one class per subset, which is 2⁴ = 16 classes. Add a fifth add-on and it's 32. With Decorator you write 4 small wrapper classes, ever, and compose any of the 16 combinations at runtime by stacking. That's the subclass explosion the pattern kills — and it's [[open-closed]] in action: you extend behavior by adding new wrapper classes, never by modifying Espresso.

You've already used this pattern

• Java I/O streams — new BufferedReader(new FileReader("log.txt")): FileReader is the core component, BufferedReader is a decorator that adds buffering while staying a Reader. GZIPInputStream, DataInputStream — same idea, stackable.
• Web middleware — logging, auth, and compression layers each wrap a handler, do their bit, and delegate to the next. A request unwinds through them exactly like cost() unwinds through the coffee stack.
• GUI components — the Gang of Four's original example: a ScrollDecorator or BorderDecorator wraps any visual component and adds scrollbars or a border without the component knowing.

Don't confuse it with two neighbors: [[adapter]] also wraps one object, but its goal is to change the interface so incompatible code can talk; Decorator keeps the interface and adds behavior. And [[composite]] aggregates many children behind one interface, while a Decorator wraps exactly one object and enhances it.

Reach for Decorator when behavior comes in optional, stackable pieces

• Add responsibilities at runtime — the caller decides while the program runs which extras an object gets (this order wants milk and whip; the next one doesn't). Inheritance fixes behavior at compile time; wrapping composes it on the fly.
• Combinations of optional features — buffering + encryption + compression on a stream; logging + auth + rate-limiting on a handler. A handful of decorators covers every subset; subclasses would explode (n features → 2ⁿ classes).
• When subclassing is closed to you — the class is final, comes from a third-party library, or you only ever hold it behind an interface. You can't extend it, but you can always wrap it.
• Keeping the core class small — Espresso stays a dumb, honest espresso. Every extra lives in its own tiny class with one job. That's [[open-closed]]: open to extension by new wrappers, closed to modification.