README.md

Structured cloning and transfer

Overview

Structured cloning algorithm defines the semantics of copying a well-defined subset of ECMAScript
objects between Code Realms. This algorithm is extensible by host enviroment to support cloning of host objects.

Optionally, some kinds of objects may support a "transfer" operation, the effect of which is to transfer
"ownership" of some resource associated with an object to a different Code Realm.
The object then becomes unusable in the source Code Realm.

HTML spec will be updated to refer to this specification of the StructuredClone algorithm.

We introduce a StructuredClone operator.

Transferable objects carry a [[Transfer]] internal data property that is either a transfer operator or "neutered",
and an [[OnSuccessfulTransfer]] internal method.

Objects defined outside ECMAScript need to define a [[Clone]] internal method that returns a copy of the
object.

Note: The first iteration is not user-pluggable. It is about moving the semantics into ECMAScript
proper and tying them down.

StructuredClone(input, transferList, targetRealm)

The operator StructuredClone either returns a structured clone of input or throws an exception.
A structured clone of an object input is an object in Code Realm targetRealm. transferList is a list of objects that should be transferred during cloning of input.

Let memory be a map of source-to-destination object mappings.

For each object transferable in transferList:

If transferable does not have a [[Transfer]] internal data property whose value is an operator,
throw a DataCloneError exception.

Let transferResult be a result of a call to a transferable's internal method
[[Transfer]] with argument targetRealm.

ReturnIfAbrupt( transferResult )

Append a mapping from transferable to transferResult to memory.

Let clone be the result of InternalStructuredClone( input, memory, targetRealm ).

ReturnIfAbrupt( clone ).

For each object transferable in transferList:

Let transferResult be a target of mapping from transferable in memory.