System Design LLDStructural Patterns

Proxy Pattern

LevelIntermediate

Duration90 mins

TopicStructural Patterns

2 / 4

Solution — Surrogate with Same Interface

The Power of the Stand-In

In the previous page, we identified a fundamental design challenge: how do we control access to objects without modifying the objects themselves or burdening client code?

The Proxy pattern's solution is elegant in its simplicity: create a stand-in object that looks exactly like the real object but controls access to it.

Think of a proxy like a personal assistant to a busy executive. When you call the executive's office, you speak to the assistant who:

Uses the same communication protocol (phone, email)
Can answer many questions directly (cached information)
Screens requests (access control)
Schedules appropriate times for actual contact (lazy initialization)
Summarizes interactions afterward (logging)

The caller might not even realize they're not speaking directly to the executive—the interface is identical.

What You Will Learn

By the end of this page, you will understand how the Proxy pattern is structured—the relationship between Subject interface, RealSubject, and Proxy. You'll see how interface conformance enables transparent substitution and learn the fundamental implementation patterns that all proxy types share.

The Proxy Pattern Structure

The Proxy pattern defines three essential components that work together:

1.1 Pattern Participants

Subject (Interface) Defines the common interface for RealSubject and Proxy. This shared interface is what enables the Proxy to be used anywhere the RealSubject is expected.

RealSubject The actual object that does the real work. It implements the Subject interface and contains the business logic, expensive resources, or protected operations.

Proxy Maintains a reference to the RealSubject and implements the same Subject interface. The Proxy controls access to the RealSubject and may perform additional operations before or after forwarding requests.

Converting Mermaid diagram...

The Interface Is Key

The Subject interface is the linchpin of the pattern. By defining a contract that both RealSubject and Proxy implement, we gain the ability to substitute one for the other transparently. This is the Liskov Substitution Principle (LSP) in action.

1.2 Collaboration Flow

Here's how the participants collaborate at runtime:

Converting Mermaid diagram...

Implementing the Basic Structure

Let's build a concrete implementation step by step. We'll start with the foundational structure before exploring specific proxy types.

Step 1: Define the Subject Interface

The interface defines what operations are available. Both the real subject and proxy must implement this exactly.

subject-interface.ts
TypeScript
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
// Subject Interface - the contract both must fulfill
interface ImageLoader {
    /**
     * Load an image from the specified path
     * @returns The loaded image data ready for display
     */
    loadImage(): ImageData;
    
    /**
     * Get the dimensions without fully loading the image
     * @returns Width and height in pixels
     */
    getDimensions(): { width: number; height: number };
    
    /**
     * Get metadata about the image (EXIF, format, etc.)
     */
    getMetadata(): ImageMetadata;
    
    /**
     * Render the image to a canvas at specified dimensions
     */
    render(targetWidth: number, targetHeight: number): Canvas;
}
 
// Type definitions for clarity
interface ImageData {
    pixels: Uint8Array;
    width: number;
    height: number;
    format: 'RGB' | 'RGBA' | 'Grayscale';
}
 
interface ImageMetadata {
    format: string;
    colorSpace: string;
    createdAt?: Date;
    camera?: string;
    location?: { lat: number; lng: number };
}

Step 2: Implement the RealSubject

The real subject contains the actual implementation. It knows nothing about proxies—it simply does its job.

real-subject.ts
TypeScript
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
// RealSubject - the actual implementation
class RealImageLoader implements ImageLoader {
    private imageData: ImageData | null = null;
    private metadata: ImageMetadata | null = null;
    
    constructor(private readonly imagePath: string) {
        // Note: We intentionally don't load in constructor
        // But a naive implementation might!
    }
    
    loadImage(): ImageData {
        if (!this.imageData) {
            console.log(`Loading image from disk: ${this.imagePath}`);
            
            // Expensive operation - reads file, decodes format
            const rawBytes = FileSystem.readFile(this.imagePath);
            this.imageData = ImageDecoder.decode(rawBytes);
            
            console.log(`Loaded ${this.imageData.pixels.length} bytes`);
        }
        return this.imageData;
    }
    
    getDimensions(): { width: number; height: number } {
        // For dimensions, we can read just the header
        // without loading the full image
        if (!this.metadata) {
            this.metadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return {
            width: this.metadata.width,
            height: this.metadata.height,
        };
    }
    
    getMetadata(): ImageMetadata {
        if (!this.metadata) {
            this.metadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return this.metadata;
    }
    
    render(targetWidth: number, targetHeight: number): Canvas {
        const image = this.loadImage();
        const canvas = new Canvas(targetWidth, targetHeight);
        canvas.drawImage(image, 0, 0, targetWidth, targetHeight);
        return canvas;
    }
}

Step 3: Create the Proxy

The proxy implements the same interface but adds control logic. Here's a basic proxy structure:

proxy-implementation.ts
TypeScript
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
// Proxy - controls access to RealSubject
class ImageLoaderProxy implements ImageLoader {
    // Reference to the real subject - may be null initially
    private realLoader: RealImageLoader | null = null;
    
    // Cached lightweight data
    private cachedMetadata: ImageMetadata | null = null;
    
    constructor(private readonly imagePath: string) {
        // Proxy is cheap to create - doesn't load anything
        console.log(`Proxy created for: ${imagePath}`);
    }
    
    // Lazy initialization - create real subject only when needed
    private getRealLoader(): RealImageLoader {
        if (!this.realLoader) {
            console.log('Proxy: Creating real loader on first access');
            this.realLoader = new RealImageLoader(this.imagePath);
        }
        return this.realLoader;
    }
    
    loadImage(): ImageData {
        console.log('Proxy: loadImage() called');
        // Delegate to real subject
        return this.getRealLoader().loadImage();
    }
    
    getDimensions(): { width: number; height: number } {
        console.log('Proxy: getDimensions() called');
        // We can get dimensions from metadata - might not need real loader
        const metadata = this.getMetadata();
        return { width: metadata.width, height: metadata.height };
    }
    
    getMetadata(): ImageMetadata {
        console.log('Proxy: getMetadata() called');
        // Cache metadata - it's lightweight
        if (!this.cachedMetadata) {
            // Read just metadata, doesn't need full image load
            this.cachedMetadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return this.cachedMetadata;
    }
    
    render(targetWidth: number, targetHeight: number): Canvas {
        console.log(`Proxy: render(${targetWidth}, ${targetHeight}) called`);
        // Must delegate to real subject for full rendering
        return this.getRealLoader().render(targetWidth, targetHeight);
    }
}

The Proxy's Added Value

Notice how the proxy adds value: it's cheap to create, caches lightweight metadata, and only creates the expensive RealImageLoader when truly necessary. The client sees the same interface but gets optimized behavior.

Client Code and Transparency

The beauty of the Proxy pattern lies in client code transparency. Clients work with the Subject interface and don't know—or care—whether they're using a proxy or the real object.

transparent-client.ts
TypeScript
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
// Client code - works identically with Proxy or RealSubject
class ImageGallery {
    private images: ImageLoader[] = [];
    
    addImage(loader: ImageLoader): void {
        // Gallery doesn't know if this is a Proxy or RealSubject
        this.images.push(loader);
    }
    
    renderThumbnails(container: HTMLElement): void {
        for (const image of this.images) {
            // Only getDimensions is called for layout
            // If using proxies, heavy image data isn't loaded yet!
            const dims = image.getDimensions();
            
            const placeholder = document.createElement('div');
            placeholder.style.width = `${dims.width / 10}px`;
            placeholder.style.height = `${dims.height / 10}px`;
            placeholder.onclick = () => this.showFullSize(image);
            
            container.appendChild(placeholder);
        }
    }
    
    showFullSize(image: ImageLoader): void {
        // NOW the full image is needed
        // If proxy, this triggers actual loading
        const canvas = image.render(800, 600);
        this.displayCanvas(canvas);
    }
}
 
// Usage - client doesn't know about proxies
const gallery = new ImageGallery();
 
// Could pass RealImageLoader or ImageLoaderProxy - same interface!
gallery.addImage(new ImageLoaderProxy('/photos/vacation1.jpg'));
gallery.addImage(new ImageLoaderProxy('/photos/vacation2.jpg'));
gallery.addImage(new ImageLoaderProxy('/photos/vacation3.jpg'));
// ... add 1000 more images
 
// Renders thumbnails instantly - no heavy loading yet
gallery.renderThumbnails(document.getElementById('gallery')!);
 
// Only when user clicks does the specific image load

Without Proxy

•Loading 1000 images consumes 10GB RAM
•Gallery takes 5+ minutes to open
•User waits before seeing anything
•System might crash from memory pressure

With Proxy

•1000 proxies consume ~100KB total
•Gallery opens in milliseconds
•User sees thumbnails immediately
•Images load on-demand, never crash

Substitutability in Action

The client code (ImageGallery) works identically whether you pass proxies or real subjects. This is true polymorphism—behavior varies based on the actual object type, but the interface remains constant.

The Reference Management Question

A critical design decision in proxy implementation is how the proxy obtains and manages its reference to the real subject. There are several strategies, each with tradeoffs.

4.1 Lazy Creation

The proxy creates the real subject on first access. This is the most common approach for virtual proxies.

lazy-creation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class LazyProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    private ensureRealSubject(): RealSubject {
        if (!this.realSubject) {
            // Created on first need
            this.realSubject = new RealSubject(this.config);
        }
        return this.realSubject;
    }
    
    request(): Result {
        return this.ensureRealSubject().request();
    }
}
 
// Pros: Deferred creation, simple interface
// Cons: Creation parameters must be stored by proxy

4.2 Injected Reference

The real subject is provided to the proxy at construction. This is common for protection and logging proxies.

injected-reference.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class InjectedProxy implements Subject {
    constructor(private readonly realSubject: RealSubject) {
        // Real subject already exists
    }
    
    request(): Result {
        // Pre-processing (logging, auth check, etc.)
        this.logAccess();
        
        const result = this.realSubject.request();
        
        // Post-processing
        this.logResult(result);
        
        return result;
    }
}
 
// Pros: Clear dependency, easy to test with mocks
// Cons: Real subject must exist before proxy (no lazy creation)

4.3 Factory-Based Creation

The proxy receives a factory that creates the real subject. This provides maximum flexibility.

factory-creation.ts
TypeScript
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
interface SubjectFactory {
    create(): RealSubject;
}
 
class FactoryProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    constructor(private readonly factory: SubjectFactory) {}
    
    private ensureRealSubject(): RealSubject {
        if (!this.realSubject) {
            this.realSubject = this.factory.create();
        }
        return this.realSubject;
    }
    
    request(): Result {
        return this.ensureRealSubject().request();
    }
}
 
// Usage
const proxy = new FactoryProxy({
    create: () => new RealSubject(getConfig(), getDependencies())
});
 
// Pros: Lazy + complex construction, easily testable
// Cons: More indirection, factory interface needed

Reference Management Strategy Comparison
Strategy	Best For	Tradeoffs
Lazy Creation	Virtual proxies, expensive resources	Must store creation parameters; complex construction challenging
Injected Reference	Protection proxies, logging proxies	No lazy creation; real subject must exist first
Factory-Based	Complex dependencies, testable code	More indirection; requires factory interface
Service Locator	Remote proxies, dynamic discovery	Hidden dependencies; harder to test

Handling the Full Interface

When the real subject has many methods, implementing proxy methods one by one becomes tedious. There are several strategies to handle this:

5.1 Explicit Delegation (Most Control)

explicit-delegation.ts
TypeScript
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
// Explicit delegation - each method individually implemented
class ExplicitProxy implements ComplexService {
    constructor(private readonly real: RealComplexService) {}
    
