JavaScript structuredClone: глубокая копия объекта

structuredClone() создаёт глубокую копию значения по алгоритму structured clone. Он сохраняет Date, Map, Set, ArrayBuffer, типизированные массивы и циклические ссылки, которые теряются при JSON.parse(JSON.stringify(value)). Метод доступен в современных браузерах и Node.js 17+.

Скопировать вложенный объект с циклом

const original = {
    name: "Анна",
    tags: ["admin", "editor"],
    createdAt: new Date("2026-01-01T00:00:00Z"),
    meta: new Map([["role", "admin"]]),
};
original.self = original;

const copy = structuredClone(original);
copy.tags.push("viewer");

console.log(copy.tags.length);                // 3
console.log(original.tags.length);            // 2
console.log(copy.createdAt instanceof Date);  // true
console.log(copy.meta.get("role"));           // admin
console.log(copy.self === copy);              // true

Массив tags скопирован отдельно, поэтому изменение копии не затрагивает оригинал. Циклическая ссылка self превращается в ссылку на саму копию, а не на исходный объект. Map и Date остаются соответствующими типами, тогда как JSON-сериализация превратила бы дату в строку, а Map — в пустой объект.

structuredClone() не копирует функции, DOM-узлы, WeakMap, WeakSet и объекты с методами: попытка клонировать функцию выбрасывает DataCloneError. Экземпляры классов становятся обычными объектами без прототипа, поэтому методы и геттеры пропадут. Для таких типов реализуйте собственный clone() или используйте библиотеку.

Для передачи больших буферов без копирования есть второй аргумент: structuredClone(buffer, {transfer: [buffer]}). После переноса исходный ArrayBuffer становится отсоединённым, а копия получает его память. Это полезно для postMessage и Worker, но не для обычного дублирования данных.

Метод поддерживается в Chrome 98+, Firefox 94+, Safari 15.4+ и Node.js 17+. В старых окружениях нужен полифил. Не используйте его для реактивных proxy-объектов и экземпляров ORM: копия потеряет связи и метаданные.

Документация: structuredClone, Structured clone algorithm.