Freezing, sealing & immutability

Locking an object

Normally, you can change an object in many ways:

• Add a new property.
• Change the value of a property.
• Delete a property.
• Change a property's flags with Object.defineProperty.

That freedom is useful while you build an object. But some objects should stay as they are once they are ready. Think of the settings of an app, or a list of user roles that a lot of code reads. If some code changes them by mistake, the bug shows up far away from the line that caused it.

JavaScript has three built-in locks for objects: Object.preventExtensions, Object.seal, and Object.freeze. Each one changes the object you give it. None of them makes a copy.

The locks work through the property flags from the last lesson, Property flags & descriptors. Every property has hidden settings called flags. Two of them matter here:

• writable: can the property's value be changed?
• configurable: can the property be deleted, or its flags be changed?

What happens when code tries something that a lock blocks? That depends on strict mode. Strict mode is a set of stricter rules. You turn it on by writing "use strict", and it is always on in modules and classes.

• In strict code, a blocked change throws a TypeError. A TypeError is the error JavaScript throws when you try something a value doesn't allow.
• In code that is not strict, many blocked changes just do nothing. There is no error, so the mistake is easy to miss.

const cart = { items: 1 };
Object.preventExtensions(cart);

cart.newItem = "tea";
console.log(Object.hasOwn(cart, "newItem"));

function strictAdd() {
  "use strict";
  try {
    cart.otherItem = "coffee";
  } catch (error) {
    console.log(error.name);
  }
}

strictAdd();

Line 2 locks cart, so it can't get new properties. Line 4 tries to add newItem anyway. This line is not in strict mode, so nothing happens and there is no error.

Line 5 asks whether cart now has its own newItem property. Object.hasOwn answers that question, and it prints false.

The function strictAdd turns on strict mode on line 8. So the add on line 10 throws a TypeError. The catch on line 11 catches it, and line 12 prints its name, TypeError.

That is why strict mode helps when you test locked objects. A blocked change shows up as an error instead of hiding.

Object.preventExtensions(obj) is the weakest lock. It does one thing: it stops new own properties from being added. An own property is one stored on the object itself. An object that can't get new properties is called non-extensible.

Properties that already exist keep their flags. So:

• If a property is writable, you can still change its value.
• If a property is configurable, you can still delete it.

Use preventExtensions when an object should stop growing, but its current properties should still work as before.

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

Pick preventExtensions and try each action. Here is what happens:

• add property is blocked. This is the one thing the lock stops.
• change value works: retries becomes 3.
• delete property works. Properties written inside { } start out configurable, so theme can be deleted.
• change nested value works. settings.nested holds a separate object, and the lock only covers settings itself.
• redefine value works. It changes retries with Object.defineProperty, and retries is still configurable and writable.

Object.seal(obj) does everything preventExtensions does. Then it sets the configurable flag of every own property to false. After that:

• You can't add new properties.
• You can't delete properties.
• You can't change a property's flags.
• You can still change a value, if the property is writable.

So a sealed settings object still allows settings.retries = 3. But it blocks delete settings.theme.

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 code. It uses Object.getOwnPropertyDescriptors(obj), which returns the flags of every own property. Watch two flags:

• seal changes configurable to false.
• seal leaves writable as it was.

One more detail. An accessor property is a property that runs a getter or a setter function, from the Getters & setters lesson. It has no writable flag. So seal and freeze only stop it from being deleted or redefined. They don't change what its getter or setter does.

Object.freeze(obj) is the strongest built-in lock. It does three things:

• It stops new properties, like preventExtensions.
• It sets configurable to false on every own property, like seal.
• It sets writable to false on every data property. A data property is one that holds a value, not a getter or setter.

So no value on the object can change. In strict code, assigning to a frozen property throws a TypeError.

freeze only covers the object's own properties. A property can hold another object. Then the property can't be pointed at a different object, but that other object can still change. You'll see this in the "Deep freeze" section below.

Checking lock levels

JavaScript has three methods that tell you how locked an object is. Each one returns true or false:

• Object.isExtensible(obj): can new properties be added?
• Object.isSealed(obj): is the object non-extensible, and are all its own properties non-configurable?
• Object.isFrozen(obj): is the object sealed, and are all its own data properties non-writable too?

const cart = { items: 1 };
console.log(Object.isExtensible(cart), Object.isSealed(cart), Object.isFrozen(cart));
Object.seal(cart);
console.log(Object.isExtensible(cart), Object.isSealed(cart), Object.isFrozen(cart));
Object.freeze(cart);
console.log(Object.isExtensible(cart), Object.isSealed(cart), Object.isFrozen(cart));

• Line 2 checks a plain object. It prints true false false.
• Line 3 seals the object. Line 4 prints false true false.
• Line 5 freezes the object. Line 6 prints false true true.

Each method answers a different question. If you only check isFrozen, you miss the middle state: sealed, but values can still change.

The table below shows what the three checks return after each lock. Read each row as: "after this lock, the checks say this, and existing values can or can't change."

To see the exact flags of each property, use Object.getOwnPropertyDescriptors(obj). The three checks give a quick summary. The flags explain why a change, a delete, or a redefine is allowed or blocked.

Object.freeze is shallow. Shallow means it locks only the object you give it, not the objects stored inside it.

In the code below, team.lead holds a second object. After Object.freeze(team), the lead property can't point to a different object. But the lead object itself is not frozen, so its points can still change.

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 freezes the object, then every object inside it, then every object inside those, and so on. The helper below does this. It calls itself for each property value. A function that calls itself is called recursive.

The helper uses two tools you may not have seen yet:

• Reflect.ownKeys(value) lists every own property name of an object, including symbol keys.
• A WeakSet is a set that holds objects. The helper adds each object to it, so it can tell which objects it has already visited.

Why remember visited objects? An object can point back to itself, like config.self = config. This is called a cycle. Two properties can also share the same nested object. Without the WeakSet, a cycle would make the helper call itself forever.

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}

A deep freeze protects objects from change. It is not the only way to avoid unwanted changes. Later, the Immutability lesson shows another way: make an updated copy instead of changing the original object.

const and Object.freeze lock different things. const locks the variable: once the name points to a value, it can't be pointed at a different value. It doesn't lock anything inside that value.

The table compares the two. Read each row as a question, then the answer for const and for Object.freeze.

1const profile = { name: "Ada", score: 1 };2profile.score = 2;      // allowed: the object changed3Object.freeze(profile);4profile.score = 3;      // blocked in strict code5// profile = {};        // TypeError: a const variable can't get a new value

Where you use it

Locks are most useful where your code hands an object to other code. They turn an accidental change into an error you can see while you build. They also tell other developers that the value is finished and should not change.

• Freeze fixed lookup data, such as a table of keyboard shortcuts or a list of allowed roles.
• Seal an object whose list of properties must stay the same, but whose values still update. One example is an object that counts page visits.
• Use preventExtensions when plugin code should not add new properties to an object you own. Plugin code is code that other people write to add features to your app.
• Deep freeze test fixtures. A test fixture is sample data that several tests share. Freezing it means one test can't change the data that the next test uses.

const appConfig = Object.freeze({ apiUrl: "/api", retries: 2 });
const roles = Object.freeze(["reader", "editor"]);
console.log(Object.isFrozen(appConfig), appConfig.retries);
try {
  roles.push("admin");
} catch (error) {
  console.log(error.name);
}

• Line 1 freezes appConfig. Line 2 freezes the roles array.
• Line 3 prints true 2. The object is frozen, but you can still read its values.
• Line 5 tries roles.push("admin"). push needs to add a new index and change length, so it throws. Line 7 prints TypeError.

Freeze values like these only when they really are fixed. Don't freeze them when other code needs to update them.

Freezing stops changes, but it doesn't give you a way to make an updated version of an object. The Immutability lesson, linked above, shows how to do that with copies.

Common misconceptions

These questions mix ideas with real code. Read the explanation for every choice, even when you get it right.

Key takeaways

• Object.preventExtensions only stops new properties from being added.
• Object.seal also stops properties from being deleted or having their flags changed. Values can still change.
• Object.freeze also stops the values of data properties from changing.
• Object.isExtensible, Object.isSealed, and Object.isFrozen tell you how locked an object is. Object.getOwnPropertyDescriptors shows the exact flags.
• Freeze is shallow. A deepFreeze helper with a WeakSet freezes the nested objects too, even when an object points back to itself.
• const locks the variable, not what is inside the object.

Up next: Enumerability & ownership. You'll learn which properties loops and object methods can see.