TheObject.freeze() static methodfreezes an object. Freezing an objectprevents extensions and makes existing properties non-writable and non-configurable. A frozen object can no longer be changed: new properties cannot be added, existing properties cannot be removed, their enumerability, configurability, writability, or value cannot be changed, and the object's prototype cannot be re-assigned.freeze() returns the same object that was passed in.

Freezing an object is the highest integrity level that JavaScript provides.

Try it

const obj = {  prop: 42,};Object.freeze(obj);obj.prop = 33;// Throws an error in strict modeconsole.log(obj.prop);// Expected output: 42

Syntax

Object.freeze(obj)

Parameters

obj

The object to freeze.

Return value

The object that was passed to the function.

Description

Freezing an object is equivalent topreventing extensions and then changing all existingproperties' descriptors'configurable tofalse — and for data properties,writable tofalse as well. Nothing can be added to or removed from the properties set of a frozen object. Any attempt to do so will fail, either silently or by throwing aTypeError exception (most commonly, but not exclusively, when instrict mode).

For data properties of a frozen object, their values cannot be changed since thewritable andconfigurable attributes are set tofalse. Accessor properties (getters and setters) work the same — the property value returned by the getter may still change, and the setter can still be called without throwing errors when setting the property. Note that valuesthat are objects can still be modified, unless they are also frozen. As an object, anarray can be frozen; after doing so, its elements cannot be altered and no elements canbe added to or removed from the array.

Private elements are not properties and do not have the concept of property descriptors. Freezing an object with private elements does not prevent the values of these private elements from being changed. (Freezing objects is usually meant as a security measure against external code, but external code cannot access private elements anyway.) Private elements cannot be added or removed from the object, whether the object is frozen or not.

freeze() returns the same object that was passed into the function. Itdoes not create a frozen copy.

ATypedArray or aDataView with elements will cause aTypeError,as they are views over memory and will definitely cause other possible issues:

Object.freeze(new Uint8Array(0)); // No elements// Uint8Array []Object.freeze(new Uint8Array(1)); // Has elements// TypeError: Cannot freeze array buffer views with elementsObject.freeze(new DataView(new ArrayBuffer(32))); // No elements// DataView {}Object.freeze(new Float64Array(new ArrayBuffer(64), 63, 0)); // No elements// Float64Array []Object.freeze(new Float64Array(new ArrayBuffer(64), 32, 2)); // Has elements// TypeError: Cannot freeze array buffer views with elements

Note that as the standard three properties (buf.byteLength,buf.byteOffset andbuf.buffer) are read-only (as are those ofanArrayBuffer orSharedArrayBuffer), there is no reason forattempting to freeze these properties.

UnlikeObject.seal(), existing properties in objects frozen withObject.freeze() are made immutable and data properties cannot be re-assigned.

Examples

Freezing objects

const obj = {  prop() {},  foo: "bar",};// Before freezing: new properties may be added,// and existing properties may be changed or removedobj.foo = "baz";obj.lumpy = "woof";delete obj.prop;// Freeze.const o = Object.freeze(obj);// The return value is just the same object we passed in.o === obj; // true// The object has become frozen.Object.isFrozen(obj); // === true// Now any changes will failobj.foo = "quux"; // silently does nothing// silently doesn't add the propertyobj.quaxxor = "the friendly duck";// In strict mode such attempts will throw TypeErrorsfunction fail() {  "use strict";  obj.foo = "sparky"; // throws a TypeError  delete obj.foo; // throws a TypeError  delete obj.quaxxor; // returns true since attribute 'quaxxor' was never added  obj.sparky = "arf"; // throws a TypeError}fail();// Attempted changes through Object.defineProperty;// both statements below throw a TypeError.Object.defineProperty(obj, "ohai", { value: 17 });Object.defineProperty(obj, "foo", { value: "eit" });// It's also impossible to change the prototype// both statements below will throw a TypeError.Object.setPrototypeOf(obj, { x: 20 });obj.__proto__ = { x: 20 };

Freezing arrays

const a = [0];Object.freeze(a); // The array cannot be modified now.a[0] = 1; // fails silently// In strict mode such attempt will throw a TypeErrorfunction fail() {  "use strict";  a[0] = 1;}fail();// Attempted to pusha.push(2); // throws a TypeError

The object being frozen isimmutable. However, it is not necessarilyconstant. The following example shows that a frozen object is not constant(freeze is shallow).

const obj1 = {  internal: {},};Object.freeze(obj1);obj1.internal.a = "value";obj1.internal.a; // 'value'

To be a constant object, the entire reference graph (direct and indirect references toother objects) must reference only immutable frozen objects. The object being frozen issaid to be immutable because the entire objectstate (values and references toother objects) within the whole object is fixed. Note that strings, numbers, andbooleans are always immutable and that Functions and Arrays are objects.

Deep freezing

The result of callingObject.freeze(object) only applies to theimmediate properties ofobject itself and will prevent future propertyaddition, removal or value re-assignment operationsonly onobject. If the value of those properties are objects themselves, thoseobjects are not frozen and may be the target of property addition, removal or valuere-assignment operations.

const employee = {  name: "Mayank",  designation: "Developer",  address: {    street: "Rohini",    city: "Delhi",  },};Object.freeze(employee);employee.name = "Dummy"; // fails silently in non-strict modeemployee.address.city = "Noida"; // attributes of child object can be modifiedconsole.log(employee.address.city); // "Noida"

To make an object immutable, recursively freeze each non-primitive property (deep freeze). Use the pattern on a case-by-case basis based on your design when you know the object contains nocycles in the reference graph, otherwise an endless loop will be triggered. For example, functions created with thefunction syntax have aprototype property with aconstructor property that points to the function itself, so they have cycles by default. Other functions, such asarrow functions, can still be frozen.

An enhancement todeepFreeze() would be to store the objects it has already visited, so you can suppress callingdeepFreeze() recursively when an object is in the process of being made immutable. For one example, seeusingWeakSet to detect circular references. You still run a risk of freezing an object that shouldn't be frozen, such aswindow.

function deepFreeze(object) {  // Retrieve the property names defined on object  const propNames = Reflect.ownKeys(object);  // Freeze properties before freezing self  for (const name of propNames) {    const value = object[name];    if ((value && typeof value === "object") || typeof value === "function") {      deepFreeze(value);    }  }  return Object.freeze(object);}const obj2 = {  internal: {    a: null,  },};deepFreeze(obj2);obj2.internal.a = "anotherValue"; // fails silently in non-strict modeobj2.internal.a; // null

Specifications

Browser compatibility

See also

• Object.isFrozen()
• Object.preventExtensions()
• Object.isExtensible()
• Object.seal()
• Object.isSealed()