JavaScript Reflect API Guide

The Reflect API provides methods for interceptable JavaScript operations, making it essential for Proxy implementations. Here's how to use it.

Basic Methods#

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

// Get property
console.log(Reflect.get(obj, 'name')); // 'John'

// Set property
Reflect.set(obj, 'age', 31);
console.log(obj.age); // 31

// Check property existence
console.log(Reflect.has(obj, 'name')); // true

// Delete property
Reflect.deleteProperty(obj, 'age');
console.log(obj.age); // undefined

// Get own property keys
console.log(Reflect.ownKeys(obj)); // ['name']

Property Operations#

const obj = {};

// Define property
Reflect.defineProperty(obj, 'id', {
  value: 1,
  writable: false,
  enumerable: true,
  configurable: false,
});

// Get property descriptor
const desc = Reflect.getOwnPropertyDescriptor(obj, 'id');
console.log(desc);
// { value: 1, writable: false, enumerable: true, configurable: false }

// Check if property is defined
console.log(Reflect.has(obj, 'id')); // true

// Get all keys (including symbols)
const sym = Symbol('key');
obj[sym] = 'symbol value';
console.log(Reflect.ownKeys(obj)); // ['id', Symbol(key)]

Prototype Operations#

const animal = { type: 'animal' };
const dog = { breed: 'Labrador' };

// Set prototype
Reflect.setPrototypeOf(dog, animal);

// Get prototype
console.log(Reflect.getPrototypeOf(dog)); // { type: 'animal' }

// Check inheritance
console.log(Reflect.has(dog, 'type')); // true (from prototype)
console.log(Reflect.get(dog, 'type')); // 'animal'

Function Calls#

function greet(greeting, punctuation) {
  return `${greeting}, ${this.name}${punctuation}`;
}

const person = { name: 'Alice' };

// Apply function with this context
const result = Reflect.apply(greet, person, ['Hello', '!']);
console.log(result); // 'Hello, Alice!'

// Compare to Function.prototype.apply
const result2 = greet.apply(person, ['Hi', '?']);
console.log(result2); // 'Hi, Alice?'

Constructor Calls#

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

// Create instance with Reflect.construct
const user = Reflect.construct(User, ['John', 'admin']);
console.log(user); // User { name: 'John', role: 'admin' }

// With different newTarget
class Admin extends User {}

const admin = Reflect.construct(User, ['Jane', 'superadmin'], Admin);
console.log(admin instanceof Admin); // true
console.log(admin); // Admin { name: 'Jane', role: 'superadmin' }

With Proxies#

// Reflect methods are perfect for proxy traps
const handler = {
  get(target, prop, receiver) {
    console.log(`Getting ${prop}`);
    return Reflect.get(target, prop, receiver);
  },

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

  has(target, prop) {
    console.log(`Checking ${prop}`);
    return Reflect.has(target, prop);
  },

  deleteProperty(target, prop) {
    console.log(`Deleting ${prop}`);
    return Reflect.deleteProperty(target, prop);
  },
};

const obj = { name: 'Original' };
const proxy = new Proxy(obj, handler);

proxy.name;           // Getting name
proxy.age = 25;       // Setting age to 25
'name' in proxy;      // Checking name
delete proxy.age;     // Deleting age

Validation Proxy#

const userSchema = {
  name: (value) => typeof value === 'string' && value.length > 0,
  age: (value) => typeof value === 'number' && value >= 0,
  email: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
};

const handler = {
  set(target, prop, value, receiver) {
    const validator = userSchema[prop];

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

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

  defineProperty(target, prop, descriptor) {
    const validator = userSchema[prop];

    if (validator && descriptor.value !== undefined) {
      if (!validator(descriptor.value)) {
        throw new Error(`Invalid value for ${prop}`);
      }
    }

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

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

user.name = 'John';    // OK
user.age = 30;         // OK
// user.age = -5;      // Error: Invalid value for age

Observable Objects#

function createObservable(target, onChange) {
  return new Proxy(target, {
    set(target, prop, value, receiver) {
      const oldValue = Reflect.get(target, prop, receiver);
      const result = Reflect.set(target, prop, value, receiver);

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

      return result;
    },

    deleteProperty(target, prop) {
      const hadProperty = Reflect.has(target, prop);
      const oldValue = Reflect.get(target, prop);
      const result = Reflect.deleteProperty(target, prop);

      if (result && hadProperty) {
        onChange(prop, undefined, oldValue);
      }

      return result;
    },
  });
}

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

data.count = 1;  // count changed from 0 to 1
data.count = 2;  // count changed from 1 to 2

Access Control#

function createPrivate(obj, privateProps = []) {
  return new Proxy(obj, {
    get(target, prop, receiver) {
      if (privateProps.includes(prop)) {
        throw new Error(`Cannot access private property: ${prop}`);
      }
      return Reflect.get(target, prop, receiver);
    },

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

    has(target, prop) {
      if (privateProps.includes(prop)) {
        return false;
      }
      return Reflect.has(target, prop);
    },

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

    getOwnPropertyDescriptor(target, prop) {
      if (privateProps.includes(prop)) {
        return undefined;
      }
      return Reflect.getOwnPropertyDescriptor(target, prop);
    },
  });
}

const user = createPrivate(
  { name: 'John', password: 'secret', id: 1 },
  ['password']
);

console.log(user.name);        // 'John'
// console.log(user.password); // Error
console.log(Object.keys(user)); // ['name', 'id']

Lazy Initialization#

function createLazy(initializer) {
  let initialized = false;
  let value;

  return new Proxy({}, {
    get(target, prop, receiver) {
      if (!initialized) {
        value = initializer();
        initialized = true;
      }
      return Reflect.get(value, prop);
    },

    set(target, prop, newValue, receiver) {
      if (!initialized) {
        value = initializer();
        initialized = true;
      }
      return Reflect.set(value, prop, newValue);
    },

    has(target, prop) {
      if (!initialized) {
        value = initializer();
        initialized = true;
      }
      return Reflect.has(value, prop);
    },
  });
}

const lazyConfig = createLazy(() => {
  console.log('Loading config...');
  return { apiUrl: 'https://api.example.com', timeout: 5000 };
});

// Config not loaded yet
console.log(lazyConfig.apiUrl);
// Loading config...
// 'https://api.example.com'

Method Interception#

function createMethodLogger(obj) {
  return new Proxy(obj, {
    get(target, prop, receiver) {
      const value = Reflect.get(target, prop, receiver);

      if (typeof value === 'function') {
        return function (...args) {
          console.log(`Calling ${prop} with args:`, args);
          const result = Reflect.apply(value, target, args);
          console.log(`${prop} returned:`, result);
          return result;
        };
      }

      return value;
    },
  });
}

const calculator = createMethodLogger({
  add: (a, b) => a + b,
  multiply: (a, b) => a * b,
});

calculator.add(2, 3);
// Calling add with args: [2, 3]
// add returned: 5

Extensibility Control#

const obj = { name: 'John' };

// Check if extensible
console.log(Reflect.isExtensible(obj)); // true

// Prevent extensions
Reflect.preventExtensions(obj);

console.log(Reflect.isExtensible(obj)); // false

// Can't add new properties
const result = Reflect.set(obj, 'age', 30);
console.log(result); // false in strict mode

// Can still modify existing properties
Reflect.set(obj, 'name', 'Jane');
console.log(obj.name); // 'Jane'

Best Practices#

Usage:
✓ Use with Proxy traps
✓ Maintain default behavior
✓ Handle return values
✓ Forward receiver properly

Benefits:
✓ Consistent return values
✓ Matches Proxy trap signatures
✓ Better than Object methods
✓ Works with primitives

Patterns:
✓ Validation proxies
✓ Observable objects
✓ Access control
✓ Method interception

Avoid:
✗ Ignoring return values
✗ Forgetting receiver
✗ Using when unnecessary
✗ Breaking invariants

The Reflect API provides methods that correspond to Proxy trap operations, making proxy implementations cleaner and more reliable. Use Reflect.get, Reflect.set, and other methods in proxy handlers to maintain default behavior while adding custom logic. The consistent return values and proper receiver handling make Reflect essential for meta-programming in JavaScript.