fix: safely serialize query/mutation data to prevent DataCloneError with framework proxies

[biesbjerg]

Frameworks like Vue 3, MobX, and Solid wrap state in Proxy objects. When mapQueryToData / mapMutationToData pass these values directly into the payload sent via window.postMessage, the structured clone algorithm fails with a DataCloneError.

Add a safeClone helper that JSON-round-trips values before they are included in the message payload. This reads through Proxy getters and produces plain objects that are safe for structured cloning.

[Copilot]

Pull request overview

This pull request addresses a serialization issue when using TanStack Query DevTools with reactive frameworks (Vue 3, MobX, Solid) that wrap state in Proxy objects. The structured clone algorithm used by window.postMessage fails with DataCloneError when encountering these proxies. The solution adds a safeClone helper that uses JSON round-tripping to convert Proxy objects into plain objects before they are sent via postMessage.

Changes:

• Added safeClone helper function using JSON.parse(JSON.stringify()) to handle Proxy objects
• Applied safeClone to query fields: queryKey, state.data, state.error, and meta
• Applied safeClone to mutation fields: variables, context, data, and error

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The return type "[Unserializable]" as T creates a type safety issue. When T is expected to be an object or array (like queryKey, which is QueryKey type), returning a string breaks the type contract. This could cause runtime errors in code that expects the original type structure.

Consider either:

1. Returning {} as T for objects/arrays to maintain structural compatibility
2. Adding proper type narrowing to handle different value types appropriately
3. Using a union type that allows the function to return the original type or a serialization error indicator

