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,22 @@ 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` accept an optional second argument that includes an `onchange` function.
+
+This function is called synchronously whenever the value is reassigned or (for `$state`) mutated, allowing you to respond to changes before [effects]($effect) run. It's useful for — for example — persisting data, or validating it:
+
+```js
+let count = $state(0, {
+	onchange() {
+		count = Math.min(count, 10);
+	}
+});
+```
+
+> The `onchange` function is [untracked](svelte#untrack).
+
 ## `$state.snapshot`
 
 To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:

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/phases/2-analyze/visitors/CallExpression.js

@@ -125,8 +125,10 @@ 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 (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');
+				}
 			}
 
 			break;

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

@@ -295,8 +295,8 @@ 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');
-			return [getter, b.set(alias ?? name, [b.stmt(b.call('$.set', b.id(name), value))])];
+			const call = b.call('$.set', b.id(name), b.id('$$value'), binding.kind === 'state' && b.true);
+			return [getter, b.set(alias ?? name, [b.stmt(call)])];
 		}
 
 		return getter;

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

@@ -4,6 +4,7 @@ import * as b from '#compiler/builders';
 import { regex_invalid_identifier_chars } from '../../../patterns.js';
 import { get_rune } from '../../../scope.js';
 import { should_proxy } from '../utils.js';
+import { get_onchange } from './shared/state.js';
 
 /**
  * @param {ClassBody} node
@@ -114,17 +115,20 @@ export function ClassBody(node, context) {
 						context.visit(definition.value.arguments[0], child_state)
 					);
 
-					value =
-						field.kind === 'state'
-							? b.call(
-									'$.state',
-									should_proxy(init, context.state.scope) ? b.call('$.proxy', init) : init
-								)
-							: field.kind === 'raw_state'
-								? b.call('$.state', init)
-								: field.kind === 'derived_by'
-									? b.call('$.derived', init)
-									: b.call('$.derived', b.thunk(init));
+					if (field.kind === 'state' || field.kind === 'raw_state') {
+						const onchange = get_onchange(
+							/** @type {Expression} */ (definition.value.arguments[1]),
+							// @ts-ignore mismatch between Context and ComponentContext. TODO look into
+							context
+						);
+
+						value =
+							field.kind === 'state' && should_proxy(init, context.state.scope)
+								? b.call('$.assignable_proxy', init, onchange)
+								: b.call('$.state', init, onchange);
+					} else {
+						value = b.call('$.derived', field.kind === 'derived_by' ? init : b.thunk(init));
+					}
 				} else {
 					// if no arguments, we know it's state as `$derived()` is a compile error
 					value = b.call('$.state');

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

@@ -8,6 +8,7 @@ import * as assert from '../../../../utils/assert.js';
 import { get_rune } from '../../../scope.js';
 import { get_prop_source, is_prop_source, is_state_source, should_proxy } from '../utils.js';
 import { is_hoisted_function } from '../../utils.js';
+import { get_onchange } from './shared/state.js';
 
 /**
  * @param {VariableDeclaration} node
@@ -118,27 +119,33 @@ export function VariableDeclaration(node, context) {
 			const args = /** @type {CallExpression} */ (init).arguments;
 			const value = args.length > 0 ? /** @type {Expression} */ (context.visit(args[0])) : b.void0;
 
+			const onchange = get_onchange(/** @type {Expression} */ (args[1]), context);
+
 			if (rune === '$state' || rune === '$state.raw') {
 				/**
 				 * @param {Identifier} id
 				 * @param {Expression} value
+				 * @param {Expression} [onchange]
 				 */
-				const create_state_declarator = (id, value) => {
-					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);
+				const create_state_declarator = (id, value, onchange) => {
+					const binding = /** @type {Binding} */ (context.state.scope.get(id.name));
+					const proxied = rune === '$state' && should_proxy(value, context.state.scope);
+					const is_state = is_state_source(binding, context.state.analysis);
+
+					if (proxied) {
+						return b.call(is_state ? '$.assignable_proxy' : '$.proxy', value, onchange);
 					}
-					if (is_state_source(binding, context.state.analysis)) {
-						value = b.call('$.state', value);
+
+					if (is_state) {
+						return b.call('$.state', value, onchange);
 					}
+
 					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, onchange))
 					);
 				} else {
 					const tmp = context.state.scope.generate('tmp');
@@ -151,7 +158,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, onchange)
 									: value
 							);
 						})

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

@@ -0,0 +1,31 @@
+/** @import { Expression, Property } from 'estree' */
+/** @import { ComponentContext } from '../../types' */
+import * as b from '../../../../../utils/builders.js';
+
+/**
+ * Extract the `onchange` callback from the options passed to `$state`
+ * @param {Expression} options
+ * @param {ComponentContext} context
+ * @returns {Expression | undefined}
+ */
+export function get_onchange(options, context) {
+	if (!options) return;
+
+	if (options.type === 'ObjectExpression') {
+		const onchange = /** @type {Property | undefined} */ (
+			options.properties.find(
+				(property) =>
+					property.type === 'Property' &&
+					!property.computed &&
+					property.key.type === 'Identifier' &&
+					property.key.name === 'onchange'
+			)
+		);
+
+		if (!onchange) return;
+
+		return /** @type {Expression} */ (context.visit(onchange.value));
+	}
+
+	return b.member(/** @type {Expression} */ (context.visit(options)), 'onchange');
+}

packages/svelte/src/index.d.ts

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

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

@@ -23,5 +23,6 @@ export const EFFECT_HAS_DERIVED = 1 << 20;
 export const EFFECT_IS_UPDATING = 1 << 21;
 
 export const STATE_SYMBOL = Symbol('$state');
+export const PROXY_ONCHANGE_SYMBOL = Symbol('proxy onchange');
 export const LEGACY_PROPS = Symbol('legacy props');
 export const LOADING_ATTR_SYMBOL = Symbol('');

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

@@ -141,7 +141,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,