This topic has not yet been rated - Rate this topic

Object.freeze Function (JavaScript)

JavaScript - Internet Explorer 10

Prevents the modification of existing property attributes and values, and prevents the addition of new properties.

Object.freeze(object)

Parameters

object: Required. The object on which to lock the attributes. This can be a native JavaScript object or a DOM object.

Return Value

The object that is passed to the function.

Exceptions

If the object argument is not an object, a TypeError exception is thrown.

Remarks

The Object.freeze function does the following:

Makes the object non-extensible, so that new properties cannot be added to it.
Sets the configurable attribute to false for all properties of the object. When configurable is false, the property attributes cannot be changed and the property cannot be deleted.
Sets the writable attribute to false for all data properties of the object. When writable is false, the data property value cannot be changed.

For more information about how to set property attributes, see Object.defineProperty Function (JavaScript). To obtain the attributes of a property, you can use the Object.getOwnPropertyDescriptor Function (JavaScript).

Related Functions

The following related functions prevent the modification of object attributes.

Function	Object is made non-extensible	configurable is set to false for each property	writable is set to false for each property
Object.preventExtensions	Yes	No	No
Object.seal	Yes	Yes	No
Object.freeze	Yes	Yes	Yes

The following functions return true if all of the conditions marked in the following table are true.

Function	Object is extensible?	Object is non-extensible?	configurable is false for all properties?	writable is false for all data properties?
Object.isExtensible	X
Object.isSealed		X	X
Object.isFrozen		X	X	X

Example

The following example illustrates the use of the Object.freeze function.

JScript

function showFreeze() {

    // Create an object that has two properties.
    var obj = { pasta: "spaghetti", length: 10 };
    
    // Show attributes of the object and its properties.
    showAttributes(obj);

    // Freeze the object.
    Object.freeze(obj);

    // Show the attributes again.
    showAttributes(obj);

    // Try to add a new property, and then verify that it is
    // not added. It is not added because Object.freeze makes the
    // object non-extensible.
    obj.newProp = 50;
    document.write (typeof(obj.newProp) === "undefined");
    document.write (" ");

    // Try to delete a property, and then verify that it is
    // still present. It is not deleted because Object.freeze sets
    // the property's configurable attribute to false.
    delete obj.length;
    document.write (obj.length === 10);
    document.write (" ");

    // Try to change a property value, and then verify that it
    // is not changed. It is unchanged because Object.freeze sets
    // the data property's writable attribute to false.
    obj.pasta = "linguini";
    document.write (obj.pasta === "spaghetti");
}

function showAttributes(obj)
{
    var newLine = "<br />";

    // Show attributes of the object.
    document.write ("non-extensible: "+ !Object.isExtensible(obj));
    document.write (", isSealed: "+ Object.isSealed(obj));
    document.write (", isFrozen: "+ Object.isFrozen(obj));
    document.write (newLine);

    // Show attributes of each property.
    for (var prop in obj)
    {
        var descriptor = Object.getOwnPropertyDescriptor(obj, prop);

        document.write (prop + " - ");
        document.write ("configurable: " + descriptor.configurable);
        document.write (", writable: " + descriptor.writable);
        document.write(newLine);
    }
    document.write(newLine);
}

Following is the output.

non-extensible: false, isSealed: false, isFrozen: false
pasta - configurable: true, writable: true
length - configurable: true, writable: true

non-extensible: true, isSealed: true, isFrozen: true
pasta - configurable: false, writable: false
length - configurable: false, writable: false

true true true

Requirements

Supported in the Internet Explorer 9 standards document mode. See Version Information.

Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards.