Proxy Pattern

Analogy categoryAnalogies

A Stand-In That Controls Access

The Proxy pattern introduces a class that implements the same interface as a real subject object but sits in front of it, controlling how and when the real object is created, accessed, or invoked. Unlike Decorator, which adds new behavior to an object the client actively wants to use as-is, Proxy's defining intent is controlling access: deciding whether a call reaches the real object at all, deferring its creation, checking permissions before forwarding, or intercepting calls to add caching or logging without the client knowing the real object was ever bypassed or delayed. Because the proxy and real subject share an interface, client code written against the interface works identically whether it holds a proxy or the real object.

🏏

Cricket analogy: A team's media manager acts as a proxy between journalists and a star player like MS Dhoni, deciding which questions actually reach him and when, while journalists interact with the same 'press access' interface regardless of whether the manager or Dhoni himself is answering.

The Main Proxy Variants

Virtual proxies defer creation of an expensive real object until it's actually needed, such as not loading a large image from disk until it's actually scrolled into view. Protection proxies check the caller's permissions before forwarding a request, rejecting unauthorized calls without the real object ever being touched. Remote proxies represent an object that lives in a different address space or on a different machine, hiding network communication details behind a local-looking interface, as with gRPC or RMI stubs. Caching proxies store the results of expensive calls and return cached results for repeated identical requests instead of re-invoking the real subject. All four variants share the identical structural shape: same interface as the real subject, a held reference to it, and added logic wrapped around the delegated call.

🏏

Cricket analogy: A stadium doesn't print the giant screen replay until a boundary is actually hit (virtual proxy, deferred work), a ground pass checks accreditation before letting someone onto the pitch (protection proxy), and a satellite feed relays live footage from an overseas venue as if it were local (remote proxy).

A Worked Example

typescript

interface Image {
  display(): void;
}

class RealImage implements Image {
  constructor(private filename: string) {
    this.loadFromDisk(); // expensive operation
  }
  private loadFromDisk() {
    console.log(`Loading ${this.filename} from disk (slow)`);
  }
  display() {
    console.log(`Displaying ${this.filename}`);
  }
}

// Virtual proxy: defers creating RealImage until display() is actually called
class ImageProxy implements Image {
  private realImage: RealImage | null = null;
  constructor(private filename: string) {}

  display() {
    if (this.realImage === null) {
      this.realImage = new RealImage(this.filename); // lazy load, only once
    }
    this.realImage.display();
  }
}

const gallery: Image[] = [
  new ImageProxy('vacation1.jpg'),
  new ImageProxy('vacation2.jpg'),
];
// Disk loading only happens for images the user actually scrolls to and views
gallery[0].display();

Proxy and Decorator share the identical UML structure (a wrapper implementing the same interface as the wrapped object), which is why they're often confused. The difference is intent: Decorator's purpose is to add or enhance behavior the client wants applied to an object it's actively using; Proxy's purpose is to control whether, when, and how the client's calls reach the real object at all, sometimes without the client ever knowing a substitution or interception occurred.

A remote proxy that makes a method call look exactly like a local, in-memory call can hide real network latency, partial failure, and serialization costs from callers who reasonably assume the call is cheap and synchronous. This is sometimes called violating the 'first law of distributed computing' (don't pretend the network isn't there); document remote proxies clearly so callers understand the hidden cost.

Choosing Proxy Over Alternatives

Reach for Proxy when you need to intervene in access to an object without changing the object's own code and without the client needing to know an intervention is happening at all, such as adding authorization checks around a legacy service class you cannot modify. If the client should be aware that extra behavior is being layered on and actively opts into it, Decorator communicates that intent more clearly. If what you actually need is a completely different, simplified interface rather than gatekeeping the existing one, Facade is the better fit. Choosing between these three structurally similar patterns comes down to answering one question: are you translating an interface, simplifying a subsystem, adding wanted behavior, or gating and deferring access?

🏏

Cricket analogy: A board uses a 'central contract' gatekeeping layer (proxy-like) to control which players can be selected for international duty without changing the players themselves, distinct from a coach who openly adds a new batting technique a player wants (decorator-like).

Proxy provides a surrogate object implementing the same interface as a real subject, controlling access to it.
It differs from Decorator in intent: controlling access versus adding wanted behavior to an object.
Virtual proxies defer expensive object creation until it's actually needed.
Protection proxies check permissions before forwarding a call to the real subject.
Remote proxies hide network communication behind a local-looking interface.
Caching proxies return stored results instead of re-invoking the real subject for repeated calls.
Proxies that make remote calls look local risk hiding real latency and failure modes from callers.