From 1e610d403f0b608e12aa5286d19fb67d603c94b5 Mon Sep 17 00:00:00 2001 From: Surma Date: Sat, 27 Jan 2018 21:59:30 +0000 Subject: [PATCH] Define self.structuredClone() Closes #793. --- source | 93 +++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 70 insertions(+), 23 deletions(-) diff --git a/source b/source index a58d36bf7cd..3a9a857bf09 100644 --- a/source +++ b/source @@ -7967,13 +7967,24 @@ interface DOMStringList { -
-

Safe passing of structured data

+

To support passing JavaScript objects, + including platform objects, across realm boundaries, this specification defines the following + 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 structuredClone() method.)

+ +
+

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 if their primary interface is decorated with the [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

Transferable objects support being transferred across 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 if their primary interface is decorated with the [Transferable] IDL extended @@ -9138,11 +9155,6 @@ o.myself = o; 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 @@ -9170,6 +9182,39 @@ o.myself = o;

+

Structured cloning API

+ +
+
result = self . structuredClone( value + [, { transfer } ] )
+
+

Takes the input value and returns a deep copy by performing the structured clone algorithm. + Transferable objects listed in the transfer array are transferred, not + 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.

+
+
+ +
+ +

The structuredClone(value, + options) method steps are:

+ +
    +

  1. Let serialized be ? + StructuredSerializeWithTransfer(value, options["transfer"]).

    2. + +

  2. Return ? StructuredDeserialize(serialized, this's + relevant Realm).

    3. +
+ +
+

Semantics, structure, and APIs of HTML documents

@@ -80416,7 +80461,7 @@ interface Window : EventTarget { Window includes GlobalEventHandlers; Window includes WindowEventHandlers; -dictionary WindowPostMessageOptions : PostMessageOptions { +dictionary WindowPostMessageOptions : StructuredSerializeOptions { USVString targetOrigin = "/"; }; @@ -94809,6 +94854,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; WorkerGlobalScope includes WindowOrWorkerGlobalScope; @@ -99740,7 +99788,7 @@ function receiver(e) { and can contain certain data objects such as File Blob, FileList, and ArrayBuffer objects.

-

Objects listed in the transfer member +

Objects listed in the transfer member of options are transferred, not just cloned, meaning that they are no longer usable on the sending side.

@@ -99816,7 +99864,7 @@ function receiver(e) {

  • Let transfer be options["transfer"].

    • + data-x="dom-StructuredSerializeOptions-transfer">transfer"].

  • Let serializeWithTransferResult be StructuredSerializeWithTransfer(message, transfer). Rethrow @@ -99892,7 +99940,7 @@ function receiver(e) {

  • Let options be «[ "targetOrigin" → - targetOrigin, "transfer" → + targetOrigin, "transfer" → transfer ]».

  • Run the window post message steps providing targetWindow, @@ -100160,7 +100208,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 +100217,8 @@ interface MessagePort : EventTarget {
   attribute EventHandler onmessageerror;
 };
 
-dictionary PostMessageOptions {
-  sequence<object> transfer = [];
+dictionary StructuredSerializeOptions {
+  sequence<object> transfer = [];
 };
    @@ -100313,7 +100361,7 @@ dictionary PostMessageOptions {

    1. Let transfer be options["transfer"].

      2. + data-x="dom-StructuredSerializeOptions-transfer">transfer"].

    2. If transfer contains this MessagePort, then throw a "DataCloneError" @@ -100403,7 +100451,8 @@ dictionary PostMessageOptions { entangled, if any; otherwise let it be null.

    3. Let options be «[ "transfer" → transfer ]».

      4. + data-x="dom-StructuredSerializeOptions-transfer">transfer" → + transfer ]».

    4. Run the message port post message steps providing targetPort, message and options.

      5. @@ -101272,7 +101321,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 +101343,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 [, - transfer ])
      -
      dedicatedWorkerGlobal.postMessage(message - [, { transfer } ])
      +
      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 +102054,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 +102084,7 @@ enum WorkerType { "classic", "module" };
      Aborts worker's associated global environment.
      worker.postMessage(message [, transfer ])
      -
      worker.postMessage(message [, { transfer } ])
      +
      worker.postMessage(message [, { 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.