doc: add note about uncloneable objects

Signed-off-by: James M Snell <[email protected]>

PR-URL: #36534
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Franziska Hinkelmann <[email protected]>

doc/api/worker_threads.md

@@ -547,11 +547,6 @@ const otherChannel = new MessageChannel();
 port2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]);
 ```
 
-Because the object cloning uses the structured clone algorithm,
-non-enumerable properties, property accessors, and object prototypes are
-not preserved. In particular, [`Buffer`][] objects are read as
-plain [`Uint8Array`][]s on the receiving side.
-
 The message object is cloned immediately, and can be modified after
 posting without having side effects.
 
@@ -606,6 +601,49 @@ The `ArrayBuffer`s for `Buffer` instances created using
 transferred but doing so renders all other existing views of
 those `ArrayBuffer`s unusable.
 
+#### Considerations when cloning objects with prototypes, classes, and accessors
+
+Because object cloning uses the [HTML structured clone algorithm][],
+non-enumerable properties, property accessors, and object prototypes are
+not preserved. In particular, [`Buffer`][] objects will be read as
+plain [`Uint8Array`][]s on the receiving side, and instances of JavaScript
+classes will be cloned as plain JavaScript objects.
+
+```js
+const b = Symbol('b');
+
+class Foo {
+  #a = 1;
+  constructor() {
+    this[b] = 2;
+    this.c = 3;
+  }
+
+  get d() { return 4; }
+}
+
+const { port1, port2 } = new MessageChannel();
+
+port1.onmessage = ({ data }) => console.log(data);
+
+port2.postMessage(new Foo());
+
+// Prints: { c: 3 }
+```
+
+This limitation extends to many built-in objects, such as the global `URL`
+object:
+
+```js
+const { port1, port2 } = new MessageChannel();
+
+port1.onmessage = ({ data }) => console.log(data);
+
+port2.postMessage(new URL('https://example.org'));
+
+// Prints: { }
+```
+
 ### `port.ref()`
 <!-- YAML
 added: v10.5.0