Skip to content

Implement structuredClone() in TypeScript behind an autogate - #7977

Merged
bartlomieju merged 10 commits into
mainfrom
biwanczuk/structured-clone-ts
Nov 19, 2026
Merged

bartlomieju merged 10 commits into
mainfrom
biwanczuk/structured-clone-ts

Conversation

@bartlomieju

@bartlomieju bartlomieju commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Behind the TS_STRUCTURED_CLONE autogate, replace the JSG structuredClone
method on ServiceWorkerGlobalScope.prototype with a TypeScript
implementation installed by the per-isolate bootstrap (GS-4 in the API
migration catalogue). Like TS_URL and TS_EVENT_SOURCE, it replaces the
C++ method rather than sitting next to it: under the autogate,
global-scope.h leaves out the C++ JSG_METHOD, and main.ts installs the
TypeScript method where JSG would, with the same attributes.

The TypeScript side (src/per_isolate/structured-clone.ts) is the WebIDL
layer: it checks the receiver, requires the value argument, and converts
the StructuredSerializeOptions dictionary, using captured primordials.
transfer is read as WebIDL reads a sequence: [Symbol.iterator]
and next once each, with the iterator left open when an element is
rejected. The clone itself goes through a new native
utils.structuredClone(), which calls the same jsg::structuredClone as
the C++ method, so which values clone, which objects transfer, and the
errors for either are unchanged.

Divergences from the C++ method, all in the argument conversion, each
pinned by a test and tabled in src/tests/structured-clone/AGENTS.md:

  1. structuredClone.length is 1 (WebIDL) rather than 0.
  2. Function.prototype.toString gives the method's source rather than
    [native code].
  3. transfer accepts any iterable (WebIDL sequence) rather than
    only Arrays.
  4. A rejected transfer reads "... not of type 'sequence'."
    rather than "... not of type 'Array'.".
  5. A non-object transfer element fails the conversion with a TypeError
    rather than reaching the serializer's "Object is not transferable".
  6. An array's [Symbol.iterator] is called once rather than not at all.
  7. The serializer's own deviations from the HTML spec are shared by both
    implementations: duplicate or detached buffers are accepted, and
    non-ArrayBuffer objects throw a TypeError instead of a DataCloneError.

    Compatibility: no change while the autogate is off. With it on, the
    divergences above apply to every Worker.

    Types: structuredClone() and StructuredSerializeOptions are now declared
    in types/defines/structured-clone.d.ts, as URL, URLPattern and
    DOMException are, and global-scope.h overrides the C++ method and its
    options struct to never. The signatures are unchanged; they move within
    the generated snapshot. Since the types no longer come from
    JSG_METHOD(structuredClone), retiring the C++ method leaves them as they
    are.


    Not for the merge commit:

    The first commit predates review and uses an experimental compat flag.
    Gate the TypeScript structuredClone() behind an autogate replaces that
    flag with the autogate.

    Tests

    src/tests/structured-clone/ runs one module set against both implementations. Each cell says
    which one it runs through a USING_TS_IMPL binding, since user code cannot read an autogate; the
    C++ cell has no @all-autogates variant. The full suite passes with the autogate on in every
    @all-autogates variant.

    Benchmarks

    src/bench/serialization/ now has structured-clone-cpp and structured-clone-ts, running the
    same modules, with cases for the options and a structured-clone-cold service whose startup
    group times the first calls in a new isolate. Medians from a local --config=benchmark run
    (Apple Silicon, V8 15.8):

    Case C++ TS TS/C++
    empty object 280 ns 260 ns 0.93
    flat object 16 keys 791 ns 772 ns 0.98
    tree 4x4 (341 objects) 49.2 µs 58.6 µs 1.19
    tree 6x4 (5461 objects) 807 µs 974 µs 1.21
    array of 1000 objects 104.0 µs 104.8 µs 1.01
    array of 1000 class instances 157.8 µs 159.3 µs 1.01
    array of 1000 numbers 9.57 µs 9.57 µs 1.00
    string 8192 540 ns 552 ns 1.02
    small object, options without transfer 334 ns 303 ns 0.91
    small object, empty transfer 362 ns 311 ns 0.86
    transfer 1 ArrayBuffer 624 ns 582 ns 0.93
    transfer 16 ArrayBuffers 5.75 µs 5.51 µs 0.96
    cold: startup:script 650 µs ±3% 663 µs ±2% 1.02
    cold: startup:worker (first calls) 407 µs ±2% 433 µs ±4% 1.06

    The options conversion is cheaper in TypeScript than in JSG. Cold, the first calls cost a few
    tens of microseconds more, within about twice the confidence interval.

    Open: the tree cases are consistently about 20% slower under the TypeScript config, though
    the serializer is the same. The cost is in V8's ValueDeserializer: its profile shows
    property-name internalization and transition-array searches where the C++ config mostly takes the
    ExpectedTransition fast path. It depends on the isolate's map-transition state: in a module
    that holds fewer inputs, the same tree clones at parity. The cause is not yet identified.

