feat: add onchange option to $state

.changeset/red-rules-share.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: add `onchange` option to `$state`

documentation/docs/02-runes/02-$state.md

@@ -147,6 +147,35 @@ person = {
 
 This can improve performance with large arrays and objects that you weren't planning to mutate anyway, since it avoids the cost of making them reactive. Note that raw state can _contain_ reactive state (for example, a raw array of reactive objects).
 
+## State options
+
+Both `$state` and `$state.raw` can optionally accept a second argument. This allows you to specify an `onchange` function that will be called synchronously whenever the state value changes (for `$state` it will also be called for deep mutations).
+
+The `onchange` function is untracked so even if you assign within an `$effect` it will not cause unwanted dependencies.
+
+```js
+let count = $state(0, {
+	onchange(){
+		console.log("count is now", count);
+	}
+});
+
+// this will log "count is now 1"
+count++;
+```
+
+this could be especially useful if you want to sync some stateful variable that could be mutated without using an effect.
+
+```js
+let array = $state([], {
+	onchange(){
+		localStorage.setItem('array', JSON.stringify(array));
+	}
+});
+
+array.push(array.length);
+```
+
 ## `$state.snapshot`
 
 To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:

documentation/docs/98-reference/.generated/compile-errors.md

@@ -648,6 +648,12 @@ Cannot access a computed property of a rune
 `%name%` is not a valid rune
 ```
 
+### rune_invalid_options
+
+```
+Options for `%rune%` needs to be declared inline
+```
+
 ### rune_invalid_usage
 
 ```

packages/svelte/messages/compile-errors/script.md

@@ -158,6 +158,10 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 > `%name%` is not a valid rune
 
+## rune_invalid_options
+
+> Options for `%rune%` needs to be declared inline
+
 ## rune_invalid_usage
 
 > Cannot use `%rune%` rune in non-runes mode

packages/svelte/src/ambient.d.ts

@@ -20,6 +20,11 @@ declare module '*.svelte' {
  *
  * @param initial The initial value
  */
+declare function $state<T>(
+	initial: undefined,
+	options?: import('svelte').StateOptions
+): T | undefined;
+declare function $state<T>(initial: T, options?: import('svelte').StateOptions): T;
 declare function $state<T>(initial: T): T;
 declare function $state<T>(): T | undefined;
 
@@ -116,6 +121,11 @@ declare namespace $state {
 	 *
 	 * @param initial The initial value
 	 */
+	export function raw<T>(
+		initial: undefined,
+		options?: import('svelte').StateOptions
+	): T | undefined;
+	export function raw<T>(initial?: T, options?: import('svelte').StateOptions): T;
 	export function raw<T>(initial: T): T;
 	export function raw<T>(): T | undefined;
 	/**

packages/svelte/src/compiler/errors.js

@@ -373,6 +373,16 @@ export function rune_invalid_name(node, name) {
 	e(node, 'rune_invalid_name', `\`${name}\` is not a valid rune\nhttps://svelte.dev/e/rune_invalid_name`);
 }
 
+/**
+ * Options for `%rune%` needs to be declared inline
+ * @param {null | number | NodeLike} node
+ * @param {string} rune
+ * @returns {never}
+ */
+export function rune_invalid_options(node, rune) {
+	e(node, 'rune_invalid_options', `Options for \`${rune}\` needs to be declared inline\nhttps://svelte.dev/e/rune_invalid_options`);
+}
+
 /**
  * Cannot use `%rune%` rune in non-runes mode
  * @param {null | number | NodeLike} node

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

@@ -87,8 +87,13 @@ export function CallExpression(node, context) {
 
 			if ((rune === '$derived' || rune === '$derived.by') && node.arguments.length !== 1) {
 				e.rune_invalid_arguments_length(node, rune, 'exactly one argument');
-			} else if (rune === '$state' && node.arguments.length > 1) {
-				e.rune_invalid_arguments_length(node, rune, 'zero or one arguments');
+			} else if (rune === '$state' || rune === '$state.raw') {
+				if (node.arguments.length > 2) {
+					e.rune_invalid_arguments_length(node, rune, 'at most two arguments');
+				}
+				if (node.arguments.length === 2 && node.arguments[1].type !== 'ObjectExpression') {
+					e.rune_invalid_options(node.arguments[1], rune);
+				}
 			}
 
 			break;

packages/svelte/src/compiler/phases/3-transform/client/transform-client.js

@@ -292,7 +292,10 @@ export function client_component(analysis, options) {
 		}
 
 		if (binding?.kind === 'state' || binding?.kind === 'raw_state') {
-			const value = binding.kind === 'state' ? b.call('$.proxy', b.id('$$value')) : b.id('$$value');
+			const value =
+				binding.kind === 'state'
+					? b.call('$.proxy', b.id('$$value'), b.call('$.get_options', b.id(name)))
+					: b.id('$$value');
 			return [getter, b.set(alias ?? name, [b.stmt(b.call('$.set', b.id(name), value))])];
 		}
 

packages/svelte/src/compiler/phases/3-transform/client/types.d.ts

@@ -30,7 +30,7 @@ export interface ClientTransformState extends TransformState {
 			/** turn `foo` into e.g. `$.get(foo)` */
 			read: (id: Identifier) => Expression;
 			/** turn `foo = bar` into e.g. `$.set(foo, bar)` */
-			assign?: (node: Identifier, value: Expression) => Expression;
+			assign?: (node: Identifier, value: Expression, proxy?: boolean) => Expression;
 			/** turn `foo.bar = baz` into e.g. `$.mutate(foo, $.get(foo).bar = baz);` */
 			mutate?: (node: Identifier, mutation: AssignmentExpression | UpdateExpression) => Expression;
 			/** turn `foo++` into e.g. `$.update(foo)` */

packages/svelte/src/compiler/phases/3-transform/client/utils.js

@@ -45,14 +45,6 @@ export function build_getter(node, state) {
 	return node;
 }
 
-/**
- * @param {Expression} value
- * @param {Expression} previous
- */
-export function build_proxy_reassignment(value, previous) {
-	return dev ? b.call('$.proxy', value, b.null, previous) : b.call('$.proxy', value);
-}
-
 /**
  * @param {FunctionDeclaration | FunctionExpression | ArrowFunctionExpression} node
  * @param {ComponentContext} context

packages/svelte/src/compiler/phases/3-transform/client/visitors/AssignmentExpression.js

@@ -9,7 +9,7 @@ import {
 	is_event_attribute
 } from '../../../../utils/ast.js';
 import { dev, filename, is_ignored, locate_node, locator } from '../../../../state.js';
-import { build_proxy_reassignment, should_proxy } from '../utils.js';
+import { should_proxy } from '../utils.js';
 import { visit_assignment_expression } from '../../shared/assignments.js';
 
 /**
@@ -65,21 +65,20 @@ function build_assignment(operator, left, right, context) {
 				context.visit(build_assignment_value(operator, left, right))
 			);
 
-			if (
+			const needs_proxy =
 				private_state.kind === 'state' &&
 				is_non_coercive_operator(operator) &&
-				should_proxy(value, context.state.scope)
-			) {
-				value = build_proxy_reassignment(value, b.member(b.this, private_state.id));
-			}
-
-			if (context.state.in_constructor) {
-				// inside the constructor, we can assign to `this.#foo.v` rather than using `$.set`,
-				// since nothing is tracking the signal at this point
-				return b.assignment(operator, /** @type {Pattern} */ (context.visit(left)), value);
-			}
-
-			return b.call('$.set', left, value);
+				should_proxy(value, context.state.scope);
+
+			return b.call(
+				// inside the constructor, we use `$.simple_set` rather than using `$.set`,
+				// that only assign the value and eventually call onchange since nothing is tracking the signal at this point
+				context.state.in_constructor ? '$.simple_set' : '$.set',
+				left,
+				value,
+				needs_proxy && b.true,
+				dev && needs_proxy && b.true
+			);
 		}
 	}
 
@@ -113,19 +112,17 @@ function build_assignment(operator, left, right, context) {
 			context.visit(build_assignment_value(operator, left, right))
 		);
 
-		if (
+		return transform.assign(
+			object,
+			value,
 			!is_primitive &&
-			binding.kind !== 'prop' &&
-			binding.kind !== 'bindable_prop' &&
-			binding.kind !== 'raw_state' &&
-			context.state.analysis.runes &&
-			should_proxy(right, context.state.scope) &&
-			is_non_coercive_operator(operator)
-		) {
-			value = build_proxy_reassignment(value, object);
-		}
-
-		return transform.assign(object, value);
+				binding.kind !== 'prop' &&
+				binding.kind !== 'bindable_prop' &&
+				binding.kind !== 'raw_state' &&
+				context.state.analysis.runes &&
+				should_proxy(right, context.state.scope) &&
+				is_non_coercive_operator(operator)
+		);
 	}
 
 	// mutation

packages/svelte/src/compiler/phases/3-transform/client/visitors/ClassBody.js

@@ -5,7 +5,7 @@ import { dev, is_ignored } from '../../../../state.js';
 import * as b from '../../../../utils/builders.js';
 import { regex_invalid_identifier_chars } from '../../../patterns.js';
 import { get_rune } from '../../../scope.js';
-import { build_proxy_reassignment, should_proxy } from '../utils.js';
+import { should_proxy } from '../utils.js';
 
 /**
  * @param {ClassBody} node
@@ -116,14 +116,22 @@ export function ClassBody(node, context) {
 						context.visit(definition.value.arguments[0], child_state)
 					);
 
+					let options =
+						definition.value.arguments.length === 2
+							? /** @type {Expression} **/ (
+									context.visit(definition.value.arguments[1], child_state)
+								)
+							: undefined;
+
+					let proxied = should_proxy(init, context.state.scope);
+
 					value =
 						field.kind === 'state'
-							? b.call(
-									'$.state',
-									should_proxy(init, context.state.scope) ? b.call('$.proxy', init) : init
-								)
+							? should_proxy(init, context.state.scope)
+								? b.call('$.assignable_proxy', init, options)
+								: b.call('$.state', init, options)
 							: field.kind === 'raw_state'
-								? b.call('$.state', init)
+								? b.call('$.state', init, options)
 								: field.kind === 'derived_by'
 									? b.call('$.derived', init)
 									: b.call('$.derived', b.thunk(init));
@@ -152,7 +160,7 @@ export function ClassBody(node, context) {
 								'set',
 								definition.key,
 								[value],
-								[b.stmt(b.call('$.set', member, build_proxy_reassignment(value, prev)))]
+								[b.stmt(b.call('$.set', member, value, b.true, dev && b.true))]
 							)
 						);
 					}

packages/svelte/src/compiler/phases/3-transform/client/visitors/VariableDeclaration.js

@@ -113,28 +113,34 @@ export function VariableDeclaration(node, context) {
 			const args = /** @type {CallExpression} */ (init).arguments;
 			const value =
 				args.length === 0 ? b.id('undefined') : /** @type {Expression} */ (context.visit(args[0]));
+			let options =
+				args.length === 2 ? /** @type {Expression} */ (context.visit(args[1])) : undefined;
 
 			if (rune === '$state' || rune === '$state.raw') {
 				/**
 				 * @param {Identifier} id
 				 * @param {Expression} value
+				 * @param {Expression} [options]
 				 */
-				const create_state_declarator = (id, value) => {
+				const create_state_declarator = (id, value, options) => {
 					const binding = /** @type {import('#compiler').Binding} */ (
 						context.state.scope.get(id.name)
 					);
-					if (rune === '$state' && should_proxy(value, context.state.scope)) {
-						value = b.call('$.proxy', value);
-					}
-					if (is_state_source(binding, context.state.analysis)) {
-						value = b.call('$.state', value);
+					const proxied = rune === '$state' && should_proxy(value, context.state.scope);
+					const is_state = is_state_source(binding, context.state.analysis);
+					if (proxied && is_state) {
+						value = b.call('$.assignable_proxy', value, options);
+					} else if (proxied) {
+						value = b.call('$.proxy', value, options);
+					} else if (is_state) {
+						value = b.call('$.state', value, options);
 					}
 					return value;
 				};
 
 				if (declarator.id.type === 'Identifier') {
 					declarations.push(
-						b.declarator(declarator.id, create_state_declarator(declarator.id, value))
+						b.declarator(declarator.id, create_state_declarator(declarator.id, value, options))
 					);
 				} else {
 					const tmp = context.state.scope.generate('tmp');
@@ -147,7 +153,7 @@ export function VariableDeclaration(node, context) {
 							return b.declarator(
 								path.node,
 								binding?.kind === 'state' || binding?.kind === 'raw_state'
-									? create_state_declarator(binding.node, value)
+									? create_state_declarator(binding.node, value, options)
 									: value
 							);
 						})

packages/svelte/src/compiler/phases/3-transform/client/visitors/shared/declarations.js

@@ -1,7 +1,8 @@
 /** @import { Identifier } from 'estree' */
 /** @import { ComponentContext, Context } from '../../types' */
-import { is_state_source } from '../../utils.js';
+import { is_state_source, should_proxy } from '../../utils.js';
 import * as b from '../../../../../utils/builders.js';
+import { dev } from '../../../../../state.js';
 
 /**
  * Turns `foo` into `$.get(foo)`
@@ -24,8 +25,8 @@ export function add_state_transformers(context) {
 		) {
 			context.state.transform[name] = {
 				read: binding.declaration_kind === 'var' ? (node) => b.call('$.safe_get', node) : get_value,
-				assign: (node, value) => {
-					let call = b.call('$.set', node, value);
+				assign: (node, value, proxy = false) => {
+					let call = b.call('$.set', node, value, proxy && b.true, dev && proxy && b.true);
 
 					if (context.state.scope.get(`$${node.name}`)?.kind === 'store_sub') {
 						call = b.call('$.store_unsub', call, b.literal(`$${node.name}`), b.id('$$stores'));

packages/svelte/src/index.d.ts

@@ -351,4 +351,6 @@ export type MountOptions<Props extends Record<string, any> = Record<string, any>
 			props: Props;
 		});
 
+export { ValueOptions as StateOptions } from './internal/client/types.js';
+
 export * from './index-client.js';

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

@@ -22,6 +22,7 @@ export const HEAD_EFFECT = 1 << 19;
 export const EFFECT_HAS_DERIVED = 1 << 20;
 
 export const STATE_SYMBOL = Symbol('$state');
+export const PROXY_ONCHANGE_SYMBOL = Symbol('proxy onchange');
 export const STATE_SYMBOL_METADATA = Symbol('$state metadata');
 export const LEGACY_PROPS = Symbol('legacy props');
 export const LOADING_ATTR_SYMBOL = Symbol('');

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

@@ -109,7 +109,14 @@ export {
 	user_effect,
 	user_pre_effect
 } from './reactivity/effects.js';
-export { mutable_state, mutate, set, state } from './reactivity/sources.js';
+export {
+	mutable_state,
+	mutate,
+	set,
+	simple_set,
+	state,
+	get_options
+} from './reactivity/sources.js';
 export {
 	prop,
 	rest_props,
@@ -152,7 +159,7 @@ export {
 } from './runtime.js';
 export { validate_binding, validate_each_keys } from './validate.js';
 export { raf } from './timing.js';
-export { proxy } from './proxy.js';
+export { proxy, assignable_proxy } from './proxy.js';
 export { create_custom_element } from './dom/elements/custom-element.js';
 export {
 	child,