Suggested change

	function safeClone<T>(value: T): T {
	try {
	return JSON.parse(JSON.stringify(value));
	} catch {
	return "[Unserializable]" as T;
	function safeClone<T>(value: T): T | "[Unserializable]" {
	try {
	return JSON.parse(JSON.stringify(value));
	} catch {
	return "[Unserializable]";

[Copilot]

JSON.stringify has important limitations that may cause data loss:

1. Functions, symbols, and undefined values in objects are omitted; in arrays they become null
2. Dates become strings and lose their Date type
3. Sets, Maps, RegExp, and other built-in types are not properly serialized
4. BigInt values throw errors
5. NaN and Infinity become null

While JSON round-tripping solves the Proxy issue, it fundamentally changes the data. For example, if query.state.data contains a Date, it will become a string. This could break devtools functionality that expects to inspect the original data types. Consider documenting these limitations or handling specific known types (like Date, Set, Map) with custom serialization logic if the devtools needs to display them correctly.

Suggested change

	* JSON round-tripping reads through Proxy getters, producing plain objects.
	*/
	function safeClone<T>(value: T): T {
	try {
	return JSON.parse(JSON.stringify(value));
	* We first prefer `structuredClone` to preserve types, and fall back to
	* JSON round-tripping with a custom replacer/reviver to handle common
	* built-in types (Date, Set, Map, RegExp, BigInt, NaN, Infinity).
	*/
	const globalStructuredClone: (<T>(value: T) => T) | undefined =
	typeof (globalThis as any).structuredClone === "function"
	? ((globalThis as any).structuredClone as <T>(value: T) => T)
	: undefined;
	function devtoolsJsonReplacer(_key: string, value: unknown): unknown {
	// Preserve BigInt by converting to a tagged string representation.
	if (typeof value === "bigint") {
	return { __devtools_type: "BigInt", value: value.toString() };
	}
	// Preserve Dates.
	if (value instanceof Date) {
	return { __devtools_type: "Date", value: value.toISOString() };
	}
	// Preserve Sets as arrays.
	if (value instanceof Set) {
	return {
	__devtools_type: "Set",
	value: Array.from(value.values()),
	};
	}
	// Preserve Maps as [key, value] entry arrays.
	if (value instanceof Map) {
	return {
	__devtools_type: "Map",
	value: Array.from(value.entries()),
	};
	}
	// Preserve regular expressions.
	if (value instanceof RegExp) {
	return {
	__devtools_type: "RegExp",
	value: value.source,
	flags: value.flags,
	};
	}
	// Preserve special number values that JSON would otherwise turn into null.
	if (typeof value === "number" && !Number.isFinite(value)) {
	return { __devtools_type: "Number", value: value.toString() };
	}
	return value;
	}
	function devtoolsJsonReviver(_key: string, value: unknown): unknown {
	if (
	value &&
	typeof value === "object" &&
	Object.prototype.hasOwnProperty.call(value, "__devtools_type")
	) {
	const tagged = value as {
	__devtools_type: string;
	value?: unknown;
	flags?: string;
	};
	switch (tagged.__devtools_type) {
	case "BigInt":
	return typeof tagged.value === "string"
	? BigInt(tagged.value)
	: value;
	case "Date":
	return typeof tagged.value === "string"
	? new Date(tagged.value)
	: value;
	case "Set":
	return Array.isArray(tagged.value)
	? new Set(tagged.value)
	: value;
	case "Map":
	return Array.isArray(tagged.value)
	? new Map(tagged.value as [any, any][])
	: value;
	case "RegExp":
	return typeof tagged.value === "string"
	? new RegExp(tagged.value, tagged.flags || "")
	: value;
	case "Number":
	if (tagged.value === "NaN") return NaN;
	if (tagged.value === "Infinity") return Infinity;
	if (tagged.value === "-Infinity") return -Infinity;
	return value;
	default:
	return value;
	}
	}
	return value;
	}
	function safeClone<T>(value: T): T {
	// Prefer native structuredClone when available to preserve types where possible.
	if (globalStructuredClone) {
	try {
	return globalStructuredClone(value);
	} catch {
	// Fall through to JSON-based cloning if structuredClone fails
	// (for example, on certain Proxy-wrapped values).
	}
	}
	try {
	const json = JSON.stringify(value, devtoolsJsonReplacer);
	return JSON.parse(json, devtoolsJsonReviver);

[Copilot]

The silent error handling (empty catch block) makes debugging difficult. If safeClone fails, developers won't know which field caused the serialization error or why. This is especially problematic since the function is called on multiple different fields (queryKey, data, error, variables, context, meta).

Consider logging a warning when serialization fails to aid debugging. For example: console.warn('Failed to serialize value:', error); This follows the pattern used elsewhere in the codebase for non-critical errors.

Suggested change

	} catch {
	} catch (error) {
	console.warn("Failed to serialize value in safeClone:", error);

[Copilot]

JSON.parse(JSON.stringify()) is called on every query/mutation update, potentially multiple times per second during active operations. This creates performance overhead since:

1. JSON.stringify traverses the entire object tree
2. JSON.parse rebuilds the entire object tree
3. This happens for every field (queryKey, data, error, meta, variables, context) on every query/mutation

Consider optimizing by:

1. Only applying safeClone when the value is actually a Proxy (check using util.types.isProxy in Node.js or a custom detector)
2. Caching cloned results if the same object reference is seen repeatedly
3. Using a shallow clone for simple primitives and arrays of primitives

The performance impact will be especially noticeable with large query caches or complex data objects.

Suggested change

	function safeClone<T>(value: T): T {
	function safeClone<T>(value: T): T {
	// Fast path for primitives: JSON cloning would yield the same value.
	if (value === null || typeof value !== "object") {
	return value;
	}
	// Fast path for arrays of primitives: shallow copy is equivalent to JSON clone.
	if (Array.isArray(value)) {
	let allPrimitives = true;
	for (let i = 0; i < value.length; i++) {
	const el = value[i];
	if (el !== null && typeof el === "object") {
	allPrimitives = false;
	break;
	}
	}
	if (allPrimitives) {
	return value.slice() as T;
	}
	}
	// Fallback: deep clone via JSON round-trip to unwrap proxies and nested objects.

[Copilot]

The expression query.meta || {} already creates a new plain object when meta is falsy, so safeClone is unnecessary in that case. Consider optimizing to: query.meta ? safeClone(query.meta) : {} to avoid the overhead of JSON serialization when meta is undefined or null.

Suggested change

	meta: safeClone(query.meta || {}),
	meta: query.meta ? safeClone(query.meta) : {},

[dborysov]

Thank you for the contribution @biesbjerg!

Yeah, that's quite a lot of feedback from dependabot. One pretty important one is about serialization issues - we need to support bigint in the query data, see #1