Object Freeze in JavaScript: Shallow vs Deep, Seal and const
Object freeze in JavaScript makes an object read-only: no new properties, no changes, no deletions. But it is shallow, it fails silently in some code and loudly in other code, and it does nothing to a Map or a Date. We tested Object.freeze, Object.seal, preventExtensions and const side by side in Node.js 24, built a deep freeze, and measured the cost.
- Object freeze (
Object.freeze(obj)) blocks adding, changing and deleting properties, but only one level deep. - In an ES module, writing to a frozen object threw a TypeError; in a plain CommonJS script, the same write was ignored silently.
- A frozen object’s nested object and array were still changeable until we wrote a recursive deep freeze.
- Freezing a
Mapor aDatedid not stopmap.set()ordate.setFullYear().
Shared configuration, constants, application state and default options are all objects that should not change after they are created. JavaScript objects are mutable by default, and a single accidental assignment somewhere in a large codebase can change behaviour everywhere. Object freeze lets you lock an object so such mistakes are caught or prevented, but it has rules that surprise even experienced developers.
All examples ran in Node.js v24.22.1. Browsers behave the same; the strict-mode differences apply everywhere.
const is not freeze
const c = { a: 1 };
c.a = 2; // allowed: c.a is now 2
c = {}; // TypeError: Assignment to constant variable.
const protects the variable: it can never point to a different object. It does nothing to the object itself, so its properties can still change. Freezing protects the object. The two are complementary, and constants that should be truly fixed usually need both.
What Object.freeze does
const f = Object.freeze({ a: 1, nested: { b: 1 }, list: [1, 2] });
Object.isFrozen(f) // true
Object.getOwnPropertyDescriptor(f, "a")
// { value: 1, writable: false, enumerable: true, configurable: false }
Freezing makes the object non-extensible (no new properties) and marks every existing property as non-writable and non-configurable (no changes, no deletions, no redefinition). It returns the same object, so const CONFIG = Object.freeze({...}) is a common one-liner. The change cannot be undone; there is no “unfreeze”.
Silent or loud: strict mode decides
// CommonJS script (non-strict)
f.a = 99; f.z = 1; delete f.a;
f.a, f.z, "a" in f // 1 undefined true (all ignored, no error)
// strict mode, and every ES module
f.a = 99 // TypeError: Cannot assign to read only property 'a' of object '#<Object>'
f.z = 1 // TypeError: Cannot add property z, object is not extensible
delete f.a // TypeError: Cannot delete property 'a' of #<Object>
This was the most important result in our tests. In non-strict code, writes to a frozen object simply did nothing, which can hide bugs for a long time: the program keeps running with an old value. In strict mode they throw, pointing straight at the faulty line. Our first test file was an ES module (.mjs), and it crashed on the very first write, because modules and class bodies are always strict. Use modules or "use strict" so frozen objects fail loudly.
Object.freeze is shallow
f.nested.b = 2;
f.list.push(3);
f.nested.b, f.list // 2 [ 1, 2, 3 ]
Object.isFrozen(f.nested) // false
Freezing only affects the object’s own properties. The nested property cannot be pointed at a different object, but the nested object itself is still fully mutable, and so is the array. This catches people out with configuration objects, which are almost always nested.
Object.seal and Object.preventExtensions
const s = Object.seal({ a: 1 });
s.a = 2; s.z = 3; delete s.a;
s.a, s.z, Object.isSealed(s) // 2 undefined true
const p = Object.preventExtensions({ a: 1 });
p.a = 2; p.z = 3; delete p.a;
p.a, p.z // undefined undefined
There are three levels of protection. preventExtensions only blocks new properties: our object allowed the change to a and then the deletion. seal also blocks deletion and reconfiguration but still allows existing values to change, which suits objects with a fixed shape whose values update. freeze blocks everything.
Comparison table
| Operation | const | preventExtensions | seal | freeze |
|---|---|---|---|---|
| Reassign the variable | No | Yes | Yes | Yes |
| Add properties | Yes | No | No | No |
| Delete properties | Yes | Yes | No | No |
| Change values | Yes | Yes | Yes | No |
| Nested objects protected | No | No | No | No |
Deep freeze
function deepFreeze(o) {
for (const k of Reflect.ownKeys(o)) {
const v = o[k];
if (v && typeof v === "object" && !Object.isFrozen(v)) deepFreeze(v);
}
return Object.freeze(o);
}
const d = deepFreeze({ nested: { b: 1, deeper: { c: [1] } } });
d.nested.deeper.c.push(2) // TypeError: Cannot add property 1, object is not extensible
Object.isFrozen(d.nested.deeper.c) // true
A recursive helper freezes every nested object and array. Reflect.ownKeys includes symbol keys, and the isFrozen check stops infinite loops on circular references and avoids refreezing shared objects. Add functions to the check if your objects contain functions with properties. Be careful freezing objects you do not own, such as library instances: freezing them can break the library.
Frozen arrays
const arr = Object.freeze([3, 1, 2]);
arr.sort() // TypeError: Cannot assign to read only property '0' of object '[object Array]'
arr.toSorted() // [ 1, 2, 3 ] (new array)
arr.map(x => x * 2) // [ 6, 2, 4 ]
Mutating methods such as sort, push, splice and reverse throw on a frozen array. Non-mutating methods work, and since ES2023 there are copying versions of the mutating ones: toSorted, toReversed, toSpliced and with. Frozen arrays pair naturally with these; see our array methods guide.
Map, Set and Date ignore freeze
const m = Object.freeze(new Map([["k", 1]]));
m.set("k", 2); m.get("k") // 2
const dt = Object.freeze(new Date(0));
dt.setFullYear(2030); dt.getUTCFullYear() // 2030
Map, Set and Date keep their data in internal slots, not in properties, so freezing the object does not stop their methods from changing it. If you need read-only collections, wrap them in an object that exposes only read methods, or use plain frozen objects and arrays. The differences between maps and objects are covered in our Map vs object guide.
Classes, private fields and getters
class P { #x = 1; inc() { return ++this.#x; } }
const fp = Object.freeze(new P());
fp.inc() // 2 (private fields are not properties)
Object.freeze({ _v: 1, get v() { return this._v; } }).v // 1
Freezing a class instance did not stop its #private field from changing, because private fields are not ordinary properties. Getters still run normally. A common pattern for immutable value objects is to set fields in the constructor and call Object.freeze(this) at the end; our JavaScript classes guide covers private fields in more depth.
Copies are not frozen
const sc = structuredClone(f); sc.a = 5; // 5, Object.isFrozen(sc) is false
const spread = { ...f, a: 7 }; // 7, Object.isFrozen(spread) is false
Copying a frozen object with spread syntax or structuredClone produces a normal, mutable object. That is useful for the “update by copying” style used with immutable state: freeze the current state, create a modified copy, freeze that. More on copying in our deep copy guide. If you want writes blocked with custom logic instead, a Proxy can intercept them, but note that proxies must respect a frozen target’s rules.
Performance
20 million property reads (after warm-up): frozen 13.9 to 17.6 ms, plain 13.8 to 16.6 ms
100,000 objects: Object.freeze 12 ms, deepFreeze 53 ms
Reading from frozen objects was as fast as from plain ones across three rounds. Our first, single-round measurement suggested frozen reads were slower, but that was JIT warm-up order, not freezing; repeated rounds removed the difference. Freezing itself is cheap, about 0.1 microseconds per small object, and deep freezing costs more in proportion to the number of nested objects. For large state trees updated many times per second, consider freezing only in development builds.
When to use Object.freeze
- Constants and configuration that must never change at runtime: deep freeze them once at start-up.
- Enum-like objects:
const Color = Object.freeze({ RED: "red", GREEN: "green" }). - Default options passed to many functions, so one caller cannot change them for everyone.
- Immutable state in reducers, to catch accidental mutation early (in strict mode).
- Not for security: freezing prevents mistakes; it does not protect secrets from code running on the page.
Final thoughts
Object freeze is the strongest built-in way to make a JavaScript object read-only, but our tests showed its limits clearly: it is shallow, it fails silently outside strict mode, and Map, Set, Date and private fields ignore it. Combine const with a deep freeze for configuration, run in modules or strict mode so violations throw, use seal when values should change but shape should not, and remember that copies start out mutable.
Frequently asked questions
What does Object.freeze do in JavaScript?
It prevents adding, changing and deleting the properties of an object. The object becomes read-only at the top level, and Object.isFrozen returns true.
What is the difference between const and Object.freeze?
const stops the variable from being reassigned to a different value. Object.freeze stops the object itself from being changed. A const object can still be modified unless it is also frozen.
Does Object.freeze freeze nested objects?
No. It is shallow. Nested objects and arrays stay mutable unless you freeze them too, usually with a recursive deep freeze function.
What is the difference between Object.seal and Object.freeze?
Both block adding and deleting properties. Seal still allows existing values to change, while freeze makes them read-only as well.
Why does changing a frozen object not throw an error?
Outside strict mode, writes to frozen objects fail silently. In strict mode and in ES modules, the same write throws a TypeError.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.