structuredClone
The structuredClone() function of Azion Runtime: its parameters, the values it copies, the properties it does not keep, and the DataCloneError it throws.
The structuredClone() global function of Azion Runtime returns a deep copy of a value with the structured clone algorithm, the JavaScript mechanism that duplicates complex objects. In browsers, the same algorithm also copies data that postMessage() passes between workers and objects that IndexedDB stores. The algorithm walks the input recursively and records each object it visits, so a circular reference does not make it loop forever. For more information, refer to Structured clone algorithm on MDN Web Docs.
Syntax
| Parameter | Type | Description |
|---|---|---|
value | Any | Value to copy. |
options | Object | Optional. Holds the transfer option. |
options.transfer | Array | Transferable objects, such as an ArrayBuffer, that move into the copy instead of being copied. After the call, a transferred buffer in the source has a byteLength of 0. |
The function returns the copy. The copy is a new object, and the objects nested in it are copies too.
Cloned values
The deployed runtime clones each value in the source into this value in the copy:
| Value in the source | Value in the copy |
|---|---|
| Nested objects and arrays | A copy at every level, with the same values. |
| An object that references itself | A new object that references itself: the cycle is kept. |
Map | A Map with the same entries. |
Set | A Set with the same values. |
BigInt | A BigInt. |
Uint8Array | A Uint8Array. |
RangeError | A RangeError with the same name. |
Date | A value that is not an instance of Date. |
RegExp | A RegExp with the same source and flags. lastIndex resets to 0. |
| An instance of a class | A plain object with the own properties of the instance. The prototype chain is not copied, so the methods of the class are absent and constructor.name is Object. |
Request | An empty object, {}. The call does not throw. |
The copy does not keep property descriptors, getters, setters, or similar metadata:
- A getter becomes a data property that holds the value the getter returned.
- A property marked read-only with a property descriptor is writable in the copy, because writable is the default.
Errors
A value the algorithm cannot copy makes structuredClone() throw a DOMException whose name is DataCloneError. The deployed runtime refuses these values with these errors, shown as name: message:
| Value | Error |
|---|---|
A function, such as the method in { 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. |
Example
This handler clones an object that holds a Date, a Map, a Set, a BigInt, a Uint8Array, a RangeError, and nested data, then returns what it read from the copy:
A deployed function returns these values from the copy. map is the entry read from the cloned Map, and date is false because the cloned Date is not an instance of Date: