JavaScript Object.freeze Is Shallow: Stop Nested Mutation

Check the object that actually changes#

The ECMAScript Object.freeze algorithm applies the frozen integrity level to the supplied object. It does not recursively call itself on property values. MDN’s freeze reference describes this shallow boundary.

This explains an apparently contradictory pair of observations: Object.isFrozen(settings) returns true, yet settings.retry.attempts++ succeeds. Check Object.isFrozen(settings.retry) too. The first check says nothing about the second object.

Run the following as freeze-check.mjs with node freeze-check.mjs. The assertions and output were verified with Node.js 24.13.0 on macOS on November 2, 2026. ES modules use strict mode, so rejected assignments throw rather than failing silently.

1
import assert from 'node:assert/strict';
2
const child = { count: 0 };
3
const outer = Object.freeze({ child });
4
assert.equal(Object.isFrozen(outer), true);
5
assert.equal(Object.isFrozen(child), false);
6
assert.throws(() => { outer.child = {}; }, TypeError);
7
child.count++;
8
assert.equal(outer.child.count, 1);
9
Object.freeze(child);
10
assert.throws(() => { child.count++; }, TypeError);
11
const items = Object.freeze([{ count: 0 }]);
12
assert.throws(() => items.push({ count: 2 }), TypeError);
13
items[0].count++;
14
assert.equal(items[0].count, 1);
15
const independent = Object.freeze({ child: Object.freeze({ ...child }) });
16
assert.notEqual(independent.child, child);
17
assert.throws(() => { independent.child.count++; }, TypeError);
18
console.log('outer=true child-before=false shared-count=1 array-item-count=1 copied-child=true');

Expected output:

1
outer=true child-before=false shared-count=1 array-item-count=1 copied-child=true

The fixture separates four operations: replacing an outer property, changing a child field, adding an array entry, and changing a field inside an existing entry. A frozen array rejects the new entry while its unfrozen element still accepts a field change.

Choose which objects your code owns#

The independent record in the fixture is a copy of the child’s current value: its count is already 1. Copying does not recover an earlier snapshot. Construct the protected copy before handing mutable state to code that may change it.

For ordinary records with known primitive fields, an explicit copy keeps the ownership decision visible. If a child itself contains another object, spreading that child still shares the deeper reference. The same identity issue appears in nested object spread; reconstruct every level that needs independence.

Avoid introducing a generic recursive freezer solely to fix one known shape. This example does not validate arbitrary object graphs, cycles, getters, proxies, class instances, or collection internals. A recursive implementation needs an explicit policy for those inputs. Freezing also does not clone data or make an existing shared object private.

For this fixture’s plain records, inspect the exact mutation target, decide whether shared aliases should be affected, and freeze the owned objects at each required level. Keep the identity and rejected-write assertions beside the code that constructs the settings so a later nested field does not silently expand the mutable boundary.

References:

• ECMAScript: Object.freeze
• MDN: Object.freeze