Define self.structuredClone()

Closes #793.

Author: surma

source

@@ -7967,13 +7967,24 @@ interface DOMStringList {
   
 
 
-
-
   Safe passing of structured data
 
+  To support passing JavaScript objects,
+  including platform objects, across 
+  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
+
+
+
+
+
   This section uses the terminology and typographic conventions from the JavaScript
   specification. 
 
+  
+
   Serializable objects
 
   Serializable objects support being serialized, and later deserialized, in a way
@@ -7984,6 +7995,8 @@ interface DOMStringList {
   Not all objects are serializable objects, and not all aspects of objects that are
   serializable objects are necessarily preserved when they are serialized.
 
+
+
   Platform objects can be serializable objects
 
   data-lt="Serializable" data-x="Serializable">[Serializable] IDL extended
@@ -8091,6 +8104,8 @@ interface DOMStringList {
   However, to better specify the behavior of certain more complex situations, the model was updated
   to make the serialization and deserialization explicit.
 
+  
+
   Transferable objects
 
 
@@ -8103,6 +8118,8 @@ interface DOMStringList {
   Transferring is an irreversible and non-idempotent operation. Once an object has
   been transferred, it cannot be transferred, or indeed used, again.
 
+
+
   Platform objects can be transferable objects
 
   data-lt="Transferable" data-x="Transferable">[Transferable] IDL extended
   understood to perform an implicit conversion to the
   JavaScript value before invoking these algorithms.
 
-  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.
-
   
 
   Call sites that are not invoked as a result of author code synchronously calling into a user
 
   
 
+  Structured cloning API
+
+  
+   result = self.structuredClone(value[, { transfer }])
+   
+    Takes the input value and returns a deep copy by performing the structured clone algorithm.
+
+
+    just cloned, meaning that they are no longer usable in the input value.
+
+    Throws a "DataCloneError" DOMException if any part of
+    the input value is not serializable.
+   
+  
+
+
+
+
+  data-x="dom-structuredClone">structuredClone(value,
+
+
+  
+   Let serialized be ?
+
+
+
+   Return ? StructuredDeserialize(serialized, this's
+   relevant Realm).
+  
+
+  
+
 
   Semantics, structure, and APIs of HTML documents
 
@@ -80416,7 +80460,7 @@ interface Window : EventTarget {
 Window includes GlobalEventHandlers;
 Window includes WindowEventHandlers;
 
-dictionary WindowPostMessageOptions : PostMessageOptions {
+dictionary WindowPostMessageOptions : StructuredSerializeOptions {
   USVString targetOrigin = "/";
 
 
@@ -94809,6 +94853,9 @@ interface mixin WindowOrWorkerGlobalScope {
   // ImageBitmap
   Promise<ImageBitmap> createImageBitmap(ImageBitmapSource image, optional ImageBitmapOptions options = {});
   Promise<ImageBitmap> createImageBitmap(ImageBitmapSource image, long sx, long sy, long sw, long sh, optional ImageBitmapOptions options = {});
+
+  // structured cloning
+  any structuredClone(any value, optional StructuredSerializeOptions options = {});
 };
 Window includes WindowOrWorkerGlobalScope;
 
@@ -99740,7 +99787,7 @@ function receiver(e) {
     and can contain certain data objects such as File Blob,
     FileList, and ArrayBuffer objects.
 
-    Objects listed in the PostMessageOptions-transfer">transfer member
+    Objects listed in the StructuredSerializeOptions-transfer">transfer member
     of options are transferred, not just cloned, meaning that they are no longer usable
     on the sending side.
 
@@ -99816,7 +99863,7 @@ function receiver(e) {
    
 
 
-
+
 
    Let serializeWithTransferResult be
    StructuredSerializeWithTransfer(message, transfer). Rethrow
@@ -99892,7 +99939,7 @@ function receiver(e) {
 
 
 
-   targetOrigin, "PostMessageOptions-transfer">transfer" →
+   targetOrigin, "StructuredSerializeOptions-transfer">transfer" →
    transfer ]».
 
    Run the window post message steps providing targetWindow,
@@ -100160,7 +100207,7 @@ interface MessageChannel {
   [Exposed=(Window,Worker,AudioWorklet), Transferable]
 interface MessagePort : EventTarget {
   undefined postMessage(any message, sequence<object> transfer);
-  undefined postMessage(any message, optional PostMessageOptions options = {});
+  undefined postMessage(any message, optional StructuredSerializeOptions options = {});
   undefined start();
   undefined close();
 
@@ -100169,8 +100216,8 @@ interface MessagePort : EventTarget {
   attribute EventHandler onmessageerror;
 };
 
-dictionary PostMessageOptions {
-  sequence<object> PostMessageOptions" data-x="dom-PostMessageOptions-transfer">transfer = [];
+dictionary StructuredSerializeOptions {
+  sequence<object> StructuredSerializeOptions" data-x="dom-StructuredSerializeOptions-transfer">transfer = [];
 
 
   
@@ -100313,7 +100360,7 @@ dictionary PostMessageOptions {
 
    
 
-
+
 
    If transfer contains this
    MessagePort, then throw a "DataCloneError"
@@ -100403,7 +100450,8 @@ dictionary PostMessageOptions {
    entangled, if any; otherwise let it be null.
 
 
-
+
+   transfer ]».
 
    Run the message port post message steps providing targetPort,
    message and options.
@@ -101272,7 +101320,7 @@ interface DedicatedWorkerGlobalScope : WorkerGlobalSc
   [Replaceable] readonly attribute DOMString name;
 
   undefined postMessage(any message, sequence<object> transfer);
-  undefined postMessage(any message, optional PostMessageOptions options = {});
+  undefined postMessage(any message, optional StructuredSerializeOptions options = {});
 
   undefined close();
 
@@ -101294,10 +101342,8 @@ interface DedicatedWorkerGlobalScope : WorkerGlobalSc
    data-x="concept-WorkerGlobalScope-name">name, i.e. the value given to the
    Worker constructor. Primarily useful for debugging.
 
-   dedicatedWorkerGlobal.postMessage(message [,
-
-   dedicatedWorkerGlobal.postMessage(message
-
+   dedicatedWorkerGlobal.postMessage(message [, transfer ])
+   dedicatedWorkerGlobal.postMessage(message [, { transfer } ])
    Clones message and transmits it to the Worker object associated
    with dedicatedWorkerGlobal. transfer can be passed as a list of objects
    that are to be transferred rather than cloned.
@@ -102007,7 +102053,7 @@ interface Worker : EventTarget {
   undefined terminate();
 
   undefined postMessage(any message, sequence<object> transfer);
-  undefined postMessage(any message, optional PostMessageOptions options = {});
+  undefined postMessage(any message, optional StructuredSerializeOptions options = {});
   attribute EventHandler onmessage;
   attribute EventHandler onmessageerror;
 };
@@ -102037,7 +102083,7 @@ enum WorkerType { "classic", "module" };
    Aborts worker's associated global environment.
 
    worker.postMessage(message [, transfer ])
-   worker.postMessage(message [, { PostMessageOptions-transfer">transfer } ])
+   worker.postMessage(message [, { StructuredSerializeOptions-transfer">transfer } ])
    Clones message and transmits it to worker's global environment.
    transfer can be passed as a list of objects that are to be transferred rather than
    cloned.