    // Access control on specific methods
    sensitiveOperation(): void {
        if (!this.hasPermission()) {
            throw new UnauthorizedError('No permission');
        }
        this.real.sensitiveOperation();
    }
    
    // Caching on expensive methods
    expensiveQuery(criteria: Criteria): Results {
        const cacheKey = this.computeCacheKey(criteria);
        const cached = this.cache.get(cacheKey);
        if (cached) return cached;
        
        const result = this.real.expensiveQuery(criteria);
        this.cache.set(cacheKey, result);
        return result;
    }
    
    // Simple passthrough for other methods
    simpleGetter(): string {
        return this.real.simpleGetter();
    }
    
    anotherGetter(): number {
        return this.real.anotherGetter();
    }
    
    // ... potentially many more passthroughs
}

5.2 Dynamic Proxy (Less Boilerplate)

Modern languages offer mechanisms for dynamic proxies that intercept all method calls. This reduces boilerplate but may sacrifice type safety.

dynamic-proxy.ts
TypeScript
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
// Dynamic proxy in JavaScript/TypeScript using Proxy object
function createLoggingProxy<T extends object>(target: T, logger: Logger): T {
    return new Proxy(target, {
        get(obj, prop) {
            const value = Reflect.get(obj, prop);
            
            if (typeof value === 'function') {
                return function(...args: unknown[]) {
                    logger.log(`Calling ${String(prop)} with args:`, args);
                    const start = performance.now();
                    
                    try {
                        const result = value.apply(obj, args);
                        
                        // Handle promises
                        if (result instanceof Promise) {
                            return result.then(r => {
                                logger.log(`${String(prop)} resolved in ${performance.now() - start}ms`);
                                return r;
                            });
                        }
                        
                        logger.log(`${String(prop)} completed in ${performance.now() - start}ms`);
                        return result;
                    } catch (error) {
                        logger.error(`${String(prop)} threw error:`, error);
                        throw error;
                    }
                };
            }
            
            return value;
        }
    });
}
 
// Usage - no manual method implementations needed!
const service = new RealComplexService();
const loggedService = createLoggingProxy(service, console);
 
// All method calls are now logged automatically
loggedService.anyMethod();  // Logged!
loggedService.anotherMethod();  // Logged!

Dynamic Proxy Tradeoffs

Dynamic proxies are powerful but have drawbacks: loss of static type checking, potential performance overhead, debugging can be confusing (stack traces include proxy machinery), and they may not work with all edge cases (constructors, getters, symbols). Use explicit delegation when behavior differs per method.

5.3 Mixin / Trait Pattern

For languages supporting mixins, proxy behavior can be composed from reusable traits:

mixin-proxy.ts
TypeScript
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
// Reusable proxy behaviors as mixins
const LoggingMixin = <T extends Constructor<{}>>(Base: T) =>
    class extends Base {
        protected logMethodCall(method: string, args: unknown[]): void {
            console.log(`[${new Date().toISOString()}] ${method}`, args);
        }
    };
 
const CachingMixin = <T extends Constructor<{}>>(Base: T) =>
    class extends Base {
        protected cache = new Map<string, unknown>();
        
