Structural

Proxy

Provide a surrogate or placeholder for another object to control access to it.

Intent

Introduce a stand-in object that controls access to a real subject -- deferring its creation, guarding its operations, or adding cross-cutting concerns -- while presenting the same interface so that clients cannot tell the difference.

Problem

You have an object that is expensive to create, located on a remote server, or requires access control. Allowing unrestricted direct access wastes resources, compromises security, or couples the client to infrastructure details. You need a way to interpose control logic without changing the client or the real object.

Solution

Create a proxy class that implements the same interface as the real subject. The proxy holds a reference (or lazily creates one) to the real subject and forwards requests to it, adding behavior such as lazy initialization, access checks, logging, or caching around each delegation.

Participants

Subject -- the common interface shared by RealSubject and Proxy
RealSubject -- the actual object that performs the work
Proxy -- controls access to the RealSubject; implements the same interface
Client -- works with the Subject interface, unaware whether it holds a Proxy or the RealSubject

Advantages

Controls access to the real object without clients knowing
Enables lazy initialization of heavyweight objects (virtual proxy)
Can add caching, logging, or access control transparently
The real object's lifecycle can be managed independently of the client

Disadvantages

Adds an extra layer of indirection, which can complicate debugging
Response time may increase due to additional processing in the proxy
Proxy code can become complex when combining multiple concerns (caching + auth + logging)
The proxy must stay in sync with the real subject's interface evolution

Real-World Analogy

A credit card is a proxy for your bank account. The store (client) swipes the card (proxy) instead of accessing your cash (real subject) directly. The card performs access control (PIN verification), communicates with the bank, and may apply spending limits -- all before letting the transaction through.

Use Cases

Virtual proxy: deferring the loading of a high-resolution image until it is scrolled into view
Protection proxy: checking user permissions before allowing operations on a sensitive resource
Caching proxy: storing results of expensive database queries and returning cached data on repeat calls
Remote proxy: representing an object on a different server and marshalling calls over the network
Logging proxy: recording every method invocation for auditing or debugging purposes

Code Examples

proxy.ts

// Subject interface
interface Image {
  display(): void;
  getFilename(): string;
}

// RealSubject -- expensive to create
class HighResImage implements Image {
  private data: string;

  constructor(private readonly filename: string) {
    // Simulate expensive loading
    this.data = `[binary data of ${filename}]`;
    console.log(`Loaded ${filename} from disk (expensive!)`);
  }

  display(): void {
    console.log(`Displaying ${this.filename}`);
  }

  getFilename(): string {
    return this.filename;
  }
}

// Virtual Proxy -- defers creation until actually needed
class LazyImageProxy implements Image {
  private real: HighResImage | null = null;

  constructor(private readonly filename: string) {
    console.log(`Proxy created for ${filename} (no loading yet)`);
  }

  private ensureLoaded(): HighResImage {
    if (!this.real) {
      this.real = new HighResImage(this.filename);
    }
    return this.real;
  }

  display(): void {
    this.ensureLoaded().display();
  }

  getFilename(): string {
    return this.filename; // no need to load just for the name
  }
}

// Protection Proxy -- adds access control
class ProtectedImageProxy implements Image {
  constructor(
    private readonly inner: Image,
    private readonly userRole: string,
  ) {}

  display(): void {
    if (this.userRole !== "admin" && this.userRole !== "viewer") {
      throw new Error("Access denied: insufficient permissions");
    }
    this.inner.display();
  }

  getFilename(): string {
    return this.inner.getFilename();
  }
}

// Client code
const image: Image = new ProtectedImageProxy(
  new LazyImageProxy("sunset-4k.png"),
  "viewer",
);
console.log("Filename:", image.getFilename()); // no heavy load
image.display(); // triggers lazy load + access check

A virtual proxy that lazily loads a heavy image object on first access and a protection proxy that checks permissions before delegating operations.

Related Patterns