Freezing, sealing & immutability

Locking an object

Objects are flexible by default. You can add a property, replace a value, delete a property, or redefine its descriptor flags. That is useful while an object is being built, but it can be risky when the object represents configuration, a public API, or a value other code should not casually reshape.

This lesson is about the built-in object locks. They do not create a new object. They change the object you already have, in bulk, using the property descriptor ideas from Property flags & descriptors: configurable decides whether a property can be deleted or reconfigured, and writable decides whether a data property’s value can be assigned.

Strict mode matters. In strict code, failed writes throw a TypeError. In sloppy classic scripts, many failed writes silently do nothing. You met strict mode earlier; this lesson proves both outcomes in tests and shows strict results in the playground.

Object.preventExtensions(obj) is the lightest lock. It changes one big fact about the object: no new own properties can be added. Existing properties keep the descriptor flags they already had. If room was writable, you can still assign a new value. If it was configurable, you can still delete it.

That makes preventExtensions useful when the shape of an object must stop growing, but the existing fields are still active. It is like closing construction permits while letting people keep using and remodeling the rooms already inside.

1const settings = { theme: "dark", retries: 2, nested: { count: 1 } };2// no lock3settings.retries = 3;4settings.newFlag = true;5delete settings.theme;6settings.nested.count = 2;7Object.defineProperty(settings, "retries", { value: 4 });

Try preventExtensions with each operation. Adding fails. Changing visits works. Deleting room works because ordinary object-literal properties start configurable. Redefining visits works in this example because it is still configurable and writable. The nested write works because the nested object is a separate object.

Object.seal(obj) includes non-extensibility, then sets every own property’s configurable flag to false. Once sealed, properties cannot be deleted and their descriptor shape cannot be changed. Data properties that are still writable can still receive new values.

The building analogy says: no new rooms, and no knocking down walls. But if a room is writable, you can still redecorate it. That is why a sealed settings object can allow settings.retries = 3 while blocking delete settings.retries.

1const ticket = { status: "open", count: 1 };Run2Object.seal(ticket);3const sealed = Object.getOwnPropertyDescriptors(ticket);4 5const badge = { name: "Ada", score: 10 };6Object.freeze(badge);7const frozen = Object.getOwnPropertyDescriptors(badge);

Step through the descriptors. seal changes configurable to false; it does not change writable for data properties. Accessor properties, from the Getters & setters lesson, have no writable flag, so freezing and sealing affect their configurability, not the behavior inside a setter.

Object.freeze(obj) is the strongest built-in lock for an ordinary object. It makes the object non-extensible, makes every own property non-configurable, and for data properties sets writable to false. In strict code, assigning to a frozen data property throws a TypeError.

Freeze is still about properties. If a property contains a reference to another object, the reference cannot be swapped, but the object it points at may still be changed. That shallow behavior is the next section’s big surprise.

Checking lock levels

JavaScript gives you three checks that match the locks:

• Object.isExtensible(obj) asks whether new own properties may be added.
• Object.isSealed(obj) asks whether the object is non-extensible and all own properties are non-configurable.
• Object.isFrozen(obj) asks whether it is sealed and all own data properties are non-writable.

When you need the exact flags, use Object.getOwnPropertyDescriptors(obj). The inspection methods are excellent summaries, but descriptors explain why a write, delete, or definition is allowed.

Object.freeze is shallow. It freezes the main hall, not every building on campus. If team.lead points to another object, the lead property cannot point elsewhere after a freeze, but the lead object itself may still be mutable.

1const team = {Run2  name: "UI",3  lead: { name: "Ada", points: 1 },4};5Object.freeze(team);6team.lead.points = 2;7console.log(team.lead.points);8console.log(Object.isFrozen(team.lead));

A deep freeze walks the object graph and freezes each nested object it reaches. A safe helper needs a WeakSet so cycles do not recurse forever: an object can point back to itself, or two properties can share the same nested object.

1function deepFreeze(value, seen = new WeakSet()) {2  if (value === null || typeof value !== "object") return value;3  if (seen.has(value)) return value;4  seen.add(value);5  for (const key of Reflect.ownKeys(value)) {6    deepFreeze(value[key], seen);7  }8  return Object.freeze(value);9}

Deep freezing is a defensive technique, not the whole story of immutability. Later, the Immutability lesson in Stage 8 focuses on patterns that create updated copies instead of mutating existing objects.

const and Object.freeze solve different problems. const locks a binding: the name cannot be pointed at a different value. It says nothing about what happens inside the object currently attached to that name.

1const profile = { name: "Ada", score: 1 };2profile.score = 2;      // allowed: the object changed3Object.freeze(profile);4profile.score = 3;      // blocked in strict code5// profile = {};        // Syntax/runtime error: const label cannot point elsewhere

Where you use it

These locks are most useful at boundaries. They make accidental mutation loud while code is being developed, and they document that a value should be treated as finished.

• Freeze constant lookup data, such as a table of keyboard shortcuts or allowed roles.
• Seal objects whose shape is part of an API, but whose values still update, such as a long-lived metrics record.
• Prevent extensions when plugin code should not invent new fields on an object you own.
• Deep freeze test fixtures so one test cannot accidentally mutate a fixture used by the next test.

Common misconceptions

These questions mix definitions with real output. Read the explanation for every choice, especially when you guess correctly.

Key takeaways

• Object.preventExtensions blocks adding new own properties only.
• Object.seal also makes own properties non-configurable, so deletion and reconfiguration are blocked.
• Object.freeze also makes data properties non-writable.
• Use Object.isExtensible, Object.isSealed, Object.isFrozen, and descriptors to inspect the exact state.
• Freeze is shallow; a cycle-safe deepFreeze recursively freezes nested objects.
• const locks the binding, not the object’s inside.

Up next: Enumerability & ownership, where you learn which properties loops and object methods can see.