        protected withCache<R>(key: string, compute: () => R): R {
            if (this.cache.has(key)) {
                return this.cache.get(key) as R;
            }
            const result = compute();
            this.cache.set(key, result);
            return result;
        }
    };
 
// Compose behaviors
class EnhancedProxy extends LoggingMixin(CachingMixin(BaseProxy)) {
    expensiveOperation(input: string): Result {
        this.logMethodCall('expensiveOperation', [input]);
        return this.withCache(`expensive:${input}`, () => 
            this.realSubject.expensiveOperation(input)
        );
    }
}

Proxy vs. Decorator — Understanding the Difference

Proxy and Decorator patterns look structurally similar—both wrap an object implementing the same interface. However, their intent differs fundamentally:

Proxy vs. Decorator Pattern Comparison
Aspect	Proxy	Decorator
Primary Intent	Control access to object	Add responsibilities to object
Relationship	Proxy manages the wrapped object's lifecycle	Decorator enhances without managing lifecycle
Transparency	Client often doesn't know proxy exists	Decorators can be chained visibly
Creation	Proxy often creates the wrapped object	Decorator typically receives existing object
Multiplicity	Usually single proxy per subject	Multiple decorators commonly stacked
Focus	Access control, lazy loading, remote access	Adding features, modifying behavior

proxy-vs-decorator.ts
TypeScript
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
// PROXY: Controls access - creates/manages the subject
class ProtectionProxy implements Document {
    private realDocument: RealDocument | null = null;
    
    constructor(
        private documentId: string,
        private user: User
    ) {
        // Proxy creates subject internally
    }
    
    read(): string {
        // Access control - the core proxy purpose
        if (!this.user.canRead(this.documentId)) {
            throw new UnauthorizedError();
        }
        return this.getDocument().read();
    }
    
    private getDocument(): RealDocument {
        if (!this.realDocument) {
            this.realDocument = new RealDocument(this.documentId);
        }
        return this.realDocument;
    }
}
 
// DECORATOR: Adds behavior - wraps existing subject
class EncryptionDecorator implements Document {
    constructor(
        private document: Document,  // Receives existing subject
        private encryptionKey: string
    ) {}
    
    read(): string {
        // Adds behavior: decryption
        const encrypted = this.document.read();
        return this.decrypt(encrypted);
    }
    
    write(content: string): void {
        // Adds behavior: encryption
        const encrypted = this.encrypt(content);
        this.document.write(encrypted);
    }
}
 
// Decorators stack; proxies typically don't
const doc = new RealDocument('doc-123');
const encrypted = new EncryptionDecorator(doc, 'key');
const compressed = new CompressionDecorator(encrypted);  // Stack decorators
const versioned = new VersioningDecorator(compressed);

The Mental Model

Think of Proxy as a 'gatekeeper' that decides IF and WHEN you can access something. Think of Decorator as a 'wrapper' that modifies WHAT you get when you access it. Proxy controls access; Decorator transforms results.

Thread Safety Considerations

When proxies manage lazy initialization, thread safety becomes critical. Multiple threads may attempt to access the proxy simultaneously, potentially creating multiple instances of the real subject or causing race conditions.

thread-safe-proxy.ts
TypeScript
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
// PROBLEM: Race condition in lazy initialization
class UnsafeProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    request(): Result {
        // Thread A: checks null -> true
        // Thread B: checks null -> true (before A creates)
        if (!this.realSubject) {
            // Both threads create instances!
            this.realSubject = new RealSubject();
        }
        return this.realSubject.request();
    }
}
 
// SOLUTION 1: Lock-based synchronization
class SynchronizedProxy implements Subject {
    private realSubject: RealSubject | null = null;
    private mutex = new Mutex();
    
    async request(): Promise<Result> {
        await this.mutex.acquire();
        try {
            if (!this.realSubject) {
                this.realSubject = new RealSubject();
            }
            return this.realSubject.request();
        } finally {
            this.mutex.release();
        }
    }
}
 
// SOLUTION 2: Double-checked locking
class DoubleCheckedProxy implements Subject {
    private realSubject: RealSubject | null = null;
    private mutex = new Mutex();
    
    async request(): Promise<Result> {
        // First check (no lock)
        if (!this.realSubject) {
            await this.mutex.acquire();
            try {
                // Second check (with lock)
                if (!this.realSubject) {
                    this.realSubject = new RealSubject();
                }
            } finally {
                this.mutex.release();
            }
        }
        return this.realSubject.request();
    }
}
 
// SOLUTION 3: Eager initialization (simplest, if feasible)
class EagerProxy implements Subject {
    private readonly realSubject = new RealSubject();
    
    request(): Result {
        // No synchronization needed - already initialized
        return this.realSubject.request();
    }
}

JavaScript/TypeScript Note

JavaScript is single-threaded (except for Workers), so race conditions in lazy initialization are rare in typical client code. However, when using async/await with external resources, interleaving can still cause issues. Server-side TypeScript with clustering or Workers requires full thread-safety consideration.

Summary: The Surrogate Solution

