JavaScript Proxy and Reflect API

Proxy enables custom behavior for fundamental operations. Here's how to use it effectively.

Basic Proxy#

// Simple proxy
const target = { name: 'Alice', age: 25 };

const handler = {
  get(target, property) {
    console.log(`Getting ${property}`);
    return target[property];
  },
  set(target, property, value) {
    console.log(`Setting ${property} to ${value}`);
    target[property] = value;
    return true;
  },
};

const proxy = new Proxy(target, handler);

proxy.name; // Logs: "Getting name", returns "Alice"
proxy.age = 26; // Logs: "Setting age to 26"

// With Reflect
const handlerWithReflect = {
  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);
  },
};

Common Traps#

const handler = {
  // Property access
  get(target, property, receiver) {
    return Reflect.get(target, property, receiver);
  },

  // Property assignment
  set(target, property, value, receiver) {
    return Reflect.set(target, property, value, receiver);
  },

  // Property check
  has(target, property) {
    return Reflect.has(target, property);
  },

  // Property deletion
  deleteProperty(target, property) {
    return Reflect.deleteProperty(target, property);
  },

  // Object.keys, for...in
  ownKeys(target) {
    return Reflect.ownKeys(target);
  },

  // Object.getOwnPropertyDescriptor
  getOwnPropertyDescriptor(target, property) {
    return Reflect.getOwnPropertyDescriptor(target, property);
  },

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

  // Function call
  apply(target, thisArg, args) {
    return Reflect.apply(target, thisArg, args);
  },

  // new operator
  construct(target, args, newTarget) {
    return Reflect.construct(target, args, newTarget);
  },
};

Validation#

// Property validation
function createValidatedObject(schema) {
  return new Proxy({}, {
    set(target, property, value) {
      const validator = schema[property];

      if (!validator) {
        throw new Error(`Unknown property: ${property}`);
      }

      if (!validator(value)) {
        throw new Error(`Invalid value for ${property}: ${value}`);
      }

      target[property] = value;
      return true;
    },
  });
}

const userSchema = {
  name: (v) => typeof v === 'string' && v.length > 0,
  age: (v) => typeof v === 'number' && v >= 0 && v <= 150,
  email: (v) => typeof v === 'string' && v.includes('@'),
};

const user = createValidatedObject(userSchema);

user.name = 'Alice'; // OK
user.age = 25; // OK
user.email = 'alice@example.com'; // OK
user.age = -5; // Error: Invalid value for age: -5

// Type-safe proxy
function createTypedObject(types) {
  const data = {};

  return new Proxy(data, {
    set(target, property, value) {
      const expectedType = types[property];

      if (expectedType && typeof value !== expectedType) {
        throw new TypeError(
          `${property} must be ${expectedType}, got ${typeof value}`
        );
      }

      target[property] = value;
      return true;
    },
  });
}

const config = createTypedObject({
  port: 'number',
  host: 'string',
  debug: 'boolean',
});

Reactive Programming#

// Observable object
function createReactive(target, callback) {
  return new Proxy(target, {
    set(target, property, value, receiver) {
      const oldValue = target[property];
      const result = Reflect.set(target, property, value, receiver);

      if (oldValue !== value) {
        callback(property, value, oldValue);
      }

      return result;
    },
  });
}

const state = createReactive({ count: 0 }, (prop, newVal, oldVal) => {
  console.log(`${prop} changed from ${oldVal} to ${newVal}`);
});

state.count = 1; // Logs: "count changed from 0 to 1"

// Deep reactive
function deepReactive(target, callback, path = '') {
  const handler = {
    get(target, property, receiver) {
      const value = Reflect.get(target, property, receiver);

      if (typeof value === 'object' && value !== null) {
        return deepReactive(
          value,
          callback,
          path ? `${path}.${property}` : property
        );
      }

      return value;
    },

    set(target, property, value, receiver) {
      const fullPath = path ? `${path}.${property}` : property;
      const oldValue = target[property];
      const result = Reflect.set(target, property, value, receiver);

      if (oldValue !== value) {
        callback(fullPath, value, oldValue);
      }

      return result;
    },
  };

  return new Proxy(target, handler);
}

const deepState = deepReactive(
  { user: { name: 'Alice', settings: { theme: 'dark' } } },
  (path, newVal, oldVal) => {
    console.log(`${path}: ${oldVal} -> ${newVal}`);
  }
);

deepState.user.settings.theme = 'light';
// Logs: "user.settings.theme: dark -> light"

Default Values#

// Default property values
function withDefaults(target, defaults) {
  return new Proxy(target, {
    get(target, property, receiver) {
      const value = Reflect.get(target, property, receiver);
      return value !== undefined ? value : defaults[property];
    },
  });
}

const config = withDefaults(
  { port: 8080 },
  { port: 3000, host: 'localhost', debug: false }
);

console.log(config.port); // 8080 (from target)
console.log(config.host); // 'localhost' (from defaults)
console.log(config.debug); // false (from defaults)

// Nested defaults
function withNestedDefaults(target, defaults) {
  return new Proxy(target, {
    get(target, property, receiver) {
      let value = Reflect.get(target, property, receiver);
      const defaultValue = defaults[property];

      if (value === undefined) {
        value = defaultValue;
      } else if (
        typeof value === 'object' &&
        typeof defaultValue === 'object'
      ) {
        value = withNestedDefaults(value, defaultValue);
      }

      return value;
    },
  });
}

Access Control#

// Private properties
function createPrivateObject(target, privateKeys) {
  return new Proxy(target, {
    get(target, property, receiver) {
      if (privateKeys.includes(property)) {
        throw new Error(`Cannot access private property: ${property}`);
      }
      return Reflect.get(target, property, receiver);
    },

    set(target, property, value, receiver) {
      if (privateKeys.includes(property)) {
        throw new Error(`Cannot set private property: ${property}`);
      }
      return Reflect.set(target, property, value, receiver);
    },

    ownKeys(target) {
      return Reflect.ownKeys(target).filter(
        (key) => !privateKeys.includes(key)
      );
    },
  });
}

const user = createPrivateObject(
  { name: 'Alice', password: 'secret123' },
  ['password']
);

console.log(user.name); // 'Alice'
console.log(user.password); // Error: Cannot access private property

// Read-only object
function readonly(target) {
  return new Proxy(target, {
    set() {
      throw new Error('Cannot modify readonly object');
    },
    deleteProperty() {
      throw new Error('Cannot delete from readonly object');
    },
  });
}

const frozenConfig = readonly({ apiKey: '12345' });
frozenConfig.apiKey = 'new'; // Error: Cannot modify readonly object

Function Proxies#

// Logging decorator
function createLogger(fn, name) {
  return new Proxy(fn, {
    apply(target, thisArg, args) {
      console.log(`Calling ${name} with`, args);
      const result = Reflect.apply(target, thisArg, args);
      console.log(`${name} returned`, result);
      return result;
    },
  });
}

const add = createLogger((a, b) => a + b, 'add');
add(2, 3); // Logs: Calling add with [2, 3], add returned 5

// Memoization
function memoize(fn) {
  const cache = new Map();

  return new Proxy(fn, {
    apply(target, thisArg, args) {
      const key = JSON.stringify(args);

      if (cache.has(key)) {
        return cache.get(key);
      }

      const result = Reflect.apply(target, thisArg, args);
      cache.set(key, result);
      return result;
    },
  });
}

const fibonacci = memoize((n) => {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
});

// Rate limiting
function rateLimit(fn, limit, window) {
  const calls = [];

  return new Proxy(fn, {
    apply(target, thisArg, args) {
      const now = Date.now();
      const windowStart = now - window;

      // Remove old calls
      while (calls.length && calls[0] < windowStart) {
        calls.shift();
      }

      if (calls.length >= limit) {
        throw new Error('Rate limit exceeded');
      }

      calls.push(now);
      return Reflect.apply(target, thisArg, args);
    },
  });
}

Array Proxy#

// Negative index support
function createArrayProxy(arr) {
  return new Proxy(arr, {
    get(target, property, receiver) {
      const index = Number(property);

      if (!isNaN(index) && index < 0) {
        return target[target.length + index];
      }

      return Reflect.get(target, property, receiver);
    },
  });
}

const arr = createArrayProxy([1, 2, 3, 4, 5]);
console.log(arr[-1]); // 5
console.log(arr[-2]); // 4

// Observable array
function createObservableArray(arr, onChange) {
  return new Proxy(arr, {
    set(target, property, value, receiver) {
      const result = Reflect.set(target, property, value, receiver);
      onChange(property, value);
      return result;
    },

    deleteProperty(target, property) {
      const result = Reflect.deleteProperty(target, property);
      onChange(property, undefined);
      return result;
    },
  });
}

Reflect API#

// Reflect provides default behavior
const obj = { x: 1 };

// These are equivalent
Reflect.get(obj, 'x'); // 1
obj.x; // 1

// But Reflect returns success/failure
Reflect.set(obj, 'y', 2); // true
Reflect.defineProperty(obj, 'z', { value: 3 }); // true

// Object methods vs Reflect
Object.defineProperty(obj, 'a', { value: 1 }); // throws on failure
Reflect.defineProperty(obj, 'a', { value: 1 }); // returns false on failure

// Method application
function greet(greeting) {
  return `${greeting}, ${this.name}`;
}

Reflect.apply(greet, { name: 'Alice' }, ['Hello']); // "Hello, Alice"

// Constructor
class Person {
  constructor(name) {
    this.name = name;
  }
}

const person = Reflect.construct(Person, ['Bob']);
console.log(person.name); // "Bob"

Best Practices#

Design:
✓ Use Reflect for default behavior
✓ Always return from set trap
✓ Preserve prototype chain
✓ Handle all edge cases

Performance:
✓ Avoid proxying hot paths
✓ Cache proxy instances
✓ Minimize trap operations
✓ Profile performance impact

Patterns:
✓ Validation and type checking
✓ Change detection/reactivity
✓ Access control
✓ Logging and debugging

Avoid:
✗ Overusing proxies
✗ Forgetting receiver argument
✗ Breaking invariants
✗ Circular proxy chains

Proxy and Reflect enable powerful metaprogramming in JavaScript. Use them for validation, reactivity, access control, and function decoration. Always use Reflect for default behavior and be mindful of performance implications.