What Does Object.freeze Guarantee?

Freezing an object makes its own properties non-writable and non-configurable. That means you cannot add a new property, you cannot delete an existing one, and you cannot change the value or the attributes of an existing one. The freeze is enforced by the engine, so attempts to break it fail.

const settings = Object.freeze({ theme: "dark", nested: { font: "serif" } });

console.log(Object.isFrozen(settings));   // true
console.log(Object.isSealed(settings));    // true

try {
  settings.theme = "light";
} catch (err) {
  console.log(err.name);   // "TypeError" in strict mode
}
console.log(settings.theme);   // "dark"

// The freeze is shallow.
settings.nested.font = "sans";
console.log(settings.nested.font);   // "sans" - the inner object is not frozen

There is a difference between strict and sloppy mode here that is worth mentioning. In strict mode, which includes every ES module and every class body, a failed assignment throws a TypeError, so you find out immediately. In sloppy mode the assignment fails silently and the object is unchanged, which is worse because the code carries on as though it worked.

Freezing also makes the object non-extensible and marks its properties as non-configurable. The isFrozen and isSealed checks report on that state, and the seal method does the weaker version, preventing additions and deletions but still allowing existing values to change.

Two things freeze does not do. It does not make the object deeply immutable, because it only touches the top level, and it does not affect the internal state of exotic objects. A frozen date still changes with setTime, and a frozen array still rejects new elements because the length property is frozen, but other built-ins keep their own behaviour.

No. Freeze is shallow by design, and that is deliberate. It marks the own properties of the object you pass in, and it does not walk into nested objects or arrays. A frozen object with a nested object still lets you change that nested object freely, which is the single most common misunderstanding about the feature.

If you need a genuinely deep freeze, you have to write it yourself, because the language does not provide one. The pattern is recursive: freeze the object, then walk its own enumerable properties and freeze each one that is an object. You also need to guard against circular references, which a naive recursive freeze will loop through forever.

Before reaching for that, ask whether you need it. Deep freezing is expensive, it makes legitimate code awkward, and it is easy to freeze something by accident and then break a library that expects to attach a cache to it. In most application code, the better tool is not immutability by freezing but immutability by convention: build new objects when you change something and never mutate what you were given.

Where freezing genuinely earns its place is in configuration objects and in shared constants, where you want to catch accidental mutation early. In development it turns a silent bug into a loud error. In production, freezing a shared constant can also protect you from one part of the code changing a value another part relies on.