#object.freeze

Immutability in JavaScript is an interesting problem. It is easy to make variables unchangeable via const, but if those variables are objects, the object elements can be modified. There are various utilities to help make an object immutable, like Object.freeze, but they have issues too. Object.freeze only applies to the top level properties and does not affect array indices. So the only way is to combine the methods by looping through objects:

function makeImmutable(value) { // The extra instance of handles cases like new Number() if (typeof value === 'object' && !(value instanceof Number) && !(value instanceof String)) { for (let key in value) { value[key] = makeImmutable(value[key]) } return Object.freeze(value); } else { return value; } }; function printError(callback) { // Not a good practice unless you are debugging or showing an example try { callback(); } catch(e) { console.info(e); } } const obj = { property1: 'value1', array1: [ new String('element1'), 'element2', { property2: { property3: [1, 2] } } ] }; const objImmutable = makeImmutable(obj); // Each of the below will through an error in most environments (Some // environments will just not modify the value) printError(() => objImmutable.property1 = 'EDITED'); printError(() => objImmutable.property1[0] = 'EDITED'); printError(() => objImmutable.array1[0] = 'EDITED'); printError(() => objImmutable.array1[2].property2 = 'EDITED'); printError(() => objImmutable.array1[2].property2.property3 = 'EDITED'); printError(() => objImmutable.array1[2].property2.property3[1] = 'EDITED'); printError(() => objImmutable.array1[2].property2.property3[30] = 'EDITED'); // Stringify gaurantees the full depth of the object will be printed console.log(JSON.stringify(objImmutable, null, 2));

In other words start from the lowest level of an object, progressively building immutability. Note that I used arrow functions here to reduce the syntax and show the code flow bwtter. For environments that don't support arrow functions, like IE 11, just replace them with normal functions.

Immutability is useful to reduce errors by reducing the number of ways a system can change. Additionally, the above code can be used to detect when foreign code that you do not know about is modifying any object. With the above a stack trace will tell you exactly where. Finally, although the above covers any case, it is slow for large objects. So it is better to use a library like immutable.js.

In my last post I talked about making entire objects extensible instead of just a variable using Object.freeze. This is actually the most strict way of making object immutable. There are 2 other ways: Object.seal and Object.preventExtensions. Essentially, Object.freeze is a superset of Object.seal which is a superset of Object.preventExtensions. It is best to demonstrate this in an example.

var attempt = function(callback) { try { callback(); } catch (e) {} }; var obj = Object.preventExtensions({ property1: 'value1', property2: 'value2', property3: 'value3' }); obj.property1 = 'value1 EDITED'; attempt(function() { obj.property3 = 'value3' });// can't extend delete obj.property3; Object.defineProperty(obj, 'property2', { get: function() { return 'test' } }); console.log(obj); // { property1: 'value1 EDITED', property2: [Getter] } var obj2 = Object.seal({ property1: 'value1', property2: 'value2', property3: 'value3' }); obj2.property1 = 'value1 EDITED'; attempt(function() { obj2.property3 = 'value3' });// can't extend attempt(function() { delete obj2.property3 });// can't delete attempt(function() { Object.defineProperty(obj2, 'property2', { get: function() { return 'test' } }); });// can't changing property definitions console.log(obj2); // { property1: 'value1 EDITED', // property2: 'value2', // property3: 'value3' } var obj3 = Object.freeze({ property1: 'value1', property2: 'value2', property3: 'value3' }); attempt(function() { obj3.property1 = 'value1 EDITED' }); attempt(function() { obj3.property3 = 'value3' });// can't extend attempt(function() { delete obj3.property3 });// can't delete attempt(function() { Object.defineProperty(obj3, 'property2', { get: function() { return 'test' } }); });// can't changing property definitions console.log(obj3); // { property1: 'value1', property2: 'value2', property3: 'value3' }

So the only difference difference between Object.seal and Object.freeze is that seal does allow properties to be changed. Note that the attempt was used to clarify the example code and in general errors should not be hidden like that. Finally, here is a table giving a clear explanation.

Node.js already supports const and most browsers eventaully will, but that only creates immutable variables not objects. For example:

const obj = { property1: 'value1' }; // some implementations will error out, some will just not assign to it. try { obj = { property2: 'value2' }; } catch (e) { console.log(obj); } console.log(obj); // { property1: 'value1' } obj.property1 = 'value2'; console.log(obj); // { property1: 'value2' }

This is where Object.freeze comes in, it prevents the entire object from being modified:

const obj = Object.freeze({ property1: 'value1' }); // some implementations will error out, some will just not assign to it. try { obj.property1 = 'value2'; } catch (e) {} console.log(obj); // { property1: 'value1' }

This is useful for the same reason that const is useful, it makes code more predictable by ensuring that an object's properties and values can always be relied on once defined. Though it does have a weakness with arrays:

const arr = Object.freeze([{ property1: 'value1' }, { property2: 'value2' }]); // some implementations will error out, some will just not assign to it. try { arr[0] = { property2: 'value2' }; } catch (e) {} arr[0].property1 = 'value2'; console.log(arr);

So it is important to remember to use Object.freeze on each array element:

const arr2 = [{ property1: 'value1' }, { property2: 'value2' }].map(Object.freeze); // some implementations will error out, some will just not assign to it. try { arr2[0].property1 = 'value2'; } catch (e) {} console.log(arr2); // [ { property1: 'value1' }, { property2: 'value2' } ]

Although, this does not seem like something that has good support, it actually works in all modern browsers. Though since Object.freeze is most useful with const and const is still not supported in some environments, you will need another way of generating constants. Finally, frozen objects run just as fast as regular objects. Frozen objects only ran slower in the past due to browser bugs. For example: https://bugs.chromium.org/p/chromium/issues/detail?id=115960.