Command Pattern - Learning Module

Loading content...

0/246

Problem: Encapsulating Requests as Objects

The Request Coupling Problem

Imagine you're building a sophisticated document editor. Users can perform countless operations: typing text, formatting paragraphs, inserting images, applying styles, creating tables, and more. Now consider implementing an undo system. How do you track what changed? How do you reverse it? What about redo?

Or picture a remote control for a smart home system. Different buttons trigger different devices—lights, thermostats, music systems, security cameras. How do you decouple the buttons from the specific device operations? How do you add new device commands without modifying the remote control hardware?

These scenarios share a fundamental architecture challenge: the object that invokes an operation is tightly coupled to the object that knows how to perform it. This coupling creates rigid, inflexible systems that are difficult to extend, test, and maintain.

What You Will Learn

By the end of this page, you will deeply understand the problem of tightly coupled request invocation—why direct method calls create architectural constraints, how this coupling manifests in real systems, and why treating requests as first-class objects transforms system design possibilities.

The Direct Invocation Anti-Pattern

In most object-oriented code, when an object needs to trigger an action, it does so through direct method invocation. This seems natural and straightforward:

client.doSomething();
device.turnOn();
document.format();

But this simplicity conceals architectural constraints that become problematic as systems grow. Let's examine why direct invocation creates coupling problems.

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
81
82
83
// A simple remote control for home automation
// The remote directly knows about each device and how to control it
 
class Light {
    turnOn(): void {
        console.log("Light is ON");
    }
    
    turnOff(): void {
        console.log("Light is OFF");
    }
    
    dim(level: number): void {
        console.log(`Light dimmed to ${level}%`);
    }
}
 
class Thermostat {
    setTemperature(temp: number): void {
        console.log(`Temperature set to ${temp}°F`);
    }
    
    turnOn(): void {
        console.log("Thermostat is ON");
    }
    
    turnOff(): void {
        console.log("Thermostat is OFF");
    }
}
 
class MusicPlayer {
    play(): void {
        console.log("Music playing");
    }
    
    pause(): void {
        console.log("Music paused");
    }
    
    setVolume(volume: number): void {
        console.log(`Volume set to ${volume}`);
    }
}
 
// The remote control is tightly coupled to ALL devices
class RemoteControl {
    private light: Light;
    private thermostat: Thermostat;
    private musicPlayer: MusicPlayer;
    
    constructor(light: Light, thermostat: Thermostat, musicPlayer: MusicPlayer) {
        this.light = light;
        this.thermostat = thermostat;
        this.musicPlayer = musicPlayer;
    }
    
    // Each button requires knowledge of specific device operations
    pressButton1(): void {
        this.light.turnOn(); // Direct coupling to Light
    }
    
    pressButton2(): void {
        this.light.turnOff(); // Direct coupling to Light
    }
    
    pressButton3(): void {
        this.thermostat.setTemperature(72); // Direct coupling to Thermostat
    }
    
    pressButton4(): void {
        this.musicPlayer.play(); // Direct coupling to MusicPlayer
    }
    
    // What happens when we want to:
    // - Add a new device (garage door)?
    // - Change what a button does at runtime?
    // - Implement undo for button presses?
    // - Log all operations for debugging?
    // - Queue operations for batch execution?
    
    // Answer: We must modify this class extensively for EVERY change.
}

The RemoteControl class demonstrates classic tight coupling:

Knowledge coupling: The remote knows about Light, Thermostat, and MusicPlayer—their types, methods, and parameters.
Structural coupling: Adding a new device (e.g., GarageDoor) requires modifying the RemoteControl constructor and adding new button methods.
Behavioral coupling: Changing button behavior means editing the remote's code directly.
Testing coupling: Unit testing the remote requires mocking all devices, even if you're only testing one button.
Extension impossibility: Features like undo, logging, queueing, or macro recording cannot be added without invasive changes.

The Open/Closed Principle Violation

This design violates the Open/Closed Principle: the RemoteControl is not closed for modification. Every new device type, every new button assignment, every new feature requires changing existing code. In a production system, this leads to ever-growing classes, regression risks, and engineering bottlenecks.

Analyzing the Coupling Dimensions

To truly understand the problem, we need to dissect the coupling between invokers (objects that trigger operations) and receivers (objects that perform operations). This coupling occurs across multiple dimensions, each creating distinct architectural constraints.

Coupling Dimensions in Direct Invocation
Dimension	Description	Architectural Impact
Type Coupling	Invoker must know receiver's concrete type	Cannot substitute receivers without code changes; violates DIP
Method Coupling	Invoker must know exact method signatures	Interface changes ripple through all invokers; high change amplification
Parameter Coupling	Invoker must assemble method parameters	Parameter changes affect invokers; data and behavior intertwined
Temporal Coupling	Invocation and execution occur simultaneously	Cannot delay, queue, schedule, or retry operations
Cardinality Coupling	One invocation maps to one execution	Cannot batch, aggregate, or deduplicate operations
Lifecycle Coupling	Invoker controls execution lifecycle	Cannot cancel, pause, resume, or monitor operations

Why These Dimensions Matter:

Each coupling dimension removes a degree of freedom from your architecture. Type coupling means you can't swap implementations. Temporal coupling means you can't delay execution. Lifecycle coupling means you can't add cross-cutting concerns like logging or monitoring.

The cumulative effect is an architecture that is ossified against change—brittle, rigid, and increasingly difficult to maintain as the system evolves.

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
// Demonstrating each coupling dimension
 
class DocumentEditor {
    private document: Document;
    private printer: Printer;
    private spellChecker: SpellChecker;
    
    // TYPE COUPLING: We must know concrete types
    constructor(doc: Document, printer: Printer, checker: SpellChecker) {
        this.document = doc;
        this.printer = printer;
        this.spellChecker = checker;
    }
    
    // METHOD COUPLING: We must know exact method signatures
    formatDocument(): void {
        this.document.applyStyle("header", { size: 18, bold: true });
        this.document.applyStyle("body", { size: 12, bold: false });
    }
    
    // PARAMETER COUPLING: We assemble parameters inline
    insertImage(path: string): void {
        const width = 400;
        const height = 300;
        const alignment = "center";
        const caption = "Figure 1";
        
        // Parameters are scattered in the invoker
        this.document.insertImage(path, width, height, alignment, caption);
    }
    
    // TEMPORAL COUPLING: Execution is immediate, synchronous
    printDocument(): void {
        // What if printer is busy? Network is slow?
        // We have no way to queue, retry, or delay.
        this.printer.print(this.document);
    }
    
    // CARDINALITY COUPLING: One call = one operation
    spellCheckAll(): void {
        // What if we want to batch multiple checks?
        // Or deduplicate repeated checks on the same paragraph?
        for (const paragraph of this.document.paragraphs) {
            this.spellChecker.check(paragraph);
        }
    }
    
    // LIFECYCLE COUPLING: No control over operation lifecycle
    // We cannot:
    // - Cancel an in-progress print
    // - See what operations are pending
    // - Retry a failed format operation
    // - Log all operations uniformly
}

The Fundamental Insight

Direct method invocation treats operations as ephemeral events—they happen and they're gone. We have no handle on the operation itself. We cannot inspect it, store it, pass it, replay it, or reverse it. This is the core limitation that the Command Pattern addresses.

Real-World Manifestations of the Problem

The request coupling problem appears throughout software systems. Understanding these manifestations helps you recognize when the Command Pattern is an appropriate solution.

GUI Button Actions

Consider a typical GUI framework where buttons trigger actions:

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
// Traditional approach: button is coupled to specific handler
class SaveButton extends Button {
    private document: Document;
    private fileSystem: FileSystem;
    
