implement structuredClone (#33796)

implement structuredClone with credit to Deno.
this is our first op that doesn't use `convex_macro::v8_op` because it wants to do its own serde.
some of the options are simplified away because they aren't hit by the structuredClone codepath. And I skipped some of the optimizations, like calling `slice` to clone TypedArray subclasses, because converting the primordials seemed tricky.

added a bunch of tests that i thought were relevant. haven't yet looked through the deno tests to see what other cases we might want to check.

GitOrigin-RevId: 9f72cca9e25db1d51149d62fa07b04961b5bb83a

Author: ldanilek

crates/isolate/src/ops/mod.rs

@@ -13,6 +13,7 @@ mod http;
 mod random;
 mod storage;
 mod stream;
+mod structured_clone;
 mod text;
 mod time;
 mod validate_args;
@@ -43,6 +44,7 @@ use deno_core::{
 };
 use rand_chacha::ChaCha12Rng;
 use sourcemap::SourceMap;
+use structured_clone::op_structured_clone;
 use uuid::Uuid;
 use validate_returns::op_validate_returns;
 use value::{
@@ -389,6 +391,7 @@ pub fn run_op<'b, P: OpProvider<'b>>(
         "textEncoder/normalizeLabel" => op_text_encoder_normalize_label(provider, args, rv)?,
         "atob" => op_atob(provider, args, rv)?,
         "btoa" => op_btoa(provider, args, rv)?,
+        "structuredClone" => op_structured_clone(provider, args.get(1), rv)?,
         "environmentVariables/get" => op_environment_variables_get(provider, args, rv)?,
         "getTableMappingWithoutSystemTables" => {
             op_get_table_mapping_without_system_tables(provider, args, rv)?

crates/isolate/src/ops/structured_clone.rs

@@ -0,0 +1,170 @@
+// Copyright 2018-2025 the Deno authors. All rights reserved. MIT license.
+// https://github.com/denoland/deno_core/blob/main/core/ops_builtin_v8.rs
+
+use deno_core::v8::{
+    self,
+    ValueDeserializerHelper,
+    ValueSerializerHelper,
+};
+use errors::ErrorMetadata;
+
+use super::OpProvider;
+
+// NOTE: not using `v8_op` macro because we want to handle serde ourselves.
+pub fn op_structured_clone<'b, P: OpProvider<'b>>(
+    provider: &mut P,
+    value: v8::Local<v8::Value>,
+    mut rv: v8::ReturnValue,
+) -> anyhow::Result<()> {
+    let data = op_serialize(provider.scope(), value)?;
+    let value = op_deserialize(provider.scope(), data)?;
+    rv.set(value);
+    Ok(())
+}
+
+// The following is copied from `deno_core/core/ops_builtin_v8.rs`
+// With simplifications to remove unused options.
+struct SerializeDeserialize {
+    host_object_brand: Option<v8::Global<v8::Symbol>>,
+}
+
+impl v8::ValueSerializerImpl for SerializeDeserialize {
+    #[allow(unused_variables)]
+    fn throw_data_clone_error<'s>(
+        &mut self,
+        scope: &mut v8::HandleScope<'s>,
+        message: v8::Local<'s, v8::String>,
+    ) {
+        let error = v8::Exception::type_error(scope, message);
+        scope.throw_exception(error);
+    }
+
+    fn get_shared_array_buffer_id<'s>(
+        &mut self,
+        _scope: &mut v8::HandleScope<'s>,
+        _shared_array_buffer: v8::Local<'s, v8::SharedArrayBuffer>,
+    ) -> Option<u32> {
+        None
+    }
+
+    fn get_wasm_module_transfer_id(
+        &mut self,
+        _scope: &mut v8::HandleScope<'_>,
+        _module: v8::Local<v8::WasmModuleObject>,
+    ) -> Option<u32> {
+        None
+    }
+
+    fn has_custom_host_object(&mut self, _isolate: &mut v8::Isolate) -> bool {
+        true
+    }
+
+    fn is_host_object<'s>(
+        &mut self,
+        scope: &mut v8::HandleScope<'s>,
+        object: v8::Local<'s, v8::Object>,
+    ) -> Option<bool> {
+        if let Some(symbol) = &self.host_object_brand {
+            let key = v8::Local::new(scope, symbol);
+            object.has_own_property(scope, key.into())
+        } else {
+            Some(false)
+        }
+    }
+
+    fn write_host_object<'s>(
+        &mut self,
+        scope: &mut v8::HandleScope<'s>,
+        _object: v8::Local<'s, v8::Object>,
+        _value_serializer: &mut dyn v8::ValueSerializerHelper,
+    ) -> Option<bool> {
+        let message = v8::String::new(scope, "Unsupported object type").unwrap();
+        self.throw_data_clone_error(scope, message);
+        None
+    }
+}
+
+impl v8::ValueDeserializerImpl for SerializeDeserialize {
+    fn get_shared_array_buffer_from_id<'s>(
+        &mut self,
+        _scope: &mut v8::HandleScope<'s>,
+        _transfer_id: u32,
+    ) -> Option<v8::Local<'s, v8::SharedArrayBuffer>> {
+        None
+    }
+
+    fn get_wasm_module_from_id<'s>(
+        &mut self,
+        _scope: &mut v8::HandleScope<'s>,
+        _clone_id: u32,
+    ) -> Option<v8::Local<'s, v8::WasmModuleObject>> {
+        None
+    }
+
+    fn read_host_object<'s>(
+        &mut self,
+        scope: &mut v8::HandleScope<'s>,
+        _value_deserializer: &mut dyn v8::ValueDeserializerHelper,
+    ) -> Option<v8::Local<'s, v8::Object>> {
+        let message: v8::Local<v8::String> =
+            v8::String::new(scope, "Failed to deserialize host object").unwrap();
+        let error = v8::Exception::error(scope, message);
+        scope.throw_exception(error);
+        None
+    }
+}
+
+pub fn op_serialize(
+    scope: &mut v8::HandleScope,
+    value: v8::Local<v8::Value>,
+) -> anyhow::Result<Vec<u8>> {
+    let key = v8::String::new(scope, "Deno.core.hostObject").unwrap();
+    let symbol = v8::Symbol::for_key(scope, key);
+    let host_object_brand = Some(v8::Global::new(scope, symbol));
+
+    let serialize_deserialize = Box::new(SerializeDeserialize { host_object_brand });
+    let mut value_serializer = v8::ValueSerializer::new(scope, serialize_deserialize);
+    value_serializer.write_header();
+
+    let scope = &mut v8::TryCatch::new(scope);
+    let ret = value_serializer.write_value(scope.get_current_context(), value);
+    if scope.has_caught() || scope.has_terminated() {
+        scope.rethrow();
+        // Dummy value, this result will be discarded because an error was thrown.
+        Ok(vec![])
+    } else if let Some(true) = ret {
+        let vector = value_serializer.release();
+        Ok(vector)
+    } else {
+        // TODO: incorrect error type, should be TypeError
+        Err(ErrorMetadata::bad_request("SerializeFailed", "Failed to serialize response").into())
+    }
+}
+
+pub fn op_deserialize<'a>(
+    scope: &mut v8::HandleScope<'a>,
+    data: Vec<u8>,
+) -> anyhow::Result<v8::Local<'a, v8::Value>> {
+    let serialize_deserialize = Box::new(SerializeDeserialize {
+        host_object_brand: None,
+    });
+    let mut value_deserializer = v8::ValueDeserializer::new(scope, serialize_deserialize, &data);
+    let parsed_header = value_deserializer
+        .read_header(scope.get_current_context())
+        .unwrap_or_default();
+    if !parsed_header {
+        return Err(
+            // TODO: incorrect error type, should be RangeError
+            ErrorMetadata::bad_request("DeserializeFailed", "could not deserialize value").into(),
+        );
+    }
+
+    let value = value_deserializer.read_value(scope.get_current_context());
+    match value {
+        Some(deserialized) => Ok(deserialized),
+        None => Err(
+            // TODO: incorrect error type, should be RangeError
+            ErrorMetadata::bad_request("DeserializeFailed", "could not deserialize value").into(),
+        ),
+    }
+}

