📘 Proxy Pattern: Controlled Access

🎯 Introduction

Have you ever had a friend who acted as your “representative” when you couldn’t be somewhere? 🤝 That’s exactly what the Proxy Pattern does in programming! It creates a stand-in object that controls access to another object, adding an extra layer of control and functionality.

In this tutorial, you’ll discover how to implement the Proxy Pattern in TypeScript to create powerful, controlled access to your objects. Whether you’re building secure systems, optimizing performance, or adding logging capabilities, the Proxy Pattern has got your back! 💪

What You’ll Learn Today 🎓

• The fundamentals of the Proxy Pattern and when to use it 🧠
• How to implement different types of proxies in TypeScript 🛡️
• Real-world applications like caching, validation, and security 🔐
• Best practices and common pitfalls to avoid 🚀

Let’s dive in and become proxy pattern masters! 🎉

📚 Understanding Proxy Pattern

Think of a proxy like a security guard at a building entrance 👮‍♂️. Before you can enter the building (access the real object), you must go through the security guard (the proxy). The guard can check your credentials, log your entry, or even deny access entirely!

What is the Proxy Pattern? 🤔

The Proxy Pattern provides a placeholder or surrogate for another object to control access to it. It’s like having a personal assistant who screens your calls and manages your schedule! 📱

Key Components 🔧

1. Subject Interface: Defines the common interface for RealSubject and Proxy
2. RealSubject: The actual object that the proxy represents
3. Proxy: Maintains a reference to the RealSubject and controls access to it
4. Client: Interacts with RealSubject through the Proxy

Types of Proxies 🎭

• Virtual Proxy: Delays expensive object creation (lazy loading) 💤
• Protection Proxy: Controls access based on permissions 🔒
• Remote Proxy: Represents objects in different address spaces 🌐
• Caching Proxy: Stores results to avoid repeated calculations 💾
• Logging Proxy: Adds logging functionality transparently 📝

🔧 Basic Syntax and Usage

Let’s start with a simple example to understand the basic structure of the Proxy Pattern in TypeScript! 🚀

// 🎯 Define the subject interface
interface Image {
  display(): void;
}

// 📸 Real subject - the actual image
class RealImage implements Image {
  private filename: string;

  constructor(filename: string) {
    this.filename = filename;
    this.loadFromDisk(); // 💾 Expensive operation!
  }

  private loadFromDisk(): void {
    console.log(`📂 Loading ${this.filename} from disk...`);
  }

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

// 🛡️ Proxy - controls access to the real image
class ProxyImage implements Image {
  private realImage: RealImage | null = null;
  private filename: string;

  constructor(filename: string) {
    this.filename = filename;
  }

  display(): void {
    // 💡 Lazy loading - create only when needed!
    if (this.realImage === null) {
      console.log('🔄 First time accessing, creating real image...');
      this.realImage = new RealImage(this.filename);
    }
    this.realImage.display();
  }
}

// 🎮 Using the proxy
const image1 = new ProxyImage('vacation-photo.jpg');
const image2 = new ProxyImage('family-portrait.jpg');

console.log('🎬 Images created but not loaded yet!');

// Images are loaded only when displayed
image1.display(); // Loads and displays
image1.display(); // Just displays (already loaded!)

Using JavaScript’s Built-in Proxy 🌟

TypeScript also supports JavaScript’s native Proxy object for even more flexibility!

// 🎯 Target object
const user = {
  name: 'Alice',
  age: 25,
  role: 'admin'
};

// 🛡️ Create a proxy with custom behavior
const secureUser = new Proxy(user, {
  get(target, property) {
    console.log(`📖 Accessing property: ${String(property)}`);
    return target[property as keyof typeof target];
  },
  
  set(target, property, value) {
    console.log(`✏️ Setting ${String(property)} = ${value}`);
    
    // 🔒 Add validation
    if (property === 'age' && typeof value === 'number' && value < 0) {
      throw new Error('❌ Age cannot be negative!');
    }
    
    target[property as keyof typeof target] = value;
    return true;
  }
});

// 🎮 Test it out!
console.log(secureUser.name); // Logs access, returns 'Alice'
secureUser.age = 30; // Logs the change

💡 Practical Examples

Let’s explore some real-world scenarios where the Proxy Pattern shines! 🌟

Example 1: API Cache Proxy 🚀

Imagine you’re building a weather app that makes expensive API calls. Let’s create a caching proxy to improve performance!

// 🌤️ Weather service interface
interface WeatherService {
  getWeather(city: string): Promise<string>;
}

// 🌐 Real weather service (makes actual API calls)
class RealWeatherService implements WeatherService {
  async getWeather(city: string): Promise<string> {
    console.log(`🌐 Making API call for ${city}...`);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 2000));
    return `${city}: Sunny, 25°C ☀️`;
  }
}

// 💾 Caching proxy
class CachedWeatherService implements WeatherService {
  private realService: RealWeatherService;
  private cache: Map<string, { data: string; timestamp: number }> = new Map();
  private cacheTimeout = 60000; // 1 minute cache

  constructor() {
    this.realService = new RealWeatherService();
  }

  async getWeather(city: string): Promise<string> {
    const cached = this.cache.get(city);
    
    // 🎯 Check if we have valid cached data
    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
      console.log(`💾 Returning cached weather for ${city}`);
      return cached.data;
    }

    // 🔄 Fetch fresh data
    console.log(`🔄 Cache miss for ${city}, fetching fresh data...`);
    const weather = await this.realService.getWeather(city);
    
    // 💾 Store in cache
    this.cache.set(city, { data: weather, timestamp: Date.now() });
    
    return weather;
  }
}

// 🎮 Usage
const weatherService = new CachedWeatherService();

async function checkWeather() {
  // First call - hits the API
  console.log(await weatherService.getWeather('London'));
  
  // Second call - returns from cache! 🚀
  console.log(await weatherService.getWeather('London'));
  
  // Different city - hits the API
  console.log(await weatherService.getWeather('Tokyo'));
}

checkWeather();

Example 2: Permission-Based Access Proxy 🔐

Let’s create a document management system with access control!

// 📄 Document interface
interface Document {
  read(): string;
  write(content: string): void;
  delete(): void;
}

// 👤 User roles
type UserRole = 'admin' | 'editor' | 'viewer';

// 📋 Real document
class RealDocument implements Document {
  private content: string;
  private title: string;

  constructor(title: string, content: string) {
    this.title = title;
    this.content = content;
  }

  read(): string {
    return this.content;
  }

  write(content: string): void {
    this.content = content;
    console.log(`✏️ Document updated: ${this.title}`);
  }

  delete(): void {
    console.log(`🗑️ Document deleted: ${this.title}`);
  }
}

// 🛡️ Security proxy
class SecureDocument implements Document {
  private document: RealDocument;
  private userRole: UserRole;

  constructor(document: RealDocument, userRole: UserRole) {
    this.document = document;
    this.userRole = userRole;
  }

  read(): string {
    console.log(`👁️ ${this.userRole} is reading the document`);
    return this.document.read();
  }

  write(content: string): void {
    if (this.userRole === 'viewer') {
      throw new Error('❌ Viewers cannot edit documents!');
    }
    console.log(`✅ ${this.userRole} has write permission`);
    this.document.write(content);
  }

  delete(): void {
    if (this.userRole !== 'admin') {
      throw new Error('❌ Only admins can delete documents!');
    }
    console.log(`✅ Admin deleting document`);
    this.document.delete();
  }
}

// 🎮 Test different user permissions
const doc = new RealDocument('Secret Plans', 'Top secret content 🤫');

// Different users with different permissions
const adminDoc = new SecureDocument(doc, 'admin');
const editorDoc = new SecureDocument(doc, 'editor');
const viewerDoc = new SecureDocument(doc, 'viewer');

// Everyone can read ✅
console.log(viewerDoc.read());

// Editor can write ✅
editorDoc.write('Updated content 📝');

// Viewer cannot write ❌
try {
  viewerDoc.write('Hacker attempt! 👾');
} catch (error) {
  console.log(error.message);
}

Example 3: Virtual Scroll Proxy 📜

Let’s create a virtual scrolling system for handling large lists efficiently!

// 📊 Data item interface
interface ListItem {
  id: number;
  render(): HTMLElement;
}

// 🎯 Real list item (expensive to create)
class RealListItem implements ListItem {
  constructor(public id: number, private data: string) {
    console.log(`🏗️ Creating expensive item ${id}`);
  }

  render(): HTMLElement {
    const element = document.createElement('div');
    element.textContent = `Item ${this.id}: ${this.data}`;
    element.className = 'list-item';
    return element;
  }
}

// 🚀 Lightweight proxy
class VirtualListItem implements ListItem {
  private realItem: RealListItem | null = null;

  constructor(public id: number, private dataLoader: () => string) {}

  render(): HTMLElement {
    // 💡 Create real item only when rendering
    if (!this.realItem) {
      console.log(`⚡ Lazy loading item ${this.id}`);
      this.realItem = new RealListItem(this.id, this.dataLoader());
    }
    return this.realItem.render();
  }
}

// 📜 Virtual scroll manager
class VirtualScrollList {
  private items: VirtualListItem[] = [];
  private visibleRange = { start: 0, end: 10 };

