Property flags & descriptors

Every property has switches

You already use object properties constantly: user.name, settings.theme, cart.total. Until now, a property may have looked like just a name and a value. JavaScript keeps a little more information than that. A property descriptor is the complete settings panel for one property.

This lesson is about data descriptors, the kind that hold a value. They have the value plus three flags: writable, enumerable, and configurable. The next lesson, Getters & setters, swaps the value box for get and set functions. That is called an accessor descriptor.

These flags explain why Math.PI cannot be overwritten, why some properties are invisible to Object.keys, and why libraries can expose a stable public API while keeping internal slots out of loops and JSON output.

Ordinary assignment goes through a property’s normal door: obj.x = 1. Definition is stronger. Object.defineProperty installs or rewrites the property rules directly. It takes the object, the property name, and a descriptor object.

"use strict";
const account = {};

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

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

The code says: install an id property with value 42, make it visible in listings, but do not allow assignment to replace it or a later descriptor to loosen the rules. Because CompleteFrontend’s site code is strict, a failed write throws a TypeError. In sloppy scripts, the same failed write silently leaves the old value.

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 switches. Notice the surprise: enumerable does not control whether you can read panel.choice. It controls whether listing tools see it. configurable is the lock that affects deletion and most redefinition.

JavaScript gives you two inspection tools. Use Object.getOwnPropertyDescriptor(obj, name) for one own property. Use Object.getOwnPropertyDescriptors(obj) for every own property at once. They do not walk the prototype chain.

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"));

A built-in property is a useful reality check. In current JavaScript, Math.PI is a data property whose descriptor says writable: false, enumerable: false, and configurable: false. That is why strict code cannot replace it, Object.keys(Math) does not show it, and you cannot delete it.

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

Default flags: assignment is friendly, definition is strict

The most important gotcha is that different creation paths choose different defaults. Object literal syntax and assignment create normal everyday properties: writable, enumerable, and configurable are all true. Object.defineProperty is the opposite: every flag you omit defaults to false.

This is deliberate. Definition is a low-level tool. If JavaScript guessed permissive flags while you were defining a property, it would be easy to accidentally expose or loosen an internal detail.

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); }
})();

The first half is a sloppy script: assigning to a non-writable property does not throw, and the value remains 1. The second half is strict, so the same write is reported as TypeError. The course uses strict modules, so the strict behavior is the one you should expect in lesson code.

A descriptor map is an object whose keys are property names and whose values are descriptor objects. Two APIs use that shape: Object.defineProperties adds many descriptors to an existing object, and Object.create can create an object with descriptors in one step.

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));

A common use is creating visible public fields and hidden metadata together. In the walkthrough, token exists and can be read directly, but because enumerable was omitted it is skipped by Object.keys and JSON.stringify.

"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 can look like two ways to “put a property on an object,” but they obey different rules. Assignment uses the normal property access machinery. It can call inherited setters and it respects inherited non-writable data properties. Definition writes an own descriptor directly onto the target object.

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);

This distinction matters when you work with objects created from prototypes, class instances, or library objects. If you want to trigger the public API, assign. If you need to install a precise descriptor, define.

Where you’ll use this

Descriptors are not something you use for every property. They are a professional tool for edges where “normal property” is too broad.

• Read-only public constants. A library can expose version information or a token name without letting consumers overwrite it by accident.
• Hidden metadata. Frameworks often store internal markers that should not appear in Object.keys, object spread, or JSON output.
• Compatibility wrappers. You can install a property now with a shape that a later getter or setter can replace when the next lesson’s accessor descriptors become useful.
• Testing and debugging. Inspecting descriptors helps explain why a write, loop, or delete behaves differently from a plain object literal.

Misconceptions and one-way locks

Key takeaways

• A property descriptor is the value plus hidden flags for an own property.
• writable controls assignment to a data property’s value.
• enumerable controls whether common listing tools see the property.
• configurable controls deletion and most future descriptor changes.
• Literal and assignment defaults are permissive; defineProperty defaults omitted flags to false.
• Assignment uses normal property access. Definition installs an own descriptor directly.

Up next: Getters & setters.