Property Descriptors and Object Immutability

Properties Are More Than Key-Value Pairs

When you write obj.name = "Alice", you're not just storing a value. You're creating a property with hidden metadata — three boolean flags that control whether the property can be changed, deleted, or seen in loops. Most developers never touch these flags, which means they miss a powerful tool for defensive programming and can't explain why Object.freeze doesn't actually make objects immutable.

The Property Descriptor Model

Every property has a descriptor — an object describing the property's metadata. There are two types:

Data Descriptors

const obj = {};
Object.defineProperty(obj, "name", {
  value: "Alice",
  writable: true,      // Can the value be changed?
  enumerable: true,    // Does it show up in for...in and Object.keys()?
  configurable: true   // Can the descriptor be modified? Can the property be deleted?
});

Accessor Descriptors

const obj = {};
let _name = "Alice";
Object.defineProperty(obj, "name", {
  get() { return _name; },
  set(value) { _name = value; },
  enumerable: true,
  configurable: true
  // No 'value' or 'writable' — accessor descriptors use get/set instead
});

A property is either a data descriptor or an accessor descriptor. Never both. You can't have value and get on the same property.

The Three Flags

writable — Can the Value Change?

const obj = {};
Object.defineProperty(obj, "id", {
  value: 42,
  writable: false, // read-only
  enumerable: true,
  configurable: true
});

obj.id = 100;
console.log(obj.id); // 42 — silent failure in sloppy mode
// In strict mode: TypeError: Cannot assign to read-only property

enumerable — Is the Property Visible?

const obj = { a: 1 };
Object.defineProperty(obj, "hidden", {
  value: 2,
  enumerable: false
});

Object.keys(obj);          // ["a"] — hidden is not listed
JSON.stringify(obj);        // '{"a":1}' — hidden excluded
for (const key in obj) {}   // Only iterates "a"

// But it's still accessible:
obj.hidden;                 // 2
Object.getOwnPropertyNames(obj); // ["a", "hidden"] — shows ALL own properties

This is how built-in methods like Array.prototype.push stay invisible in for...in loops — they're non-enumerable.

configurable — Can the Descriptor Be Modified?

const obj = {};
Object.defineProperty(obj, "locked", {
  value: 42,
  writable: true,
  enumerable: true,
  configurable: false // Can't change descriptor or delete property
});

// This still works (writable is true):
obj.locked = 100;

// But these fail:
delete obj.locked; // false (silently fails) or TypeError (strict)
Object.defineProperty(obj, "locked", { enumerable: false }); // TypeError
Object.defineProperty(obj, "locked", { configurable: true }); // TypeError

// One exception: you CAN change writable from true to false
// (but not back to true once configurable is false)
Object.defineProperty(obj, "locked", { writable: false }); // OK
Object.defineProperty(obj, "locked", { writable: true });  // TypeError

Default Values Matter

When you create properties normally vs with defineProperty, the defaults are different:

// Normal assignment — all flags default to true
const obj = {};
obj.name = "Alice";
Object.getOwnPropertyDescriptor(obj, "name");
// { value: "Alice", writable: true, enumerable: true, configurable: true }

// defineProperty — all flags default to FALSE
Object.defineProperty(obj, "age", { value: 30 });
Object.getOwnPropertyDescriptor(obj, "age");
// { value: 30, writable: false, enumerable: false, configurable: false }

This is a common source of bugs — Object.defineProperty with just { value: x } creates a frozen, hidden, non-deletable property.

Object Immutability Levels

JavaScript gives you three levels of object lockdown, each stricter than the last:

Level 1: Object.preventExtensions(obj)

• Cannot add new properties
• CAN modify existing properties
• CAN delete existing properties

const obj = { a: 1 };
Object.preventExtensions(obj);
obj.b = 2;     // Silently fails (TypeError in strict)
obj.a = 10;    // Works
delete obj.a;  // Works

Level 2: Object.seal(obj)

• Cannot add new properties
• Cannot delete existing properties
• CAN modify values of existing properties
• Sets configurable: false on all existing properties

const obj = { a: 1 };
Object.seal(obj);
obj.a = 10;    // Works (writable is still true)
obj.b = 2;     // Fails
delete obj.a;  // Fails

Level 3: Object.freeze(obj)

• Cannot add new properties
• Cannot delete existing properties
• Cannot modify values of existing properties
• Sets writable: false AND configurable: false on all data properties

const obj = { a: 1 };
Object.freeze(obj);
obj.a = 10;    // Fails
obj.b = 2;     // Fails
delete obj.a;  // Fails

The Shallow Freeze Problem

And here's the gotcha that catches everyone. Object.freeze only freezes the top level. Nested objects are still mutable:

const config = Object.freeze({
  database: {
    host: "localhost",
    port: 5432
  }
});

config.database.host = "hacked.com"; // WORKS — nested object is not frozen
config.database = {};                // Fails — top-level property is frozen

Deep Freeze Implementation

function deepFreeze(obj) {
  Object.freeze(obj);
  for (const key of Object.getOwnPropertyNames(obj)) {
    const value = obj[key];
    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
      deepFreeze(value);
    }
  }
  return obj;
}

Production Scenario: Protecting Configuration

// Without freeze — any module can accidentally mutate shared config
export const config = {
  apiUrl: "https://api.example.com",
  retries: 3,
};
// Somewhere else: config.retries = 0; — silent bug

// With freeze — mutations fail loudly in strict mode
export const config = Object.freeze({
  apiUrl: "https://api.example.com",
  retries: 3,
});
// config.retries = 0; → TypeError in strict mode