  constructor(totalItems: number) {
    // 🎯 Create lightweight proxies for all items
    for (let i = 0; i < totalItems; i++) {
      this.items.push(
        new VirtualListItem(i, () => `Data for item ${i} 📦`)
      );
    }
    console.log(`✨ Created ${totalItems} virtual items!`);
  }

  renderVisibleItems(): HTMLElement[] {
    console.log(`🖼️ Rendering items ${this.visibleRange.start}-${this.visibleRange.end}`);
    
    const rendered: HTMLElement[] = [];
    for (let i = this.visibleRange.start; i < this.visibleRange.end; i++) {
      if (this.items[i]) {
        rendered.push(this.items[i].render());
      }
    }
    return rendered;
  }

  scrollTo(start: number): void {
    this.visibleRange = { start, end: start + 10 };
  }
}

// 🎮 Usage with thousands of items!
const hugeList = new VirtualScrollList(10000);

// Only renders what's visible 🚀
hugeList.renderVisibleItems();

// Scroll down
hugeList.scrollTo(100);
hugeList.renderVisibleItems();

🚀 Advanced Concepts

Ready to level up your Proxy Pattern skills? Let’s explore some advanced techniques! 🎯

Dynamic Property Validation 🔍

Create proxies that validate object properties dynamically:

// 🎯 Type-safe validation proxy
type ValidationRule<T> = {
  validate: (value: T) => boolean;
  message: string;
};

type ValidationSchema<T> = {
  [K in keyof T]?: ValidationRule<T[K]>;
};

function createValidatedProxy<T extends object>(
  target: T,
  schema: ValidationSchema<T>
): T {
  return new Proxy(target, {
    set(obj, prop, value) {
      const key = prop as keyof T;
      const rule = schema[key];

      if (rule && !rule.validate(value)) {
        throw new Error(`❌ Validation failed for ${String(key)}: ${rule.message}`);
      }

      obj[key] = value;
      console.log(`✅ ${String(key)} validated and set to ${value}`);
      return true;
    }
  });
}

// 🏪 Example: Product with validation
interface Product {
  name: string;
  price: number;
  stock: number;
}

const productSchema: ValidationSchema<Product> = {
  name: {
    validate: (v) => v.length > 0 && v.length <= 100,
    message: 'Name must be 1-100 characters'
  },
  price: {
    validate: (v) => v > 0 && v <= 10000,
    message: 'Price must be between 0 and 10000'
  },
  stock: {
    validate: (v) => v >= 0 && Number.isInteger(v),
    message: 'Stock must be a non-negative integer'
  }
};

// 🎮 Create validated product
const product = createValidatedProxy<Product>(
  { name: '', price: 0, stock: 0 },
  productSchema
);

// Test validations
product.name = 'Gaming Laptop 🎮'; // ✅ Valid
product.price = 1299.99; // ✅ Valid

try {
  product.price = -50; // ❌ Will throw error
} catch (error) {
  console.log(error.message);
}

Revocable Proxies 🔐

Create proxies that can be revoked for enhanced security:

// 🔒 Secure data access with revocable proxy
class SecureDataAccess<T extends object> {
  private revocableProxy: { proxy: T; revoke: () => void };
  private accessLog: string[] = [];
  private isRevoked = false;

  constructor(private sensitiveData: T, private accessDuration: number) {
    this.revocableProxy = Proxy.revocable(sensitiveData, {
      get: (target, prop) => {
        if (this.isRevoked) {
          throw new Error('❌ Access has been revoked!');
        }
        
        const access = `Read ${String(prop)} at ${new Date().toISOString()}`;
        this.accessLog.push(access);
        console.log(`📖 ${access}`);
        
        return target[prop as keyof T];
      }
    });

    // 🕐 Auto-revoke after duration
    setTimeout(() => {
      this.revoke();
    }, this.accessDuration);
  }

  getProxy(): T {
    return this.revocableProxy.proxy;
  }

  revoke(): void {
    console.log('🔒 Revoking access to sensitive data...');
    this.revocableProxy.revoke();
    this.isRevoked = true;
  }

  getAccessLog(): string[] {
    return [...this.accessLog];
  }
}

// 🎮 Usage
const sensitiveInfo = {
  creditCard: '1234-5678-9012-3456 💳',
  ssn: '123-45-6789 🔐',
  password: 'super-secret-123 🤫'
};

// Grant 5-second access
const secureAccess = new SecureDataAccess(sensitiveInfo, 5000);
const proxy = secureAccess.getProxy();

// Access data while allowed
console.log(proxy.creditCard); // ✅ Works