We've explored the structural foundation of the Proxy pattern and how surrogates provide controlled access to real subjects:

Key Takeaways

•Three participants: Subject interface, RealSubject implementation, Proxy implementation
•Same interface requirement enables transparent substitution (LSP in action)
•Client transparency — clients don't know they're using proxies
•Reference management strategies: lazy creation, injection, factory-based, service locator
•Implementation approaches: explicit delegation, dynamic proxies, mixin composition
•Proxy vs. Decorator: proxy controls access; decorator adds responsibilities
•Thread safety must be considered for lazy initialization in concurrent environments

What's Next:

Now that we understand the basic structure, the next page dives deep into the different types of proxies: Virtual Proxy for lazy loading, Protection Proxy for access control, and Remote Proxy for location transparency. Each type applies the same structural pattern but serves distinct purposes.

Page Complete

You now understand how the Proxy pattern structures its solution—creating a surrogate that shares the same interface as the real subject. Next, we'll explore the specific proxy types and their implementations in detail.

2 / 4

Loading learning content...

System Design LLDStructural Patterns

Proxy Pattern

LevelIntermediate

Duration90 mins

TopicStructural Patterns

2 / 4

Solution — Surrogate with Same Interface

The Power of the Stand-In

In the previous page, we identified a fundamental design challenge: how do we control access to objects without modifying the objects themselves or burdening client code?

The Proxy pattern's solution is elegant in its simplicity: create a stand-in object that looks exactly like the real object but controls access to it.

Think of a proxy like a personal assistant to a busy executive. When you call the executive's office, you speak to the assistant who:

Uses the same communication protocol (phone, email)
Can answer many questions directly (cached information)
Screens requests (access control)
Schedules appropriate times for actual contact (lazy initialization)
Summarizes interactions afterward (logging)

The caller might not even realize they're not speaking directly to the executive—the interface is identical.

What You Will Learn

The Proxy Pattern Structure

The Proxy pattern defines three essential components that work together:

1.1 Pattern Participants

Subject (Interface) Defines the common interface for RealSubject and Proxy. This shared interface is what enables the Proxy to be used anywhere the RealSubject is expected.

RealSubject The actual object that does the real work. It implements the Subject interface and contains the business logic, expensive resources, or protected operations.

Converting Mermaid diagram...

The Interface Is Key

1.2 Collaboration Flow

Here's how the participants collaborate at runtime:

Converting Mermaid diagram...

Implementing the Basic Structure

Let's build a concrete implementation step by step. We'll start with the foundational structure before exploring specific proxy types.

Step 1: Define the Subject Interface

The interface defines what operations are available. Both the real subject and proxy must implement this exactly.

subject-interface.ts
TypeScript
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
// Subject Interface - the contract both must fulfill
interface ImageLoader {
    /**
     * Load an image from the specified path
     * @returns The loaded image data ready for display
     */
    loadImage(): ImageData;
    
    /**
     * Get the dimensions without fully loading the image
     * @returns Width and height in pixels
     */
    getDimensions(): { width: number; height: number };
    
    /**
     * Get metadata about the image (EXIF, format, etc.)
     */
    getMetadata(): ImageMetadata;
    
    /**
     * Render the image to a canvas at specified dimensions
     */
    render(targetWidth: number, targetHeight: number): Canvas;
}
 
// Type definitions for clarity
interface ImageData {
    pixels: Uint8Array;
    width: number;
    height: number;
    format: 'RGB' | 'RGBA' | 'Grayscale';
}
 
interface ImageMetadata {
    format: string;
    colorSpace: string;
    createdAt?: Date;
    camera?: string;
    location?: { lat: number; lng: number };
}

Step 2: Implement the RealSubject

The real subject contains the actual implementation. It knows nothing about proxies—it simply does its job.

real-subject.ts
TypeScript
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
// RealSubject - the actual implementation
class RealImageLoader implements ImageLoader {
    private imageData: ImageData | null = null;
    private metadata: ImageMetadata | null = null;
    
    constructor(private readonly imagePath: string) {
        // Note: We intentionally don't load in constructor
        // But a naive implementation might!
    }
    
    loadImage(): ImageData {
        if (!this.imageData) {
            console.log(`Loading image from disk: ${this.imagePath}`);
            
            // Expensive operation - reads file, decodes format
            const rawBytes = FileSystem.readFile(this.imagePath);
            this.imageData = ImageDecoder.decode(rawBytes);
            
            console.log(`Loaded ${this.imageData.pixels.length} bytes`);
        }
        return this.imageData;
    }
    
