Skip to content
JavaScript: Freeze the nested objects in a small configuration

JavaScript: Freeze the nested objects in a small configuration

November 17, 2026

Freezing a settings object does not freeze the objects stored inside it. For a small configuration with a known shape, freeze the nested objects explicitly before freezing the outer one.

Set up

Tested on Debian 13 Linux with Node.js v24.19.0. Use Bash, Node.js on your PATH, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal through cleanup. Stop if setup fails before saving the source.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as javascript-freeze-nested-config.mjs:

import assert from 'node:assert/strict';

const shallow = Object.freeze({ retry: { attempts: 3 } });
shallow.retry.attempts = 9;
console.log('Shallow freeze allows nested update:', shallow.retry.attempts);

const settings = Object.freeze({
  retry: Object.freeze({ attempts: 3, delayMs: 100 }),
  formats: Object.freeze(['json', 'text']),
});

assert.throws(() => { settings.retry.attempts = 9; }, TypeError);
assert.throws(() => { settings.retry = { attempts: 9 }; }, TypeError);
assert.throws(() => { settings.formats.push('xml'); }, TypeError);
assert.throws(() => { settings.extra = true; }, TypeError);
assert.equal(settings.retry.attempts, 3);
assert.deepEqual(settings.formats, ['json', 'text']);
assert.ok(Object.isFrozen(settings));
assert.ok(Object.isFrozen(settings.retry));
assert.ok(Object.isFrozen(settings.formats));
console.log('Frozen attempts:', settings.retry.attempts);
console.log('Frozen formats:', settings.formats.join(', '));

Run:

node javascript-freeze-nested-config.mjs

Observed output:

Shallow freeze allows nested update: 9
Frozen attempts: 3
Frozen formats: json, text

Freeze each owned layer

const prevents reassignment of the variable binding. Object.freeze prevents adding or removing own properties and makes own data properties non-writable. Neither operation recursively freezes referenced objects.

Here the nested retry object and formats array are created specifically for this configuration. Freezing them does not unexpectedly freeze an object owned by a caller. The .mjs file runs as an ES module in strict mode, so the attempted assignments throw. In non-strict code some failed assignments can be silent; do not use exceptions as the only way to discover mutability.

Keep the shape explicit

The ECMAScript Object.freeze algorithm acts on the supplied object. Object.isFrozen(settings) checks that outer object only; the assertions inspect each nested object separately.

This configuration contains primitive values and an array of strings, so those three freezes cover its current mutable containers. Adding another nested object requires freezing that object too. Freezing a Map or Set object does not disable its collection-mutating methods, and accessor properties can still call code. A general recursive freezer needs a policy for cycles, shared ownership and built-in object types. For a short configuration whose fields you control, the explicit construction makes its limits easier to inspect.

Clean up

Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.

rm -- javascript-freeze-nested-config.mjs
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on