    constructor(doc: Document, fs: FileSystem) {
        super();
        this.document = doc;
        this.fileSystem = fs;
    }
    
    onClick(): void {
        // Button knows HOW to save
        const content = this.document.getContent();
        const path = this.document.getPath();
        this.fileSystem.writeFile(path, content);
    }
}
 
class PrintButton extends Button {
    private document: Document;
    private printer: Printer;
    private dialogService: DialogService;
    
    constructor(doc: Document, printer: Printer, dialogs: DialogService) {
        super();
        this.document = doc;
        this.printer = printer;
        this.dialogService = dialogs;
    }
    
    onClick(): void {
        // Button knows HOW to print
        const settings = this.dialogService.showPrintDialog();
        if (settings) {
            this.printer.print(this.document, settings);
        }
    }
}
 
// Problems:
// 1. Every action type needs a new Button subclass
// 2. Buttons are not reusable—SaveButton can only save
// 3. How do we reuse "save" from a menu item? Or a keyboard shortcut?
// 4. How do we implement undo? The action is lost after onClick()
// 5. How do we record macros? We'd need to duplicate all button logic

Transaction Processing Systems

In banking and financial systems, operations must be logged, validated, potentially reversed, and often queued for batch processing:

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
// Problematic approach: account handles transfers directly
class BankAccount {
    private balance: number;
    private accountNumber: string;
    
    transfer(targetAccount: BankAccount, amount: number): void {
        if (this.balance < amount) {
            throw new Error("Insufficient funds");
        }
        
        // Direct manipulation—no audit trail of the operation itself
        this.balance -= amount;
        targetAccount.balance += amount;
        
        // Questions arise:
        // - How do we reverse this if something goes wrong downstream?
        // - How do we batch transfers for end-of-day processing?
        // - How do we replay this for disaster recovery?
        // - How do we validate this against fraud rules BEFORE executing?
        // - How do we hold this pending manager approval?
        
        // The transfer "knowledge" is embedded in BankAccount
        // We have no representation of "the transfer" as an entity
    }
}
 
// We might try to fix with more methods...
class BankAccount_V2 {
    pendingTransfer(target: BankAccount, amount: number): TransferId {
        // Creates pending record, but still tightly coupled
    }
    
    approveTransfer(transferId: TransferId): void {
        // Still need all the transfer logic here
    }
    
    reverseTransfer(transferId: TransferId): void {
        // Reversal logic duplicates or inverts transfer logic
    }
    
    // The class keeps growing with transfer-related responsibilities
}

Game Engine Input Handling

Games require flexible input mapping, where the same action might be triggered by keyboard, controller, touch, or network events:

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
// Problematic: Input handler knows about all game actions
class GameInputHandler {
    private player: Player;
    private gameWorld: GameWorld;
    private menuSystem: MenuSystem;
    
    handleKeyPress(key: string): void {
        switch (key) {
            case "W":
                this.player.moveForward();
                break;
            case "Space":
                this.player.jump();
                break;
            case "E":
                this.player.interact(this.gameWorld.getNearestInteractable());
                break;
            case "Escape":
                this.menuSystem.openPauseMenu();
                break;
            // ... dozens more cases
        }
    }
    
    handleControllerButton(button: ControllerButton): void {
        // Duplicate logic for controller input with different mapping
        switch (button) {
            case ControllerButton.A:
                this.player.jump();
                break;
            // ... repeat all actions with controller buttons
        }
    }
    
    // Problems:
    // 1. Input handler knows about Player, GameWorld, MenuSystem...
    // 2. Cannot rebind keys at runtime (hardcoded switch statements)
    // 3. Cannot record and playback input for replays
    // 4. Cannot implement input buffering or combo detection
    // 5. Adding new actions requires modifying this massive switch
}

Common Symptoms of the Request Coupling Problem

•Large switch statements mapping inputs/events to actions
•Classes that know too many concrete types—violating DIP and SRP
•Difficulty implementing cross-cutting concerns like logging, validation, or authentication
•Undo/redo appears impossible without massive refactoring
•Copy-paste logic for the same action from different entry points
•Hard-to-test code due to deep dependencies in action handlers
•Rigid input/button mappings that can't be customized by users

The Request as a First-Class Concept

The solution to these coupling problems lies in a profound conceptual shift: treating requests as objects rather than method calls.

In direct invocation, a request is an ephemeral event—it happens and immediately ceases to exist. There's no artifact, no handle, no representation. But what if we materialized the request into an object?

Consider the difference:

Request as Method Call

•Ephemeral—exists only during the call
•Cannot be stored or transmitted
•Cannot be inspected before execution
•Cannot be reversed after execution
•Invoker must know receiver
•Parameters scattered in calling code
•Execution is synchronous and immediate

Request as Object

•Persistent—can be stored indefinitely
•Can be serialized, queued, transmitted
•Can be validated, authorized, logged
•Can store undo information
•Invoker decoupled from receiver
•Parameters encapsulated in command
•Execution can be delayed or scheduled

The Reification Principle:

In programming language theory, reification means making an implicit concept explicit—giving it existence as a first-class entity. When we reify requests into objects, we gain the full power of object-oriented programming for manipulating operations themselves:

Parameterization: Objects can be passed as parameters. We can parameterize invokers with different requests.
Storage: Objects can be stored in collections. We can build queues, stacks, logs of requests.
Polymorphism: Objects can implement interfaces. We can treat different requests uniformly.
Composition: Objects can be combined. We can build composite requests (macros).
Serialization: Objects can be serialized. We can persist requests across restarts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// === BEFORE: Request as method call ===
 
// The request is implicit—it exists only in the act of calling
remote.pressButton() → light.turnOn()
// ↑ Ephemeral event, no artifact remains
 
// === AFTER: Request as object ===
 
// The request is explicit—it's an object we can manipulate
const turnOnCommand = new TurnOnLightCommand(light);
// ↑ An object that REPRESENTS the request
 
// Now we have options:
commandQueue.add(turnOnCommand);        // Queue it for later
undoStack.push(turnOnCommand);          // Store for undo
logger.log(turnOnCommand.describe());   // Log before execution
if (authorize(turnOnCommand)) {         // Validate/authorize
    turnOnCommand.execute();            // Execute when ready
}
 
// The key insight:
// turnOnCommand is not the execution—it's a DATA STRUCTURE
// describing an operation that CAN BE executed.
// This separation is the heart of the Command Pattern.

The Power of Indirection

Every problem in computer science can be solved by adding another level of indirection. By placing an object between the invoker and the execution, we gain the ability to intercept, modify, record, and control that execution. This indirection is not overhead—it's architectural capability.

Requirements for Undo Systems

One of the most compelling motivations for the Command Pattern is implementing undo/redo functionality. Let's deeply examine what undo requires and why direct invocation makes it nearly impossible.

The Undo Challenge

To undo an operation, we must:

Know what operation was performed — After document.delete(selection), what selection was deleted?
Store the operation for reversal — Where do we keep track of past operations?
Know how to reverse it — What's the inverse of each operation?
Execute the reversal — Actually perform the undo
Support undo of the undo (redo) — Maintain undo/redo stacks

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
81
82
83
84
85
86
87
88
89
90
91
92
93
// Attempting undo with direct invocation
 
class TextEditor_NoUndo {
    private text: string = "";
    
    insert(position: number, content: string): void {
        this.text = 
            this.text.slice(0, position) + 
            content + 
            this.text.slice(position);
        
        // How do we record what we just did?
        // The operation is complete. There's no artifact.
        // position and content only existed during the call.
    }
    
