Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Algoritmo de clonación estructurada y transferencia de propiedad

structuredClone() copia estructuras de datos compatibles y conserva los ciclos y las referencias repetidas dentro de la copia. La opción transfer mueve recursos en vez de copiarlos y separa el ArrayBuffer original.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

structuredClone(value)
structuredClone(value, { transfer: [buffer] })

structuredClone(value) clona los datos compatibles. El algoritmo recuerda los objetos ya visitados: conserva los ciclos y las referencias compartidas en el resultado, pero los objetos clonados tienen una identidad distinta de la de los originales. postMessage() e IndexedDB también utilizan este algoritmo.

Que un objeto sea distinto no implica que tenga memoria independiente. Como muestra el ejemplo, al clonar un ArrayBuffer ordinario sin transferirlo se crea una copia independiente de sus bytes. Cuando se permite clonar un SharedArrayBuffer, el clon es un objeto búfer distinto que comparte la misma memoria subyacente que el original.

Entre los tipos compatibles se incluyen objetos simples, arrays, Map, Set, Date, ArrayBuffer y arrays tipados. Las funciones, los nodos DOM y los valores symbol no se pueden clonar; un valor no compatible en los datos provoca DataCloneError. El algoritmo no conserva las cadenas de prototipos personalizadas, los descriptores de propiedades, los getters/setters ni los elementos privados de las clases. Por tanto, no es una forma universal de copiar instancias de clases.

structuredClone(value, { transfer: [buffer] }) transfiere la propiedad de un recurso en vez de copiar sus bytes. El ArrayBuffer de origen queda separado: su byteLength es 0 y las vistas existentes dejan de permitir el acceso a los datos. Se puede clonar un Uint8Array, pero se transfiere su buffer, no la vista en sí. Un ArrayBuffer incluido en la lista transfer puede quedar separado aunque no sea accesible desde value. En ese caso, no aparecerá en la copia devuelta. La transferencia no requiere un worker.

Esta es una API del entorno anfitrión definida por el estándar HTML, no una característica de una edición concreta de ECMAScript. MDN indica que está ampliamente disponible en navegadores desde marzo de 2022; comprueba el entorno de destino con typeof structuredClone === "function". Que un repositorio use Node 24 no demuestra que los navegadores lo admitan. El ejemplo compara la copia con la transferencia y comprueba que se conservan un ciclo y un alias.

Identificadores de referencia incluidos en esta entrada: Structured clone algorithm and transferable ownership.

Ejemplos

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes