Skip to content

Latest commit

 

History

History
91 lines (74 loc) · 3.93 KB

index.md

File metadata and controls

91 lines (74 loc) · 3.93 KB
Raw
title slug page-type tags
The structured clone algorithm
Web/API/Web_Workers_API/Structured_clone_algorithm
guide
Advanced
DOM
HTML
JavaScript
Reference

{{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.

Things that don't work with structured clone

  • {{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.

Supported types

JavaScript types

  • {{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")}}

Error types

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).

Web/API types

  • {{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")}}

See also