Decorator Pattern · Design Patterns

What is the Decorator pattern?

Decorator means: wrap an object to add behavior at runtime, instead of baking that behavior into a subclass.

Every decorator implements the same interface as the thing it wraps, holds a reference to it, and adds a little extra work before or after forwarding the call. Because a decorator implements the same interface it wraps, decorators stack: you can wrap a decorator in another decorator, and the caller never needs to know how many layers are underneath.

To build one you usually need:

A shared interface (the thing being decorated).
A base decorator that holds the wrapped object and forwards calls to it.
Concrete decorators that override a method to add their own bit of behavior.

The problem it solves

Say drinks can optionally get milk, sugar, or whipped cream, in any combination.

class Coffee:
    def get_description(self) -> str:
        raise NotImplementedError

    def get_cost(self) -> float:
        raise NotImplementedError

public interface Coffee {
    String getDescription();
    double getCost();
}

package coffee

type Coffee interface {
	Description() string
	Cost() float64
}

interface Coffee {
  getDescription(): string;
  getCost(): number;
}

Solving this with subclassing needs a class for every combination: MilkCoffee, SugarCoffee, MilkSugarCoffee, and so on. Three optional toppings already produce eight classes, and each new topping doubles that count again. Decorator solves the same problem with composition instead of a subclass per combination.

How it works

Start with a plain implementation and an abstract decorator that forwards every call by default. Each concrete decorator overrides the methods to add its own contribution.

class SimpleCoffee(Coffee):
    def get_description(self) -> str:
        return "Simple Coffee"

    def get_cost(self) -> float:
        return 2.0


class CoffeeDecorator(Coffee):
    def __init__(self, coffee: Coffee) -> None:
        self._coffee = coffee

    def get_description(self) -> str:
        return self._coffee.get_description()

    def get_cost(self) -> float:
        return self._coffee.get_cost()


class MilkDecorator(CoffeeDecorator):
    def get_description(self) -> str:
        return f"{self._coffee.get_description()}, Milk"

    def get_cost(self) -> float:
        return self._coffee.get_cost() + 0.5


class SugarDecorator(CoffeeDecorator):
    def get_description(self) -> str:
        return f"{self._coffee.get_description()}, Sugar"

    def get_cost(self) -> float:
        return self._coffee.get_cost() + 0.2


# use
coffee: Coffee = SimpleCoffee()
coffee = MilkDecorator(coffee)
coffee = SugarDecorator(coffee)

print(coffee.get_description())  # "Simple Coffee, Milk, Sugar"
print(coffee.get_cost())         # 2.7

public class SimpleCoffee implements Coffee {
    @Override
    public String getDescription() {
        return "Simple Coffee";
    }

    @Override
    public double getCost() {
        return 2.0;
    }
}

public abstract class CoffeeDecorator implements Coffee {
    protected final Coffee coffee;

    protected CoffeeDecorator(Coffee coffee) {
        this.coffee = coffee;
    }

    @Override
    public String getDescription() {
        return coffee.getDescription();
    }

    @Override
    public double getCost() {
        return coffee.getCost();
    }
}

public class MilkDecorator extends CoffeeDecorator {
    public MilkDecorator(Coffee coffee) {
        super(coffee);
    }

    @Override
    public String getDescription() {
        return coffee.getDescription() + ", Milk";
    }

    @Override
    public double getCost() {
        return coffee.getCost() + 0.5;
    }
}

public class SugarDecorator extends CoffeeDecorator {
    public SugarDecorator(Coffee coffee) {
        super(coffee);
    }

    @Override
    public String getDescription() {
        return coffee.getDescription() + ", Sugar";
    }

    @Override
    public double getCost() {
        return coffee.getCost() + 0.2;
    }
}

// use
Coffee coffee = new SimpleCoffee();
coffee = new MilkDecorator(coffee);
coffee = new SugarDecorator(coffee);

System.out.println(coffee.getDescription()); // "Simple Coffee, Milk, Sugar"
System.out.println(coffee.getCost());        // 2.7

type SimpleCoffee struct{}

func (c SimpleCoffee) Description() string { return "Simple Coffee" }
func (c SimpleCoffee) Cost() float64       { return 2.0 }

type MilkDecorator struct {
	Coffee Coffee
}

func (m MilkDecorator) Description() string { return m.Coffee.Description() + ", Milk" }
func (m MilkDecorator) Cost() float64       { return m.Coffee.Cost() + 0.5 }

type SugarDecorator struct {
	Coffee Coffee
}

func (s SugarDecorator) Description() string { return s.Coffee.Description() + ", Sugar" }
func (s SugarDecorator) Cost() float64       { return s.Coffee.Cost() + 0.2 }

// use
var coffee Coffee = SimpleCoffee{}
coffee = MilkDecorator{Coffee: coffee}
coffee = SugarDecorator{Coffee: coffee}

fmt.Println(coffee.Description()) // "Simple Coffee, Milk, Sugar"
fmt.Println(coffee.Cost())        // 2.7

class SimpleCoffee implements Coffee {
  getDescription() {
    return 'Simple Coffee';
  }

  getCost() {
    return 2.0;
  }
}

abstract class CoffeeDecorator implements Coffee {
  constructor(protected coffee: Coffee) {}

  getDescription() {
    return this.coffee.getDescription();
  }

  getCost() {
    return this.coffee.getCost();
  }
}

class MilkDecorator extends CoffeeDecorator {
  getDescription() {
    return `${this.coffee.getDescription()}, Milk`;
  }

  getCost() {
    return this.coffee.getCost() + 0.5;
  }
}

class SugarDecorator extends CoffeeDecorator {
  getDescription() {
    return `${this.coffee.getDescription()}, Sugar`;
  }

  getCost() {
    return this.coffee.getCost() + 0.2;
  }
}

// use
let coffee: Coffee = new SimpleCoffee();
coffee = new MilkDecorator(coffee);
coffee = new SugarDecorator(coffee);

console.log(coffee.getDescription()); // "Simple Coffee, Milk, Sugar"
console.log(coffee.getCost());        // 2.7

Each call walks down through the stack: SugarDecorator adds its bit to whatever MilkDecorator returns, which adds its bit to the base coffee. No single class knows the full combination — each one only knows its own small addition, plus how to ask the next layer for the rest.

This is the same shape behind Java’s BufferedInputStream and DataInputStream wrapping a FileInputStream: each layer adds one capability on top of the one before it.

Worked example: decorating an HTTP request

Add authentication and logging to an outgoing request without hardcoding either into the request class.

class HttpRequest:
    def send(self) -> None:
        raise NotImplementedError


class BasicHttpRequest(HttpRequest):
    def __init__(self, url: str) -> None:
        self._url = url

    def send(self) -> None:
        print(f"Sending request to: {self._url}")


class HttpRequestDecorator(HttpRequest):
    def __init__(self, request: HttpRequest) -> None:
        self._request = request

    def send(self) -> None:
        self._request.send()


class AuthDecorator(HttpRequestDecorator):
    def __init__(self, request: HttpRequest, token: str) -> None:
        super().__init__(request)
        self._token = token

    def send(self) -> None:
        print(f"Attaching token: {self._token}")
        super().send()


class LoggingDecorator(HttpRequestDecorator):
    def send(self) -> None:
        print("Logging: sending request")
        super().send()
        print("Logging: request sent")


# use
request: HttpRequest = BasicHttpRequest("https://api.example.com")
request = AuthDecorator(request, "token123")
request = LoggingDecorator(request)
request.send()

public interface HttpRequest {
    void send();
}

public class BasicHttpRequest implements HttpRequest {
    private final String url;

    public BasicHttpRequest(String url) {
        this.url = url;
    }

    @Override
    public void send() {
        System.out.println("Sending request to: " + url);
    }
}

public abstract class HttpRequestDecorator implements HttpRequest {
    protected final HttpRequest request;

    protected HttpRequestDecorator(HttpRequest request) {
        this.request = request;
    }

    @Override
    public void send() {
        request.send();
    }
}

public class AuthDecorator extends HttpRequestDecorator {
    private final String token;

    public AuthDecorator(HttpRequest request, String token) {
        super(request);
        this.token = token;
    }

    @Override
    public void send() {
        System.out.println("Attaching token: " + token);
        super.send();
    }
}

public class LoggingDecorator extends HttpRequestDecorator {
    public LoggingDecorator(HttpRequest request) {
        super(request);
    }

    @Override
    public void send() {
        System.out.println("Logging: sending request");
        super.send();
        System.out.println("Logging: request sent");
    }
}

// use
HttpRequest request = new BasicHttpRequest("https://api.example.com");
request = new AuthDecorator(request, "token123");
request = new LoggingDecorator(request);
request.send();

type HttpRequest interface {
	Send()
}

type BasicHttpRequest struct {
	URL string
}

func (r BasicHttpRequest) Send() {
	fmt.Println("Sending request to:", r.URL)
}

type AuthDecorator struct {
	Request HttpRequest
	Token   string
}

func (a AuthDecorator) Send() {
	fmt.Println("Attaching token:", a.Token)
	a.Request.Send()
}

type LoggingDecorator struct {
	Request HttpRequest
}

func (l LoggingDecorator) Send() {
	fmt.Println("Logging: sending request")
	l.Request.Send()
	fmt.Println("Logging: request sent")
}

// use
var request HttpRequest = BasicHttpRequest{URL: "https://api.example.com"}
request = AuthDecorator{Request: request, Token: "token123"}
request = LoggingDecorator{Request: request}
request.Send()

interface HttpRequest {
  send(): void;
}

class BasicHttpRequest implements HttpRequest {
  constructor(private url: string) {}

  send() {
    console.log(`Sending request to: ${this.url}`);
  }
}

abstract class HttpRequestDecorator implements HttpRequest {
  constructor(protected request: HttpRequest) {}

  send() {
    this.request.send();
  }
}

class AuthDecorator extends HttpRequestDecorator {
  constructor(request: HttpRequest, private token: string) {
    super(request);
  }

  send() {
    console.log(`Attaching token: ${this.token}`);
    super.send();
  }
}

class LoggingDecorator extends HttpRequestDecorator {
  send() {
    console.log('Logging: sending request');
    super.send();
    console.log('Logging: request sent');
  }
}

// use
let request: HttpRequest = new BasicHttpRequest('https://api.example.com');
request = new AuthDecorator(request, 'token123');
request = new LoggingDecorator(request);
request.send();

Neither decorator touched BasicHttpRequest. You can drop either one out of the stack, or add a retry or timing decorator later, without editing anything that already exists.

When it helps

Decorator earns its place when features are genuinely optional and combinable — a coffee with any subset of toppings, or a request that can optionally be authenticated, logged, or retried in any mix.

It also helps when you cannot or should not modify the original class because it is shared, generated, or owned by someone else.

When it hurts

If a feature is not really optional — every caller needs it, always — just put it in the base class.

Decorator assumes each wrapper’s behavior is independent of the others. If your “features” actually depend on each other or conflict in certain orders, plain conditional logic is often more honest than a decorator chain. Long decorator stacks are also genuinely hard to debug — keep them short.

Decorator vs. interceptor

“Interceptor” describes something similar — code that runs before or after an operation for logging, auth, or timing. The difference is ownership.

Decorator is code you compose yourself around an interface you own. Interceptor usually names a role inside a framework’s pipeline — a servlet filter, a Spring HandlerInterceptor — where the framework decides the order and dispatches through it. If you own the composition, call it a decorator. If you are plugging into a framework’s pipeline, “interceptor” or “middleware” is the expected term.

Practical tips

Keep each decorator responsible for exactly one thing.
Every decorator must implement the same interface as the thing it wraps.
Never let a decorator mutate the state of the object it wraps — wrap and forward only.
Avoid decorating for the sake of it: a small dedicated class beats a two-layer decorator stack for one fixed combination.

Check your understanding

What is Decorator, in one sentence?
A pattern that adds behavior to an object at runtime by wrapping it in one or more objects that share its interface.

Why not just use subclassing?
Subclassing needs a new class for every combination of optional features. Decorator combines features by stacking wrappers instead.

Can decorators be stacked in any order?
Usually yes, as long as the behaviors are independent. If they depend on each other, order starts to matter.

What is the biggest risk with Decorator?
Stacking too many layers makes the code hard to trace, and decorators that secretly depend on each other’s order undermine the point of composable behavior.

What to learn next

Next: Facade Pattern — give callers one simple door into a subsystem made of many objects.