Property flags & descriptors

Every property has three flags

You already use object properties all the time: user.name, settings.theme, cart.total. So far, a property has looked like a name and a value. JavaScript keeps a little more for each property. It also keeps three yes-or-no settings, called flags.

A property descriptor is a plain object that lists the value and the flags of one property. This lesson is about data descriptors. A data descriptor has four parts:

• value: the value the property holds.
• writable: can assignment, like obj.x = 2, change the value?
• enumerable: does the property show up when JavaScript lists properties?
• configurable: can you delete the property or change its flags?

There is a second kind, the accessor descriptor. It has no value. Instead it has a get function, which runs when you read the property, and a set function, which runs when you assign to it. The next lesson, Getters & setters, is about this kind. Here is a quick look.

let displayName = "Asha";
const user = {};
Object.defineProperty(user, "name", {
  get() { return displayName; },
  set(value) { displayName = value; },
  enumerable: true,
});
console.log(user.name);
user.name = "Mina";
console.log(user.name);

The real name lives in the separate displayName variable. Line 7 reads user.name, so get runs and prints Asha. Line 8 assigns, so set runs and stores Mina. Line 9 prints Mina. One descriptor uses either value and writable, or get and set. It can't mix the two.

The table shows each flag. Read across a row to see what happens when that flag is true and when it is false.

These flags explain things you may have seen. You can't overwrite Math.PI. Some properties never show up in Object.keys. Libraries can keep their own notes on an object without those notes appearing in loops or in JSON text.

Plain assignment, like obj.x = 1, sets a value. You don't choose any flags. Object.defineProperty lets you set the value and the flags yourself. We call this defining a property. It takes three things:

• the object, like account
• the property name, like "id"
• a descriptor object with the value and flags

"use strict";
const account = {};

Object.defineProperty(account, "id", {
  value: 42,
  writable: false,
  enumerable: true,
  configurable: false,
});

console.log(account.id); // 42

Lines 4 to 9 give account an id property:

• value: 42: id holds 42.
• writable: false: assignment can't change it.
• enumerable: true: it shows up in lists like Object.keys.
• configurable: false: you can't delete it or change its flags later.

Line 1 turns on strict mode, the stricter set of JavaScript rules. This site's code runs in strict mode. In strict mode, a write that isn't allowed throws a TypeError, an error you can catch. Without strict mode (people call it sloppy mode), the same write does nothing and gives no error. The old value stays.

1"use strict";2const panel = {};3Object.defineProperty(panel, "choice", {4  value: "open",5  writable: true,6  enumerable: true,7  configurable: true,8});9 10panel.choice = "changed";11delete panel.choice;12Object.keys(panel);13JSON.stringify(panel);

Try all three flags. Notice one surprise. With enumerable off, you can still read panel.choice. The flag only decides whether lists like Object.keys include it. And configurable is the flag that decides whether delete and redefining work.

JavaScript gives you two ways to read descriptors:

• Object.getOwnPropertyDescriptor(obj, name) returns the descriptor of one property.
• Object.getOwnPropertyDescriptors(obj) returns the descriptors of all the object's properties at once.

Both look only at the object's own properties: the ones stored on the object itself. They don't look at its prototype, the object it borrows properties from.

1"use strict";2const normal = { visible: 1 };Run3Object.defineProperty(normal, "quiet", { value: 2 });4 5console.log(Object.getOwnPropertyDescriptor(normal, "visible"));6console.log(Object.getOwnPropertyDescriptor(normal, "quiet"));

You can read the flags of built-in properties too. Math.PI has writable: false, enumerable: false, and configurable: false. So:

• strict code can't change it,
• Object.keys(Math) doesn't list it,
• and you can't delete it.

const pi = Object.getOwnPropertyDescriptor(Math, "PI");
console.log(pi.value);
console.log(pi.writable);
console.log(pi.configurable);

Line 1 saves the descriptor of Math.PI in pi. Line 2 prints the value, 3.141592653589793. Lines 3 and 4 print false and false.

Default flags: assignment turns them on, defineProperty turns them off

This is the rule that surprises people most. How you make a property decides its starting flags:

• An object literal, like { x: 1 }, or an assignment, like obj.x = 1, makes all three flags true.
• Object.defineProperty makes every flag you leave out false.

The table lists each way. Read a row to see the flags you get.

const assigned = {};
assigned.price = 3;
const defined = {};
Object.defineProperty(defined, "price", { value: 3 });
console.log(Object.getOwnPropertyDescriptor(assigned, "price").writable);
console.log(Object.getOwnPropertyDescriptor(defined, "price").writable);

Line 2 uses assignment, so line 5 prints true for writable. Line 4 gives only a value, so line 6 prints false. The other two flags are false too, unless you write them in the descriptor.

This is on purpose. defineProperty is for when you want exact control. If it turned flags on by itself, you could open up a property by mistake.

const sloppy = {};
Object.defineProperty(sloppy, "x", { value: 1, writable: false });
sloppy.x = 2;
console.log(sloppy.x);

(function strictMode() {
  "use strict";
  const strict = {};
  Object.defineProperty(strict, "x", { value: 1, writable: false });
  try { strict.x = 2; } catch (error) { console.log(error.name); }
})();

Lines 1 to 4 run in sloppy mode. Line 3 tries to change a read-only property. Nothing happens and there's no error, so line 4 prints 1. Lines 6 to 11 run in strict mode. The same write on line 10 throws, and the catch prints TypeError. This course's code is strict, so expect the error.

A descriptor map is an object where each key is a property name and each value is that property's descriptor. Two tools take a descriptor map:

• Object.defineProperties(obj, map) adds the properties to an object you already have.
• Object.create(proto, map) makes a new object with those properties.

1"use strict";2const user = Object.create(null, {Run3  id: { value: 42, enumerable: true },4  role: { value: "admin", enumerable: true },5});6 7Object.defineProperties(user, {8  token: { value: "abc", writable: false },9  label: { value: "Ada", writable: true, enumerable: true },10});11 12console.log(Object.keys(user));13console.log(Object.getOwnPropertyDescriptors(user));

This is handy when an object needs some properties that everyone sees and some hidden ones. In the walkthrough, the descriptor for token leaves out enumerable, so it is false. You can still read user.token, but Object.keys and JSON.stringify skip it.

const original = {};
Object.defineProperties(original, {
  id: { value: 42, writable: false, enumerable: true },
  token: { value: "abc", enumerable: false },
});
const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(original));
const spread = { ...original };
console.log(Object.keys(clone));
console.log(Object.getOwnPropertyDescriptor(clone, "token").enumerable);
console.log(Object.getOwnPropertyDescriptor(spread, "id").writable);

Line 6 makes clone. getOwnPropertyDescriptors gives a descriptor map, and defineProperties uses it. So clone keeps token hidden and id read-only. Line 7 makes spread with the spread syntax ..., which copies only listed values. Its id is a normal property, so line 10 prints true for writable. Use the descriptor way when the copy must follow the same rules as the original.

"use strict";
const user = Object.create(null, {
  id: { value: 42, enumerable: true },
  role: { value: "admin", enumerable: true },
});

Object.defineProperties(user, {
  token: { value: "abc", writable: false },
  label: { value: "Ada", writable: true, enumerable: true },
});

console.log(Object.keys(user));
console.log(Object.getOwnPropertyDescriptors(user));

Assignment and definition both put a property on an object. But they follow different rules:

• Assignment, like child.name = "Ada", first looks for name on the object and its prototype. If the prototype has a setter (a set function for that name), the setter runs. If the prototype has a read-only property with that name, the assignment fails.
• Definition, with Object.defineProperty, puts the property straight onto the object. It doesn't check the prototype.

1"use strict";2const log = [];3const proto = {Run4  set name(value) { log.push("setter:" + value); }5};6Object.defineProperty(proto, "locked", { value: 1, writable: false });7 8const child = Object.create(proto);9child.name = "Ada";10Object.defineProperty(child, "name", { value: "Ada", enumerable: true });11 12try { child.locked = 2; } catch (error) { log.push(error.name); }13Object.defineProperty(child, "locked", { value: 2, enumerable: true });14 15console.log(log);16console.log(child.name, child.locked);

"use strict";
const log = [];
const proto = {
  set name(value) { log.push("setter:" + value); }
};
Object.defineProperty(proto, "locked", { value: 1, writable: false });

const child = Object.create(proto);
child.name = "Ada";
Object.defineProperty(child, "name", { value: "Ada", enumerable: true });

try { child.locked = 2; } catch (error) { log.push(error.name); }
Object.defineProperty(child, "locked", { value: 2, enumerable: true });

console.log(log);
console.log(child.name, child.locked);

Line 9 assigns, so the setter on proto runs and adds "setter:Ada" to log. Line 10 defines, so child gets its own name, and the setter doesn't run.

Line 12 assigns to locked. The prototype's locked is read-only, so the assignment throws TypeError. Line 13 defines locked on child and works.

This matters for objects made from prototypes, like class instances and objects from libraries. Assign when you want the object's setters to run. Define when you need exact flags on the object itself.

Where you'll use this

Most properties don't need special flags. Descriptors help in a few places where a normal property allows too much:

• Read-only constants. A library can share a version number that other code can't overwrite by mistake.
• Hidden notes. Frameworks often store their own notes on your objects. With enumerable: false, those notes stay out of Object.keys, spread copies, and JSON text.
• A property that can change kind later. With configurable: true, you can later replace a plain value with get and set functions, as in the next lesson.
• Finding bugs. Reading a property's flags tells you why a write, a loop, or a delete acts differently than you expected.

Common mistakes and the one-way lock

"use strict";
const account = {};
Object.defineProperty(account, "id", {
  value: 1,
  writable: true,
  configurable: false,
});
Object.defineProperty(account, "id", { writable: false });
console.log(Object.getOwnPropertyDescriptor(account, "id").writable);
try { Object.defineProperty(account, "id", { writable: true }); } catch (error) {
  console.log(error.name);
}

Lines 3 to 7 define id with configurable: false. Line 8 changes writable from true to false. That is allowed, because it only makes the property stricter. Line 9 prints false. Line 10 tries to turn writable back on, so it throws, and line 11 prints TypeError. You can still read the value.

Key takeaways

• A property descriptor lists a property's value and its three flags.
• writable decides whether assignment can change the value.
• enumerable decides whether lists like Object.keys include the property.
• configurable decides whether you can delete the property or change its flags.
• Literals and assignment turn every flag on. defineProperty turns off every flag you leave out.
• Assignment checks the prototype for setters and read-only properties. Definition puts the property straight onto the object.

Up next: Getters & setters.