structuredClone

A função global structuredClone() do Azion Runtime retorna uma cópia profunda de um valor com o algoritmo de structured clone, o mecanismo do JavaScript que duplica objetos complexos. Nos navegadores, o mesmo algoritmo também copia os dados que postMessage() passa entre workers e os objetos que o IndexedDB armazena. O algoritmo percorre a entrada de forma recursiva e registra cada objeto que visita, por isso uma referência circular não o faz entrar em loop infinito. Para mais informações, consulte Structured clone algorithm na MDN Web Docs.

nota — Com azion dev, a opção transfer copia o buffer e deixa o buffer de origem anexado, com o byteLength completo. Um Map clonado não é uma instância de Map, um RangeError clonado não é uma instância de RangeError e um DataCloneError não é uma instância de DOMException, embora o nome do seu construtor seja DOMException.

Sintaxe

structuredClone(value, options)

Parâmetro	Tipo	Descrição
`value`	Any	Valor a copiar.
`options`	Object	Opcional. Contém a opção `transfer`.
`options.transfer`	Array	Objetos transferíveis, como um `ArrayBuffer`, que passam para a cópia em vez de serem copiados. Depois da chamada, um buffer transferido na origem tem `byteLength` igual a `0`.

A função retorna a cópia. A cópia é um objeto novo, e os objetos aninhados nela também são cópias.

Valores clonados

O runtime com deploy feito clona cada valor da origem neste valor da cópia:

Valor na origem	Valor na cópia
Objetos e arrays aninhados	Uma cópia em cada nível, com os mesmos valores.
Um objeto que referencia a si mesmo	Um objeto novo que referencia a si mesmo: o ciclo é mantido.
`Map`	Um `Map` com as mesmas entradas.
`Set`	Um `Set` com os mesmos valores.
`BigInt`	Um `BigInt`.
`Uint8Array`	Um `Uint8Array`.
`RangeError`	Um `RangeError` com o mesmo `name`.
`Date`	Um valor que não é uma instância de `Date`.
`RegExp`	Um `RegExp` com os mesmos `source` e `flags`. `lastIndex` volta a `0`.
Uma instância de uma classe	Um objeto simples com as propriedades próprias da instância. A cadeia de protótipos não é copiada, por isso os métodos da classe ficam ausentes e `constructor.name` é `Object`.
`Request`	Um objeto vazio, `{}`. A chamada não lança erro.

A cópia não mantém descritores de propriedade, getters, setters nem metadados semelhantes:

Um getter se torna uma propriedade de dados que contém o valor que o getter retornou.
Uma propriedade marcada como somente leitura com um descritor de propriedade é gravável na cópia, porque gravável é o padrão.

Erros

Um valor que o algoritmo não consegue copiar faz structuredClone() lançar uma DOMException cujo name é DataCloneError. O runtime com deploy feito recusa estes valores com estes erros, mostrados como name: message:

Valor	Erro
Uma função, como o método em `{ f() {} }`	`DataCloneError: f(){} could not be cloned.`
`Symbol('s')`	`DataCloneError: Symbol(s) could not be cloned.`
`new WeakMap()`	`DataCloneError: [object WeakMap] could not be cloned.`
`Promise.resolve(1)`	`DataCloneError: [object Promise] could not be cloned.`

Exemplo

Este handler clona um objeto que contém um Date, um Map, um Set, um BigInt, um Uint8Array, um RangeError e dados aninhados, e depois retorna o que leu da cópia:

JavaScript

01export default {

02 async fetch(request, env, ctx) {

03 const source = {

04 d: new Date(0),

05 m: new Map([[1, 'a']]),

06 s: new Set([1]),

07 big: 10n,

08 ab: new Uint8Array([1, 2]),

09 err: new RangeError('r'),

10 nested: { a: [1, { b: 2 }] },

11 };

12 const copy = structuredClone(source);

13 return Response.json({

14 date: copy.d instanceof Date,

15 map: copy.m instanceof Map && copy.m.get(1),

16 set: copy.s.has(1),

17 bigint: typeof copy.big,

18 typedArray: copy.ab.constructor.name,

19 errorName: copy.err?.name,

20 errorIsRangeError: copy.err instanceof RangeError,

21 deepCopy: copy.nested !== source.nested && copy.nested.a[1].b === 2,

22 });

23 },

24};

Uma function com deploy feito retorna estes valores da cópia. map é a entrada lida do Map clonado, e date é false porque o Date clonado não é uma instância de Date:

JSON

01{

02 "date": false,

03 "map": "a",

04 "set": true,

05 "bigint": "bigint",

06 "typedArray": "Uint8Array",

07 "errorName": "RangeError",

08 "errorIsRangeError": true,

09 "deepCopy": true

10}