// After 5 seconds, access is revoked automatically!
setTimeout(() => {
  try {
    console.log(proxy.ssn); // ❌ Will throw error
  } catch (error) {
    console.log(error.message);
  }
  
  // View access log 📊
  console.log('Access Log:', secureAccess.getAccessLog());
}, 6000);

Proxy Chains 🔗

Combine multiple proxies for layered functionality:

// 🎯 Chainable proxy behaviors
type ProxyHandler<T> = {
  name: string;
  handler: ProxyHandler<T>;
};

// 📝 Logging behavior
function loggingProxy<T extends object>(target: T): T {
  return new Proxy(target, {
    get(obj, prop) {
      console.log(`📖 [LOG] Getting ${String(prop)}`);
      return obj[prop as keyof T];
    },
    set(obj, prop, value) {
      console.log(`✏️ [LOG] Setting ${String(prop)} = ${value}`);
      obj[prop as keyof T] = value;
      return true;
    }
  });
}

// ⏱️ Performance monitoring behavior
function performanceProxy<T extends object>(target: T): T {
  return new Proxy(target, {
    get(obj, prop) {
      const start = performance.now();
      const result = obj[prop as keyof T];
      const duration = performance.now() - start;
      console.log(`⏱️ [PERF] ${String(prop)} took ${duration.toFixed(2)}ms`);
      return result;
    }
  });
}

// 💾 Caching behavior
function cachingProxy<T extends object>(target: T): T {
  const cache = new Map<string | symbol, unknown>();
  
  return new Proxy(target, {
    get(obj, prop) {
      const key = prop as keyof T;
      if (cache.has(prop)) {
        console.log(`💾 [CACHE] Hit for ${String(prop)}`);
        return cache.get(prop);
      }
      
      console.log(`🔄 [CACHE] Miss for ${String(prop)}`);
      const value = obj[key];
      cache.set(prop, value);
      return value;
    }
  });
}

// 🔗 Create proxy chain
function createProxyChain<T extends object>(
  target: T,
  ...proxies: ((obj: T) => T)[]
): T {
  return proxies.reduce((acc, proxyFn) => proxyFn(acc), target);
}

// 🎮 Example usage
const dataService = {
  fetchUser: () => {
    console.log('🌐 Fetching user from database...');
    return { id: 1, name: 'Alice 👩' };
  },
  fetchPosts: () => {
    console.log('🌐 Fetching posts from database...');
    return ['Post 1 📝', 'Post 2 📝', 'Post 3 📝'];
  }
};

// Apply multiple proxy behaviors! 🚀
const enhancedService = createProxyChain(
  dataService,
  cachingProxy,
  performanceProxy,
  loggingProxy
);

// First call - all behaviors active
enhancedService.fetchUser();

// Second call - cache hit! 💾
enhancedService.fetchUser();

⚠️ Common Pitfalls and Solutions

Let’s explore common mistakes and how to avoid them! 🛡️

Pitfall 1: Performance Overhead 🐌

❌ Wrong Way:

// Creating proxies for every single object
class DataStore {
  private items: any[] = [];

  addItem(item: any): void {
    // ❌ Creating a proxy for each item is expensive!
    const proxiedItem = new Proxy(item, {
      get(target, prop) {
        console.log(`Accessing ${String(prop)}`);
        return target[prop];
      }
    });
    this.items.push(proxiedItem);
  }
}

✅ Right Way:

// Use proxies strategically
class OptimizedDataStore {
  private items: any[] = [];
  private accessCounts = new Map<number, number>();

  addItem(item: any): void {
    const index = this.items.length;
    this.items.push(item);
    
    // ✅ Track access patterns without proxy overhead
    this.accessCounts.set(index, 0);
  }

  getItem(index: number): any {
    this.accessCounts.set(index, (this.accessCounts.get(index) || 0) + 1);
    
    // ✅ Only create proxy for frequently accessed items
    if (this.accessCounts.get(index)! > 10) {
      console.log(`🔥 Creating optimized proxy for hot item ${index}`);
      return new Proxy(this.items[index], {
        get(target, prop) {
          console.log(`⚡ Fast access to ${String(prop)}`);
          return target[prop];
        }
      });
    }
    
    return this.items[index];
  }
}

Pitfall 2: Breaking Object Identity 🎭

❌ Wrong Way:

// Proxy breaks object identity checks
const user = { id: 1, name: 'Bob' };
const proxyUser = new Proxy(user, {});

// ❌ This will be false!
console.log(user === proxyUser); // false

// ❌ Can cause issues with Maps/Sets
const userSet = new Set([user]);
console.log(userSet.has(proxyUser)); // false!

✅ Right Way:

// Maintain reference to original object
class IdentityPreservingProxy<T extends object> {
  private static proxyMap = new WeakMap<object, object>();

  static create<T extends object>(target: T): T {
    // ✅ Return existing proxy if already created
    const existing = this.proxyMap.get(target);
    if (existing) return existing as T;

    const proxy = new Proxy(target, {
      get(obj, prop) {
        console.log(`📖 Accessing ${String(prop)}`);
        return obj[prop as keyof T];
      }
    });

    // ✅ Store proxy reference
    this.proxyMap.set(target, proxy);
    return proxy;
  }

  static getOriginal<T extends object>(proxy: T): T | undefined {
    // ✅ Utility to get original object
    for (const [original, stored] of this.proxyMap) {
      if (stored === proxy) return original as T;
    }
    return undefined;
  }
}

// ✅ Usage
const user2 = { id: 2, name: 'Charlie' };
const proxy1 = IdentityPreservingProxy.create(user2);
const proxy2 = IdentityPreservingProxy.create(user2);

console.log(proxy1 === proxy2); // true! Same proxy returned 🎉

Pitfall 3: Hidden Errors 🐛

❌ Wrong Way:

// Silently catching errors
const dangerousProxy = new Proxy({}, {
  get(target, prop) {
    try {
      return target[prop as keyof typeof target];
    } catch (error) {
      // ❌ Hiding errors makes debugging nightmare!
      return undefined;
    }
  }
});

✅ Right Way:

// Proper error handling with context
class SafeProxy<T extends object> {
  static create<T extends object>(
    target: T,
    errorHandler?: (error: Error, operation: string, prop: string | symbol) => void
  ): T {
    return new Proxy(target, {
      get(obj, prop) {
        try {
          const value = obj[prop as keyof T];
          
          // ✅ Type checking
          if (typeof value === 'function') {
            return value.bind(obj);
          }
          
          return value;
        } catch (error) {
          // ✅ Provide context for debugging
          const enhancedError = new Error(
            `❌ Error accessing property ${String(prop)}: ${error.message}`
          );
          
          if (errorHandler) {
            errorHandler(enhancedError, 'get', prop);
          } else {
            throw enhancedError;
          }
        }
      },
      
      set(obj, prop, value) {
        try {
          // ✅ Validation before setting
          if (value === undefined) {
            console.warn(`⚠️ Setting ${String(prop)} to undefined`);
          }
          
          obj[prop as keyof T] = value;
          return true;
        } catch (error) {
          // ✅ Detailed error information
          const enhancedError = new Error(
            `❌ Error setting property ${String(prop)}: ${error.message}`
          );
          
          if (errorHandler) {
            errorHandler(enhancedError, 'set', prop);
          } else {
            throw enhancedError;
          }
          
          return false;
        }
      }
    });
  }
}

// ✅ Usage with error handling
const config = SafeProxy.create(
  { apiUrl: 'https://api.example.com' },
  (error, operation, prop) => {
    console.error(`🚨 Proxy error during ${operation} on ${String(prop)}:`, error);
  }
);

🛠️ Best Practices

Follow these guidelines to master the Proxy Pattern! 🌟

1. Choose the Right Proxy Type 🎯

// 🎯 Decision helper for proxy selection
class ProxySelector {
  static recommendProxy(requirements: {
    needsLazyLoading?: boolean;
    needsAccessControl?: boolean;
    needsCaching?: boolean;
    needsLogging?: boolean;
    needsValidation?: boolean;
  }): string[] {
    const recommendations: string[] = [];

    if (requirements.needsLazyLoading) {
      recommendations.push('🌙 Virtual Proxy - Delays expensive operations');
    }
    if (requirements.needsAccessControl) {
      recommendations.push('🔐 Protection Proxy - Controls permissions');
    }
    if (requirements.needsCaching) {
      recommendations.push('💾 Caching Proxy - Improves performance');
    }
    if (requirements.needsLogging) {
      recommendations.push('📝 Logging Proxy - Tracks operations');
    }
    if (requirements.needsValidation) {
      recommendations.push('✅ Validation Proxy - Ensures data integrity');
    }

    return recommendations;
  }
}

// Example usage
const needs = {
  needsCaching: true,
  needsLogging: true,
  needsValidation: true
};

console.log('Recommended proxies:', ProxySelector.recommendProxy(needs));

2. Implement Transparent Proxies 🔍

// 🎯 Transparent proxy that preserves object behavior
interface ProxyOptions {
  beforeGet?: (prop: string | symbol) => void;
  afterGet?: (prop: string | symbol, value: unknown) => void;
  beforeSet?: (prop: string | symbol, value: unknown) => boolean;
  afterSet?: (prop: string | symbol, value: unknown) => void;
}

