mozilla
Your Search Results

    Object.freeze()

    Summary

    The Object.freeze() method freezes an object: that is, prevents new properties from being added to it; prevents existing properties from being removed; and prevents existing properties, or their enumerability, configurability, or writability, from being changed. In essence the object is made effectively immutable. The method returns the object being frozen.

    Syntax

    Object.freeze(obj)

    Parameters

    obj
    The object to freeze.

    Description

    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 a TypeError exception (most commonly, but not exclusively, when in strict mode).

    Values cannot be changed for data properties. Accessor properties (getters and setters) work the same (and still give the illusion that you are changing the value). Note that values that are objects can still be modified, unless they are also frozen.

    Examples

    var obj = {
      prop: function() {},
      foo: 'bar'
    };
    
    // New properties may be added, existing properties may be changed or removed
    obj.foo = 'baz';
    obj.lumpy = 'woof';
    delete obj.prop;
    
    var o = Object.freeze(obj);
    
    assert(Object.isFrozen(obj) === true);
    
    // Now any changes will fail
    obj.foo = 'quux'; // silently does nothing
    obj.quaxxor = 'the friendly duck'; // silently doesn't add the property
    
    // ...and in strict mode such attempts will throw TypeErrors
    function fail(){
      'use strict';
      obj.foo = 'sparky'; // throws a TypeError
      delete obj.quaxxor; // throws a TypeError
      obj.sparky = 'arf'; // throws a TypeError
    }
    
    fail();
    
    // Attempted changes through Object.defineProperty will also throw
    Object.defineProperty(obj, 'ohai', { value: 17 }); // throws a TypeError
    Object.defineProperty(obj, 'foo', { value: 'eit' }); // throws a TypeError
    

    The following example shows that object values in a frozen object can be mutated (freeze is shallow).

    obj = {
      internal: {}
    };
    
    Object.freeze(obj);
    obj.internal.a = 'aValue';
    
    obj.internal.a // 'aValue'
    
    // To make obj fully immutable, freeze each object in obj.
    // To do so, we use this function.
    
    function deepFreeze(o) {
      var prop, propKey;
      Object.freeze(o); // First freeze the object.
      for (propKey in o) {
        prop = o[propKey];
        if (!o.hasOwnProperty(propKey) || !(typeof prop === 'object') || Object.isFrozen(prop)) {
          // If the object is on the prototype, not an object, or is already frozen,
          // skip it. Note that this might leave an unfrozen reference somewhere in the
          // object if there is an already frozen object containing an unfrozen object.
          continue;
        }
    
        deepFreeze(prop); // Recursively call deepFreeze.
      }
    }
    
    obj2 = {
      internal: {}
    };
    
    deepFreeze(obj2);
    obj2.internal.a = 'anotherValue';
    obj2.internal.a; // undefined
    

    Notes

    In ES5, if the argument to this method is not an object (a primitive), then it will cause a TypeError. In ES6, a non-object argument will be treated as if it was a  frozen ordinary object, simply return it.

    > Object.freeze(1)
    TypeError: 1 is not an object // ES5 code
    
    > Object.freeze(1)
    1                             // ES6 code
    

    Specifications

    Specification Status Comment
    ECMAScript 5.1 (ECMA-262)
    The definition of 'Object.freeze' in that specification.
    Standard Initial definition. Implemented in JavaScript 1.8.5.
    ECMAScript 6 (ECMA-262)
    The definition of 'Object.freeze' in that specification.
    Draft  

    Browser compatibility

    Help improve compatibility tables by filling out this 11 question survey.
    Feature Firefox (Gecko) Chrome Internet Explorer Opera Safari
    Basic support 4.0 (2) 6 9 12 5.1
    Feature Firefox Mobile (Gecko) Android IE Mobile Opera Mobile Safari Mobile
    Basic support ? ? ? ? ?

    Based on Kangax's compat table.

    See also

    Document Tags and Contributors

    Last updated by: ziyunfei,