The structured clone algorithm
The structured clone algorithm copies complex JavaScript objects.
It is used internally when invoking structuredClone(), to transfer data between Workers via 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.
Things that don't work with structured clone
Functionobjects cannot be duplicated by the structured clone algorithm; attempting to throws aDataCloneErrorexception.- Cloning DOM nodes likewise throws a
DataCloneErrorexception. - Certain object properties are not preserved:
- The
lastIndexproperty ofRegExpobjects 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.
- Class private elements are not duplicated. (Although internal fields of built-in types may.)
- The
Supported types
JavaScript types
ArrayArrayBufferBooleanDataViewDateErrortypes (but see Error types below).MapNumberObjectobjects: but only plain objects (e.g., from object literals).- Primitive types, except
symbol. RegExp: but note thatlastIndexis not preserved.SetStringTypedArray
Error types
For Error types, the error name must be one of: Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, 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.
AggregateError support is expected to be added to the specification in whatwg/html#5749 (and is already supported in some browsers).
Web/API types
AudioDataBlobCropTargetCryptoKeyDOMException: browsers must serialize the propertiesnameandmessage. Other attributes may also be serialized/cloned.DOMMatrixDOMMatrixReadOnlyDOMPointDOMPointReadOnlyDOMQuadDOMRectDOMRectReadOnlyEncodedAudioChunkEncodedVideoChunkFencedFrameConfigFileFileListFileSystemDirectoryHandleFileSystemFileHandleFileSystemHandleGPUCompilationInfoGPUCompilationMessageGPUPipelineErrorImageBitmapImageDataRTCCertificateRTCEncodedAudioFrameRTCEncodedVideoFrameVideoFrameWebTransportError
Note:
Serializable objects are marked up in Web IDL files with the attribute [Serializable].