Object.freeze()

Il metodo Object.freeze() congela un oggetto: ne previene l'aggiunta, la modifica e la rimozione di proprietà, inclusa la loro enumerabilità, configurabilità e accessibilità. In sostanza, l'oggetto è reso effettivamente immutabile. Il metodo restituisce lo stesso oggetto che è stato passato alla funzione. 

Sintassi

Object.freeze(obj)

Parametri

obj

L'oggetto da congelare.

Valore di ritorno

L'oggetto passato alla funzione.

Descrizione

Nulla può essere aggiunto o rimosso dall'insieme delle proprietà di un oggetto congelato. Qualsiasi tentativo di fare ciò fallirebbe, o silenziosamente o attraverso il ritorno di un errore TypeError (più frequentemente, ma non necessariamente, quest'ultimo scenario accadrebbe in strict mode).

I valori delle proprietà non possono essere cambiati, anche quando si tratta di setters e getters. Da notare che se un oggetto costituisce il valore di una proprietà, esso può essere ancora modificato senza problemi, a meno che anch'esso non sia stato congelato.

Esempi

var obj = {
  prop: function() {},
  foo: 'bar'
};

// Nuove proprietà possono essere aggiunte, proprietà già esistenti possono 
// essere modificate o rimosse
obj.foo = 'baz';
obj.lumpy = 'woof';
delete obj.prop;


// Sia l'oggetto che viene passato che quello restituito verranno congelati.
// No serve salvare l'oggetto restituito per congelare l'originale
var o = Object.freeze(obj);

o === obj; // true
Object.isFrozen(obj); // === true

// Adesso qualsiasi cambiamento fallirà
obj.foo = 'quux'; // silenziosamente, non succede niente
obj.quaxxor = 'the friendly duck'; // silenziosamente, non aggiungerà alcuna proprietò


// ...e nella modalità strict questi tentativi di modifica faranno lanciare TypeErrors
function fail(){
  'use strict';
  obj.foo = 'sparky'; // throws a TypeError
  delete obj.quaxxor; // throws a TypeError
  obj.sparky = 'arf'; // throws a TypeError
}

fail();


// Tentare di cambiare attraverso Object.defineProperty farà anche lanciare un TypeError
Object.defineProperty(obj, 'ohai', { value: 17 }); // throws a TypeError
Object.defineProperty(obj, 'foo', { value: 'eit' }); // throws a TypeError

Il seguente esempio mostra come oggetti che sono valori di proprietà possono essere mutati(il congelamento si ferma ad un solo livello di profondità).

obj1 = {
  internal: {}
};

Object.freeze(obj1);
obj1.internal.a = 'aValue';

obj1.internal.a // 'aValue'


// Per fare un oggetto totalmente non modificabile, congela ciascun oggetto in obj.
// Per farlo noi usiamo questa funzione.
function deepFreeze(obj) {

  // Prende tutti i nomi delle proprietà definite in obj
  var propNames = Object.getOwnPropertyNames(obj);

  // Congela tutte le proprietà prima di congelare obj
  propNames.forEach(function(name) {
    var prop = obj[name];

    // Congela prop se esso è un oggetto
    if (typeof prop == 'object' && prop !== null)
      deepFreeze(prop);
  });

  // Congela se stesso (niente operazione se esso è già congelato)
  return Object.freeze(obj);
}

obj2 = {
  internal: {}
};

deepFreeze(obj2);
obj2.internal.a = 'anotherValue';
obj2.internal.a; // undefined

Note

In ES5, se l'argomento di questo metodo non è un oggetto, allora verrà ritornato un errore TypeError. In ES2015, un argomento che non è un oggetto verrà trattato come se fosse un normale oggetto già congelato, e verrà perciò semplicemente ritornato.

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

> Object.freeze(1)
1                             // ES2015 code

Specifiche

Compatibilità con i browser

Guarda anche

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