function createTransparentProxy<T extends object>(
  target: T,
  options: ProxyOptions = {}
): T {
  return new Proxy(target, {
    get(obj, prop, receiver) {
      options.beforeGet?.(prop);
      
      // ✅ Preserve correct 'this' binding
      const value = Reflect.get(obj, prop, receiver);
      
      options.afterGet?.(prop, value);
      
      // ✅ Bind methods to maintain context
      if (typeof value === 'function') {
        return value.bind(obj);
      }
      
      return value;
    },
    
    set(obj, prop, value, receiver) {
      const shouldProceed = options.beforeSet?.(prop, value) ?? true;
      
      if (!shouldProceed) return false;
      
      // ✅ Use Reflect for proper behavior
      const result = Reflect.set(obj, prop, value, receiver);
      
      if (result) {
        options.afterSet?.(prop, value);
      }
      
      return result;
    },
    
    // ✅ Implement other traps for full transparency
    has(obj, prop) {
      return Reflect.has(obj, prop);
    },
    
    deleteProperty(obj, prop) {
      return Reflect.deleteProperty(obj, prop);
    }
  });
}

3. Document Proxy Behavior 📚

// 🎯 Self-documenting proxy with metadata
class DocumentedProxy<T extends object> {
  private static metadata = new WeakMap<object, {
    type: string;
    purpose: string;
    behaviors: string[];
    created: Date;
  }>();

  static create<T extends object>(
    target: T,
    type: string,
    purpose: string,
    behaviors: string[]
  ): T {
    const proxy = new Proxy(target, {
      get(obj, prop) {
        if (prop === Symbol.for('proxy.metadata')) {
          return DocumentedProxy.metadata.get(proxy);
        }
        return obj[prop as keyof T];
      }
    });

    // ✅ Store metadata
    this.metadata.set(proxy, {
      type,
      purpose,
      behaviors,
      created: new Date()
    });

    return proxy;
  }

  static getInfo(proxy: any): string {
    const metadata = proxy[Symbol.for('proxy.metadata')];
    if (!metadata) return 'Not a documented proxy';

    return `
🎯 Proxy Information:
- Type: ${metadata.type}
- Purpose: ${metadata.purpose}
- Behaviors: ${metadata.behaviors.join(', ')}
- Created: ${metadata.created.toISOString()}
    `.trim();
  }
}

// ✅ Usage
const apiClient = { endpoint: 'https://api.example.com' };
const proxiedClient = DocumentedProxy.create(
  apiClient,
  'Caching Proxy',
  'Reduces API calls by caching responses',
  ['caching', 'logging', 'retry']
);

console.log(DocumentedProxy.getInfo(proxiedClient));

4. Test Proxy Behavior 🧪

// 🎯 Proxy testing utilities
class ProxyTester {
  static testAccessControl<T extends object>(
    createProxy: (target: T, role: string) => T,
    target: T,
    tests: { role: string; operation: () => void; shouldSucceed: boolean }[]
  ): void {
    console.log('🧪 Testing access control proxy...');
    
    tests.forEach(({ role, operation, shouldSucceed }) => {
      const proxy = createProxy(target, role);
      
      try {
        operation.call(proxy);
        if (shouldSucceed) {
          console.log(`✅ ${role}: Operation succeeded as expected`);
        } else {
          console.log(`❌ ${role}: Operation should have failed!`);
        }
      } catch (error) {
        if (!shouldSucceed) {
          console.log(`✅ ${role}: Operation failed as expected`);
        } else {
          console.log(`❌ ${role}: Operation should have succeeded!`);
        }
      }
    });
  }
}

5. Performance Monitoring 📊

// 🎯 Performance-aware proxy
class PerformanceProxy<T extends object> {
  private metrics = new Map<string | symbol, {
    calls: number;
    totalTime: number;
    avgTime: number;
  }>();

  create(target: T): T {
    return new Proxy(target, {
      get: (obj, prop) => {
        const value = obj[prop as keyof T];
        
        if (typeof value === 'function') {
          return (...args: any[]) => {
            const start = performance.now();
            const result = value.apply(obj, args);
            const duration = performance.now() - start;
            
            // ✅ Track metrics
            this.updateMetrics(prop, duration);
            
            return result;
          };
        }
        
        return value;
      }
    });
  }

  private updateMetrics(method: string | symbol, duration: number): void {
    const current = this.metrics.get(method) || { calls: 0, totalTime: 0, avgTime: 0 };
    
    current.calls++;
    current.totalTime += duration;
    current.avgTime = current.totalTime / current.calls;
    
    this.metrics.set(method, current);
  }

  getReport(): string {
    let report = '📊 Performance Report:\n';
    
    this.metrics.forEach((metrics, method) => {
      report += `
📌 ${String(method)}:
  - Calls: ${metrics.calls}
  - Avg Time: ${metrics.avgTime.toFixed(2)}ms
  - Total Time: ${metrics.totalTime.toFixed(2)}ms
      `.trim() + '\n';
    });
    
    return report;
  }
}

🧪 Hands-On Exercise

Time to put your Proxy Pattern skills to the test! 💪

Challenge: Build a Smart Shopping Cart 🛒

Create a shopping cart system with the following features:

1. Validation: Ensure only valid products can be added
2. Logging: Track all cart operations
3. Caching: Cache total calculations
4. Access Control: Different permissions for customers vs admins

// 🎯 Your challenge starts here!
interface Product {
  id: string;
  name: string;
  price: number;
  stock: number;
}

interface CartItem {
  product: Product;
  quantity: number;
}

interface ShoppingCart {
  items: CartItem[];
  addItem(product: Product, quantity: number): void;
  removeItem(productId: string): void;
  getTotal(): number;
  checkout(): void;
}

// TODO: Implement these proxy features:
// 1. ValidationProxy - Validate products and quantities
// 2. LoggingProxy - Log all operations
// 3. CachingProxy - Cache total calculations
// 4. AccessControlProxy - Control who can checkout

// Start coding here! 🚀

// 🎯 Complete solution for Smart Shopping Cart

// Basic shopping cart implementation
class BasicShoppingCart implements ShoppingCart {
  items: CartItem[] = [];

  addItem(product: Product, quantity: number): void {
    const existing = this.items.find(item => item.product.id === product.id);
    
    if (existing) {
      existing.quantity += quantity;
    } else {
      this.items.push({ product, quantity });
    }
  }

  removeItem(productId: string): void {
    this.items = this.items.filter(item => item.product.id !== productId);
  }

  getTotal(): number {
    return this.items.reduce(
      (total, item) => total + (item.product.price * item.quantity),
      0
    );
  }

  checkout(): void {
    console.log('💳 Processing checkout...');
    console.log(`Total: $${this.getTotal().toFixed(2)}`);
    this.items = [];
  }
}

// 1. Validation Proxy
class ValidatedCart implements ShoppingCart {
  constructor(private cart: ShoppingCart) {}

  get items() { return this.cart.items; }

  addItem(product: Product, quantity: number): void {
    // ✅ Validate product
    if (!product.id || !product.name || product.price <= 0) {
      throw new Error('❌ Invalid product!');
    }
    
    // ✅ Validate quantity
    if (quantity <= 0 || quantity > product.stock) {
      throw new Error(`❌ Invalid quantity! Stock available: ${product.stock}`);
    }
    
    console.log('✅ Product validation passed');
    this.cart.addItem(product, quantity);
  }

  removeItem(productId: string): void {
    if (!productId) {
      throw new Error('❌ Product ID required!');
    }
    this.cart.removeItem(productId);
  }

  getTotal(): number {
    return this.cart.getTotal();
  }

  checkout(): void {
    if (this.items.length === 0) {
      throw new Error('❌ Cart is empty!');
    }
    this.cart.checkout();
  }
}

// 2. Logging Proxy
class LoggedCart implements ShoppingCart {
  private operations: string[] = [];

  constructor(private cart: ShoppingCart) {}

  get items() { return this.cart.items; }

  addItem(product: Product, quantity: number): void {
    const log = `📝 Added ${quantity}x ${product.name} to cart`;
    this.operations.push(log);
    console.log(log);
    this.cart.addItem(product, quantity);
  }

  removeItem(productId: string): void {
    const log = `📝 Removed product ${productId} from cart`;
    this.operations.push(log);
    console.log(log);
    this.cart.removeItem(productId);
  }

  getTotal(): number {
    console.log('📝 Calculated total');
    return this.cart.getTotal();
  }

  checkout(): void {
    const log = `📝 Checkout completed at ${new Date().toISOString()}`;
    this.operations.push(log);
    console.log(log);
    this.cart.checkout();
  }

  getLog(): string[] {
    return [...this.operations];
  }
}

// 3. Caching Proxy
class CachedCart implements ShoppingCart {
  private totalCache: { value: number; dirty: boolean } = { value: 0, dirty: true };

  constructor(private cart: ShoppingCart) {}

  get items() { return this.cart.items; }

  addItem(product: Product, quantity: number): void {
    this.totalCache.dirty = true;
    this.cart.addItem(product, quantity);
  }

