title | slug | page-type |
---|---|---|
The structured clone algorithm |
Web/API/Web_Workers_API/Structured_clone_algorithm |
guide |
{{DefaultAPISidebar("Web Workers API") }}
The structured clone algorithm copies complex JavaScript objects. It is used internally when invoking {{domxref("structuredClone()")}}, to transfer data between Workers via {{domxref("Worker.postMessage()", "postMessage()")}}, storing objects with IndexedDB, or copying objects for other APIs.
It clones by recursing through the input object while maintaining a map of previously visited references, to avoid infinitely traversing cycles.
-
{{jsxref("Function")}} objects cannot be duplicated by the structured clone algorithm; attempting to throws a
DataCloneError
exception. -
Cloning DOM nodes likewise throws a
DataCloneError
exception. -
Certain object properties are not preserved:
- The
lastIndex
property of {{jsxref("RegExp")}} objects is not preserved. - Property descriptors, setters, getters, and similar metadata-like features are not duplicated. For example, if an object is marked readonly with a property descriptor, it will be read/write in the duplicate, since that's the default.
- The prototype chain is not walked or duplicated.
- The
- {{jsxref("Array")}}
- {{jsxref("ArrayBuffer")}}
- {{jsxref("Boolean")}}
- {{jsxref("DataView")}}
- {{jsxref("Date")}}
- {{jsxref("Error")}} types (but see Error types below).
- {{jsxref("Map")}}
- {{jsxref("Object")}} objects: but only plain objects (e.g. from object literals).
- Primitive types, except
symbol
. - {{jsxref("RegExp")}}: but note that
lastIndex
is not preserved. - {{jsxref("Set")}}
- {{jsxref("String")}}
- {{jsxref("TypedArray")}}
For Error
types, the error name must be one of: {{jsxref("Error")}}, {{JSxRef("EvalError")}}, {{JSxRef("RangeError")}}, {{JSxRef("ReferenceError")}}, {{JSxRef("SyntaxError")}}, {{JSxRef("TypeError")}}, {{JSxRef("URIError")}} (or will be set to "Error").
Browsers must serialize the properties name
and message
, and are expected to serialize other "interesting" properties of the errors such as stack
, cause
, etc.
{{JSxRef("AggregateError")}} support is expected to be added to the specification in whatwg/html#5749 (and is already supported in some browsers).
- {{domxref("AudioData")}}
- {{domxref("Blob")}}
- {{domxref("CropTarget")}}
- {{domxref("CryptoKey")}}
- {{domxref("DOMException")}}: browsers must serialize the properties {{domxref("DOMException.name","name")}} and {{domxref("DOMException.message","message")}}. Other attributes may also be serialized/cloned.
- {{domxref("DOMMatrix")}}
- {{domxref("DOMMatrixReadOnly")}}
- {{domxref("DOMPoint")}}
- {{domxref("DOMPointReadOnly")}}
- {{domxref("DOMQuad")}}
- {{domxref("DOMRect")}}
- {{domxref("DOMRectReadOnly")}}
- {{domxref("File")}}
- {{domxref("FileList")}}
- {{domxref("FileSystemDirectoryHandle")}}
- {{domxref("FileSystemFileHandle")}}
- {{domxref("FileSystemHandle")}}
- {{domxref("GPUCompilationInfo")}}
- {{domxref("GPUCompilationMessage")}}
- {{domxref("ImageBitmap")}}
- {{domxref("ImageData")}}
- {{domxref("RTCCertificate")}}
- {{domxref("VideoFrame")}}
- HTML Specification: Safe passing of structured data
- Transferable objects
- {{domxref("structuredClone()")}}
- {{domxref("window.postMessage()")}}
- Web Workers
- IndexedDB