crates/isolate/src/tests/js_builtins.rs

@@ -207,3 +207,16 @@ async fn test_set_timeout(rt: TestRuntime) -> anyhow::Result<()> {
         Ok(())
     }).await
 }
+
+#[convex_macro::test_runtime]
+async fn test_structured_clone(rt: TestRuntime) -> anyhow::Result<()> {
+    UdfTest::run_test_with_isolate2(rt, async move |t: UdfTestType| {
+        must_let!(let ConvexValue::String(r) = t.query("js_builtins/structuredClone", assert_obj!()).await?);
+        assert_eq!(String::from(r), "success".to_string());
+
+        let e = t.query_js_error("js_builtins/structuredClone:withTransfer", assert_obj!()).await?;
+        assert_contains(&e, "structuredClone with transfer not supported");
+        Ok(())
+    })
+    .await
+}

npm-packages/udf-runtime/src/02_structured_clone.ts

@@ -0,0 +1,15 @@
+import { performOp } from "udf-syscall-ffi";
+import { throwUncatchableDeveloperError } from "./helpers";
+
+function structuredClone(value: any, options?: { transfer: any[] }) {
+  if (options !== undefined) {
+    return throwUncatchableDeveloperError(
+      "structuredClone with transfer not supported",
+    );
+  }
+  return performOp("structuredClone", value);
+}
+
+export const setupStructuredClone = (global: any) => {
+  global.structuredClone = structuredClone;
+};

