Reflect

Reflect does object jobs with plain functions

You already know many ways to work with an object:

• read a property, like cart.tea
• check for a key with in, like "tea" in cart
• remove a key with delete
• make a new object with new
• add a property with Object.defineProperty

Reflect is a built-in object that holds functions for these same jobs. Each job becomes a plain function call, like Reflect.has(cart, "tea").

Why use a function when the short syntax works? The main reason is a proxy. A proxy is an object that stands in front of another object, called the target. You met proxies in the Proxy lesson. A proxy has traps: functions that catch an action, like a read or a write. A trap often does one small extra thing, like writing a log. Then it wants to do the normal action. Reflect has one function for each normal action, so the trap can call it.

Start with a normal object. Three Reflect calls check for a key, delete it, and check again.

const cart = { tea: 2 };
console.log(Reflect.has(cart, "tea"));
console.log(Reflect.deleteProperty(cart, "tea"));
console.log(Reflect.has(cart, "tea"));

In plain words, line by line:

1. Line 1 makes a small cart object with one key, tea.
2. Line 2 asks: does cart have a key named tea? It does, so it prints true.
3. Line 3 deletes tea. The delete works, so it prints true.
4. Line 4 asks again. The key is gone, so it prints false.

In this lesson you will:

• compare Reflect with Object methods
• keep a getter's this right when a proxy passes a read on
• pass proxy traps on to Reflect
• list every key of an object, in order
• call functions and constructors with Reflect.apply and Reflect.construct

Reflect is not magic. Each method is a named function for a job JavaScript already knows how to do. Here are all 13: apply, construct, defineProperty, deleteProperty, get, getOwnPropertyDescriptor, getPrototypeOf, has, isExtensible, ownKeys, preventExtensions, set, and setPrototypeOf.

Read each row of the next table from left to right: the job, the Reflect method that does it, and what the method gives back.

Five methods change an object and answer true or false. The answer tells you whether the change worked:

• defineProperty
• set
• deleteProperty
• preventExtensions
• setPrototypeOf

This answer is most useful inside proxy traps. A set trap, for example, must give back true or false.

A false answer does not mean Reflect never throws. Reflect still throws a TypeError in these cases:

• The target is not an object, for example the number 1.
• Reflect.apply gets something that is not a function.
• A proxy breaks one of its fixed rules. The Proxy lesson calls these rules invariants.

The next table names each of the five methods and the case where it returns false.

Some Object methods act differently from their Reflect twins. Two differences matter most:

• When the job fails. Object.defineProperty throws an error. Reflect.defineProperty returns false.
• When the target is not an object. Object.getPrototypeOf(1) treats the number like a number object and returns Number.prototype. Reflect.getPrototypeOf(1) throws a TypeError, because Reflect only accepts objects.

Step through the first difference. Line 2 uses Object.preventExtensions, which stops an object from growing: no new properties can be added to it. Then the code tries to add id two ways.

1"use strict";2const locked = Object.preventExtensions({});Run3let objectResult;4try {5  Object.defineProperty(locked, "id", { value: 1 });6} catch (error) {7  objectResult = error.name;8}9const reflectResult = Reflect.defineProperty(locked, "id", { value: 1 });10console.log(objectResult);11console.log(reflectResult);

Here are three more pairs:

• Reflect.has does the same job as in.
• Reflect.deleteProperty does the same job as delete.
• Reflect.ownKeys lists more keys than Object.keys.

1const box = { visible: 1 };2const sym = Symbol("tag");3Object.defineProperty(box, "hidden", { value: 2 });4box[sym] = 3;5 6console.log(Reflect.has(box, "visible"));7console.log(Reflect.deleteProperty(box, "missing"));8console.log(Reflect.ownKeys(box));9console.log(Object.keys(box));

Next, see two kinds of failure side by side: a thrown error, and a false answer.

try {
  Reflect.getPrototypeOf(1);
} catch (error) {
  console.log(error.name);
}
const box = {};
Object.defineProperty(box, "id", { value: 1, configurable: false });
console.log(Reflect.deleteProperty(box, "id"));

In plain words, line by line:

1. Line 2 passes the number 1, but Reflect needs an object. It throws a TypeError, and line 4 prints its name.
2. Line 7 adds an id property. configurable: false locks it, so it can't be deleted.
3. Line 8 tries to delete id. The target is a real object, so nothing throws. The delete fails, so Reflect returns false.

So the two failures mean different things. false means a fair try that didn't work. A TypeError means the call itself was wrong.

Here is the code from the lab as a plain block, so you can paste it into a console.

const box = { visible: 1 };
const sym = Symbol("tag");
Object.defineProperty(box, "hidden", { value: 2 });
box[sym] = 3;

console.log(Reflect.has(box, "visible"));
console.log(Reflect.deleteProperty(box, "missing"));
console.log(Reflect.ownKeys(box));
console.log(Object.keys(box));

Line 7 returns true even though missing never existed. After the call, the key is not there, and that counts as success.

First, a reminder about getters. A getter is a function that runs when you read a property. Inside the getter, this is the object you read from.

The receiver is the object that becomes this when a getter or setter runs. When you write obj.value, the receiver is obj.

Most of the time, the object that holds the getter is the object you read from. But they can be different:

• With a prototype, the getter can live on the prototype, while you read from a child object.
• With a proxy, the getter is found through the target, while you read from the proxy.

Step through a proxy that passes a getter read on. Pick line 12 first: plain target[key], or Reflect.get(target, key, receiver).

1"use strict";2const badge = {Run3  name: "prototype badge",4  get label() {5    return this.name;6  }7};8const user = Object.create(badge);9user.name = "Ada";10const proxy = new Proxy(user, {11  get(target, key, receiver) {12    return target[key];13  }14});15console.log(proxy.label);

The next example makes the difference easy to see. Each proxy writes every key it is asked for into a list named reads.

const reads = [];
const profile = { name: "Asha", get label() { return this.name; } };
const user = Object.create(profile);
const naive = new Proxy(user, { get(target, key) { reads.push(String(key)); return target[key]; } });
console.log(naive.label, reads.join(","));
reads.length = 0;
const forwarded = new Proxy(user, { get(target, key, receiver) { reads.push(String(key)); return Reflect.get(target, key, receiver); } });
console.log(forwarded.label, reads.join(","));

In plain words, line by line:

1. Line 2: profile has a name and a label getter that returns this.name.
2. Line 3: user is a new, empty object whose prototype is profile.
3. Line 4: the naive proxy writes down each key, then reads it with target[key].
4. Line 5 prints Asha label. The getter ran with this set to user, so its name read skipped the proxy.
5. Line 6 empties the list.
6. Line 7: the forwarded proxy writes down each key, then reads it with Reflect.get(target, key, receiver).
7. Line 8 prints Asha label,name. The getter ran with this set to the proxy, so its name read went through the trap too.

Here both proxies print the same name. The difference matters when:

• the getter does more work with this
• a setter checks a value using this
• the proxy must see every read

So inside a proxy get trap, write return Reflect.get(target, key, receiver).

A proxy trap often does two things: it writes a note in a log, then it does the normal job. The simplest safe way to do the normal job:

• Take every argument the trap gets with ...args. This rest syntax collects all the arguments into one array named args.
• Pass the same arguments to the Reflect method with the same name, like Reflect.get(...args). The ... here spreads the array back out into separate arguments.

1"use strict";2const target = { count: 0 };Run3const log = [];4const proxy = new Proxy(target, {5  get(...args) {6    log.push("get:" + String(args[1]));7    return Reflect.get(...args);8  },9  set(...args) {10    log.push("set:" + String(args[1]));11    return Reflect.set(...args);12  }13});14proxy.count = proxy.count + 1;15console.log(target.count);16console.log(log.join(", "));

A trap can also refuse a write. This set trap refuses a negative balance.

const account = { balance: 10 };
const safe = new Proxy(account, {
  set(target, key, value, receiver) {
    if (key === "balance" && value < 0) return false;
    return Reflect.set(target, key, value, receiver);
  }
});
console.log(Reflect.set(safe, "balance", 20));
console.log(Reflect.set(safe, "balance", -1));
console.log(account.balance);

In plain words, line by line:

1. Line 4: if the key is balance and the new value is below 0, the trap returns false and writes nothing.
2. Line 5: any other write goes on to Reflect.set, which does the write and returns true.
3. Line 8 writes 20. The trap accepts it, so it prints true.
4. Line 9 writes -1. The trap refuses it, so it prints false.
5. Line 10 prints 20. The refused write never reached account.

Lines 8 and 9 call Reflect.set on the proxy, so a refusal comes back as false, not as an error. The code that made the call can decide what to do next, for example throw its own error.

An object's own keys are the keys stored on the object itself, not on its prototype. Object.keys lists only some of them:

• It lists string keys only, never symbol keys.
• It lists enumerable keys only. An enumerable key is one that shows up in loops and key lists. A key added with Object.defineProperty is not enumerable unless you ask for it.

Reflect.ownKeys lists every own key, enumerable or not, in this order:

1. Number keys: keys that look like whole numbers, such as "3" and "20", from smallest to biggest.
2. String keys: all other strings, in the order they were added.
3. Symbol keys, in the order they were added.

1const sym = Symbol("id");2const record = { 20: "twenty", name: "Ada", 3: "three" };3Object.defineProperty(record, "hidden", { value: true });4record[sym] = "symbol value";5 6console.log(Reflect.ownKeys(record));7console.log(Object.keys(record));

That fixed order is why an array's indexes always come out as 0, 1, 2, and so on. Symbol keys always come last. If symbol keys are new to you, review the Symbols lesson first.

Sometimes you want only one kind of key. Two Object methods split the list.

