structuredClone: cópias profundas sem truques

O truque de copiar um objeto com JSON.parse(JSON.stringify(objeto)) anda em código de produção há anos. Funciona até ao dia em que o objeto tem uma data, um Map, um undefined ou uma referência a si próprio — e aí falha em silêncio ou rebenta.

O structuredClone é a função nativa que faz esse trabalho como deve ser. Está nos browsers e no Node desde 2022, e não é preciso instalar nada.

1. Onde é que o truque do JSON falha

const original = {
  criadoEm: new Date('2026-07-14'),
  etiquetas: new Set(['a', 'b']),
  porPreencher: undefined,
};

const copiaJson = JSON.parse(JSON.stringify(original));

console.log(typeof copiaJson.criadoEm); // 'string' — deixou de ser uma data
console.log(copiaJson.etiquetas); // {} — o Set virou um objeto vazio
console.log('porPreencher' in copiaJson); // false — a chave desapareceu

Com o structuredClone, cada um deles sobrevive:

const copia = structuredClone(original);

console.log(copia.criadoEm instanceof Date); // true
console.log(copia.etiquetas.has('a')); // true
console.log('porPreencher' in copia); // true

2. Referências circulares

O JSON.stringify atira um erro quando um objeto se refere a si próprio. O structuredClone aguenta, e mantém a circularidade na cópia:

const pasta = { nome: 'raiz' };
pasta.pai = pasta;

const copiaPasta = structuredClone(pasta);

console.log(copiaPasta.pai === copiaPasta); // true

3. O que ele não copia

• Funções — atira DataCloneError. Um objeto com métodos não passa.

• O protótipo — a cópia de uma instância de uma classe é um objeto simples, sem os métodos dela.

• Getters e setters — fica o valor que o getter devolveu, já sem o getter.

class Utilizador {
  constructor(nome) {
    this.nome = nome;
  }
  saudacao() {
    return 'Olá, ' + this.nome;
  }
}

const copiado = structuredClone(new Utilizador('Ana'));

console.log(copiado.nome); // 'Ana'
console.log(copiado instanceof Utilizador); // false
console.log(typeof copiado.saudacao); // 'undefined'

Para dados, é exatamente o que se quer. Para objetos com comportamento, continua a ser preciso passar pelo construtor.