  removeItem(productId: string): void {
    this.totalCache.dirty = true;
    this.cart.removeItem(productId);
  }

  getTotal(): number {
    if (!this.totalCache.dirty) {
      console.log('💾 Returning cached total');
      return this.totalCache.value;
    }
    
    console.log('🔄 Calculating fresh total');
    this.totalCache.value = this.cart.getTotal();
    this.totalCache.dirty = false;
    return this.totalCache.value;
  }

  checkout(): void {
    this.totalCache.dirty = true;
    this.cart.checkout();
  }
}

// 4. Access Control Proxy
type UserRole = 'customer' | 'admin';

class SecureCart implements ShoppingCart {
  constructor(
    private cart: ShoppingCart,
    private userRole: UserRole
  ) {}

  get items() { 
    if (this.userRole === 'admin') {
      return this.cart.items;
    }
    // Customers see limited info
    return this.cart.items.map(item => ({
      product: { ...item.product, stock: 0 }, // Hide stock
      quantity: item.quantity
    }));
  }

  addItem(product: Product, quantity: number): void {
    console.log(`👤 ${this.userRole} adding item`);
    this.cart.addItem(product, quantity);
  }

  removeItem(productId: string): void {
    console.log(`👤 ${this.userRole} removing item`);
    this.cart.removeItem(productId);
  }

  getTotal(): number {
    return this.cart.getTotal();
  }

  checkout(): void {
    if (this.userRole !== 'customer') {
      throw new Error('❌ Only customers can checkout!');
    }
    console.log('✅ Customer checkout authorized');
    this.cart.checkout();
  }
}

// 🎮 Putting it all together!
function createSmartCart(userRole: UserRole): ShoppingCart {
  const basicCart = new BasicShoppingCart();
  
  // Apply proxies in order
  const cachedCart = new CachedCart(basicCart);
  const loggedCart = new LoggedCart(cachedCart);
  const validatedCart = new ValidatedCart(loggedCart);
  const secureCart = new SecureCart(validatedCart, userRole);
  
  return secureCart;
}

// 🧪 Test the smart cart
const customerCart = createSmartCart('customer');
const adminCart = createSmartCart('admin');

// Test products
const laptop: Product = { id: '1', name: 'Gaming Laptop 💻', price: 1299.99, stock: 5 };
const mouse: Product = { id: '2', name: 'RGB Mouse 🖱️', price: 79.99, stock: 20 };

// Customer operations
console.log('=== Customer Cart Test ===');
customerCart.addItem(laptop, 1);
customerCart.addItem(mouse, 2);
console.log(`Total: $${customerCart.getTotal()}`); // Cached on second call
console.log(`Total: $${customerCart.getTotal()}`); // From cache!
customerCart.checkout(); // ✅ Success

// Admin operations
console.log('\n=== Admin Cart Test ===');
adminCart.addItem(laptop, 1);
try {
  adminCart.checkout(); // ❌ Admins can't checkout
} catch (error) {
  console.log(error.message);
}

// Invalid operations
console.log('\n=== Validation Test ===');
try {
  customerCart.addItem({ id: '', name: '', price: -10, stock: 0 }, 1);
} catch (error) {
  console.log(error.message); // ❌ Invalid product
}

console.log('\n🎉 Smart cart with multiple proxy layers working perfectly!');

🎓 Key Takeaways

Congratulations! You’ve mastered the Proxy Pattern in TypeScript! 🎉 Here’s what you’ve learned:

• 🎯 Proxy Pattern Fundamentals: Understanding how proxies control access to objects
• 🛡️ Different Proxy Types: Virtual, Protection, Remote, Caching, and Logging proxies
• 💻 TypeScript Implementation: Using both custom classes and JavaScript’s Proxy object
• 🚀 Advanced Techniques: Proxy chains, revocable proxies, and dynamic validation
• ⚠️ Common Pitfalls: Performance overhead, identity issues, and error handling
• 🛠️ Best Practices: Choosing the right proxy type and maintaining transparency

The Proxy Pattern is like having a smart assistant that manages access to your important resources! 🤝

🤝 Next Steps

Ready to continue your TypeScript design patterns journey? Here’s what to do next:

1. 🔨 Practice: Implement different proxy types in your current projects
2. 🔍 Explore: Combine proxies with other patterns like Decorator or Adapter
3. 📚 Learn More: Check out the Flyweight Pattern for memory optimization
4. 🚀 Next Tutorial: Continue with [Flyweight Pattern: Memory Optimization]

Keep coding, keep learning, and remember - with great proxy power comes great responsibility! 🦸‍♂️✨

Happy proxying! 🎯🚀