const item = { name: "tea" };
Object.defineProperty(item, "hidden", { value: true });
const id = Symbol("id");
item[id] = 1;
console.log(Object.getOwnPropertyNames(item).join(","));
console.log(Object.getOwnPropertySymbols(item).map(String).join(","));

In plain words, line by line:

1. Line 2 adds hidden with Object.defineProperty, so it is not enumerable.
2. Lines 3 and 4 add a symbol key.
3. Line 5: Object.getOwnPropertyNames lists every own string key, hidden ones too. It prints name,hidden.
4. Line 6: Object.getOwnPropertySymbols lists only symbol keys. It prints Symbol(id).

Use these when you want one kind of key. Use Reflect.ownKeys when you want both kinds, in the standard order.

Reflect.apply(fn, thisArg, args) calls a function. It takes three things:

• fn: the function to call
• thisArg: the value for this inside the function
• args: an array of arguments

It does the same job as fn.apply(thisArg, args), which you met in the call, apply & bind lesson.

Reflect.construct(Target, args, NewTarget) does the job of new Target(...args). The third argument, NewTarget, is optional. When you pass it, two things change:

• Inside the constructor, new.target is NewTarget. new.target tells a constructor which function new was used with.
• The new object's prototype is NewTarget.prototype.

The lessons on constructors and new cover these ideas. Two rules still hold:

• Target must be something you can use with new. An arrow function can't be, and NewTarget can't change that.
• If NewTarget.prototype is not an object, the new object gets Object.prototype as its prototype instead.

1function total(prefix, ...numbers) {2  return prefix + numbers.reduce((sum, n) => sum + n, 0);3}4function Base(name) {5  this.name = name;6  this.createdBy = new.target === Special ? "Special" : "Base";7}8function Special() {}9 10console.log(Reflect.apply(total, null, ["$", 2, 3, 4]));11const item = Reflect.construct(Base, ["Ada"], Special);12console.log(item.createdBy);13console.log(Object.getPrototypeOf(item) === Special.prototype);

Next, compare Reflect.apply with the older apply method.

function add(a, b) {
  return this.base + a + b;
}
const context = { base: 10 };
console.log(Reflect.apply(add, context, [2, 3]));
console.log(add.apply(context, [2, 3]));

Both lines call add with this set to context and the arguments 2 and 3. Both print 15, which is 10 + 2 + 3. Reflect puts the function, the this value, and the arguments in three separate slots. That is handy when a helper passes a call on.

Here is the code from the lab again as a plain block.

function total(prefix, ...numbers) {
  return prefix + numbers.reduce((sum, n) => sum + n, 0);
}
function Base(name) {
  this.name = name;
  this.createdBy = new.target === Special ? "Special" : "Base";
}
function Special() {}

console.log(Reflect.apply(total, null, ["$", 2, 3, 4]));
const item = Reflect.construct(Base, ["Ada"], Special);
console.log(item.createdBy);
console.log(Object.getPrototypeOf(item) === Special.prototype);

Where you'll use Reflect

Reflect shows up most in libraries. A library is code written for other programmers to reuse. Common places:

• proxies that check values before they are saved
• objects that tell the page when their data changes
• test doubles: stand-in objects used in tests
• frameworks that add a small extra step to normal object behavior

The habit is simple. Inside a proxy trap, when you want the normal behavior, call the matching Reflect method. Then add only the extra step you need.

Outside proxies, the short syntax is often clearer. Write cart[key] for a single read, and delete cart[key] for a single delete. Choose Reflect when a helper or proxy must pass on the exact job and report whether it worked.

Common misconceptions

• "Reflect never throws." Many methods return false when the job fails. But Reflect still throws a TypeError when it needs an object and gets something else, like a number.
• "Reflect is only for proxies." Proxies are the main use. The function forms also help any helper that gets the job to do as data.
• "Reflect.ownKeys is the same as Object.keys." Reflect.ownKeys also lists keys that are not enumerable, and symbol keys. Object.keys leaves both out.
• "The receiver is always the target." With inherited getters and proxy traps, the receiver can be the object that was first asked, such as the proxy.
• "Reflect.construct is just new without the word new." Its third argument also sets new.target and the new object's prototype.
• "A set trap can skip the return." Then it returns undefined, which counts as failure. In strict mode, the assignment throws a TypeError.

Key takeaways

• Reflect does basic object jobs with plain functions.
• It has 13 methods, one for each of the 13 proxy traps.
• Five methods that change an object return true or false when the job works or fails, instead of throwing.
• Reflect still throws a TypeError when it needs an object and gets something else.
• Inside proxy traps, pass receiver on to Reflect.get and Reflect.set, so this stays right.
• Reflect.ownKeys lists number keys, then other string keys, then symbol keys, hidden keys included.
• Reflect.construct can set new.target with its third argument.

Reflect is JavaScript's built-in set of functions for doing basic object jobs, and for passing them on.

Up next: Well-known symbols.