    delete(start: number, end: number): void {
        this.text = this.text.slice(0, start) + this.text.slice(end);
        
        // After this call, we don't know:
        // - What text was deleted (it's gone!)
        // - The original start/end positions
        // - That this operation even happened
    }
    
    undo(): void {
        // HOW? We have no record of operations.
        // We'd need to refactor everything.
    }
}
 
// Attempt 1: Store operation history inline (ugly and error-prone)
class TextEditor_MessyUndo {
    private text: string = "";
    private operationHistory: Array<{
        type: "insert" | "delete";
        position?: number;
        content?: string;
        start?: number;
        end?: number;
        deletedText?: string;
    }> = [];
    
    insert(position: number, content: string): void {
        // Now every method must maintain history
        this.operationHistory.push({
            type: "insert",
            position,
            content,
        });
        this.text = /*...*/;
    }
    
    delete(start: number, end: number): void {
        const deletedText = this.text.slice(start, end);
        this.operationHistory.push({
            type: "delete",
            start,
            end,
            deletedText, // Must capture deleted content!
        });
        this.text = /*...*/;
    }
    
    undo(): void {
        const lastOp = this.operationHistory.pop();
        if (!lastOp) return;
        
        // Giant switch on operation types
        switch (lastOp.type) {
            case "insert":
                // Reverse insert = delete the inserted content
                this.text = 
                    this.text.slice(0, lastOp.position!) +
                    this.text.slice(lastOp.position! + lastOp.content!.length);
                break;
            case "delete":
                // Reverse delete = re-insert deleted content
                this.text = 
                    this.text.slice(0, lastOp.start!) +
                    lastOp.deletedText +
                    this.text.slice(lastOp.start!);
                break;
        }
    }
    
    // Problems:
    // 1. History data structure is a mess of optional properties
    // 2. Undo logic duplicates/inverts operation logic
    // 3. Every new operation type expands history AND undo switch
    // 4. No type safety—easy to forget a property
    // 5. Testing requires mocking the entire editor
}

What Undo Really Requires

A proper undo system needs commands as first-class objects that:

Encapsulate all information needed to perform the operation
Encapsulate all information needed to reverse the operation
Have a uniform interface (execute(), undo()) regardless of type
Can be stored in stacks for undo/redo history
Are self-contained — each command knows its own inverse

Command Properties Required for Undo
Property	Purpose	Example
Operation parameters	Perform the operation	Insert position, insertion text
Pre-operation snapshot	Restore state for undo	Text before deletion
Post-operation snapshot	Support redo after undo	Document state after formatting
Execution status	Track whether undoable	hasBeenExecuted flag
Inverse operation logic	Actually perform undo	undo() method

The Command Pattern Enables Undo

When operations are objects, implementing undo becomes natural. We maintain a stack of command objects. To undo, pop the stack and call the command's undo() method. To redo, call execute() again. The command contains everything needed—no external tracking required.

Macro Recording and Scripting

Beyond undo/redo, request objectification enables powerful automation capabilities: macro recording, scripting, and operation replay.

The Macro Recording Problem

In applications like Excel, Photoshop, or development IDEs, users can "record" sequences of actions and replay them. How would you implement this with direct invocation?

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
// How do you record this?
class PhotoEditor_NoMacros {
    adjustBrightness(delta: number): void {
        this.image.pixels.forEach(p => p.brightness += delta);
    }
    
    applyFilter(filterType: string, intensity: number): void {
        const filter = this.filters.get(filterType);
        filter?.apply(this.image, intensity);
    }
    
    crop(x: number, y: number, width: number, height: number): void {
        this.image = this.image.extractRegion(x, y, width, height);
    }
    
    // To record macros, you'd need to:
    // 1. Add hooks in EVERY method to emit "operation occurred"
    // 2. Store operation type + parameters somewhere
    // 3. Build a replay mechanism that maps recordings to methods
    
    // This cross-cuts ALL methods with recording logic
    
    adjustBrightness_WithRecording(delta: number): void {
        // Recording logic pollutes business logic
        if (this.isRecording) {
            this.recordedOps.push({
                method: "adjustBrightness",
                args: [delta],
            });
        }
        this.image.pixels.forEach(p => p.brightness += delta);
    }
    
    // Replay requires reflection or giant switch
    replayOperation(record: { method: string; args: any[] }): void {
        switch (record.method) {
            case "adjustBrightness":
                this.adjustBrightness(record.args[0] as number);
                break;
            case "applyFilter":
                this.applyFilter(
                    record.args[0] as string,
                    record.args[1] as number
                );
                break;
            // ... every method must be listed here
        }
    }
}

Why Commands Enable Macros

When operations are command objects, macro recording is trivial:

Recording: Store each command object as it's created
Replay: Iterate through stored commands and call execute()
Editing: Manipulate the command list (add, remove, reorder)
Serialization: Persist command data for later replay
Parameterization: Modify command properties before replay

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
// With commands, macro recording is natural
 
interface PhotoCommand {
    execute(): void;
    serialize(): string; // For persistence
}
 
class BrightnessCommand implements PhotoCommand {
    constructor(
        private image: Image,
        private delta: number,
    ) {}
    
    execute(): void {
        this.image.adjustBrightness(this.delta);
    }
    
    serialize(): string {
        return JSON.stringify({ type: "brightness", delta: this.delta });
    }
}
 
class MacroRecorder {
    private commands: PhotoCommand[] = [];
    private isRecording: boolean = false;
    
    startRecording(): void {
        this.commands = [];
        this.isRecording = true;
    }
    
    record(command: PhotoCommand): void {
        if (this.isRecording) {
            this.commands.push(command);
        }
    }
    
    stopRecording(): PhotoCommand[] {
        this.isRecording = false;
        return this.commands;
    }
    
    replay(): void {
        // Replay is trivial—just execute each command
        for (const command of this.commands) {
            command.execute();
        }
    }
    
    save(): string {
        // Serialization is built into each command
        return this.commands.map(c => c.serialize()).join("
");
    }
}
 
// Usage:
// recorder.startRecording();
// recorder.record(new BrightnessCommand(image, +10));
// recorder.record(new FilterCommand(image, "sepia", 0.5));
// recorder.record(new CropCommand(image, 0, 0, 400, 400));
// const macro = recorder.stopRecording();
// recorder.replay(); // Apply to current image
// recorder.save();   // Persist for future use

Scripting as External Macros

Command-based architectures naturally support scripting. A script is just a sequence of serialized commands. You can even expose a scripting language that constructs command objects, enabling end-users to automate workflows without modifying application code.

Summary: The Problem Defined

We've thoroughly examined the problem that the Command Pattern solves. Let's consolidate the key insights:

Key Takeaways

•Direct method invocation creates tight coupling — Invokers know receiver types, method signatures, and parameters. This coupling resists change.
•Coupling operates across multiple dimensions — Type, method, parameter, temporal, cardinality, and lifecycle coupling each constrain architecture.
•Requests as method calls are ephemeral — They exist only during invocation, leaving no artifact for undo, logging, or queuing.
•Undo requires persistent operation representations — We must store what happened, with enough information to reverse it.
•Macro recording requires inspectable operations — Operations must be recordable, storable, and replayable.
•The solution is reification — Turn implicit requests into explicit command objects, gaining full object-oriented power over operations themselves.

What's Next:

In the next page, we'll explore the Command Pattern solution in detail: the structure, participants, and how command objects with execute() (and undo()) methods elegantly solve all the problems we've outlined. We'll see how to design command interfaces, implement concrete commands, and connect them to invokers and receivers.

Page Complete

You now understand the fundamental problem that the Command Pattern addresses: the tight coupling between request invocation and request execution. This coupling prevents undo, queuing, logging, and other cross-cutting capabilities that become trivial once requests are reified into first-class objects.