JavaScript Proxy Handler Guide

Proxy handlers intercept operations on objects, enabling powerful meta-programming patterns. Here's how to use each trap effectively.

Basic Structure#

const target = { name: 'Original' };

const handler = {
  get(target, property, receiver) {
    console.log(`Getting ${property}`);
    return Reflect.get(target, property, receiver);
  },

  set(target, property, value, receiver) {
    console.log(`Setting ${property} to ${value}`);
    return Reflect.set(target, property, value, receiver);
  },
};

const proxy = new Proxy(target, handler);

proxy.name;         // "Getting name"
proxy.age = 25;     // "Setting age to 25"

get Trap#

const handler = {
  get(target, property, receiver) {
    // Property doesn't exist
    if (!(property in target)) {
      return `Property '${property}' not found`;
    }

    // Transform value
    const value = Reflect.get(target, property, receiver);
    if (typeof value === 'string') {
      return value.toUpperCase();
    }

    return value;
  },
};

const obj = new Proxy({ name: 'john' }, handler);
console.log(obj.name);    // 'JOHN'
console.log(obj.missing); // "Property 'missing' not found"

set Trap#

const handler = {
  set(target, property, value, receiver) {
    // Validation
    if (property === 'age' && (typeof value !== 'number' || value < 0)) {
      throw new TypeError('Age must be a positive number');
    }

    // Transformation
    if (property === 'name' && typeof value === 'string') {
      value = value.trim();
    }

    // Logging
    console.log(`${property} changed to ${value}`);

    return Reflect.set(target, property, value, receiver);
  },
};

const user = new Proxy({}, handler);
user.name = '  John  ';  // Trimmed to 'John'
user.age = 30;           // OK
// user.age = -5;        // TypeError

has Trap#

const handler = {
  has(target, property) {
    // Hide private properties
    if (property.startsWith('_')) {
      return false;
    }

    return Reflect.has(target, property);
  },
};

const obj = new Proxy({ name: 'John', _secret: 'hidden' }, handler);
console.log('name' in obj);    // true
console.log('_secret' in obj); // false (hidden)

deleteProperty Trap#

const handler = {
  deleteProperty(target, property) {
    // Prevent deletion of certain properties
    if (property === 'id') {
      console.log('Cannot delete id');
      return false;
    }

    // Log deletion
    console.log(`Deleting ${property}`);

    return Reflect.deleteProperty(target, property);
  },
};

const obj = new Proxy({ id: 1, name: 'John' }, handler);
delete obj.name;  // "Deleting name" - succeeds
delete obj.id;    // "Cannot delete id" - fails

ownKeys Trap#

const handler = {
  ownKeys(target) {
    // Filter out private properties
    return Reflect.ownKeys(target).filter(
      (key) => !String(key).startsWith('_')
    );
  },
};

const obj = new Proxy(
  { name: 'John', age: 30, _private: 'hidden' },
  handler
);

console.log(Object.keys(obj));     // ['name', 'age']
console.log(Object.entries(obj));  // [['name', 'John'], ['age', 30]]

apply Trap (Functions)#

const handler = {
  apply(target, thisArg, argumentsList) {
    console.log(`Calling function with args: ${argumentsList}`);

    // Modify arguments
    const modifiedArgs = argumentsList.map((arg) =>
      typeof arg === 'number' ? arg * 2 : arg
    );

    return Reflect.apply(target, thisArg, modifiedArgs);
  },
};

const double = new Proxy(
  (a, b) => a + b,
  handler
);

console.log(double(2, 3)); // Calling..., returns 10 (4 + 6)

construct Trap (Classes)#

const handler = {
  construct(target, argumentsList, newTarget) {
    console.log(`Creating new instance with: ${argumentsList}`);

    // Modify constructor arguments
    const instance = Reflect.construct(target, argumentsList, newTarget);

    // Add extra properties
    instance.createdAt = new Date();

    return instance;
  },
};

class User {
  constructor(name) {
    this.name = name;
  }
}

const ProxiedUser = new Proxy(User, handler);
const user = new ProxiedUser('John');
console.log(user.createdAt); // Date object

getOwnPropertyDescriptor Trap#

