Proxy (TypeScript)

Intent

Provide a drop-in stand-in that implements the same interface as the real service while controlling access, lifecycle, or cross-cutting behavior.

When to use

•You need a drop-in stand-in that preserves the same interface.
•Lazy init is required for an expensive or remote service.
•You want caching or logging without changing clients.
•Access control should be enforced at the boundary.
•Lifecycle (connect/close/retry) must be centralized.
•The real service is remote or flaky and needs shielding.
•You want to swap proxy vs real at wiring time.

When NOT to use

•You need a different interface (Adapter).
•You need a simplified subsystem API (Facade).
•The client wants explicit behavior stacking (Decorator).
•The indirection adds no value.
•The proxy would own business logic.
•Performance overhead is unacceptable.
•The service is simple and local.

Mental model

Proxy = same interface + indirection point; clients stay unaware.

Recommended TS shapes

•Interface + RealService + Proxy class (preferred).
•Factory/wiring function to choose proxy vs real.
•Async init with cached Promise for concurrency safety.

Example 1: Virtual proxy (lazy init)

interface ProfileService {
  getProfile(id: string): Promise<{ id: string; name: string }>;
}

class RealProfileService implements ProfileService {
  constructor(private readonly baseUrl: string) {}
  async getProfile(id: string): Promise<{ id: string; name: string }> {
    return { id, name: `user-${id}` };
  }
}

class ProfileServiceProxy implements ProfileService {
  private servicePromise: Promise<RealProfileService> | null = null;

  constructor(private readonly baseUrl: string) {}

  private async getService(): Promise<RealProfileService> {
    if (!this.servicePromise) {
      this.servicePromise = Promise.resolve(new RealProfileService(this.baseUrl));
    }
    return this.servicePromise;
  }

  async getProfile(id: string) {
    const svc = await this.getService();
    return svc.getProfile(id);
  }
}

const svc: ProfileService = new ProfileServiceProxy("https://api.example.com");
await svc.getProfile("123");

Example 2: Caching proxy with TTL

interface Repo {
  get(id: string): Promise<string | null>;
}

class InMemoryRepo implements Repo {
  private data = new Map<string, string>([["a", "1"]]);
  async get(id: string): Promise<string | null> {
    return this.data.get(id) ?? null;
  }
}

type CacheEntry = { value: string | null; expiresAt: number };

class CachingRepoProxy implements Repo {
  private cache = new Map<string, CacheEntry>();

  constructor(private readonly inner: Repo, private readonly ttlMs: number) {}

  async get(id: string): Promise<string | null> {
    const now = Date.now();
    const cached = this.cache.get(id);
    if (cached && cached.expiresAt > now) return cached.value;
    const value = await this.inner.get(id);
    this.cache.set(id, { value, expiresAt: now + this.ttlMs });
    return value;
  }

  invalidate(id: string): void {
    this.cache.delete(id);
  }
}

const repo: Repo = new CachingRepoProxy(new InMemoryRepo(), 1000);
await repo.get("a");

Example 3: Protection + logging proxy

interface BillingService {
  charge(userId: string, amountCents: number): Promise<boolean>;
}

class RealBillingService implements BillingService {
  async charge(userId: string, amountCents: number): Promise<boolean> {
    return amountCents > 0;
  }
}

class BillingProxy implements BillingService {
  constructor(private readonly inner: BillingService, private readonly token: string) {}

  async charge(userId: string, amountCents: number): Promise<boolean> {
    if (!this.token) throw new Error("unauthorized");
    console.log({ userId, amountCents, action: "charge" });
    return this.inner.charge(userId, amountCents);
  }
}

const billing: BillingService = new BillingProxy(new RealBillingService(), "token");
await billing.charge("u1", 500);

Testing strategy (pragmatic)

•Test proxy behavior with fake RealService.
•Verify delegation and side-effects explicitly.
•Avoid time-based flakiness by controlling clocks for TTL.

Common pitfalls

•Hidden latency from proxy logic.
•Cache staleness without invalidation strategy.
•Double-init race when async init is not cached.
•Swallowing errors or changing error semantics silently.
•Proxy doing too much beyond access/lifecycle concerns.
•Tight coupling to concrete implementations.
•Inconsistent behavior between proxy and real service.
•Overusing proxy where direct access is fine.

Checklist for refactors

•Define the service interface first.
•Decide proxy responsibility (auth, cache, lazy init, logging).
•Keep interface identical between proxy and real.
•Make async init safe with cached Promise.
•Document semantics (timeouts, retries, cache TTL).
•Wire proxy vs real at composition root.
•Test with fakes and explicit assertions.
•Monitor for added latency or failure modes.

Output expectations

When invoked, produce:

•Service interface and proxy responsibilities.
•Wiring plan (proxy vs real).
•Failure/cache semantics and tests.