CKTIS / JavaScript
Algoritmo di structured clone e trasferimento della proprietà
structuredClone() copia le strutture di dati supportate preservando cicli e riferimenti ripetuti all’interno della copia. L’opzione transfer sposta le risorse invece di copiarle e scollega l’ArrayBuffer originale.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
structuredClone(value)
structuredClone(value, { transfer: [buffer] })structuredClone(value) clona i dati supportati. L’algoritmo ricorda gli oggetti già visitati: preserva cicli e riferimenti condivisi nel risultato, ma gli oggetti clonati hanno un’identità diversa da quella degli originali. Anche postMessage() e IndexedDB usano questo algoritmo.
Un oggetto distinto non dispone necessariamente di memoria indipendente. La clonazione di un normale ArrayBuffer senza trasferimento crea una copia indipendente dei suoi byte, come mostra l’esempio. Quando è consentito clonare un SharedArrayBuffer, il clone è un oggetto buffer distinto che condivide la stessa memoria sottostante con l’originale.
Tra i tipi supportati ci sono oggetti semplici, array, Map, Set, Date, ArrayBuffer e array tipizzati. Funzioni, nodi DOM e valori symbol non possono essere clonati; un valore non supportato nei dati causa DataCloneError. L’algoritmo non preserva catene di prototipi personalizzate, descrittori delle proprietà, getter/setter o elementi privati delle classi. Non è quindi un metodo universale per copiare istanze di classi.
structuredClone(value, { transfer: [buffer] }) trasferisce la proprietà di una risorsa invece di copiarne i byte. L’ArrayBuffer di origine viene scollegato: il suo byteLength è 0 e le viste esistenti non consentono più di accedere ai dati. Un Uint8Array può essere clonato, ma si trasferisce il suo buffer, non la vista stessa. Un ArrayBuffer incluso nell’elenco transfer può essere scollegato anche se non è raggiungibile da value. In tal caso non compare nella copia restituita. Il trasferimento non richiede un worker.
Questa è un’API dell’ambiente host definita dallo standard HTML, non una funzionalità di una particolare edizione di ECMAScript. MDN segnala un’ampia disponibilità nei browser da marzo 2022; verifica l’ambiente di destinazione con typeof structuredClone === "function". La presenza di Node 24 in un repository non dimostra il supporto nei browser. L’esempio confronta copia e trasferimento e controlla che siano preservati un ciclo e un alias.
Identificatori di riferimento trattati in questa voce: Structured clone algorithm and transferable ownership.
Esempi
const bytes = new Uint8Array([7, 8]);
const original = { bytes, alias: bytes };
original.self = original;
const copy = structuredClone(original);
copy.bytes[0] = 9;
console.log(copy !== original, copy.self === copy, copy.bytes === copy.alias);
console.log(original.bytes[0], copy.bytes[0]);
const moved = structuredClone(original, { transfer: [bytes.buffer] });
console.log(bytes.buffer.byteLength, moved.bytes.byteLength);
console.log(moved.bytes[0], moved.self === moved, moved.bytes === moved.alias);Risultato
true true true 7 9 0 2 7 true true
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.