Decorator Pattern - Learning Module

Loading content...

0/246

Decorator vs Inheritance

Two Paths to Object Extension

When faced with extending object behavior, developers have two primary mechanisms: inheritance (the "is-a" relationship) and composition (the "has-a" relationship, which Decorator leverages). These aren't equivalent alternatives—each has distinct characteristics that make it superior for specific situations.

This page provides a rigorous comparison to help you make informed decisions. We'll examine the theoretical foundations, practical implications, and the nuanced scenarios where each approach excels.

What You Will Learn

By the end of this page, you will understand the fundamental differences between decoration and inheritance, know the criteria for choosing between them, and recognize common scenarios where each is the clear winner. You'll develop judgment for making this architectural decision confidently.

Structural Comparison

Let's begin with a side-by-side structural comparison of how the same capability—adding logging to a repository—would be implemented with each approach:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Base class
class UserRepository {
    async findById(id: string): Promise<User | null> {
        // Database query logic
        return await this.db.users.findOne({ id });
    }
    
    async save(user: User): Promise<void> {
        await this.db.users.upsert(user);
    }
}
 
// Extended class with logging (inheritance)
class LoggedUserRepository extends UserRepository {
    private logger: Logger;
    
    constructor(db: Database, logger: Logger) {
        super(db);
        this.logger = logger;
    }
    
    async findById(id: string): Promise<User | null> {
        this.logger.info(`Finding user: ${id}`);
        const result = await super.findById(id);
        this.logger.info(`Found user: ${result ? 'yes' : 'no'}`);
        return result;
    }
    
    async save(user: User): Promise<void> {
        this.logger.info(`Saving user: ${user.id}`);
        await super.save(user);
        this.logger.info(`Saved user: ${user.id}`);
    }
}
 
// Usage
const repo = new LoggedUserRepository(db, logger);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Interface defining the contract
interface Repository<T> {
    findById(id: string): Promise<T | null>;
    save(entity: T): Promise<void>;
}
 
// Core implementation
class UserRepository implements Repository<User> {
    async findById(id: string): Promise<User | null> {
        return await this.db.users.findOne({ id });
    }
    
    async save(user: User): Promise<void> {
        await this.db.users.upsert(user);
    }
}
 
// Decorator with logging (composition)
class LoggingRepositoryDecorator<T> implements Repository<T> {
    private wrapped: Repository<T>;
    private logger: Logger;
    
    constructor(repository: Repository<T>, logger: Logger) {
        this.wrapped = repository;
        this.logger = logger;
    }
    
    async findById(id: string): Promise<T | null> {
        this.logger.info(`Finding entity: ${id}`);
        const result = await this.wrapped.findById(id);
        this.logger.info(`Found entity: ${result ? 'yes' : 'no'}`);
        return result;
    }
    
    async save(entity: T): Promise<void> {
        this.logger.info(`Saving entity`);
        await this.wrapped.save(entity);
        this.logger.info(`Saved entity`);
    }
}
 
// Usage
const userRepo = new UserRepository(db);
const loggedRepo = new LoggingRepositoryDecorator(userRepo, logger);

At first glance, these look similar—both add logging around method calls. The differences become apparent when we consider reusability and composition.

Structural Differences
Aspect	Inheritance	Decorator
Relationship	LoggedUserRepository IS-A UserRepository	LoggingDecorator HAS-A Repository
Binding Time	Compile-time (fixed at class definition)	Runtime (configurable at object creation)
Reusability	Specific to UserRepository	Works with ProductRepository, OrderRepository, any Repository<T>
Adding Caching	Need: LoggedCachedUserRepository (new class)	Wrap: new CachingDecorator(loggedRepo)
Multiple Enhancements	One class per combination needed	Stack decorators in any order

The Composition Over Inheritance Principle

The Decorator pattern embodies the "Favor composition over inheritance" principle from the Gang of Four. This isn't a dogmatic rejection of inheritance—it's a recognition that composition provides greater flexibility for behavioral extension.

Let's examine why composition (via decoration) is often preferable:

Advantages of Composition (Decorator)

•Runtime Flexibility — Decorators can be added, removed, or reordered at object creation time or even during execution. Inheritance hierarchies are fixed at compile time.
•Cross-Cutting Reuse — A LoggingDecorator can wrap any compatible type. LoggedUserRepository only works for user repositories. The logging behavior is duplicated for each entity type with inheritance.
•Independent Variation — Each decorator varies independently. Adding a new behavior is adding one class. With inheritance, adding a behavior requires classes for all combinations.
•Avoiding Hierarchy Lock-In — Subclasses are tightly coupled to parent implementation. Changes to UserRepository can break LoggedUserRepository. Decorators depend only on the interface.
•Testing Isolation — Decorators are easy to test in isolation with mock wrapped objects. Subclasses carry their parent's behavior, making unit testing harder.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// With Decorator: ONE logging class works for ALL repository types
 
class LoggingDecorator<T> implements Repository<T> {
    constructor(private wrapped: Repository<T>, private logger: Logger) {}
    
    async findById(id: string): Promise<T | null> {
        this.logger.info(`Finding: ${id}`);
        return this.wrapped.findById(id);
    }
    
    async save(entity: T): Promise<void> {
        this.logger.info('Saving entity');
        await this.wrapped.save(entity);
    }
}
 
// Reuse for ANY repository type
const loggedUsers = new LoggingDecorator(userRepo, logger);
const loggedProducts = new LoggingDecorator(productRepo, logger);
const loggedOrders = new LoggingDecorator(orderRepo, logger);
const loggedPayments = new LoggingDecorator(paymentRepo, logger);
 
// ----------------------------------------------------------------
// With Inheritance: SEPARATE class for EACH entity type
 
class LoggedUserRepository extends UserRepository {
    // Logging implementation for User
}
 
class LoggedProductRepository extends ProductRepository {
    // Duplicate logging implementation for Product
}
 
class LoggedOrderRepository extends OrderRepository {
    // Duplicate logging implementation for Order
}
 
class LoggedPaymentRepository extends PaymentRepository {
    // Duplicate logging implementation for Payment
}
 
// 4 entity types × 4 behaviors = 16 classes with inheritance
// 4 entity classes + 4 decorator classes = 8 classes with decoration

The DRY Principle Connection

Inheritance-based extension often violates DRY (Don't Repeat Yourself) when the same behavior must be added to multiple class hierarchies. The decorator's generic wrapper eliminates this duplication by extracting the cross-cutting concern into a single, reusable class.

When Inheritance Is Appropriate

Despite the Decorator's advantages, inheritance remains the right choice in specific scenarios. Understanding these cases prevents over-application of the Decorator pattern.

Inheritance Is Preferred When

•True IS-A Relationship — When the subclass genuinely IS a specialized version of the parent. A SavingsAccount truly IS an Account. A Car truly IS a Vehicle. This isn't about adding behavior—it's about specialization.
•Accessing Protected Members — When the extension needs access to protected state or methods that shouldn't be public. Decorators can only access the public interface.
•Modifying Core Behavior — When you need to change HOW something works, not add behavior AROUND it. Overriding template methods to provide specialized implementations fits inheritance naturally.
•Framework Requirements — Some frameworks expect subclasses (e.g., UI component classes in certain frameworks). Fighting the framework usually isn't worth it.
•Stable Parent Classes — When the parent class is stable and unlikely to change in breaking ways. The tight coupling of inheritance is less risky with stable foundations.
•Performance-Critical Paths — Inheritance has zero runtime overhead. Decorators add method call indirection. In hot paths, this can matter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
// Example 1: True IS-A relationship with specialization
// This is appropriate inheritance—not behavioral extension
 
abstract class Shape {
    abstract area(): number;
    abstract perimeter(): number;
}
 
class Rectangle extends Shape {
    constructor(private width: number, private height: number) {
        super();
    }
    
    area(): number {
        return this.width * this.height;
    }
    
    perimeter(): number {
        return 2 * (this.width + this.height);
    }
}
 
class Square extends Rectangle {
    // Square IS-A Rectangle with equal sides
    // This is proper use of inheritance
    constructor(side: number) {
        super(side, side);
    }
}
 
// ----------------------------------------------------------------
// Example 2: Template method with protected hooks
// Subclass provides specific behavior for abstract steps
 
abstract class DocumentProcessor {
    // Template method defines the algorithm
    process(doc: Document): ProcessedDocument {
        const validated = this.validate(doc);
        const transformed = this.transform(validated);
        const formatted = this.format(transformed);
        return formatted;
    }
    
    // Protected hooks for subclass customization
    protected abstract validate(doc: Document): Document;
    protected abstract transform(doc: Document): Document;
    protected abstract format(doc: Document): ProcessedDocument;
}
 
class MarkdownProcessor extends DocumentProcessor {
    protected validate(doc: Document): Document {
        // Markdown-specific validation
        return doc;
    }
    
    protected transform(doc: Document): Document {
        // Markdown-specific transformation
        return doc;
    }
    
    protected format(doc: Document): ProcessedDocument {
        // Markdown-specific formatting
        return new MarkdownDocument(doc);
    }
}
 
// This is inheritance for SPECIALIZATION, not behavioral addition
// A decorator wouldn't have access to the protected hooks

The Litmus Test

Ask yourself: "Am I creating a specialized TYPE or adding a cross-cutting BEHAVIOR?" Specialized types (SavingsAccount is a type of Account) fit inheritance. Cross-cutting behaviors (any account can have logging) fit decoration.

When Decorator Is Preferred

The Decorator pattern excels in scenarios involving cross-cutting concerns, optional features, and runtime flexibility:

Decorator Is Preferred When

•Cross-Cutting Concerns — Logging, caching, metrics, authentication, rate limiting. These apply to MANY different types, not just one hierarchy.
•Optional/Combinable Features — When behavior combinations are needed without predefined classes. Compression + encryption + buffering in any combination.
•Runtime Configuration — When the behaviors to apply are determined by configuration, feature flags, or user preferences at runtime.
•Adding Behavior to Final Classes — When you can't extend a class (it's final/sealed) but need to add behavior around it.
•Third-Party Integration — When wrapping library objects you don't control to add observability, validation, or adaptation.
•Preserving Interface Contracts — When clients expect the original interface but you need richer behavior internally.
•Order-Dependent Processing — When the order of behavior application matters and must be controllable.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// Scenario 1: Cross-cutting concerns for multiple types
// One decorator works for all implementations
 
interface HttpClient {
    request(url: string, options: RequestOptions): Promise<Response>;
}
 
class LoggingHttpClient implements HttpClient {
    constructor(private client: HttpClient, private logger: Logger) {}
    
    async request(url: string, options: RequestOptions): Promise<Response> {
        this.logger.info(`HTTP ${options.method} ${url}`);
        const start = Date.now();
        const response = await this.client.request(url, options);
        this.logger.info(`HTTP ${response.status} in ${Date.now() - start}ms`);
        return response;
    }
}
 
// Works with ANY HttpClient implementation
const fetchClient = new LoggingHttpClient(new FetchHttpClient(), logger);
const axiosClient = new LoggingHttpClient(new AxiosHttpClient(), logger);
const mockClient = new LoggingHttpClient(new MockHttpClient(), logger);
 
// ----------------------------------------------------------------
// Scenario 2: Runtime configuration with feature flags
 
function createApiClient(config: AppConfig): HttpClient {
    let client: HttpClient = new FetchHttpClient();
    
    if (config.featureFlags.enableRequestLogging) {
        client = new LoggingHttpClient(client, logger);
    }
    
    if (config.featureFlags.enableCircuitBreaker) {
        client = new CircuitBreakerHttpClient(client, circuitConfig);
    }
    
    if (config.featureFlags.enableRetries) {
        client = new RetryingHttpClient(client, { maxRetries: 3 });
    }
    
    if (config.featureFlags.enableCaching) {
        client = new CachingHttpClient(client, cache);
    }
    
    return client;
}
 
// ----------------------------------------------------------------
// Scenario 3: Wrapping third-party libraries you don't control
 
// Stripe SDK is a final/external class
const stripeClient = new Stripe(apiKey);
 
// Add logging, metrics, and retry behavior without modifying Stripe
const enhancedStripe = new RetryDecorator(
    new MetricsDecorator(
        new LoggingDecorator(stripeClient, logger),
        metrics
    ),
    { maxRetries: 3 }
);

The Identity Problem

One significant difference between inheritance and decoration is object identity. With inheritance, the extended object IS the same object. With decoration, it's a different object wrapping the original.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// INHERITANCE: Identity preserved
class UserRepository {}
class LoggedUserRepository extends UserRepository {}
 
const repo = new LoggedUserRepository();
console.log(repo instanceof UserRepository);      // true
console.log(repo instanceof LoggedUserRepository); // true
 
// Identity-based operations work as expected
const repoSet = new Set<UserRepository>();
repoSet.add(repo);
repoSet.has(repo);  // true
 
// ----------------------------------------------------------------
// DECORATOR: Identity NOT preserved
interface Repository<T> {
    findById(id: string): Promise<T | null>;
}
 
class UserRepositoryImpl implements Repository<User> {
    findById(id: string): Promise<User | null> { /* ... */ }
}
 
class LoggingDecorator<T> implements Repository<T> {
    constructor(private wrapped: Repository<T>) {}
    findById(id: string): Promise<T | null> { /* ... */ }
}
 
const baseRepo = new UserRepositoryImpl();
const decoratedRepo = new LoggingDecorator(baseRepo);
 
console.log(decoratedRepo instanceof UserRepositoryImpl);  // FALSE!
console.log(decoratedRepo === baseRepo);                   // FALSE!
 
// This can break expectations:
const repoMap = new Map<Repository<User>, string>();
repoMap.set(baseRepo, "original");
repoMap.get(decoratedRepo);  // undefined! Different object
 
// The decorated repo IS-A Repository<User> by interface
// But NOT instanceof the concrete class

Identity Problems

•instanceof checks fail — Decorated objects aren't instances of the wrapped type's class
•Reference equality fails — decoratedRepo !== originalRepo
•Type guards break — TypeScript's type narrowing may not work as expected
•Collections behave unexpectedly — Sets/Maps keyed on the object won't find decorated version

Mitigations

•Program to interfaces — Avoid instanceof; use interface type checks
•Use composition keys — Key collections on IDs, not object references
•Expose wrapped object — Provide a method to access the original if needed
•Document behavior — Make it clear that objects are decorated

Design Implication

If your codebase relies heavily on instanceof checks or object identity comparisons, decorators can introduce subtle bugs. This is one of the tradeoffs—greater flexibility comes with identity complexity. Well-designed systems program to interfaces, minimizing this issue.

Performance Considerations

Inheritance and decoration have different performance characteristics. While the differences are rarely significant, understanding them helps make informed decisions for performance-critical code.

Performance Comparison
Aspect	Inheritance	Decorator
Method Call Overhead	Single virtual dispatch (vtable lookup)	Multiple dispatches (one per decorator layer)
Memory Overhead	Single object allocation	One object allocation per decorator layer
JIT Optimization	Easier to inline (single type)	Harder to inline (multiple types in chain)
Cache Locality	Better (all data in one object)	Worse (data spread across objects)
Construction Cost	Single constructor call	Multiple constructor calls

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// INHERITANCE: One hop
// Method call: caller → [vtable lookup] → LoggedUserRepository.findById()
//              ↓
//              Goes to parent via super.findById()
// Total: 2 method calls maximum
 
class LoggedUserRepository extends UserRepository {
    async findById(id: string): Promise<User | null> {
        this.logger.info(`Finding user: ${id}`);
        return super.findById(id);  // Direct call to parent
    }
}
 
// ----------------------------------------------------------------
// DECORATOR: Multiple hops
// Method call chain with 4 decorators:
// caller → Decorator4.method() → Decorator3.method() → 
// Decorator2.method() → Decorator1.method() → ConcreteComponent.method()
// Total: 5 method calls
 
const fullyDecorated = new LoggingDecorator(        // Call 1
    new CachingDecorator(                            // Call 2
        new MetricsDecorator(                        // Call 3
            new RetryDecorator(                      // Call 4
                new UserRepository()                 // Call 5
            )
        )
    )
);
 
// Each layer adds:
// - One method call
// - One object dereference (wrapped.method())
// - Potential cache misses from different object locations

Practical perspective:

For most applications, decorator overhead is negligible. The extra microseconds from method indirection are invisible compared to I/O operations, database queries, or network calls. You should only optimize for decorator overhead if:

Profiling shows decorator chains in hot paths
The decorated operations complete in nanoseconds (pure CPU work)
The operation is called millions of times per second

In 99% of real-world code, the flexibility benefits far outweigh the minor performance cost.

Performance Guideline

Don't avoid decorators for performance reasons without evidence. Profile first, then optimize. If decorators ARE a bottleneck, consider consolidating multiple decorators into one composite decorator that performs all operations in a single pass.

Decision Framework

Here's a practical decision framework to guide your choice between inheritance and decoration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
┌─────────────────────────────────────────────────────────────────┐
│       DECISION: Should I use Inheritance or Decorator?          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Q1: Is this a TRUE "is-a" relationship (specialization)?       │
│      Example: SavingsAccount IS-A Account                        │
└─────────────────────────────────────────────────────────────────┘
         │ YES                           │ NO
         ▼                               ▼
  ┌──────────────┐            ┌─────────────────────────────────┐
  │ INHERITANCE  │            │ Q2: Is this a cross-cutting     │
  │ (likely)     │            │     concern (logging, caching,  │
  └──────────────┘            │     metrics, security)?         │
                              └─────────────────────────────────┘
                                    │ YES              │ NO
                                    ▼                  ▼
                            ┌──────────────┐   ┌──────────────────────┐
                            │  DECORATOR   │   │ Q3: Do you need      │
                            │  (likely)    │   │     runtime          │
                            └──────────────┘   │     flexibility?     │
                                               └──────────────────────┘
                                                    │ YES        │ NO
                                                    ▼            ▼
                                             ┌──────────┐  ┌────────────────┐
                                             │DECORATOR │  │ Q4: Need access│
                                             └──────────┘  │ to protected   │
                                                           │ members?       │
                                                           └────────────────┘
                                                              │ YES     │ NO
                                                              ▼         ▼
                                                        ┌───────────┐ ┌──────────┐
                                                        │INHERITANCE│ │ Either   │
                                                        └───────────┘ │ works—   │
                                                                      │ prefer   │
                                                                      │ simpler  │
                                                                      └──────────┘

Quick Reference Rules

•Use inheritance when creating specialized types in a stable hierarchy with clear is-a semantics
•Use decorator when adding optional, combinable, cross-cutting behaviors that apply to multiple types
•Use inheritance when you need protected member access or template method hooks
•Use decorator when you need runtime configuration or feature flag control
•Use inheritance when the parent is stable and you control it
•Use decorator when wrapping third-party code you can't modify
•When in doubt, prefer decorator—it's more flexible and easier to change later

Combining Both Approaches

Inheritance and decoration aren't mutually exclusive. Sophisticated designs often use both—inheritance for type specialization and decoration for cross-cutting enhancement:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
// Type hierarchy using INHERITANCE (specialization)
abstract class Account {
    abstract getType(): string;
    abstract calculateInterest(): number;
    
    // Common account behavior
    deposit(amount: number): void { /* ... */ }
    withdraw(amount: number): void { /* ... */ }
}
 
class SavingsAccount extends Account {
    getType(): string { return 'SAVINGS'; }
    calculateInterest(): number { return this.balance * 0.02; }
}
 
class CheckingAccount extends Account {
    getType(): string { return 'CHECKING'; }
    calculateInterest(): number { return 0; }
}
 
// Cross-cutting concerns using DECORATION
interface AccountOperations {
    deposit(amount: number): void;
    withdraw(amount: number): void;
    getBalance(): number;
}
 
class AuditedAccount implements AccountOperations {
    constructor(
        private wrapped: AccountOperations,
        private auditLog: AuditLog
    ) {}
    
    deposit(amount: number): void {
        this.auditLog.record('DEPOSIT', amount);
        this.wrapped.deposit(amount);
    }
    
    withdraw(amount: number): void {
        this.auditLog.record('WITHDRAW', amount);
        this.wrapped.withdraw(amount);
    }
    
    getBalance(): number {
        return this.wrapped.getBalance();
    }
}
 
class NotifyingAccount implements AccountOperations {
    constructor(
        private wrapped: AccountOperations,
        private notifier: NotificationService
    ) {}
    
    withdraw(amount: number): void {
        this.wrapped.withdraw(amount);
        if (amount > 10000) {
            this.notifier.sendAlert('Large withdrawal');
        }
    }
    
    // ... other methods delegate
}
 
// USAGE: Combine both patterns
// 1. Create specialized type via inheritance
const savings = new SavingsAccount();
 
// 2. Add cross-cutting behaviors via decoration
const enhancedSavings = new NotifyingAccount(
    new AuditedAccount(savings, auditLog),
    notifier
);
 
// ANY account type can be decorated with auditing and notifications
const checking = new CheckingAccount();
const enhancedChecking = new NotifyingAccount(
    new AuditedAccount(checking, auditLog),
    notifier
);

Best of Both Worlds

Use inheritance to establish the type structure (what KINDS of accounts exist) and decoration to add orthogonal features (how ANY account can be enhanced). This separates the domain model from operational concerns elegantly.

Summary: Decorator vs Inheritance

Neither is universally better—each has its domain. Inheritance excels at creating type hierarchies with specialized behavior. Decoration excels at adding optional, combinable, cross-cutting features. The master architect knows when each is appropriate and often combines them for maximally flexible, maintainable designs.

What's next:

The final page explores practical use cases and examples of the Decorator pattern in real-world systems—from Java I/O streams to middleware stacks to UI components.

Page Complete

You now understand the tradeoffs between decoration and inheritance, can identify scenarios suited to each, and know how to combine them effectively. The next page provides extensive real-world examples demonstrating the Decorator pattern in practice.