Using Object.freeze() to Prevent Accidental Mutation in JavaScript

Why I Reach for Object.freeze() More Than You’d Think

Early in my career, I spent way too many debugging sessions chasing down bugs caused by objects being mutated in unexpected places. A config object tweaked in a utility function. A state object altered by a third-party library. It felt like playing whack-a-mole with data integrity. Then I discovered Object.freeze(), and it changed how I think about data safety in JavaScript.

This isn’t about making your code “functional” for the sake of ideology. It’s about reducing cognitive load and preventing subtle, hard-to-reproduce bugs. When you freeze an object, you’re making a contract: this data should not change from this point forward. If something tries to mutate it, you’ll know immediately — either through a silent failure in non-strict mode or an explicit error in strict mode.

A Real-World Scenario: Configuration Objects

Imagine you’re building a feature that relies on a set of feature flags or API endpoints pulled from an environment file. These values are set at startup and should remain constant throughout the app’s lifecycle. But because JavaScript objects are mutable by default, it’s all too easy for a helper function to accidentally overwrite a value:

// config.js
const config = {
  apiUrl: 'https://api.example.com/v1',
  timeout: 5000,
  features: {
    newDashboard: true,
    legacyExport: false
  }
};

// Somewhere in a utility file, months later...
function updateConfig(key, value) {
  // Oops — meant to update a copy, but got the reference
  config[key] = value;
}

updateConfig('timeout', 0); // Now every request times out immediately

// Later, in a completely unrelated module...
console.log(config.timeout); // 0 — why is this zero?! ????

This kind of bug is insidious because it doesn’t throw an error. The app keeps running, but behavior drifts silently. Freezing the config object prevents this entire class of mistake.

How to Use Object.freeze() Safely

The API is simple: pass an object to Object.freeze(), and it returns the same object, now frozen. Any attempt to change its properties will fail (in strict mode) or be ignored (in non-strict mode).

// config.js
const config = Object.freeze({
  apiUrl: 'https://api.example.com/v1',
  timeout: 5000,
  features: Object.freeze({
    newDashboard: true,
    legacyExport: false
  })
});

// Now, any mutation attempt will fail:
try {
  config.timeout = 10000; // TypeError in strict mode
} catch (e) {
  console.error('Cannot assign to read-only property \'timeout\'');
}

// Nested objects need to be frozen too!
// (More on this below)

Pro tip: Always enable strict mode ('use strict') when using Object.freeze(). Otherwise, failed mutations are silently ignored, which defeats the purpose.

The Deep Freeze Gotcha (and How to Solve It)

Here’s the thing about Object.freeze(): it’s shallow. It only freezes the immediate properties of the object. If a property is itself an object (like our features above), that inner object can still be mutated unless you freeze it too.

In the example above, I froze the features object inline. But if you have a large, nested config, doing this manually is tedious and error-prone. That’s where a deep freeze utility comes in handy:

function deepFreeze(obj) {
  // Freeze the current object
  Object.freeze(obj);

  // Recursively freeze all enumerable properties that are objects
  Object.keys(obj).forEach(key => {
    const value = obj[key];
    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
      deepFreeze(value);
    }
  });

  return obj;
}

// Usage
const config = deepFreeze({
  apiUrl: 'https://api.example.com/v1',
  timeout: 5000,
  features: {
    newDashboard: true,
    legacyExport: false
  }
});

// Now even nested mutations are blocked
try {
  config.features.newDashboard = false; // TypeError
} catch (e) {
  console.error('Cannot assign to read-only property \'newDashboard\' of object \'#