Expand structuredClone compatibility and benchmarks (#58735)

Summary:

Compare React Native structuredClone with ungap/structured-clone (**used by Expo**) and port the applicable upstream coverage. Add support for ArrayBuffer, DataView, typed arrays, boxed BigInt values, Error subclasses, deeply cloned causes, and safe __proto__ data properties. Serialization-only and JSON/lossy tests remain out of scope because React Native exposes a single-step cloning API.

Add ungap/structured-clone as a devDependency and benchmark each existing Fantom scenario against it.

Before — React Native implementation before this change:

### structuredClone (mode 🚀) ###

| (index) | Task name                | Latency avg (ns)  | Latency med (ns) | Throughput avg (ops/s) | Throughput med (ops/s) | Samples |
| ------- | ------------------------ | ----------------- | ---------------- | ---------------------- | ---------------------- | ------- |
| 0       | 'clone a string'         | '338.62 ± 0.05%'  | '330.00 ± 9.00'  | '3014547 ± 0.05%'      | '3030303 ± 84962'      | 2953184 |
| 1       | 'clone a basic array'    | '1587.6 ± 10.36%' | '1353.0 ± 19.00' | '734465 ± 0.42%'       | '739098 ± 10235'       | 638616  |
| 2       | 'clone a basic object'   | '1344.2 ± 8.81%'  | '1172.0 ± 20.00' | '828917 ± 0.33%'       | '853242 ± 14813'       | 743963  |
| 3       | 'clone a complex object' | '3370.6 ± 0.60%'  | '3255.0 ± 40.00' | '304183 ± 0.02%'       | '307220 ± 3822'        | 296680  |

After — React Native compared with ungap/structured-clone:

### structuredClone (mode 🚀) ###

| (index) | Task name                              | Latency avg (ns)  | Latency med (ns)  | Throughput avg (ops/s) | Throughput med (ops/s) | Samples |
| ------- | -------------------------------------- | ----------------- | ----------------- | ---------------------- | ---------------------- | ------- |
| 0       | 'React Native: clone a string'         | '348.44 ± 0.08%'  | '331.00 ± 1.00'   | '2927181 ± 0.04%'      | '3021148 ± 9155'       | 2869970 |
| 1       | 'ungap: clone a string'               | '2037.4 ± 11.17%' | '1592.0 ± 50.00'  | '617833 ± 0.09%'       | '628141 ± 19947'       | 490832  |
| 2       | 'React Native: clone a basic array'    | '1460.2 ± 8.39%'  | '1282.0 ± 20.00'  | '775137 ± 0.42%'       | '780031 ± 12362'       | 684824  |
| 3       | 'ungap: clone a basic array'          | '5112.8 ± 0.81%'  | '4718.0 ± 111.00' | '205586 ± 0.08%'       | '211954 ± 5107'        | 195589  |
| 4       | 'React Native: clone a basic object'   | '1373.8 ± 8.58%'  | '1152.0 ± 20.00'  | '842837 ± 0.46%'       | '868056 ± 15337'       | 727910  |
| 5       | 'ungap: clone a basic object'         | '8853.2 ± 0.76%'  | '8253.0 ± 141.00' | '117562 ± 0.05%'       | '121168 ± 2106'        | 112954  |
| 6       | 'React Native: clone a complex object' | '3539.4 ± 0.55%'  | '3456.0 ± 50.00'  | '288368 ± 0.02%'       | '289352 ± 4248'        | 282537  |
| 7       | 'ungap: clone a complex object'       | '21498 ± 0.72%'   | '20080 ± 301.00'  | '48208 ± 0.09%'        | '49801 ± 755'          | 46516   |

The benchmark shows no material regression in the existing implementation and React Native remains faster than ungap/structured-clone across all scenarios.

Changelog:
[General][Added] - Add ArrayBuffer, DataView, typed array, boxed BigInt, and Error subclass support to structuredClone

Differential Revision: D122156629

Author: rubennorte

flow-typed/npm/@ungap__structured-clone_v1.x.x.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+declare module '@ungap/structured-clone' {
+  declare export default function structuredClone<T>(value: T): T;
+}

package.json

@@ -74,6 +74,7 @@
     "@tsconfig/node22": "22.0.2",
     "@types/react": "^19.1.0",
     "@typescript-eslint/parser": "^8.59.2",
+    "@ungap/structured-clone": "^1.4.0",
     "ansi-regex": "^5.0.0",
     "ansi-styles": "^4.2.1",
     "babel-plugin-minify-dead-code-elimination": "^0.5.2",

packages/react-native/src/private/webapis/structuredClone/__tests__/structuredClone-benchmark-itest.js

@@ -12,6 +12,7 @@ import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
 
 import structuredClone from '../structuredClone';
 import * as Fantom from '@react-native/fantom';
+import ungapStructuredClone from '@ungap/structured-clone';
 
 const basicArray = [1, 2, 3];
 const basicObject = {a: 1, b: 2, c: 3};
@@ -29,15 +30,27 @@ const complexObject = {
 
 Fantom.unstable_benchmark
   .suite('structuredClone')
-  .test('clone a string', () => {
+  .test('React Native: clone a string', () => {
     structuredClone('hello world');
   })
-  .test('clone a basic array', () => {
+  .test('@ungap: clone a string', () => {
+    ungapStructuredClone('hello world');
+  })
+  .test('React Native: clone a basic array', () => {
     structuredClone(basicArray);
   })
-  .test('clone a basic object', () => {
+  .test('@ungap: clone a basic array', () => {
+    ungapStructuredClone(basicArray);
+  })
+  .test('React Native: clone a basic object', () => {
     structuredClone(basicObject);
   })
-  .test('clone a complex object', () => {
+  .test('@ungap: clone a basic object', () => {
+    ungapStructuredClone(basicObject);
+  })
+  .test('React Native: clone a complex object', () => {
     structuredClone(complexObject);
+  })
+  .test('@ungap: clone a complex object', () => {
+    ungapStructuredClone(complexObject);
   });

packages/react-native/src/private/webapis/structuredClone/__tests__/structuredClone-itest.js

@@ -67,6 +67,7 @@ describe('structuredClone', () => {
 
     expect(structuredClone(0)).toBe(0);
     expect(structuredClone(1)).toBe(1);
+    expect(Object.is(structuredClone(-0), -0)).toBe(true);
 
     expect(structuredClone(0n)).toBe(0n);
     expect(structuredClone(1n)).toBe(1n);
@@ -99,6 +100,12 @@ describe('structuredClone', () => {
     expect(booleanClone).not.toBe(booleanValue);
     expect(booleanClone).toBeInstanceOf(Boolean);
     expect(booleanClone.valueOf()).toBe(true);
+
+    const bigintValue = Object(1n);
+    const bigintClone = structuredClone(bigintValue);
+    expect(bigintClone).not.toBe(bigintValue);
+    expect(bigintClone).toBeInstanceOf(BigInt);
+    expect(bigintClone.valueOf()).toBe(1n);
   });
 
   it('throws with symbols, functions, WeakMap, WeakSet, Promise', () => {
@@ -223,6 +230,58 @@ describe('structuredClone', () => {
     expect(clone).toEqual(value);
   });
 
+  it('clones invalid dates', () => {
+    const value = new Date(NaN);
+    const clone = structuredClone(value);
+    expect(clone).not.toBe(value);
+    expect(clone).toBeInstanceOf(Date);
+    expect(Number.isNaN(clone.getTime())).toBe(true);
+  });
+
+  it('clones ArrayBuffer', () => {
+    const value = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]).buffer;
+    const clone = structuredClone(value);
+    expect(clone).not.toBe(value);
+    expect(clone).toBeInstanceOf(ArrayBuffer);
+    expect([...new Uint8Array(clone)]).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
+  });
+
+  it('clones DataView', () => {
+    const buffer = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]).buffer;
+    const value = new DataView(buffer);
+    const clone = structuredClone(value);
+    expect(clone).not.toBe(value);
+    expect(clone).toBeInstanceOf(DataView);
+    expect([...new Uint8Array(clone.buffer)]).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
+  });
+
+  it('clones typed arrays', () => {
+    const value = new Uint32Array([1, 2, 3]);
+    const clone = structuredClone(value);
+    expect(clone).not.toBe(value);
+    expect(clone).toBeInstanceOf(Uint32Array);
+    expect([...clone]).toEqual([1, 2, 3]);
+  });
+
+  it('preserves shared buffers between views', () => {
+    const buffer = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7]).buffer;
+    const value = {
+      typedArray: new Uint16Array(buffer, 2, 2),
+      dataView: new DataView(buffer, 1, 6),
+      buffer,
+    };
+
+    const clone = structuredClone(value);
+    expect(clone.buffer).not.toBe(buffer);
+    expect(clone.dataView.buffer).toBe(clone.buffer);
+    expect(clone.typedArray.buffer).toBe(clone.buffer);
+    expect(clone.dataView.byteOffset).toBe(value.dataView.byteOffset);
+    expect(clone.dataView.byteLength).toBe(value.dataView.byteLength);
+    expect(clone.typedArray.byteOffset).toBe(value.typedArray.byteOffset);
+    expect(clone.typedArray.length).toBe(value.typedArray.length);
+    expect([...clone.typedArray]).toEqual([...value.typedArray]);
+  });
+
   it('clones errors', () => {
     const cause = new Error('cause message');
     const value = new Error('error message', {cause});
@@ -261,6 +320,53 @@ describe('structuredClone', () => {
     expect(structuredClone(value).name).toBe('Error');
   });
 
+  it('preserves error subclasses', () => {
+    expect(structuredClone(new Error('boom'))).toBeInstanceOf(Error);
+    expect(structuredClone(new EvalError('boom'))).toBeInstanceOf(EvalError);
+    expect(structuredClone(new RangeError('boom'))).toBeInstanceOf(RangeError);
+    expect(structuredClone(new ReferenceError('boom'))).toBeInstanceOf(
+      ReferenceError,
+    );
+    expect(structuredClone(new SyntaxError('boom'))).toBeInstanceOf(
+      SyntaxError,
+    );
+    expect(structuredClone(new TypeError('boom'))).toBeInstanceOf(TypeError);
+    expect(structuredClone(new URIError('boom'))).toBeInstanceOf(URIError);
+  });
+
+  it('clones aggregate errors', () => {
+    const innerError = new TypeError('inner');
+    const value = new AggregateError([innerError, {foo: 'bar'}], 'outer');
+    const clone = structuredClone(value);
+    const clonedErrors = Array.from(clone.errors);
+    const clonedInnerError = ensureInstance(clonedErrors[0], TypeError);
+
+    expect(clone).not.toBe(value);
+    expect(clone).toBeInstanceOf(AggregateError);
+    expect(clone.message).toBe(value.message);
+    expect(clone.stack).toBe(value.stack);
+    expect(clone.errors).not.toBe(value.errors);
+    expect(clonedInnerError).not.toBe(innerError);
+    expect(clonedInnerError.message).toBe(innerError.message);
+    expect(clonedErrors[1]).toEqual({foo: 'bar'});
+  });
+
+  it('clones __proto__ as an own property', () => {
+    const value = JSON.parse('{"__proto__":{"foo":"bar"}}');
+    const clone = structuredClone(value);
+    const clonedValue = nullthrows(
+      Object.getOwnPropertyDescriptor(clone, '__proto__'),
+    ).value;
+    const originalValue = nullthrows(
+      Object.getOwnPropertyDescriptor(value, '__proto__'),
+    ).value;
+
+    expect(clone.foo).toBeUndefined();
+    expect(Object.hasOwn(clone, '__proto__')).toBe(true);
+    expect(clonedValue).not.toBe(originalValue);
+    expect(clonedValue).toEqual({foo: 'bar'});
+  });
+
   it('clones values deeply', () => {
     const value = {
       obj: {