JavaScript Proxy and Reflect Guide

Proxy allows you to intercept and customize fundamental operations on objects. Reflect provides methods for those operations. Here's how to use them.

Basic Proxy#

const target = {
  name: 'John',
  age: 30,
};

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 "John"
proxy.age = 31; // Logs: "Setting age to 31"

Validation with Proxy#

const validator = {
  set(target, property, value) {
    if (property === 'age') {
      if (typeof value !== 'number') {
        throw new TypeError('Age must be a number');
      }
      if (value < 0 || value > 150) {
        throw new RangeError('Age must be between 0 and 150');
      }
    }
    target[property] = value;
    return true;
  },
};

const person = new Proxy({}, validator);

person.age = 30; // OK
person.age = -5; // RangeError
person.age = 'thirty'; // TypeError

Default Values#

const withDefaults = (target, defaults) => {
  return new Proxy(target, {
    get(obj, prop) {
      return prop in obj ? obj[prop] : defaults[prop];
    },
  });
};

const config = withDefaults(
  { host: 'localhost' },
  { host: '0.0.0.0', port: 3000, timeout: 5000 }
);

console.log(config.host); // 'localhost' (from target)
console.log(config.port); // 3000 (from defaults)
console.log(config.timeout); // 5000 (from defaults)

Property Access Logging#

function createLogger(obj, name = 'Object') {
  return new Proxy(obj, {
    get(target, prop) {
      console.log(`[${name}] GET ${String(prop)}`);
      return Reflect.get(target, prop);
    },
    set(target, prop, value) {
      console.log(`[${name}] SET ${String(prop)} = ${value}`);
      return Reflect.set(target, prop, value);
    },
    deleteProperty(target, prop) {
      console.log(`[${name}] DELETE ${String(prop)}`);
      return Reflect.deleteProperty(target, prop);
    },
  });
}

const user = createLogger({ name: 'John' }, 'User');
user.name; // [User] GET name
user.age = 30; // [User] SET age = 30
delete user.age; // [User] DELETE age

Reflect API#

// Reflect provides methods matching Proxy traps
const obj = { x: 1, y: 2 };

// Get property
Reflect.get(obj, 'x'); // 1

// Set property
Reflect.set(obj, 'z', 3); // true

// Check property
Reflect.has(obj, 'x'); // true

// Delete property
Reflect.deleteProperty(obj, 'z'); // true

// Get keys
Reflect.ownKeys(obj); // ['x', 'y']

// Define property
Reflect.defineProperty(obj, 'computed', {
  get() {
    return this.x + this.y;
  },
});

// Get prototype
Reflect.getPrototypeOf(obj); // Object.prototype

// Set prototype
Reflect.setPrototypeOf(obj, null);

Revocable Proxy#

const target = { secret: 'classified' };

const { proxy, revoke } = Proxy.revocable(target, {
  get(target, prop) {
    return target[prop];
  },
});

console.log(proxy.secret); // 'classified'

// Revoke access
revoke();

console.log(proxy.secret); // TypeError: Cannot perform 'get' on a proxy that has been revoked

Observable Pattern#

function observable(target) {
  const listeners = new Map();

  return new Proxy(target, {
    set(obj, prop, value) {
      const oldValue = obj[prop];
      obj[prop] = value;

      if (listeners.has(prop)) {
        listeners.get(prop).forEach((callback) => {
          callback(value, oldValue, prop);
        });
      }

      return true;
    },

    get(obj, prop) {
      if (prop === 'subscribe') {
        return (property, callback) => {
          if (!listeners.has(property)) {
            listeners.set(property, new Set());
          }
          listeners.get(property).add(callback);

          // Return unsubscribe function
          return () => listeners.get(property).delete(callback);
        };
      }
      return obj[prop];
    },
  });
}

const state = observable({ count: 0 });

const unsubscribe = state.subscribe('count', (newVal, oldVal) => {
  console.log(`Count changed from ${oldVal} to ${newVal}`);
});

state.count = 1; // "Count changed from 0 to 1"
state.count = 2; // "Count changed from 1 to 2"

unsubscribe();
state.count = 3; // No log

Negative Array Indices#

function negativeArray(arr) {
  return new Proxy(arr, {
    get(target, prop) {
      const index = Number(prop);
      if (!isNaN(index) && index < 0) {
        return target[target.length + index];
      }
      return Reflect.get(target, prop);
    },
    set(target, prop, value) {
      const index = Number(prop);
      if (!isNaN(index) && index < 0) {
        target[target.length + index] = value;
        return true;
      }
      return Reflect.set(target, prop, value);
    },
  });
}

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

Private Properties#

function privateProps(target, privateKeys = []) {
  return new Proxy(target, {
    get(obj, prop) {
      if (privateKeys.includes(prop)) {
        throw new Error(`Cannot access private property: ${prop}`);
      }
      return Reflect.get(obj, prop);
    },
    set(obj, prop, value) {
      if (privateKeys.includes(prop)) {
        throw new Error(`Cannot set private property: ${prop}`);
      }
      return Reflect.set(obj, prop, value);
    },
    has(obj, prop) {
      if (privateKeys.includes(prop)) {
        return false;
      }
      return Reflect.has(obj, prop);
    },
    ownKeys(obj) {
      return Reflect.ownKeys(obj).filter((key) => !privateKeys.includes(key));
    },
  });
}

const user = privateProps(
  { name: 'John', _password: 'secret123' },
  ['_password']
);

console.log(user.name); // 'John'
console.log(user._password); // Error
console.log('_password' in user); // false
console.log(Object.keys(user)); // ['name']

Function Proxy#

function tracedFunction(fn, name = fn.name) {
  return new Proxy(fn, {
    apply(target, thisArg, args) {
      console.log(`Calling ${name} with:`, args);
      const start = performance.now();
      const result = Reflect.apply(target, thisArg, args);
      const duration = performance.now() - start;
      console.log(`${name} returned:`, result, `(${duration.toFixed(2)}ms)`);
      return result;
    },
  });
}

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

Caching Proxy#

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

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

      if (cache.has(key)) {
        console.log('Cache hit');
        return cache.get(key);
      }

      console.log('Cache miss');
      const result = Reflect.apply(target, thisArg, args);
      cache.set(key, result);
      return result;
    },
  });
}

const expensiveCalc = memoize((n) => {
  // Simulate expensive operation
  let result = 0;
  for (let i = 0; i < n * 1000000; i++) {
    result += i;
  }
  return result;
});

expensiveCalc(10); // Cache miss
expensiveCalc(10); // Cache hit

DOM Element Proxy#

function $(selector) {
  const elements = document.querySelectorAll(selector);

  return new Proxy(elements, {
    get(target, prop) {
      // Array methods
      if (prop in Array.prototype) {
        return Array.prototype[prop].bind([...target]);
      }

      // Style shorthand
      if (prop === 'css') {
        return (styles) => {
          target.forEach((el) => Object.assign(el.style, styles));
          return proxy;
        };
      }

      // Event shorthand
      if (prop.startsWith('on')) {
        const event = prop.slice(2).toLowerCase();
        return (handler) => {
          target.forEach((el) => el.addEventListener(event, handler));
          return proxy;
        };
      }

      // Return first element's property
      return target[0]?.[prop];
    },
  });

  const proxy = new Proxy(elements, handler);
  return proxy;
}

// Usage
$('.button').css({ color: 'red' }).onClick((e) => console.log(e));

Type Coercion#

const coerce = (schema) => (target) => {
  return new Proxy(target, {
    set(obj, prop, value) {
      if (prop in schema) {
        const type = schema[prop];
        let coerced = value;

        switch (type) {
          case 'number':
            coerced = Number(value);
            break;
          case 'string':
            coerced = String(value);
            break;
          case 'boolean':
            coerced = Boolean(value);
            break;
          case 'date':
            coerced = new Date(value);
            break;
        }

        return Reflect.set(obj, prop, coerced);
      }
      return Reflect.set(obj, prop, value);
    },
  });
};

const form = coerce({
  age: 'number',
  name: 'string',
  active: 'boolean',
})({});

form.age = '25';
form.active = 1;
console.log(form.age); // 25 (number)
console.log(form.active); // true (boolean)

Best Practices#

Usage:
✓ Validation and constraints
✓ Logging and debugging
✓ Caching and memoization
✓ Observable state

Reflect:
✓ Use with Proxy traps
✓ Forward default behavior
✓ Handle edge cases
✓ Return proper values

Performance:
✓ Cache proxy instances
✓ Minimize trap overhead
✓ Use for specific needs
✓ Profile impact

Avoid:
✗ Proxying everything
✗ Complex nested proxies
✗ Ignoring invariants
✗ Memory leak risks

Proxy and Reflect provide powerful metaprogramming capabilities in JavaScript. Use Proxy for validation, logging, caching, and reactive state management. Use Reflect to implement default behavior in proxy traps. Be mindful of performance and only use proxies when their benefits outweigh the overhead.