npm-packages/udf-runtime/src/setup.ts

@@ -17,6 +17,7 @@ import { setupSourceMapping } from "./errors.js";
 import { throwUncatchableDeveloperError } from "./helpers.js";
 import { getBlob, getResponse, storeBlob, storeRequest } from "./storage.js";
 import { performOp } from "udf-syscall-ffi";
+import { setupStructuredClone } from "./02_structured_clone.js";
 
 /**
  * Set up the global object for a UDF context with deterministic Convex APIs.
@@ -39,6 +40,7 @@ export function setup(global: any) {
   setupDOMException(global);
   setupConsole(global);
   setupEvent(global);
+  setupStructuredClone(global);
   setupTimers(global);
   setupAbortSignal(global);
   setupStreams(global);

npm-packages/udf-tests/convex/_generated/api.d.ts

@@ -56,6 +56,7 @@ import type * as js_builtins_request from "../js_builtins/request.js";
 import type * as js_builtins_response from "../js_builtins/response.js";
 import type * as js_builtins_setTimeout from "../js_builtins/setTimeout.js";
 import type * as js_builtins_stream from "../js_builtins/stream.js";
+import type * as js_builtins_structuredClone from "../js_builtins/structuredClone.js";
 import type * as js_builtins_testHelpers from "../js_builtins/testHelpers.js";
 import type * as js_builtins_textEncoder from "../js_builtins/textEncoder.js";
 import type * as js_builtins_url from "../js_builtins/url.js";
@@ -131,6 +132,7 @@ declare const fullApi: ApiFromModules<{
   "js_builtins/response": typeof js_builtins_response;
   "js_builtins/setTimeout": typeof js_builtins_setTimeout;
   "js_builtins/stream": typeof js_builtins_stream;
+  "js_builtins/structuredClone": typeof js_builtins_structuredClone;
   "js_builtins/testHelpers": typeof js_builtins_testHelpers;
   "js_builtins/textEncoder": typeof js_builtins_textEncoder;
   "js_builtins/url": typeof js_builtins_url;

npm-packages/udf-tests/convex/js_builtins/structuredClone.ts

@@ -0,0 +1,120 @@
+import { query } from "../_generated/server";
+import { assert } from "chai";
+import { wrapInTests } from "./testHelpers";
+
+function testStructuredCloneJson() {
+  // Test simple string
+  const stringValue = "hello";
+  const clonedString = structuredClone(stringValue);
+  assert.strictEqual(clonedString, stringValue);
+
+  // Test nested object
+  const objectValue = { a: ["b", "c"], d: 1 };
+  const clonedObject = structuredClone(objectValue);
+  assert.deepEqual(clonedObject, objectValue);
+  assert.notEqual(clonedObject, objectValue); // Different object reference
+}
+
+function testStructuredCloneArrayBuffer() {
+  const size = 5;
+  const buffer = new ArrayBuffer(size);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < size; i++) {
+    view[i] = i % 256;
+  }
+  const cloned = structuredClone(buffer);
+  const clonedView = new Uint8Array(cloned);
+  assert.instanceOf(cloned, ArrayBuffer);
+  assert.deepEqual(Array.from(clonedView), [0, 1, 2, 3, 4]);
+}
+
+function testStructuredCloneTypedArray() {
+  const values = [1, 2, 4];
+  const array = new Int32Array(values);
+  const cloned = structuredClone(array);
+  assert.instanceOf(cloned, Int32Array);
+  assert.deepEqual(Array.from(cloned), values);
+}
+
+function testStructuredCloneNonJson() {
+  // Test Date
+  const date = new Date(100000.0);
+  const cloneDate = structuredClone(date);
+  assert.strictEqual(date.getTime(), cloneDate.getTime());
+
+  // Test Map
+  const map = new Map();
+  map.set(1, 2);
+  const cloneMap = structuredClone(map);
+  assert.strictEqual(cloneMap.size, 1);
+  assert.strictEqual(cloneMap.get(1), 2);
+
+  // Test Set
+  const set = new Set();
+  set.add(1);
+  const cloneSet = structuredClone(set);
+  assert.strictEqual(cloneSet.size, 1);
+  assert.isTrue(cloneSet.has(1));
+
+  // Test BigInt
+  const bigint = BigInt(1);
+  const cloneBigint = structuredClone(bigint);
+  assert.strictEqual(bigint, cloneBigint);
+
+  // Test RegExp
+  const regex = /a/g;
+  const cloneRegex = structuredClone(regex);
+  assert.strictEqual(regex.toString(), cloneRegex.toString());
+  assert.instanceOf(cloneRegex, RegExp);
+
+  // Test Function
+  const func = () => {};
+  assert.throws(() => structuredClone(func), /could not deserialize value/);
+
+  // Test Symbol
+  const symbol = Symbol("test");
+  assert.throws(() => structuredClone(symbol), /could not deserialize value/);
+
+  // Test Error
+  const error = new Error("test");
+  const cloneError = structuredClone(error);
+  assert.strictEqual(error.message, cloneError.message);
+  assert.instanceOf(cloneError, Error);
+}
+
+function testStructuredCloneRecursive() {
+  // Test recursive object
+  const recursiveObject: any = { a: 1 };
+  recursiveObject["b"] = recursiveObject;
+  const cloned = structuredClone(recursiveObject);
+  assert.strictEqual(cloned.a, 1);
+  assert.strictEqual(cloned.b, cloned);
+  assert.notEqual(cloned, recursiveObject);
+
+  // Test recursive array
+  const recursiveArray: any[] = [1];
+  recursiveArray.push(recursiveArray);
+  recursiveArray.push(recursiveObject);
+  const clonedArray = structuredClone(recursiveArray);
+  assert.strictEqual(clonedArray[0], 1);
+  assert.strictEqual(clonedArray[1], clonedArray);
+  assert.strictEqual(clonedArray[2].b, clonedArray[2]);
+  assert.notEqual(clonedArray, recursiveArray);
+  assert.notEqual(clonedArray[2], recursiveObject);
+}
+
+export default query(async (): Promise<string> => {
+  return await wrapInTests({
+    testStructuredCloneJson,
+    testStructuredCloneArrayBuffer,
+    testStructuredCloneTypedArray,
+    testStructuredCloneNonJson,
+    testStructuredCloneRecursive,
+  });
+});
+
+export const withTransfer = query(async () => {
+  const array = new ArrayBuffer(8);
+  const _tranferred = structuredClone(array, { transfer: [array] });
+  return "expected uncatchable error";
+});