Decorator pattern explained with examples

Intent

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality. Decorator is one of the seven structural patterns in the Gang of Four (GoF) book, where it is also known as Wrapper.

The problem it solves

Imagine a data store with get(key). Some callers want logging, some want an in-memory cache, some want both, and some want retries for a slow network back end. With inheritance you would write LoggingStore, CachingStore, LoggingCachingStore, RetryingCachingStore and so on: one subclass for every combination, and the combinations are fixed at compile time.

Decorator turns each feature into a small wrapper class. You build the combination you need at run time by wrapping one object in another, and the code that uses the store sees the same interface no matter how many layers there are.

Structure and participants

TypeScript implementation

interface Store {
  get(key: string): string;
}

class SlowStore implements Store {
  get(key: string): string { console.log(`  (database read: ${key})`); return key.toUpperCase(); }
}

// Base decorator: forwards everything to the wrapped store.
abstract class StoreDecorator implements Store {
  constructor(protected inner: Store) {}
  get(key: string): string { return this.inner.get(key); }
}

class LoggingStore extends StoreDecorator {
  get(key: string): string {
    console.log(`get ${key}`);
    return super.get(key);
  }
}

class CachingStore extends StoreDecorator {
  private cache = new Map<string, string>();
  get(key: string): string {
    if (!this.cache.has(key)) this.cache.set(key, super.get(key));
    return this.cache.get(key)!;
  }
}

// Stack features in any order at run time.
const store: Store = new LoggingStore(new CachingStore(new SlowStore()));
console.log(store.get("ada"));
console.log(store.get("ada"));
// get ada
//   (database read: ada)
// ADA
// get ada
// ADA

The second call is logged but answered from the cache, so the database is not read again. If you swap the order, new CachingStore(new LoggingStore(...)), only cache misses are logged. The order of decorators changes the behavior, which is both a feature and a common source of confusion.

Function decorators in TypeScript

When the component is a single function, a decorator can be a higher-order function: it takes a function and returns a new function with the same signature and extra behavior.

function withTiming<A extends unknown[], R>(name: string, fn: (...args: A) => R) {
  return (...args: A): R => {
    const start = performance.now();
    try {
      return fn(...args);
    } finally {
      console.log(`${name} took ${(performance.now() - start).toFixed(1)} ms`);
    }
  };
}

const slowSquare = (n: number) => { for (let i = 0; i < 1e6; i++); return n * n; };
const timedSquare = withTiming("square", slowSquare);
console.log(timedSquare(12)); // square took ... ms, then 144

When to use it, and when not to

Use Decorator when:

• You want to add features such as logging, caching, retries, validation, compression or access checks to individual objects, without affecting other objects of the same class.
• Features must be combined freely, and subclassing would produce a class for every combination.
• You cannot or should not change the original class, for example because it comes from a library.

Avoid it when:

• You need only one fixed extra behavior. Adding it directly, or using one subclass, is simpler.
• Code depends on the object's identity or concrete class. A decorated object is a different object, so checks such as instanceof SlowStore or === comparisons fail.
• Many small layers would make debugging hard. Deep stacks of wrappers produce long call stacks and make it unclear which layer did what.

Middleware in web frameworks, such as Express or Koa, is a related idea: each layer receives a request, may act on it, and passes it on.

Real-world uses

• Java I/O: new BufferedInputStream(new FileInputStream("data.bin")) wraps a stream in another stream that adds buffering, and both have the InputStream interface. The GoF book itself discusses streams as a typical example.
• Java collections: Collections.unmodifiableList(list) and Collections.synchronizedList(list) return wrappers that add read-only behavior or locking around an existing list.
• Python: function decorators such as functools.lru_cache wrap a function and add caching, and functools.wraps helps a wrapper keep the wrapped function's name and docstring.

Related patterns