Behind the experimental typescript_implemented_structured_clone flag,
which needs the per-isolate-javascript-bootstrap autogate, replace the
JSG structuredClone method on ServiceWorkerGlobalScope.prototype with a
TypeScript one (GS-4 in the API migration catalogue). As with
typescript_implemented_streams, setting the flag without the autogate
fails worker startup.

The TypeScript side is the WebIDL layer: the receiver check, the
argument count and the options conversion. The clone itself goes
through a new native utils.structuredClone(), which calls the same
jsg::structuredClone the C++ method uses, so cloning, transfer and
their errors are unchanged.

src/tests/structured-clone/ runs one module set against both
implementations and tables their divergences, all in the WebIDL layer:
length 1 instead of 0, non-native source text, transfer accepting any
iterable rather than only Arrays and read through its iterator, and the
messages for a rejected transfer member or element.

Compatibility: no change without the experimental flag; the generated
types are unchanged, since they still come from the C++ method.
@codecov-commenter

codecov-commenter commented Oct 25, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.65217% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 67.03%. Comparing base (e8c36f9) to head (5ee2e70).
⚠️ Report is 5 commits behind head on main.

Files with missing lines Patch % Lines
src/workerd/api/global-scope.h 66.66% 0 Missing and 1 partial ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #7977   +/-   ##
=======================================
  Coverage   67.03%   67.03%           
=======================================
  Files         799      799           
  Lines      206637   206658   +21     
  Branches    32062    32065    +3     
=======================================
+ Hits       138519   138538   +19     
  Misses      49321    49321           
- Partials    18797    18799    +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@piscisaureus piscisaureus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks right. Keeping the serializer native is the important part.

Nit: Symbol.iterator is fetched twice in toObjectSequence (once for the typeof check and again by for...of); WebIDL reads it once. Please add a cold-isolate clone microbench before this goes default-on.

@jasnell jasnell left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Long term we're not going to be using the compat flag mechanism for these, especially since these are going to be replacing the original impl and not sitting next to it. Instead, these should be gated by autogate

Comment thread src/workerd/io/worker.c++ Resolved
…clone-ts

# Conflicts:
#	src/per_isolate/AGENTS.md
#	src/per_isolate/main.ts
#	src/per_isolate/per_isolate-env.d.ts
#	src/workerd/api/per-isolate-bootstrap.c++
#	src/workerd/io/compatibility-date.capnp
#	src/workerd/io/worker.c++
Replace the experimental typescript_implemented_structured_clone compat
flag with the TS_STRUCTURED_CLONE autogate. The TypeScript method is a
replacement for the C++ one rather than an alternative a Worker opts
into, so, like TS_URL and TS_EVENT_SOURCE, it rolls out per process
instead of per Worker.

Under the autogate, global-scope.h leaves out the C++ JSG_METHOD and
main.ts installs the TypeScript method where JSG would, on
ServiceWorkerGlobalScope.prototype with all three attributes true.

User code cannot read an autogate, so each cell of the structuredClone
suite says which implementation it runs through a USING_TS_IMPL binding,
as the URL suite does. The C++ cell drops its @all-autogates variant,
which would run the TypeScript implementation.

Compatibility: no change while the autogate is off. With it on, the
divergences tabled in src/tests/structured-clone/AGENTS.md apply to
every Worker, all of them in the WebIDL conversion of the arguments;
cloning and transfer go through the same native serializer. Generated
types are unchanged.
toObjectSequence() used for...of, which differs observably from WebIDL's
"create a sequence from an iterable": it read [Symbol.iterator] again
after checking it, and it closed the iterator when an element failed
the conversion to object. Spell the steps out instead: read the method
and next once each, check that the iterator and each result are objects,
and leave the iterator open on a rejected element.

Only the TypeScript implementation, under TS_STRUCTURED_CLONE, is
affected; C++ accepts only Arrays and reads them by index.
Split the structuredClone() benchmark into a config per implementation,
as src/bench/url does: structured-clone-cpp and structured-clone-ts
(TS_STRUCTURED_CLONE) run the same modules. The C++ config has no
@all-autogates variant, which would run the TypeScript one.

Add cases for the options, whose conversion is where the
implementations differ: no transfer, an empty transfer, and transfers
of 1 and 16 ArrayBuffers. Add a structured-clone-cold service whose
top level makes the first structuredClone() calls in the isolate, so
its startup group times them, and the bootstrap that installs the
function, in a new isolate per sample.
@bartlomieju bartlomieju changed the title Implement structuredClone() in the per-isolate bootstrap Implement structuredClone() in the per-isolate bootstrap behind an autogate Nov 16, 2026
@bartlomieju
bartlomieju marked this pull request as ready for review November 16, 2026 13:36
@bartlomieju
bartlomieju requested review from a team as code owners November 16, 2026 13:36

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 212b1789.

