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 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 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 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;
Takes the input value and returns a deep copy by performing the structured clone algorithm.
+ Transferable objects listed in the Throws a " The Let serialized be ?
+ StructuredSerializeWithTransfer(value, options[" Return ? StructuredDeserialize(serialized, this's
+ relevant Realm).[Transferable] IDL extended
@@ -9138,11 +9155,6 @@ o.myself = o;
understood to perform an implicit conversion to the
JavaScript value before invoking these algorithms.
Structured cloning API
+
+
+
+
+ structuredClone( value
+ [, { transfer } ] )transfer array are transferred, not
+ just cloned, meaning that they are no longer usable in the input value.DataCloneError" DOMException if any part of
+ the input value is not serializable.structuredClone(value,
+ options) method steps are:
+
+
+ transfer"]).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.
Let transfer be options["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 = [];
};Let transfer be options["transfer"].
If transfer contains this
MessagePort, then throw a "DataCloneError"
@@ -100403,7 +100451,8 @@ dictionary PostMessageOptions {
entangled, if any; otherwise let it be null.
Let options be «[ "transfer" → transfer ]».
Run the message port post message steps providing targetPort, message and options.
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.
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.