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
94
95
96
97
98
99
100
101
102
103
104

/**
 * A well-designed Originator with comprehensive state management
 */
class DocumentEditor {
    // === Core State (Always Preserved) ===
    private text: string;
    private formatRanges: FormatRange[];
    private metadata: DocumentMetadata;
    
    // === Derived State (Can Be Recomputed) ===
    private wordCount: number;  // Derived from text
    private searchIndex: SearchIndex;  // Built from text
    
    // === Transient State (Never Preserved) ===
    private isLoading: boolean;
    private pendingNetworkRequests: Set<string>;
    private undoLevel: number;  // Managed by Caretaker, not Memento
    
    // === Shared References (Preserve Reference, Not Copy) ===
    private sharedStylesheet: Stylesheet;  // Shared across documents
    private pluginRegistry: PluginRegistry;  // Application-level
    
    /**
     * Create a memento - key decisions:
     * 1. Include core state (text, formatRanges, metadata)
     * 2. Exclude derived state (can recompute)
     * 3. Exclude transient state (irrelevant to document content)
     * 4. Preserve reference to shared objects, not copies
     */
    createMemento(): DocumentMemento {
        return new DocumentMemento(
            // Deep copy core state
            this.text,
            this.formatRanges.map(r => ({ ...r })),  // Clone array of objects
            { ...this.metadata },  // Shallow clone is enough for flat object
            
            // Keep reference to shared styles (don't copy)
            this.sharedStylesheet
        );
    }
    
    /**
     * Restore from memento - key decisions:
     * 1. Restore core state from memento
     * 2. Recompute derived state after restoration
     * 3. Don't touch transient state
     * 4. Validate invariants after restoration
     */
    restore(memento: DocumentMemento): void {
        // Restore core state
        this.text = memento.getText();
        this.formatRanges = memento.getFormatRanges();
        this.metadata = memento.getMetadata();
        this.sharedStylesheet = memento.getStylesheet();
        
        // Recompute derived state
        this.wordCount = this.computeWordCount();
        this.searchIndex = this.buildSearchIndex();
        
        // Validate invariants
        this.validateState();
    }
    
    private computeWordCount(): number {
        return this.text.split(/\s+/).filter(w => w.length > 0).length;
    }
    
    private buildSearchIndex(): SearchIndex {
        // Expensive operation - worth recomputing vs storing
        return SearchIndex.buildFrom(this.text);
    }
    
    private validateState(): void {
        // Ensure format ranges don't exceed text length
        for (const range of this.formatRanges) {
            if (range.end > this.text.length) {
                throw new Error('Invalid state: format range exceeds text');
            }
        }
    }
}
 
interface FormatRange {
    start: number;
    end: number;
    format: TextFormat;
}
 
interface DocumentMetadata {
    title: string;
    author: string;
    lastModified: Date;
}
 
interface TextFormat {
    bold?: boolean;
    italic?: boolean;
    fontSize?: number;
}
 
// Placeholder types for illustration
type SearchIndex = any;
type Stylesheet = any;
type PluginRegistry = any;

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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

// ============================================================
// Strategy 1: Stack-based Undo/Redo
// Classic implementation for text editors, drawing apps
// ============================================================
class UndoRedoManager<T extends IMemento> {
    private undoStack: T[] = [];
    private redoStack: T[] = [];
    private readonly maxSize: number;
    
    constructor(maxSize: number = 100) {
        this.maxSize = maxSize;
    }
    
    /**
     * Save current state before making changes.
     * Clears redo stack (new action invalidates redo history).
     */
    save(memento: T): void {
        this.undoStack.push(memento);
        this.redoStack = [];  // Clear redo on new action
        
        // Limit memory usage
        while (this.undoStack.length > this.maxSize) {
            this.undoStack.shift();  // Remove oldest
        }
    }
    
    /**
     * Get memento for undo operation.
     * Caller should save current state to redo stack.
     */
    undo(currentMemento: T): T | null {
        if (this.undoStack.length === 0) return null;
        
        this.redoStack.push(currentMemento);
        return this.undoStack.pop()!;
    }
    
    /**
     * Get memento for redo operation.
     */
    redo(currentMemento: T): T | null {
        if (this.redoStack.length === 0) return null;
        
        this.undoStack.push(currentMemento);
        return this.redoStack.pop()!;
    }
    
    canUndo(): boolean { return this.undoStack.length > 0; }
    canRedo(): boolean { return this.redoStack.length > 0; }
}
 
// ============================================================
// Strategy 2: Named Checkpoints
// For save points, game saves, database transactions
// ============================================================
class CheckpointManager<T extends IMemento> {
    private checkpoints: Map<string, T> = new Map();
    private autoCheckpoints: T[] = [];
    private autoCheckpointInterval: number;
    
    constructor(autoCheckpointInterval: number = 10) {
        this.autoCheckpointInterval = autoCheckpointInterval;
    }
    
    /**
     * Create a named checkpoint for explicit save points.
     */
    createCheckpoint(name: string, memento: T): void {
        this.checkpoints.set(name, memento);
    }
    
    /**
     * Auto-checkpoint based on operation count or time.
     */
    autoCheckpoint(memento: T): void {
        this.autoCheckpoints.push(memento);
        
        // Keep only recent auto-checkpoints
        while (this.autoCheckpoints.length > this.autoCheckpointInterval) {
            this.autoCheckpoints.shift();
        }
    }
    
    /**
     * Restore to a named checkpoint.
     */
    restore(name: string): T | null {
        return this.checkpoints.get(name) || null;
    }
    
    /**
     * Restore to most recent auto-checkpoint.
     */
    restoreLatest(): T | null {
        return this.autoCheckpoints.length > 0
            ? this.autoCheckpoints[this.autoCheckpoints.length - 1]
            : null;
    }
    
    listCheckpoints(): string[] {
        return Array.from(this.checkpoints.keys());
    }
}
 
// ============================================================
// Strategy 3: Version History with Branching
// For version control, document history, design tools
// ============================================================
interface VersionNode<T extends IMemento> {
    id: string;
    memento: T;
    parentId: string | null;
    timestamp: Date;
    label?: string;
}
 
class VersionHistory<T extends IMemento> {
    private versions: Map<string, VersionNode<T>> = new Map();
    private currentId: string | null = null;
    private rootId: string | null = null;
    
    /**
     * Add a new version as child of current.
     * Enables branching history like Git.
     */
    addVersion(memento: T, label?: string): string {
        const id = crypto.randomUUID();
        
        const node: VersionNode<T> = {
            id,
            memento,
            parentId: this.currentId,
            timestamp: new Date(),
            label
        };
        
        this.versions.set(id, node);
        
        if (this.rootId === null) {
            this.rootId = id;
        }
        
        this.currentId = id;
        return id;
    }
    
    /**
     * Navigate to any version in history.
     * Returns null if version doesn't exist.
     */
    checkout(versionId: string): T | null {
        const node = this.versions.get(versionId);
        if (!node) return null;
        
        this.currentId = versionId;
        return node.memento;
    }
    
    /**
     * Get the path from root to current version.
     */
    getHistoryPath(): VersionNode<T>[] {
        const path: VersionNode<T>[] = [];
        let currentNode = this.currentId 
            ? this.versions.get(this.currentId) 
            : null;
        
        while (currentNode) {
            path.unshift(currentNode);
            currentNode = currentNode.parentId 
                ? this.versions.get(currentNode.parentId) 
                : null;
        }
        
        return path;
    }
    
    /**
     * Get all branches from a specific version.
     */
    getBranches(versionId: string): VersionNode<T>[] {
        return Array.from(this.versions.values())
            .filter(node => node.parentId === versionId);
    }
}
 
interface IMemento {
    timestamp: Date;
    getDescription(): string;
}

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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

// Complete example showing all three participants interacting
 
interface IMemento {
    readonly timestamp: Date;
    getDescription(): string;
}
 
// === MEMENTO ===
class GraphicsMemento implements IMemento {
    readonly timestamp = new Date();
    
    constructor(
        private readonly layerData: readonly LayerSnapshot[],
        private readonly selectedLayerId: string | null,
        private readonly viewportPosition: Readonly<Point>
    ) {}
    
    getDescription(): string {
        return `${this.layerData.length} layers at ${this.timestamp.toISOString()}`;
    }
    
    // Wide interface - package-private in practice
    getLayerData(): readonly LayerSnapshot[] { return this.layerData; }
    getSelectedLayerId(): string | null { return this.selectedLayerId; }
    getViewportPosition(): Readonly<Point> { return this.viewportPosition; }
}
 
// === ORIGINATOR ===
class GraphicsCanvas {
    private layers: Layer[] = [];
    private selectedLayerId: string | null = null;
    private viewportPosition: Point = { x: 0, y: 0 };
    
    // Business operations
    addLayer(layer: Layer): void { /* ... */ }
    removeLayer(id: string): void { /* ... */ }
    selectLayer(id: string): void { /* ... */ }
    pan(delta: Point): void { /* ... */ }
    
    // Memento operations
    createMemento(): GraphicsMemento {
        return new GraphicsMemento(
            this.layers.map(l => l.snapshot()),  // Deep copy
            this.selectedLayerId,
            { ...this.viewportPosition }
        );
    }
    
    restore(memento: GraphicsMemento): void {
        this.layers = memento.getLayerData().map(snap => 
            Layer.fromSnapshot(snap)
        );
        this.selectedLayerId = memento.getSelectedLayerId();
        this.viewportPosition = { ...memento.getViewportPosition() };
        
        this.onStateRestored();  // Hook for derived state update
    }
    
    private onStateRestored(): void {
        // Rebuild derived state, notify observers, etc.
    }
}
 
// === CARETAKER ===
class CanvasHistoryManager {
    private undoStack: IMemento[] = [];
    private redoStack: IMemento[] = [];
    
    /**
     * Call this BEFORE making changes to the canvas.
     */
    beforeChange(canvas: GraphicsCanvas): void {
        const memento = canvas.createMemento();
        this.undoStack.push(memento);
        this.redoStack = [];
        
        // Limit history
        if (this.undoStack.length > 50) {
            this.undoStack.shift();
        }
    }
    
    /**
     * Undo the last change.
     */
    undo(canvas: GraphicsCanvas): boolean {
        if (this.undoStack.length === 0) return false;
        
        // Save current for redo
        const current = canvas.createMemento();
        this.redoStack.push(current);
        
        // Restore previous
        const previous = this.undoStack.pop()! as GraphicsMemento;
        canvas.restore(previous);
        
        return true;
    }
    
    /**
     * Redo a previously undone change.
     */
    redo(canvas: GraphicsCanvas): boolean {
        if (this.redoStack.length === 0) return false;
        
        // Save current for undo
        const current = canvas.createMemento();
        this.undoStack.push(current);
        
        // Restore redo state
        const redoState = this.redoStack.pop()! as GraphicsMemento;
        canvas.restore(redoState);
        
        return true;
    }
}
 
// === USAGE ===
const canvas = new GraphicsCanvas();
const history = new CanvasHistoryManager();
 
// Before any modification
history.beforeChange(canvas);
canvas.addLayer(new Layer('background'));
 
history.beforeChange(canvas);
canvas.addLayer(new Layer('foreground'));
 
// Undo - removes foreground layer
history.undo(canvas);
 
// Types for illustration
interface Point { x: number; y: number; }
interface LayerSnapshot { id: string; data: unknown; }
class Layer {
    constructor(public name: string) {}
    snapshot(): LayerSnapshot { return { id: this.name, data: {} }; }
    static fromSnapshot(snap: LayerSnapshot): Layer { return new Layer(snap.id); }
}

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

// ❌ MISTAKE 1: Mutable memento
class BadMemento {
    constructor(public items: string[]) {}  // Mutable array!
}
 
const origItems = ['a', 'b'];
const memento = new BadMemento(origItems);  // Shares reference!
origItems.push('c');  // Memento now has 3 items!
 
// ✅ FIX: Deep copy
class GoodMemento {
    private readonly items: readonly string[];
    constructor(items: string[]) {
        this.items = Object.freeze([...items]);  // Copy and freeze
    }
}
 
// ❌ MISTAKE 2: Caretaker reading state
class BadCaretaker {
    shouldSave(memento: BadMemento): boolean {
        // WRONG: Reading internal state
        return memento.items.length > 0;
    }
}
 
// ✅ FIX: Add to narrow interface
interface IMemento {
    isEmpty(): boolean;  // Originator defines this
}
 
// ❌ MISTAKE 3: Save after modification
function badUndo(editor: Editor, history: History) {
    editor.type('text');  // Modify first
    history.push(editor.createMemento());  // Save after - WRONG!
}
 
// ✅ FIX: Save before modification
function goodUndo(editor: Editor, history: History) {
    history.push(editor.createMemento());  // Save first
    editor.type('text');  // Then modify
}
 
// ❌ MISTAKE 4: Not updating derived state
class IncompleteEditor {
    private text: string = '';
    private wordCount: number = 0;  // Derived
    
    restore(memento: Memento): void {
        this.text = memento.getText();
        // WRONG: wordCount is now stale!
    }
}
 
// ✅ FIX: Update derived state after restore
class CompleteEditor {
    private text: string = '';
    private wordCount: number = 0;
    
    restore(memento: Memento): void {
        this.text = memento.getText();
        this.updateDerivedState();  // Always recompute
    }
    
    private updateDerivedState(): void {
        this.wordCount = this.text.split(/\s+/).length;
    }
}
 
// Placeholder types
type Editor = any;
type History = any[];
type Memento = { getText(): string };