const handler = {
  getOwnPropertyDescriptor(target, property) {
    const descriptor = Reflect.getOwnPropertyDescriptor(target, property);

    // Hide private properties
    if (property.startsWith('_')) {
      return undefined;
    }

    // Modify descriptor
    if (descriptor) {
      descriptor.enumerable = true;
    }

    return descriptor;
  },
};

const obj = new Proxy({ name: 'John', _secret: 'hidden' }, handler);
console.log(Object.getOwnPropertyDescriptor(obj, 'name'));
console.log(Object.getOwnPropertyDescriptor(obj, '_secret')); // undefined

defineProperty Trap#

const handler = {
  defineProperty(target, property, descriptor) {
    // Prevent non-writable properties
    if (descriptor.writable === false) {
      console.log('Non-writable properties not allowed');
      return false;
    }

    // Validate property names
    if (property.startsWith('_')) {
      console.log('Properties cannot start with _');
      return false;
    }

    return Reflect.defineProperty(target, property, descriptor);
  },
};

const obj = new Proxy({}, handler);

Object.defineProperty(obj, 'name', {
  value: 'John',
  writable: true,
}); // OK

Object.defineProperty(obj, '_private', {
  value: 'hidden',
}); // Fails

getPrototypeOf / setPrototypeOf Traps#

const handler = {
  getPrototypeOf(target) {
    console.log('Getting prototype');
    return Reflect.getPrototypeOf(target);
  },

  setPrototypeOf(target, prototype) {
    // Prevent prototype changes
    console.log('Prototype is immutable');
    return false;
  },
};

const obj = new Proxy({}, handler);
Object.getPrototypeOf(obj);        // "Getting prototype"
Object.setPrototypeOf(obj, null);  // Fails - "Prototype is immutable"

isExtensible / preventExtensions Traps#

const handler = {
  isExtensible(target) {
    console.log('Checking extensibility');
    return Reflect.isExtensible(target);
  },

  preventExtensions(target) {
    console.log('Preventing extensions');
    return Reflect.preventExtensions(target);
  },
};

const obj = new Proxy({}, handler);
console.log(Object.isExtensible(obj));  // true
Object.preventExtensions(obj);
console.log(Object.isExtensible(obj));  // false

Complete Observable Object#

function createObservable(target, onChange) {
  const handler = {
    get(target, property, receiver) {
      const value = Reflect.get(target, property, receiver);

      // Return proxy for nested objects
      if (typeof value === 'object' && value !== null) {
        return createObservable(value, (path, newVal, oldVal) => {
          onChange(`${property}.${path}`, newVal, oldVal);
        });
      }

      return value;
    },

    set(target, property, value, receiver) {
      const oldValue = target[property];
      const result = Reflect.set(target, property, value, receiver);

      if (result && oldValue !== value) {
        onChange(property, value, oldValue);
      }

      return result;
    },

    deleteProperty(target, property) {
      const oldValue = target[property];
      const result = Reflect.deleteProperty(target, property);

      if (result) {
        onChange(property, undefined, oldValue);
      }

      return result;
    },
  };

  return new Proxy(target, handler);
}

// Usage
const state = createObservable(
  { user: { name: 'John' }, count: 0 },
  (path, newVal, oldVal) => {
    console.log(`${path}: ${oldVal} -> ${newVal}`);
  }
);

state.count = 1;              // count: 0 -> 1
state.user.name = 'Jane';     // user.name: John -> Jane

Best Practices#

Trap Usage:
✓ Use Reflect methods for defaults
✓ Return correct values
✓ Maintain invariants
✓ Handle edge cases

Performance:
✓ Keep handlers simple
✓ Cache proxies when possible
✓ Avoid deep nesting
✓ Consider alternatives for hot paths

Patterns:
✓ Validation and access control
✓ Logging and debugging
✓ Observable objects
✓ Default values

Avoid:
✗ Breaking object invariants
✗ Infinite recursion
✗ Hiding errors silently
✗ Over-engineering simple cases

Proxy handlers provide fine-grained control over object operations through traps like get, set, has, and deleteProperty. Always use Reflect methods to maintain default behavior and return appropriate values. Proxies are powerful for validation, observation, access control, and virtualization patterns, but should be used judiciously as they add overhead and complexity.