Define self.structuredClone()

Closes #793.

Author: surma

source

@@ -7967,13 +7967,24 @@ interface <dfn interface>DOMStringList</dfn> {
   </div>
 
 
-  <div w-nodev>
-
   <h3 split-filename="structured-data">Safe passing of structured data</h3>
 
+  <p id="structuredclone"><span id="structured-clone"></span>To support passing JavaScript objects,
+  including <span data-x="platform object">platform objects</span>, across <span data-x="JavaScript
+  realm">realm</span> boundaries, this specification defines <span w-nodev>the following
+  </span>infrastructure for serializing and deserializing objects, including in some cases
+  transferring the underlying data instead of copying it. Collectively this
+  serialization/deserialization process is known as "structured cloning", although most APIs perform
+  separate serialization and deserialization steps. (With the notable exception being the <code
+  data-x="dom-structuredClone">structuredClone()</code> method.)</p>
+
+  <div w-nodev>
+
   <p>This section uses the terminology and typographic conventions from the JavaScript
   specification. <ref spec=JAVASCRIPT></p>
 
+  </div>
+
   <h4><dfn>Serializable objects</dfn></h4>
 
   <p><span>Serializable objects</span> support being serialized, and later deserialized, in a way
@@ -7984,6 +7995,8 @@ interface <dfn interface>DOMStringList</dfn> {
   <p>Not all objects are <span>serializable objects</span>, and not all aspects of objects that are
   <span>serializable objects</span> are necessarily preserved when they are serialized.</p>
 
+  <div w-nodev>
+
   <p><span data-x="platform object">Platform objects</span> can be <span>serializable objects</span>
   if their <span>primary interface</span> is decorated with the <dfn extended-attribute
   data-lt="Serializable" data-x="Serializable"><code>[Serializable]</code></dfn> IDL <span>extended
@@ -8091,6 +8104,8 @@ interface <dfn interface>DOMStringList</dfn> {
   However, to better specify the behavior of certain more complex situations, the model was updated
   to make the serialization and deserialization explicit.</p>
 
+  </div>
+
   <h4 export data-lt="transferable object"><dfn>Transferable objects</dfn></h4>
 
   <p><span>Transferable objects</span> support being transferred across <span
@@ -8103,6 +8118,8 @@ interface <dfn interface>DOMStringList</dfn> {
   <p class="note">Transferring is an irreversible and non-idempotent operation. Once an object has
   been transferred, it cannot be transferred, or indeed used, again.</p>
 
+  <div w-nodev>
+
   <p><span data-x="platform object">Platform objects</span> can be <span>transferable objects</span>
   if their <span>primary interface</span> is decorated with the <dfn extended-attribute
   data-lt="Transferable" data-x="Transferable"><code>[Transferable]</code></dfn> IDL <span>extended
@@ -9138,11 +9155,6 @@ o.myself = o;</code></pre>
   understood to perform an implicit <span data-x="concept-idl-convert">conversion</span> to the
   JavaScript value before invoking these algorithms.</p>
 
-  <p class="note" id="structuredclone"><span id="structured-clone"></span>This specification used
-  to define a "structured clone" algorithm, and more recently a StructuredClone abstract operation.
-  However, in practice all known uses of it were better served by separate serialization and
-  deserialization steps, so it was removed.</p>
-
   <hr>
 
   <p>Call sites that are not invoked as a result of author code synchronously calling into a user
@@ -9170,6 +9182,38 @@ o.myself = o;</code></pre>
 
   </div>
 
+  <h4 id="structured-cloning">Structured cloning API</h4>
+
+  <dl class="domintro">
+   <dt><code data-x=""><var>result</var> = self.<span subdfn data-x="dom-structuredClone">structuredClone</span>(<var>value</var>[, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> }])</code></dt>
+   <dd>
+    <p>Takes the input value and returns a deep copy by performing the structured clone algorithm.
+    <span>Transferable objects</span> listed in the <code
+    data-x="dom-StructuredSerializeOptions-transfer">transfer</code> array are transferred, not
+    just cloned, meaning that they are no longer usable in the input value.</p>
+
+    <p>Throws a <span>"<code>DataCloneError</code>"</span> <code>DOMException</code> if any part of
+    the input value is not <span data-x="serializable objects">serializable</span>.</p>
+   </dd>
+  </dl>
+
+  <div w-nodev>
+
+  <p>The <dfn method for="WindowOrWorkerGlobalScope"
+  data-x="dom-structuredClone"><code>structuredClone(<var>value</var>,
+  <var>options</var>)</code></dfn> method steps are:</p>
+
+  <ol>
+   <li><p>Let <var>serialized</var> be ?
+   <span>StructuredSerializeWithTransfer</span>(<var>value</var>, <var>options</var>["<code
+   data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"]).</p></li>
+
+   <li><p>Return ? <span>StructuredDeserialize</span>(<var>serialized</var>, <span>this</span>'s
+   <span data-x="concept-relevant-realm">relevant Realm</span>).</p></li>
+  </ol>
+
+  </div>
+
 
   <h2 split-filename="dom" id="dom">Semantics, structure, and APIs of HTML documents</h2>
 
@@ -80416,7 +80460,7 @@ interface <dfn interface>Window</dfn> : <span>EventTarget</span> {
 <span>Window</span> includes <span>GlobalEventHandlers</span>;
 <span>Window</span> includes <span>WindowEventHandlers</span>;
 
-dictionary <dfn dictionary>WindowPostMessageOptions</dfn> : <span>PostMessageOptions</span> {
+dictionary <dfn dictionary>WindowPostMessageOptions</dfn> : <span>StructuredSerializeOptions</span> {
   USVString <dfn dict-member for="WindowPostMessageOptions" data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</dfn> = "/";
 };</code></pre>
 
@@ -94809,6 +94853,9 @@ interface mixin <dfn interface>WindowOrWorkerGlobalScope</dfn> {
   // ImageBitmap
   Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, optional <span>ImageBitmapOptions</span> options = {});
   Promise&lt;<span>ImageBitmap</span>&gt; <span data-x="dom-createImageBitmap">createImageBitmap</span>(<span>ImageBitmapSource</span> image, long sx, long sy, long sw, long sh, optional <span>ImageBitmapOptions</span> options = {});
+
+  // structured cloning
+  any <span data-x="dom-structuredClone">structuredClone</span>(any value, optional <span>StructuredSerializeOptions</span> options = {});
 };
 <span>Window</span> includes <span>WindowOrWorkerGlobalScope</span>;
 <span>WorkerGlobalScope</span> includes <span>WindowOrWorkerGlobalScope</span>;</code></pre>
@@ -99740,7 +99787,7 @@ function receiver(e) {
     and can contain certain data objects such as <code>File</code> <code>Blob</code>,
     <code>FileList</code>, and <code data-x="idl-ArrayBuffer">ArrayBuffer</code> objects.</p>
 
-    <p>Objects listed in the <code data-x="dom-PostMessageOptions-transfer">transfer</code> member
+    <p>Objects listed in the <code data-x="dom-StructuredSerializeOptions-transfer">transfer</code> member
     of <var>options</var> are transferred, not just cloned, meaning that they are no longer usable
     on the sending side.</p>
 
@@ -99816,7 +99863,7 @@ function receiver(e) {
    </li>
 
    <li><p>Let <var>transfer</var> be <var>options</var>["<code
-   data-x="dom-PostMessageOptions-transfer">transfer</code>"].</p></li>
+   data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"].</p></li>
 
    <li><p>Let <var>serializeWithTransferResult</var> be
    <span>StructuredSerializeWithTransfer</span>(<var>message</var>, <var>transfer</var>). Rethrow
@@ -99892,7 +99939,7 @@ function receiver(e) {
 
    <li><p>Let <var>options</var> be «[ "<code
    data-x="dom-WindowPostMessageOptions-targetOrigin">targetOrigin</code>" →
-   <var>targetOrigin</var>, "<code data-x="dom-PostMessageOptions-transfer">transfer</code>" →
+   <var>targetOrigin</var>, "<code data-x="dom-StructuredSerializeOptions-transfer">transfer</code>" →
    <var>transfer</var> ]».</p></li>
 
    <li><p>Run the <span>window post message steps</span> providing <var>targetWindow</var>,
@@ -100160,7 +100207,7 @@ interface <dfn interface>MessageChannel</dfn> {
   <pre><code class="idl">[Exposed=(Window,Worker,AudioWorklet), <span>Transferable</span>]
 interface <dfn interface>MessagePort</dfn> : <span>EventTarget</span> {
   undefined <span data-x="dom-MessagePort-postMessage">postMessage</span>(any message, sequence&lt;<span data-x="idl-object">object</span>&gt; transfer);
-  undefined <span data-x="dom-MessagePort-postMessage-options">postMessage</span>(any message, optional <span>PostMessageOptions</span> options = {});
+  undefined <span data-x="dom-MessagePort-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
   undefined <span data-x="dom-MessagePort-start">start</span>();
   undefined <span data-x="dom-MessagePort-close">close</span>();
 
@@ -100169,8 +100216,8 @@ interface <dfn interface>MessagePort</dfn> : <span>EventTarget</span> {
   attribute <span>EventHandler</span> <span data-x="handler-MessagePort-onmessageerror">onmessageerror</span>;
 };
 
-dictionary <dfn dictionary>PostMessageOptions</dfn> {
-  sequence&lt;<span data-x="idl-object">object</span>&gt; <dfn dict-member for="PostMessageOptions" data-x="dom-PostMessageOptions-transfer">transfer</dfn> = [];
+dictionary <dfn dictionary>StructuredSerializeOptions</dfn> {
+  sequence&lt;<span data-x="idl-object">object</span>&gt; <dfn dict-member for="StructuredSerializeOptions" data-x="dom-StructuredSerializeOptions-transfer">transfer</dfn> = [];
 };</code></pre>
 
   <dl class="domintro">
@@ -100313,7 +100360,7 @@ dictionary <dfn dictionary>PostMessageOptions</dfn> {
 
   <ol> <!-- a lot of this is similar or identical to the window post message steps -->
    <li><p>Let <var>transfer</var> be <var>options</var>["<code
-   data-x="dom-PostMessageOptions-transfer">transfer</code>"].</p></li>
+   data-x="dom-StructuredSerializeOptions-transfer">transfer</code>"].</p></li>
 
    <li><p>If <var>transfer</var> <span data-x="list contains">contains</span> this
    <code>MessagePort</code>, then throw a <span>"<code>DataCloneError</code>"</span>
@@ -100403,7 +100450,8 @@ dictionary <dfn dictionary>PostMessageOptions</dfn> {
    entangled, if any; otherwise let it be null.</p></li>
 
    <li><p>Let <var>options</var> be «[ "<code
-   data-x="dom-PostMessageOptions-transfer">transfer</code>" → <var>transfer</var> ]».</p></li>
+   data-x="dom-StructuredSerializeOptions-transfer">transfer</code>" →
+   <var>transfer</var> ]».</p></li>
 
    <li><p>Run the <span>message port post message steps</span> providing <var>targetPort</var>,
    <var>message</var> and <var>options</var>.</p></li>
@@ -101272,7 +101320,7 @@ interface <dfn interface>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalSc
   [Replaceable] readonly attribute DOMString <span data-x="dom-DedicatedWorkerGlobalScope-name">name</span>;
 
   undefined <span data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(any message, sequence&lt;<span data-x="idl-object">object</span>&gt; transfer);
-  undefined <span data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(any message, optional <span>PostMessageOptions</span> options = {});
+  undefined <span data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
 
   undefined <span data-x="dom-DedicatedWorkerGlobalScope-close">close</span>();
 
@@ -101294,10 +101342,8 @@ interface <dfn interface>DedicatedWorkerGlobalScope</dfn> : <span>WorkerGlobalSc
    data-x="concept-WorkerGlobalScope-name">name</span>, i.e. the value given to the
    <code>Worker</code> constructor. Primarily useful for debugging.</p></dd>
 
-   <dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(<var>message</var> [,
-   <var>transfer</var> ])</code></dt>
-   <dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(<var>message</var>
-   [, { <span data-x="dom-PostMessageOptions-transfer">transfer</span> } ])</code></dt>
+   <dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</span>(<var>message</var> [, <var>transfer</var> ])</code></dt>
+   <dt><code data-x=""><var>dedicatedWorkerGlobal</var>.<span subdfn data-x="dom-DedicatedWorkerGlobalScope-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> } ])</code></dt>
    <dd><p>Clones <var>message</var> and transmits it to the <code>Worker</code> object associated
    with <var>dedicatedWorkerGlobal</var>. <var>transfer</var> can be passed as a list of objects
    that are to be transferred rather than cloned.</p></dd>
@@ -102007,7 +102053,7 @@ interface <dfn interface>Worker</dfn> : <span>EventTarget</span> {
   undefined <span data-x="dom-Worker-terminate">terminate</span>();
 
   undefined <span data-x="dom-Worker-postMessage">postMessage</span>(any message, sequence&lt;<span data-x="idl-object">object</span>&gt; transfer);
-  undefined <span data-x="dom-Worker-postMessage-options">postMessage</span>(any message, optional <span>PostMessageOptions</span> options = {});
+  undefined <span data-x="dom-Worker-postMessage-options">postMessage</span>(any message, optional <span>StructuredSerializeOptions</span> options = {});
   attribute <span>EventHandler</span> <span data-x="handler-Worker-onmessage">onmessage</span>;
   attribute <span>EventHandler</span> <span data-x="handler-Worker-onmessageerror">onmessageerror</span>;
 };
@@ -102037,7 +102083,7 @@ enum <dfn enum>WorkerType</dfn> { "classic", "module" };
    <dd>Aborts <var>worker</var>'s associated global environment.</dd>
 
    <dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-postMessage">postMessage</span>(<var>message</var> [, <var>transfer</var> ])</code></dt>
-   <dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="dom-PostMessageOptions-transfer">transfer</span> } ])</code></dt>
+   <dt><code data-x=""><var>worker</var>.<span subdfn data-x="dom-Worker-postMessage-options">postMessage</span>(<var>message</var> [, { <span data-x="dom-StructuredSerializeOptions-transfer">transfer</span> } ])</code></dt>
    <dd><p>Clones <var>message</var> and transmits it to <var>worker</var>'s global environment.
    <var>transfer</var> can be passed as a list of objects that are to be transferred rather than
    cloned.</p></dd>