CKTIS / JavaScript
Algoritmo de clonagem estruturada e transferência de propriedade
structuredClone() copia estruturas de dados suportadas, preservando ciclos e referências repetidas dentro da cópia. A opção transfer move recursos em vez de os copiar e desliga o ArrayBuffer original.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
structuredClone(value)
structuredClone(value, { transfer: [buffer] })structuredClone(value) clona os dados suportados. O algoritmo memoriza os objetos já visitados: preserva ciclos e referências partilhadas no resultado, mas os objetos clonados têm uma identidade diferente da dos originais. postMessage() e IndexedDB também utilizam este algoritmo.
Um objeto distinto nem sempre tem memória independente. Como mostra o exemplo, clonar um ArrayBuffer comum sem o transferir cria uma cópia independente dos seus bytes. Quando é permitido clonar um SharedArrayBuffer, o clone é um objeto de buffer distinto que partilha a mesma memória subjacente com o original.
Entre os tipos suportados estão objetos simples, arrays, Map, Set, Date, ArrayBuffer e arrays tipados. As funções, os nós DOM e os valores symbol não podem ser clonados; um valor não suportado nos dados causa DataCloneError. O algoritmo não preserva cadeias de protótipos personalizadas, descritores de propriedades, getters/setters nem elementos privados das classes. Por isso, não é um método universal para copiar instâncias de classes.
structuredClone(value, { transfer: [buffer] }) transfere a propriedade de um recurso em vez de copiar os respetivos bytes. O ArrayBuffer de origem fica desligado: o seu byteLength é 0 e as vistas existentes deixam de permitir o acesso aos dados. Um Uint8Array pode ser clonado, mas é o seu buffer que se transfere, não a própria vista. Um ArrayBuffer incluído na lista transfer pode ficar desligado mesmo que não seja alcançável a partir de value. Nesse caso, não aparece na cópia devolvida. A transferência não requer um worker.
Esta é uma API do ambiente anfitrião definida pela norma HTML, não uma funcionalidade de uma edição específica de ECMAScript. A MDN indica ampla disponibilidade nos browsers desde março de 2022; verifica o ambiente de destino com typeof structuredClone === "function". A presença de Node 24 num repositório não comprova o suporte nos browsers. O exemplo compara a cópia com a transferência e verifica a preservação de um ciclo e de um alias.
Identificadores de referência abrangidos por esta entrada: Structured clone algorithm and transferable ownership.
Exemplos
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);Resultado
true true true 7 9 0 2 7 true true
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.