Метод Window: structuredClone()

Метод structuredClone() интерфейса Window создаёт глубокую копию заданного значения с использованием алгоритма структурированного клонирования.

Метод также позволяет передавать (а не клонировать) передаваемые объекты в исходном значении в новый объект. Переданные объекты отсоединяются от исходного объекта и присоединяются к новому; они больше недоступны в исходном объекте.

value

Объект, который нужно клонировать. Это может быть любой тип, поддерживающий структурное клонирование.

options Необязательно

Объект со следующими свойствами:

transfer

Массив передаваемых объектов, которые будут перемещены, а не скопированы в возвращаемый объект.

Глубокая копия исходного value.

DataCloneError DOMException

Выбрасывается, если какая-либо часть входного значения не может быть сериализована.

Эта функция может использоваться для создания глубокой копии значений JavaScript. Она также поддерживает циклические ссылки, как показано ниже:

// Create an object with a value and a circular reference to itself.
const original = { name: "MDN" };
original.itself = original;

// Clone it
const clone = structuredClone(original);

console.assert(clone !== original); // the objects are not the same (not same identity)
console.assert(clone.name === "MDN"); // they do have the same values
console.assert(clone.itself === clone); // and the circular reference is preserved

Передаваемые объекты (только) могут быть переданы, а не дублированы в клонированном объекте, используя свойство transfer параметра options. Передача делает исходный объект непригодным для использования.

Следующий код демонстрирует, как клонировать массив и передать его базовые ресурсы в новый объект. После возврата исходный uInt8Array.buffer будет очищен.

// 16MB = 1024 * 1024 * 16
const uInt8Array = Uint8Array.from({ length: 1024 * 1024 * 16 }, (v, i) => i);

const transferred = structuredClone(uInt8Array, {
  transfer: [uInt8Array.buffer],
});
console.log(uInt8Array.byteLength); // 0

Вы можете клонировать любое количество объектов и передать любой подмножество этих объектов. Например, следующий код передаст arrayBuffer1, но не arrayBuffer2 из переданного значения.

const transferred = structuredClone(
  { x: { y: { z: arrayBuffer1, w: arrayBuffer2 } } },
  { transfer: [arrayBuffer1] },
);

В этом примере мы клонируем объект с одним элементом — массивом. После клонирования изменения в каждом объекте не влияют на другой объект.

const mushrooms1 = {
  amanita: ["muscaria", "virosa"],
};

const mushrooms2 = structuredClone(mushrooms1);

mushrooms2.amanita.push("pantherina");
mushrooms1.amanita.pop();

console.log(mushrooms2.amanita); // ["muscaria", "virosa", "pantherina"]
console.log(mushrooms1.amanita); // ["muscaria"]

В этом примере мы создаём ArrayBuffer, а затем клонируем объект, в котором он находится, передавая буфер. Мы можем использовать буфер в клонированном объекте, но если мы попытаемся использовать исходный буфер, произойдёт исключение.

// Create an ArrayBuffer with a size in bytes
const buffer1 = new ArrayBuffer(16);

const object1 = {
  buffer: buffer1,
};

// Clone the object containing the buffer, and transfer it
const object2 = structuredClone(object1, { transfer: [buffer1] });

// Create an array from the cloned buffer
const int32View2 = new Int32Array(object2.buffer);
int32View2[0] = 42;
console.log(int32View2[0]);

// Creating an array from the original buffer throws a TypeError
const int32View1 = new Int32Array(object1.buffer);

• Полифил structuredClone доступен в core-js
• Алгоритм структурного клонирования
• Полифил структурного клонирования