    getDimensions(): { width: number; height: number } {
        // For dimensions, we can read just the header
        // without loading the full image
        if (!this.metadata) {
            this.metadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return {
            width: this.metadata.width,
            height: this.metadata.height,
        };
    }
    
    getMetadata(): ImageMetadata {
        if (!this.metadata) {
            this.metadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return this.metadata;
    }
    
    render(targetWidth: number, targetHeight: number): Canvas {
        const image = this.loadImage();
        const canvas = new Canvas(targetWidth, targetHeight);
        canvas.drawImage(image, 0, 0, targetWidth, targetHeight);
        return canvas;
    }
}

Step 3: Create the Proxy

The proxy implements the same interface but adds control logic. Here's a basic proxy structure:

proxy-implementation.ts
TypeScript
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
// Proxy - controls access to RealSubject
class ImageLoaderProxy implements ImageLoader {
    // Reference to the real subject - may be null initially
    private realLoader: RealImageLoader | null = null;
    
    // Cached lightweight data
    private cachedMetadata: ImageMetadata | null = null;
    
    constructor(private readonly imagePath: string) {
        // Proxy is cheap to create - doesn't load anything
        console.log(`Proxy created for: ${imagePath}`);
    }
    
    // Lazy initialization - create real subject only when needed
    private getRealLoader(): RealImageLoader {
        if (!this.realLoader) {
            console.log('Proxy: Creating real loader on first access');
            this.realLoader = new RealImageLoader(this.imagePath);
        }
        return this.realLoader;
    }
    
    loadImage(): ImageData {
        console.log('Proxy: loadImage() called');
        // Delegate to real subject
        return this.getRealLoader().loadImage();
    }
    
    getDimensions(): { width: number; height: number } {
        console.log('Proxy: getDimensions() called');
        // We can get dimensions from metadata - might not need real loader
        const metadata = this.getMetadata();
        return { width: metadata.width, height: metadata.height };
    }
    
    getMetadata(): ImageMetadata {
        console.log('Proxy: getMetadata() called');
        // Cache metadata - it's lightweight
        if (!this.cachedMetadata) {
            // Read just metadata, doesn't need full image load
            this.cachedMetadata = ImageDecoder.readMetadata(this.imagePath);
        }
        return this.cachedMetadata;
    }
    
    render(targetWidth: number, targetHeight: number): Canvas {
        console.log(`Proxy: render(${targetWidth}, ${targetHeight}) called`);
        // Must delegate to real subject for full rendering
        return this.getRealLoader().render(targetWidth, targetHeight);
    }
}

The Proxy's Added Value

Client Code and Transparency

The beauty of the Proxy pattern lies in client code transparency. Clients work with the Subject interface and don't know—or care—whether they're using a proxy or the real object.

transparent-client.ts
TypeScript
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
// Client code - works identically with Proxy or RealSubject
class ImageGallery {
    private images: ImageLoader[] = [];
    
    addImage(loader: ImageLoader): void {
        // Gallery doesn't know if this is a Proxy or RealSubject
        this.images.push(loader);
    }
    
    renderThumbnails(container: HTMLElement): void {
        for (const image of this.images) {
            // Only getDimensions is called for layout
            // If using proxies, heavy image data isn't loaded yet!
            const dims = image.getDimensions();
            
            const placeholder = document.createElement('div');
            placeholder.style.width = `${dims.width / 10}px`;
            placeholder.style.height = `${dims.height / 10}px`;
            placeholder.onclick = () => this.showFullSize(image);
            
            container.appendChild(placeholder);
        }
    }
    
    showFullSize(image: ImageLoader): void {
        // NOW the full image is needed
        // If proxy, this triggers actual loading
        const canvas = image.render(800, 600);
        this.displayCanvas(canvas);
    }
}
 
// Usage - client doesn't know about proxies
const gallery = new ImageGallery();
 
// Could pass RealImageLoader or ImageLoaderProxy - same interface!
gallery.addImage(new ImageLoaderProxy('/photos/vacation1.jpg'));
gallery.addImage(new ImageLoaderProxy('/photos/vacation2.jpg'));
gallery.addImage(new ImageLoaderProxy('/photos/vacation3.jpg'));
// ... add 1000 more images
 
// Renders thumbnails instantly - no heavy loading yet
gallery.renderThumbnails(document.getElementById('gallery')!);
 
// Only when user clicks does the specific image load

Without Proxy

•Loading 1000 images consumes 10GB RAM
•Gallery takes 5+ minutes to open
•User waits before seeing anything
•System might crash from memory pressure

With Proxy

•1000 proxies consume ~100KB total
•Gallery opens in milliseconds
•User sees thumbnails immediately
•Images load on-demand, never crash

Substitutability in Action

The Reference Management Question

A critical design decision in proxy implementation is how the proxy obtains and manages its reference to the real subject. There are several strategies, each with tradeoffs.

4.1 Lazy Creation

The proxy creates the real subject on first access. This is the most common approach for virtual proxies.

lazy-creation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class LazyProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    private ensureRealSubject(): RealSubject {
        if (!this.realSubject) {
            // Created on first need
            this.realSubject = new RealSubject(this.config);
        }
        return this.realSubject;
    }
    
    request(): Result {
        return this.ensureRealSubject().request();
    }
}
 
// Pros: Deferred creation, simple interface
// Cons: Creation parameters must be stored by proxy

4.2 Injected Reference

The real subject is provided to the proxy at construction. This is common for protection and logging proxies.

injected-reference.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class InjectedProxy implements Subject {
    constructor(private readonly realSubject: RealSubject) {
        // Real subject already exists
    }
    
    request(): Result {
        // Pre-processing (logging, auth check, etc.)
        this.logAccess();
        
        const result = this.realSubject.request();
        
        // Post-processing
        this.logResult(result);
        
        return result;
    }
}
 
// Pros: Clear dependency, easy to test with mocks
// Cons: Real subject must exist before proxy (no lazy creation)

4.3 Factory-Based Creation

The proxy receives a factory that creates the real subject. This provides maximum flexibility.

factory-creation.ts
TypeScript
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
interface SubjectFactory {
    create(): RealSubject;
}
 
class FactoryProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    constructor(private readonly factory: SubjectFactory) {}
    
    private ensureRealSubject(): RealSubject {
        if (!this.realSubject) {
            this.realSubject = this.factory.create();
        }
        return this.realSubject;
    }
    
    request(): Result {
        return this.ensureRealSubject().request();
    }
}
 
// Usage
const proxy = new FactoryProxy({
    create: () => new RealSubject(getConfig(), getDependencies())
});
 
// Pros: Lazy + complex construction, easily testable
// Cons: More indirection, factory interface needed

Reference Management Strategy Comparison
Strategy	Best For	Tradeoffs
Lazy Creation	Virtual proxies, expensive resources	Must store creation parameters; complex construction challenging
Injected Reference	Protection proxies, logging proxies	No lazy creation; real subject must exist first
Factory-Based	Complex dependencies, testable code	More indirection; requires factory interface
Service Locator	Remote proxies, dynamic discovery	Hidden dependencies; harder to test

Handling the Full Interface

When the real subject has many methods, implementing proxy methods one by one becomes tedious. There are several strategies to handle this:

5.1 Explicit Delegation (Most Control)

explicit-delegation.ts
TypeScript
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
// Explicit delegation - each method individually implemented
class ExplicitProxy implements ComplexService {
    constructor(private readonly real: RealComplexService) {}
    
    // Access control on specific methods
    sensitiveOperation(): void {
        if (!this.hasPermission()) {
            throw new UnauthorizedError('No permission');
        }
        this.real.sensitiveOperation();
    }
    
    // Caching on expensive methods
    expensiveQuery(criteria: Criteria): Results {
        const cacheKey = this.computeCacheKey(criteria);
        const cached = this.cache.get(cacheKey);
        if (cached) return cached;
        
        const result = this.real.expensiveQuery(criteria);
        this.cache.set(cacheKey, result);
        return result;
    }
    
    // Simple passthrough for other methods
    simpleGetter(): string {
        return this.real.simpleGetter();
    }
    
    anotherGetter(): number {
        return this.real.anotherGetter();
    }
    
    // ... potentially many more passthroughs
}

5.2 Dynamic Proxy (Less Boilerplate)

Modern languages offer mechanisms for dynamic proxies that intercept all method calls. This reduces boilerplate but may sacrifice type safety.

dynamic-proxy.ts
TypeScript
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
// Dynamic proxy in JavaScript/TypeScript using Proxy object
function createLoggingProxy<T extends object>(target: T, logger: Logger): T {
    return new Proxy(target, {
        get(obj, prop) {
            const value = Reflect.get(obj, prop);
            
            if (typeof value === 'function') {
                return function(...args: unknown[]) {
                    logger.log(`Calling ${String(prop)} with args:`, args);
                    const start = performance.now();
                    
                    try {
                        const result = value.apply(obj, args);
                        
                        // Handle promises
                        if (result instanceof Promise) {
                            return result.then(r => {
                                logger.log(`${String(prop)} resolved in ${performance.now() - start}ms`);
                                return r;
                            });
                        }
                        
                        logger.log(`${String(prop)} completed in ${performance.now() - start}ms`);
                        return result;
                    } catch (error) {
                        logger.error(`${String(prop)} threw error:`, error);
                        throw error;
                    }
                };
            }
            
            return value;
        }
    });
}
 
// Usage - no manual method implementations needed!
const service = new RealComplexService();
const loggedService = createLoggingProxy(service, console);
 
// All method calls are now logged automatically
loggedService.anyMethod();  // Logged!
loggedService.anotherMethod();  // Logged!

Dynamic Proxy Tradeoffs

5.3 Mixin / Trait Pattern

For languages supporting mixins, proxy behavior can be composed from reusable traits:

mixin-proxy.ts
TypeScript
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
// Reusable proxy behaviors as mixins
const LoggingMixin = <T extends Constructor<{}>>(Base: T) =>
    class extends Base {
        protected logMethodCall(method: string, args: unknown[]): void {
            console.log(`[${new Date().toISOString()}] ${method}`, args);
        }
    };
 
const CachingMixin = <T extends Constructor<{}>>(Base: T) =>
    class extends Base {
        protected cache = new Map<string, unknown>();
        
        protected withCache<R>(key: string, compute: () => R): R {
            if (this.cache.has(key)) {
                return this.cache.get(key) as R;
            }
            const result = compute();
            this.cache.set(key, result);
            return result;
        }
    };
 
// Compose behaviors
class EnhancedProxy extends LoggingMixin(CachingMixin(BaseProxy)) {
    expensiveOperation(input: string): Result {
        this.logMethodCall('expensiveOperation', [input]);
        return this.withCache(`expensive:${input}`, () => 
            this.realSubject.expensiveOperation(input)
        );
    }
}

Proxy vs. Decorator — Understanding the Difference

Proxy and Decorator patterns look structurally similar—both wrap an object implementing the same interface. However, their intent differs fundamentally:

Proxy vs. Decorator Pattern Comparison
Aspect	Proxy	Decorator
Primary Intent	Control access to object	Add responsibilities to object
Relationship	Proxy manages the wrapped object's lifecycle	Decorator enhances without managing lifecycle
Transparency	Client often doesn't know proxy exists	Decorators can be chained visibly
Creation	Proxy often creates the wrapped object	Decorator typically receives existing object
Multiplicity	Usually single proxy per subject	Multiple decorators commonly stacked
Focus	Access control, lazy loading, remote access	Adding features, modifying behavior

proxy-vs-decorator.ts
TypeScript
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
// PROXY: Controls access - creates/manages the subject
class ProtectionProxy implements Document {
    private realDocument: RealDocument | null = null;
    
    constructor(
        private documentId: string,
        private user: User
    ) {
        // Proxy creates subject internally
    }
    
    read(): string {
        // Access control - the core proxy purpose
        if (!this.user.canRead(this.documentId)) {
            throw new UnauthorizedError();
        }
        return this.getDocument().read();
    }
    
    private getDocument(): RealDocument {
        if (!this.realDocument) {
            this.realDocument = new RealDocument(this.documentId);
        }
        return this.realDocument;
    }
}
 
// DECORATOR: Adds behavior - wraps existing subject
class EncryptionDecorator implements Document {
    constructor(
        private document: Document,  // Receives existing subject
        private encryptionKey: string
    ) {}
    
    read(): string {
        // Adds behavior: decryption
        const encrypted = this.document.read();
        return this.decrypt(encrypted);
    }
    
    write(content: string): void {
        // Adds behavior: encryption
        const encrypted = this.encrypt(content);
        this.document.write(encrypted);
    }
}
 
// Decorators stack; proxies typically don't
const doc = new RealDocument('doc-123');
const encrypted = new EncryptionDecorator(doc, 'key');
const compressed = new CompressionDecorator(encrypted);  // Stack decorators
const versioned = new VersioningDecorator(compressed);

The Mental Model

Thread Safety Considerations

thread-safe-proxy.ts
TypeScript
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
// PROBLEM: Race condition in lazy initialization
class UnsafeProxy implements Subject {
    private realSubject: RealSubject | null = null;
    
    request(): Result {
        // Thread A: checks null -> true
        // Thread B: checks null -> true (before A creates)
        if (!this.realSubject) {
            // Both threads create instances!
            this.realSubject = new RealSubject();
        }
        return this.realSubject.request();
    }
}
 
// SOLUTION 1: Lock-based synchronization
class SynchronizedProxy implements Subject {
    private realSubject: RealSubject | null = null;
    private mutex = new Mutex();
    
    async request(): Promise<Result> {
        await this.mutex.acquire();
        try {
            if (!this.realSubject) {
                this.realSubject = new RealSubject();
            }
            return this.realSubject.request();
        } finally {
            this.mutex.release();
        }
    }
}
 
// SOLUTION 2: Double-checked locking
class DoubleCheckedProxy implements Subject {
    private realSubject: RealSubject | null = null;
    private mutex = new Mutex();
    
    async request(): Promise<Result> {
        // First check (no lock)
        if (!this.realSubject) {
            await this.mutex.acquire();
            try {
                // Second check (with lock)
                if (!this.realSubject) {
                    this.realSubject = new RealSubject();
                }
            } finally {
                this.mutex.release();
            }
        }
        return this.realSubject.request();
    }
}
 
// SOLUTION 3: Eager initialization (simplest, if feasible)
class EagerProxy implements Subject {
    private readonly realSubject = new RealSubject();
    
    request(): Result {
        // No synchronization needed - already initialized
        return this.realSubject.request();
    }
}

JavaScript/TypeScript Note

Summary: The Surrogate Solution

We've explored the structural foundation of the Proxy pattern and how surrogates provide controlled access to real subjects:

Key Takeaways

•Three participants: Subject interface, RealSubject implementation, Proxy implementation
•Same interface requirement enables transparent substitution (LSP in action)
•Client transparency — clients don't know they're using proxies
•Reference management strategies: lazy creation, injection, factory-based, service locator
•Implementation approaches: explicit delegation, dynamic proxies, mixin composition
•Proxy vs. Decorator: proxy controls access; decorator adds responsibilities
•Thread safety must be considered for lazy initialization in concurrent environments

What's Next:

Page Complete

2 / 4