Protecting objects from being changed • Deep JavaScript

10 Protecting objects from being changed

10.1 Levels of protection: preventing extensions, sealing, freezing
10.2 Preventing extensions of objects
- 10.2.1 Checking whether an object is extensible
10.3 Sealing objects
- 10.3.1 Checking whether an object is sealed
10.4 Freezing objects
- 10.4.1 Checking whether an object is frozen
- 10.4.2 Freezing is shallow
- 10.4.3 Implementing deep freezing
10.5 Further reading

In this chapter, we’ll look at how objects can be protected from being changed. Examples include: Preventing properties being added and preventing properties being changed.

Required knowledge: property attributes

For this chapter, you should be familiar with property attributes. If you aren’t, check out §9 “Property attributes: an introduction”.

10.1 Levels of protection: preventing extensions, sealing, freezing

JavaScript has three levels of protecting objects:

Preventing extensions makes it impossible to add new properties to an object. We can still delete and change properties, though.
- Method: Object.preventExtensions(obj)
Sealing prevents extensions and makes all properties unconfigurable (roughly: we can’t change how a property works anymore).
- Method: Object.seal(obj)
Freezing seals an object after making all of its properties non-writable. That is, the object is not extensible, all properties are read-only and there is no way to change that.
- Method: Object.freeze(obj)

10.2 Preventing extensions of objects

Object.preventExtensions<T>(obj: T): T

This method works as follows:

If obj is not an object, it returns it.
Otherwise, it changes obj so that we can’t add properties anymore and returns it.
The type parameter <T> expresses that the result has the same type as the parameter.

Let’s use Object.preventExtensions() in an example:

const obj = { first: 'Jane' };
Object.preventExtensions(obj);
assert.throws(
  () => obj.last = 'Doe',
  /^TypeError: Cannot add property last, object is not extensible$/);

We can still delete properties, though:

assert.deepEquals(
  Object.keys(obj), ['first']);
delete obj.first;
assert.deepEquals(
  Object.keys(obj), []);

10.2.1 Checking whether an object is extensible

Object.isExtensible(obj: any): boolean

Checks whether obj is extensible – for example:

> const obj = {};
> Object.isExtensible(obj)
true
> Object.preventExtensions(obj)
{}
> Object.isExtensible(obj)
false

10.3 Sealing objects

Object.seal<T>(obj: T): T

Description of this method:

If obj isn’t an object, it returns it.
Otherwise, it prevents extensions of obj, makes all of its properties unconfigurable, and returns it. The properties being unconfigurable means that they can’t be changed, anymore (except for their values): Read-only properties stay read-only, enumerable properties stay enumerable, etc.

The following example demonstrates that sealing makes the object non-extensible and its properties unconfigurable.

const obj = {
  first: 'Jane',
  last: 'Doe',
};

// Before sealing
assert.equal(Object.isExtensible(obj), true);
assert.deepEqual(
  Object.getOwnPropertyDescriptors(obj),
  {
    first: {
      value: 'Jane',
      writable: true,
      enumerable: true,
      configurable: true
    },
    last: {
      value: 'Doe',
      writable: true,
      enumerable: true,
      configurable: true
    }
  });

Object.seal(obj);

// After sealing
assert.equal(Object.isExtensible(obj), false);
assert.deepEqual(
  Object.getOwnPropertyDescriptors(obj),
  {
    first: {
      value: 'Jane',
      writable: true,
      enumerable: true,
      configurable: false
    },
    last: {
      value: 'Doe',
      writable: true,
      enumerable: true,
      configurable: false
    }
  });

We can still change the the value of property .first:

obj.first = 'John';
assert.deepEqual(
  obj, {first: 'John', last: 'Doe'});

But we can’t change its attributes:

assert.throws(
  () => Object.defineProperty(obj, 'first', { enumerable: false }),
  /^TypeError: Cannot redefine property: first$/);

10.3.1 Checking whether an object is sealed

Object.isSealed(obj: any): boolean

Checks whether obj is sealed – for example:

> const obj = {};
> Object.isSealed(obj)
false
> Object.seal(obj)
{}
> Object.isSealed(obj)
true

10.4 Freezing objects

Object.freeze<T>(obj: T): T;

This method immediately returns obj if it isn’t an object.
Otherwise, it makes all properties non-writable, seals obj, and returns it. That is, obj is not extensible, all properties are read-only and there is no way to change that.

const point = { x: 17, y: -5 };
Object.freeze(point);

assert.throws(
  () => point.x = 2,
  /^TypeError: Cannot assign to read only property 'x'/);

assert.throws(
  () => Object.defineProperty(point, 'x', {enumerable: false}),
  /^TypeError: Cannot redefine property: x$/);

assert.throws(
  () => point.z = 4,
  /^TypeError: Cannot add property z, object is not extensible$/);

10.4.1 Checking whether an object is frozen

Object.isFrozen(obj: any): boolean

Checks whether obj is frozen – for example:

> const point = { x: 17, y: -5 };
> Object.isFrozen(point)
false
> Object.freeze(point)
{ x: 17, y: -5 }
> Object.isFrozen(point)
true

10.4.2 Freezing is shallow

Object.freeze(obj) only freezes obj and its properties. It does not freeze the values of those properties – for example:

const teacher = {
  name: 'Edna Krabappel',
  students: ['Bart'],
};
Object.freeze(teacher);

// We can’t change own properties:
assert.throws(
  () => teacher.name = 'Elizabeth Hoover',
  /^TypeError: Cannot assign to read only property 'name'/);

// Alas, we can still change values of own properties:
teacher.students.push('Lisa');
assert.deepEqual(
  teacher, {
    name: 'Edna Krabappel',
    students: ['Bart', 'Lisa'],
  });

10.4.3 Implementing deep freezing

If we want deep freezing, we need to implement it ourselves:

function deepFreeze(value) {
  if (Array.isArray(value)) {
    for (const element of value) {
      deepFreeze(element);
    }
    Object.freeze(value);
  } else if (typeof value === 'object' && value !== null) {
    for (const v of Object.values(value)) {
      deepFreeze(v);
    }
    Object.freeze(value);
  } else {
    // Nothing to do: primitive values are already immutable
  } 
  return value;
}

Revisiting the example from the previous section, we can check if deepFreeze() really freezes deeply:

const teacher = {
  name: 'Edna Krabappel',
  students: ['Bart'],
};
deepFreeze(teacher);

assert.throws(
  () => teacher.students.push('Lisa'),
  /^TypeError: Cannot add property 1, object is not extensible$/);

10.5 Further reading

More information on patterns for preventing data structures from being changed: §15 “Immutable wrappers for collections”