feat: make deriveds writable (#15570)

* feat: make deriveds writable

* add optimistic UI example

* add note to when-not-to-use-effect

* add section on deep reactivity

* root-relative URL

* use hash URL

* mention const

* make handler async, move into script block

Author: Rich-Harris

.changeset/clever-terms-tell.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: make deriveds writable

documentation/docs/02-runes/03-$derived.md

@@ -52,6 +52,48 @@ Anything read synchronously inside the `$derived` expression (or `$derived.by` f
 
 To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack).
 
+## Overriding derived values
+
+Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them (unless they are declared with `const`). This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user:
+
+```svelte
+<script>
+	let { post, like } = $props();
+
+	let likes = $derived(post.likes);
+
+	async function onclick() {
+		// increment the `likes` count immediately...
+		likes += 1;
+
+		// and tell the server, which will eventually update `post`
+		try {
+			await like();
+		} catch {
+			// failed! roll back the change
+			likes -= 1;
+		}
+	}
+</script>
+
+<button {onclick}>🧡 {likes}</button>
+```
+
+> [!NOTE] Prior to Svelte 5.25, deriveds were read-only.
+
+## Deriveds and reactivity
+
+Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)...
+
+```svelte
+let items = $state([...]);
+
+let index = $state(0);
+let selected = $derived(items[index]);
+```
+
+...you can change (or `bind:` to) properties of `selected` and it will affect the underlying `items` array. If `items` was _not_ deeply reactive, mutating `selected` would have no effect.
+
 ## Update propagation
 
 Svelte uses something called _push-pull reactivity_ — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').

documentation/docs/02-runes/04-$effect.md

@@ -254,6 +254,8 @@ In general, `$effect` is best considered something of an escape hatch — useful
 
 > [!NOTE] For things that are more complicated than a simple expression like `count * 2`, you can also use `$derived.by`.
 
+If you're using an effect because you want to be able to reassign the derived value (to build an optimistic UI, for example) note that [deriveds can be directly overridden]($derived#Overriding-derived-values) as of Svelte 5.25.
+
 You might be tempted to do something convoluted with effects to link one value to another. The following example shows two inputs for "money spent" and "money left" that are connected to each other. If you update one, the other should update accordingly. Don't use effects for this ([demo](/playground/untitled#H4sIAAAAAAAACpVRy26DMBD8FcvKgUhtoIdeHBwp31F6MGSJkBbHwksEQvx77aWQqooq9bgzOzP7mGTdIHipPiZJowOpGJAv0po2VmfnDv4OSBErjYdneHWzBJaCjcx91TWOToUtCIEE3cig0OIty44r5l1oDtjOkyFIsv3GINQ_CNYyGegd1DVUlCR7oU9iilDUcP8S8roYs9n8p2wdYNVFm4csTx872BxNCcjr5I11fdgonEkXsjP2CoUUZWMv6m6wBz2x7yxaM-iJvWeRsvSbSVeUy5i0uf8vKA78NIeJLSZWv1I8jQjLdyK4XuTSeIdmVKJGGI4LdjVOiezwDu1yG74My8PLCQaSiroe5s_5C2PHrkVGAgAA)):
 
 ```svelte

packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js

@@ -21,10 +21,6 @@ export function validate_assignment(node, argument, state) {
 		const binding = state.scope.get(argument.name);
 
 		if (state.analysis.runes) {
-			if (binding?.kind === 'derived') {
-				e.constant_assignment(node, 'derived state');
-			}
-
 			if (binding?.node === state.analysis.props_id) {
 				e.constant_assignment(node, '$props.id()');
 			}
@@ -38,25 +34,6 @@ export function validate_assignment(node, argument, state) {
 			e.snippet_parameter_assignment(node);
 		}
 	}
-	if (
-		argument.type === 'MemberExpression' &&
-		argument.object.type === 'ThisExpression' &&
-		(((argument.property.type === 'PrivateIdentifier' || argument.property.type === 'Identifier') &&
-			state.derived_state.some(
-				(derived) =>
-					derived.name === /** @type {PrivateIdentifier | Identifier} */ (argument.property).name &&
-					derived.private === (argument.property.type === 'PrivateIdentifier')
-			)) ||
-			(argument.property.type === 'Literal' &&
-				argument.property.value &&
-				typeof argument.property.value === 'string' &&
-				state.derived_state.some(
-					(derived) =>
-						derived.name === /** @type {Literal} */ (argument.property).value && !derived.private
-				)))
-	) {
-		e.constant_assignment(node, 'derived state');
-	}
 }
 
 /**
@@ -81,7 +58,6 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 	} else if (argument.type === 'Identifier') {
 		const binding = scope.get(argument.name);
 		if (
-			binding?.kind === 'derived' ||
 			binding?.declaration_kind === 'import' ||
 			(binding?.declaration_kind === 'const' && binding.kind !== 'each')
 		) {
@@ -96,12 +72,7 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 			// );
 
 			// TODO have a more specific error message for assignments to things like `{:then foo}`
-			const thing =
-				binding.declaration_kind === 'import'
-					? 'import'
-					: binding.kind === 'derived'
-						? 'derived state'
-						: 'constant';
+			const thing = binding.declaration_kind === 'import' ? 'import' : 'constant';
 
 			if (is_binding) {
 				e.constant_binding(node, thing);