Expose structuredClone

[surma]

This is in connection to #793, to make the discussion a bit more tangible.

This is my first time touching the HTML spec and also my first time writing a spec section from scratch. I probably didn’t do everything right, so please be thorough in your review.

• At least two implementers are interested (and none opposed):
  • Chrome
  • Firefox
• Tests are written and can be reviewed and commented upon at:
  • Add tests for structuredClone web-platform-tests/wpt#11069
• Implementation bugs are filed:
  • Chrome: https://bugs.chromium.org/p/chromium/issues/detail?id=1233571
  • Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1722576
  • Safari: https://bugs.webkit.org/show_bug.cgi?id=228331

(See WHATWG Working Mode: Changes for more details.)

---

/common-dom-interfaces.html ( diff )
/index.html ( diff )
/structured-data.html ( diff )
/web-messaging.html ( diff )
/webappapis.html ( diff )
/window-object.html ( diff )
/workers.html ( diff )

[annevk]

Some additional nits from me. Thanks for taking this on. If you can convince the powers that be at Chrome (and add some tests) we can move forward with this. (Potentially after adding transferables.)

Other than the comment, the spec text LGTM. However, this will need tests (and of course, browser support).

[surma]

WPT PR here: web-platform-tests/wpt#9218

[domenic]

I think this section is misplaced. It should be part of https://html.spec.whatwg.org/multipage/structured-data.html#safe-passing-of-structured-data, probably a new sub-section at the end.

For the dev edition, the contents of this new subsection (not including its heading) should be the only content of the "Safe passing of structured data" section.

[mathiasbynens]

Thanks for getting the ball rolling on this, Surma! 👍🏻

[surma]

@domenic I hope I understood your feedback right. PTAL

[tobireif]

As a web developer / JS API user I don't care so much about how the object gets cloned (whether the "structural clone algorithm" is used or a different way of deep cloning). The name of the method doesn't have to reflect the choice of algorithm used by the implementation.

Could the method be called clone() instead of structuredClone() ? or eg deepClone() or completeClone() or completeCopy() -
or perhaps just simply copy() ? (I haven't gone through all existing names)

[surma]

The name of the method doesn't have to reflect the choice of algorithm

I disagree. The name should to convey what kind of clone the result is. The method structuredClone give you a, well, structured clone. Meaning it directly implies what will be cloned and what will not be cloned (e.g. methods and prototypes are not cloned).

A name like deepClone or completeCopy could set expectations with the developer that are not being fulfilled. That’s how we end up with misnomers on the platform.

[tobireif]

I see, thanks for your reply.

Perhaps we do need a method deepClone() or completeCopy()?

[surma]

Yeah, we have talked about that. But cloning functions is not trivial. Please continue discussing that matter in #793 :)

[annevk]

To reiterate, my main problem with this proposal is that it doesn't expose the full underlying primitive, but rather a subset, and it's unclear how to extend it to expose it fully. The primitive we have is one that takes a value and a transfer list, and returns a value and a transfer list. And the transfer list can be independent from the value. This API just drops the return transfer list on the floor.

[surma]

Thanks for re-iterating, I didn’t get that before. That’s fair, I guess. I don’t see a problem with changing the returned value to {cloned, transferredValues}.

[domenic]

I'm not sure that primitive is terribly important. I think it's more for handling cases where for whatever reason you don't put the transferred values inside the cloned data, and for spec convenience in not making you dig through to find those values, but IMO such cases are not an important part of the primitive...

[surma]

I agree, but I’m also not sure if we are thinking of everything that could be needed in the future. I’ll leave that decision up to you all, I don’t have very strong feelings either way, although in terms of developer ergonomics and arguably the current 99% use-case, returning just the clone seems more desirable.

[jeremyroman]

FWIW, +1 for just returning the deserialized values. It'd be really easy for a caller to get if they wanted, be serializing {data, transferList} themselves. Currently [[TransferredValues]] is only exposed insofar as MessagePort objects are extracted from there and separately exposed. As a result, Blink doesn't actually keep the original transfer list in order at present (we have separate lists for ports, buffers, etc.).

[surma]

The original PR for tests got side-tracked and the actual PR for adding tests for structuredClone() now lives in web-platform-tests/wpt#11069.

[surma]

Just wondering: I am not sure what the result of the conversation so far is. Have we reached some sort of consensus weather transferList should be exposed by structuredClone()? What are we missing to qualify for “implementer interest”?

[domenic]

I don't know about consensus, but I feel it should definitely be there, and my read of @annevk was that he didn't feel too strongly against it...

What we're missing in terms of implementer interest is outlined in https://whatwg.org/working-mode#additions. So far I don't see any browser engineers saying "we would like to implement this soon" on this thread.

[annevk]

I suspect Firefox would adopt this pretty quickly, but it'd be good if someone could go over #793 (comment) and work through @wanderview's concern.

[annevk]

Okay, maybe the answer here is that we update the note that starts with

This specification used to define a "structured clone" algorithm

to instead say that is the colloquial name and also the name of the API (xref)?

[annevk]

Looks great, thanks!

[annevk]

Suggested change

	data-x="dom-structuredClone">structuredClone()</code> function.)</p>
	data-x="dom-structuredClone">structuredClone()</code> method.)</p>

[domenic]

Hooray! 6+ years after the original feature request, and 3.5 years after the original PR, this is finally merged!

I've updated the OP with implementation bug links for all browsers.

[sideshowbarker]

Hooray! 6+ years after the original feature request, and 3.5 years after the original PR, this is finally merged!

🎉 I’ll make time to update the related MDN docs