This review, of 5ddbcd5c

💬 Approved with comments — No defects found. The only note (INFO) asks for the decision to accept the six API divergences, which apply to every Worker under the autogate, to be recorded, as the repository's compatibility rules require.

Findings: 1 info (1 is an inline comment on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

Sound implementation following the TS_URL pattern; one note on recording the compatibility decision.

Recommendation: 💬 Optional Nits

  • [INFO] Record the decision to accept the six observable structuredClone() divergences that apply to every Worker under TS_STRUCTURED_CLONE (src/workerd/util/autogate.h:118)
View full review

The TypeScript layer and the native StructuredClone binding look correct. The note below concerns the compatibility record for the autogate rollout.


✅ All other checks passed

🔒 Security: ✅ LGTM

The native function lives on the internal utils object. It reads only a dense array built by the bootstrap, so reading that array runs no user code. The conversion uses captured primordials, and the receiver check is at least as strict as the C++ method's.


📖 AGENTS.md: ✅ LGTM

No issues found.


⚡ Performance: ✅ LGTM

The options conversion is at parity or faster. The tree-clone slowdown is already tracked as open in the description, and a cold-isolate benchmark is included.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 5ddbcd5c

Comment thread src/workerd/util/autogate.h Resolved
Comment thread src/per_isolate/structured-clone.ts Resolved
Comment thread src/per_isolate/structured-clone.ts Resolved
Comment thread src/workerd/api/global-scope.h Resolved
The receiver and options checks test for undefined or null with `!= null`,
as elsewhere in the per-isolate bootstrap. Behaviour is unchanged.
@bartlomieju
bartlomieju requested a review from jasnell November 16, 2026 16:39

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 5d5a2f35.

This review, of 212b1789

✅ Approved — No findings. The switch to != null checks in structured-clone.ts keeps the same behaviour, and the earlier note about recording the divergences is resolved.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

No issues found. The native function reads only an array built by the bootstrap, and the conversion uses captured primordials.


📖 AGENTS.md: ✅ LGTM

No issues found.


📋 Code Quality: ✅ LGTM

The != null receiver and options checks match the bootstrap's convention, and their behaviour is unchanged. The native binding is registered in the names and values arrays of createUtilsObject, and the JSG method is left out under the autogate in global-scope.h.


⚡ Performance: ✅ LGTM

The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 212b1789

The generated types took structuredClone() and StructuredSerializeOptions
from the C++ method. Removing JSG_METHOD(structuredClone) once the
TypeScript implementation replaces it would have dropped
StructuredSerializeOptions, which only that method's parameter brought in,
and left the remaining declarations referring to a missing type.

As with URL, URLPattern and DOMException, the declarations now live in
types/defines/structured-clone.d.ts, and global-scope.h overrides the
method and its options struct to never. The signatures are unchanged;
they move within the snapshot. Generating types without the
JSG_METHOD gives identical output.

A type test, types/test/types/structured-clone.ts, covers the global
function, the global scope member and the options type.
@bartlomieju
bartlomieju requested a review from a team as a code owner November 17, 2026 13:45
@bartlomieju
bartlomieju requested a review from NuroDev November 17, 2026 13:45

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of d9a57ffc.

This review, of 5d5a2f35

✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.


📖 AGENTS.md: ✅ LGTM

The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.


📋 Code Quality: ✅ LGTM

The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.


⚡ Performance: ✅ LGTM

The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 5d5a2f35

@jasnell jasnell left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not overly concerned with the perf gap on this. We can investigate further optimizations later.

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 5ee2e70d.

This review, of d9a57ffc

✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.


📖 AGENTS.md: ✅ LGTM

The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.


📋 Code Quality: ✅ LGTM

The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.


⚡ Performance: ✅ LGTM

The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: d9a57ffc — same changes as 5d5a2f35, so this is that commit's review (no new review was run; line numbers are as of 5d5a2f35)

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.


📖 AGENTS.md: ✅ LGTM

The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.


📋 Code Quality: ✅ LGTM

The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.


⚡ Performance: ✅ LGTM

The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 5ee2e70d — same changes as 5d5a2f35, so this is that commit's review (no new review was run; line numbers are as of 5d5a2f35)

@bartlomieju bartlomieju changed the title Implement structuredClone() in the per-isolate bootstrap behind an autogate Implement structuredClone() in TypeScript behind an autogate Nov 19, 2026
@bartlomieju
bartlomieju merged commit 7dfb949 into main Nov 19, 2026
24 of 26 checks passed
@bartlomieju
bartlomieju deleted the biwanczuk/structured-clone-ts branch November 19, 2026 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants