feat: add unstate utility function

.changeset/beige-flies-wash.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: add unstate utility function

packages/svelte/src/internal/client/proxy/proxy.js

@@ -8,7 +8,13 @@ import {
 	updating_derived,
 	UNINITIALIZED
 } from '../runtime.js';
-import { define_property, get_descriptor, is_array } from '../utils.js';
+import {
+	define_property,
+	get_descriptor,
+	get_descriptors,
+	is_array,
+	object_keys
+} from '../utils.js';
 import { READONLY_SYMBOL } from './readonly.js';
 
 /** @typedef {{ s: Map<string | symbol, import('../types.js').SourceSignal<any>>; v: import('../types.js').SourceSignal<number>; a: boolean }} Metadata */
@@ -42,6 +48,56 @@ export function proxy(value) {
 	return value;
 }
 
+/**
+ * @template {StateObject} T
+ * @param {T} value
+ * @param {Map<T, Record<string | symbol, any>>} already_unwrapped
+ * @returns {Record<string | symbol, any>}
+ */
+export function unwrap(value, already_unwrapped = new Map()) {
+	if (typeof value === 'object' && value != null && !is_frozen(value) && STATE_SYMBOL in value) {
+		const unwrapped = already_unwrapped.get(value);
+		if (unwrapped !== undefined) {
+			return unwrapped;
+		}
+		if (is_array(value)) {
+			/** @type {Record<string | symbol, any>} */
+			const array = [];
+			already_unwrapped.set(value, array);
+			for (const element of value) {
+				array.push(unwrap(element, already_unwrapped));
+			}
+			return array;
+		} else {
+			/** @type {Record<string | symbol, any>} */
+			const obj = {};
+			const keys = object_keys(value);
+			const descriptors = get_descriptors(value);
+			already_unwrapped.set(value, obj);
+			for (const key of keys) {
+				if (descriptors[key].get) {
+					define_property(obj, key, descriptors[key]);
+				} else {
+					/** @type {T} */
+					const property = value[key];
+					obj[key] = unwrap(property, already_unwrapped);
+				}
+			}
+			return obj;
+		}
+	}
+	return value;
+}
+
+/**
+ * @template {StateObject} T
+ * @param {T} value
+ * @returns {Record<string | symbol, any>}
+ */
+export function unstate(value) {
+	return unwrap(value);
+}
+
 /**
  * @param {StateObject} value
  * @returns {Metadata}

packages/svelte/src/internal/client/render.js

@@ -51,7 +51,16 @@ import {
 	hydrate_block_anchor,
 	set_current_hydration_fragment
 } from './hydration.js';
-import { array_from, define_property, get_descriptor, get_descriptors, is_array } from './utils.js';
+import {
+	array_from,
+	define_property,
+	get_descriptor,
+	get_descriptors,
+	is_array,
+	object_assign,
+	object_entries,
+	object_keys
+} from './utils.js';
 import { is_promise } from '../common.js';
 import { bind_transition, trigger_transitions } from './transitions.js';
 
@@ -1196,7 +1205,7 @@ export function bind_prop(props, prop, value) {
 		const signal = expose(() => current_props[prop]);
 		if (is_signal(signal)) {
 			set(signal, value);
-		} else if (Object.getOwnPropertyDescriptor(current_props, prop)?.set !== undefined) {
+		} else if (get_descriptor(current_props, prop)?.set !== undefined) {
 			current_props[prop] = value;
 		}
 	};
@@ -2406,7 +2415,7 @@ function get_setters(element) {
  * @returns {Record<string, unknown>}
  */
 export function spread_attributes(dom, prev, attrs, lowercase_attributes, css_hash) {
-	const next = Object.assign({}, ...attrs);
+	const next = object_assign({}, ...attrs);
 	const has_hash = css_hash.length !== 0;
 	for (const key in prev) {
 		if (!(key in next)) {
@@ -2502,7 +2511,7 @@ export function spread_attributes(dom, prev, attrs, lowercase_attributes, css_ha
  */
 export function spread_dynamic_element_attributes(node, prev, attrs, css_hash) {
 	if (node.tagName.includes('-')) {
-		const next = Object.assign({}, ...attrs);
+		const next = object_assign({}, ...attrs);
 		if (prev !== null) {
 			for (const key in prev) {
 				if (!(key in next)) {
@@ -2670,7 +2679,7 @@ export function createRoot(component, options) {
 	const result =
 		/** @type {Exports & { $destroy: () => void; $set: (props: Partial<Props>) => void; }} */ ({
 			$set: (props) => {
-				for (const [prop, value] of Object.entries(props)) {
+				for (const [prop, value] of object_entries(props)) {
 					if (prop in _sources) {
 						set(_sources[prop], value);
 					} else {
@@ -2682,7 +2691,7 @@ export function createRoot(component, options) {
 			$destroy
 		});
 
-	for (const key of Object.keys(accessors || {})) {
+	for (const key of object_keys(accessors || {})) {
 		define_property(result, key, {
 			get() {
 				// @ts-expect-error TS doesn't know key exists on accessor

packages/svelte/src/internal/client/utils.js

@@ -2,6 +2,9 @@
 // to de-opt (this occurs often when using popular extensions).
 export var is_array = Array.isArray;
 export var array_from = Array.from;
+export var object_keys = Object.keys;
+export var object_entries = Object.entries;
+export var object_assign = Object.assign;
 export var define_property = Object.defineProperty;
 export var get_descriptor = Object.getOwnPropertyDescriptor;
 export var get_descriptors = Object.getOwnPropertyDescriptors;

packages/svelte/src/internal/index.js

@@ -47,7 +47,7 @@ export * from './client/each.js';
 export * from './client/render.js';
 export * from './client/validate.js';
 export { raf } from './client/timing.js';
-export { proxy, readonly } from './client/proxy/proxy.js';
+export { proxy, readonly, unstate } from './client/proxy/proxy.js';
 
 export { create_custom_element } from './client/custom-element.js';
 

packages/svelte/src/main/main-client.js

@@ -255,4 +255,12 @@ export function afterUpdate(fn) {
 
 // TODO bring implementations in here
 // (except probably untrack — do we want to expose that, if there's also a rune?)
-export { flushSync, createRoot, mount, tick, untrack, onDestroy } from '../internal/index.js';
+export {
+	flushSync,
+	createRoot,
+	mount,
+	tick,
+	untrack,
+	unstate,
+	onDestroy
+} from '../internal/index.js';

packages/svelte/tests/runtime-runes/samples/unstate/_config.js

@@ -0,0 +1,12 @@
+import { test } from '../../test';
+
+export default test({
+	html: `<button>[{"a":0}]</button>`,
+
+	async test({ assert, target }) {
+		const btn = target.querySelector('button');
+
+		await btn?.click();
+		assert.htmlEqual(target.innerHTML, `<button>[{"a":0},{"a":1}]</button>`);
+	}
+});

packages/svelte/tests/runtime-runes/samples/unstate/main.svelte

@@ -0,0 +1,7 @@
+<script>
+		import { unstate } from 'svelte';
+
+    let items = $state([{a: 0}]);
+</script>
+
+<button on:click={() => items.push({a: items.length})}>{JSON.stringify(structuredClone(unstate(items)))}</button>

sites/svelte-5-preview/src/routes/docs/content/01-api/05-functions.md

@@ -22,3 +22,22 @@ To prevent something from being treated as an `$effect`/`$derived` dependency, u
 	});
 </script>
 ```
+
+## `unstate`
+
+To remove reactivity from objects and arrays created with `$state`, use `unstate`:
+
+```svelte
+<script>
+	import { unstate } from 'svelte';
+
+	let counter = $state({ count: 0 });
+
+	$effect(() => {
+		// Will log { count: 0 }
+		console.log(unstate(counter));
+	});
+</script>
+```
+
+This is handy when you want to pass some state to an external library or API that doesn't expect a reactive object – such as `structuredClone`.