Proxy Pattern

The Problem

An e-commerce platform has a product catalog service that simulates an expensive database lookup (500ms per call). Every request hits this slow service. Additionally, the catalog should be restricted based on user roles. Without an intermediary, caching logic and access control would need to be embedded in the catalog service itself.

The Solution

The Proxy pattern introduces two proxy objects: a Caching Proxy that stores previously fetched results in memory, and an Access Control Proxy that checks the caller’s role before allowing access. Both implement the same ProductCatalog interface, so the client interacts with them transparently. The proxies are layered: access control wraps caching, which wraps the real service.

Structure

Subject Interface (ProductCatalog) — Declares getProduct(id) and listProducts().
Real Subject (ProductCatalogService) — The actual catalog service with simulated 500ms delay.
Caching Proxy (CachingProxyService) — Caches results in a Map for instant subsequent access.
Access Control Proxy (AccessControlProxyService) — Checks the caller’s role before delegating. Throws ForbiddenException for unauthorized roles.

Implementation

The ProductCatalogService holds five products with a simulated 500ms delay. The caching proxy eliminates repeated delays — the first request takes ~500ms, the second returns instantly. The access control proxy only permits "admin" and "user" roles.

export interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
}

export interface ProductCatalog {
  getProduct(id: string): Product | null;
  listProducts(): Product[];
}

import { Injectable } from '@nestjs/common';
import { Product, ProductCatalog } from './product-catalog.interface';

@Injectable()
export class ProductCatalogService implements ProductCatalog {
  private readonly products: Product[] = [
    { id: '1', name: 'Wireless Headphones', price: 79.99, category: 'Electronics' },
    { id: '2', name: 'Leather Wallet', price: 49.99, category: 'Accessories' },
    { id: '3', name: 'Running Shoes', price: 119.99, category: 'Footwear' },
    { id: '4', name: 'Coffee Maker', price: 89.99, category: 'Kitchen' },
    { id: '5', name: 'Backpack', price: 59.99, category: 'Accessories' },
  ];

  getProduct(id: string): Product | null {
    // Simulate a slow database lookup (500ms delay in real scenario)
    const start = Date.now();
    while (Date.now() - start < 500) {
      // busy-wait to simulate delay
    }

    return this.products.find((p) => p.id === id) ?? null;
  }

  listProducts(): Product[] {
    return [...this.products];
  }
}

import { Injectable } from '@nestjs/common';
import { Product, ProductCatalog } from './product-catalog.interface';
import { ProductCatalogService } from './product-catalog.service';

@Injectable()
export class CachingProxyService implements ProductCatalog {
  private readonly cache = new Map<string, Product | null>();
  private cachedList: Product[] | null = null;

  constructor(private readonly realCatalog: ProductCatalogService) {}

  getProduct(id: string): Product | null {
    if (this.cache.has(id)) {
      return this.cache.get(id) ?? null;
    }

    const product = this.realCatalog.getProduct(id);
    this.cache.set(id, product);
    return product;
  }

  listProducts(): Product[] {
    if (this.cachedList) {
      return this.cachedList;
    }

    this.cachedList = this.realCatalog.listProducts();
    return this.cachedList;
  }

  isCached(id: string): boolean {
    return this.cache.has(id);
  }

  getCacheSize(): number {
    return this.cache.size;
  }
}

import { Injectable, ForbiddenException } from '@nestjs/common';
import type { Product, ProductCatalog } from './product-catalog.interface';

@Injectable()
export class AccessControlProxyService implements ProductCatalog {
  constructor(private readonly realCatalog: ProductCatalog) {}

  private checkAccess(role: string): void {
    const allowedRoles = ['admin', 'user'];
    if (!allowedRoles.includes(role)) {
      throw new ForbiddenException(
        `Role "${role}" does not have access to the product catalog`,
      );
    }
  }

  getProduct(id: string, role: string = 'user'): Product | null {
    this.checkAccess(role);
    return this.realCatalog.getProduct(id);
  }

  listProducts(role: string = 'user'): Product[] {
    this.checkAccess(role);
    return this.realCatalog.listProducts();
  }
}

NestJS Integration

All three classes are registered as NestJS providers. The CachingProxyService receives the real service via constructor injection. The AccessControlProxyService is configured with a useFactory provider that injects the CachingProxyService, creating the proxy chain through NestJS’s dependency injection. This demonstrates how NestJS’s DI container can compose proxies declaratively in the module definition.

When to Use

You need to add caching (virtual proxy) to avoid expensive repeated operations.
You need to control access based on permissions or roles (protection proxy).
You want to add logging, monitoring, or lazy initialization without modifying the real object.

When NOT to Use

The real object is already fast and lightweight — a caching proxy adds memory overhead for no gain.
Access control is better handled by framework-level guards that apply uniformly across endpoints.
The proxy interface would diverge significantly from the real subject.

Decorator

Attach additional responsibilities to an object dynamically.

Adapter

Convert the interface of a class into another interface clients expect.

Facade

Provide a unified interface to a set of interfaces in a subsystem.