init

Author: Ocean-OS

.changeset/breezy-baboons-exercise.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: add `$state.invalidate` rune

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

@@ -828,6 +828,12 @@ Cannot export state from a module if it is reassigned. Either export a function
 `%rune%(...)` can only be used as a variable declaration initializer or a class field
 ```
 
+### state_invalidate_nonreactive_argument
+
+```
+`$state.invalidate` only takes a variable declared with `$state` or `$state.raw` as its argument
+```
+
 ### store_invalid_scoped_subscription
 
 ```

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

@@ -220,6 +220,10 @@ It's possible to export a snippet from a `<script module>` block, but only if it
 
 > `%rune%(...)` can only be used as a variable declaration initializer or a class field
 
+## state_invalidate_nonreactive_argument
+
+> `$state.invalidate` only takes a variable declared with `$state` or `$state.raw` as its argument
+
 ## store_invalid_scoped_subscription
 
 > Cannot subscribe to stores that are not declared at the top level of the component

packages/svelte/src/ambient.d.ts

@@ -93,6 +93,30 @@ declare namespace $state {
 							: never
 						: never;
 
+	/**
+	 * Forces an update on a `$state` or `$state.raw` variable.
+	 * This is primarily meant as an escape hatch to be able to use external or native classes
+	 * with Svelte's reactivity system.
+	 * If you used Svelte 3 or 4, this is the equivalent of `foo = foo`.
+	 * Example:
+	 * ```svelte
+	 * <script>
+	 *   import Counter from 'external-class';
+	 * 
+	 *   let counter = $state(new Counter());
+	 * 
+	 *   function increment() {
+	 *     counter.increment(); 
+	 *     $state.invalidate(counter);
+	 *   }
+	 * </script>
+	 * <button onclick={increment}>
+	 *   Count is {counter.count}
+	 * </button>
+	 * ```
+	 */
+	export function invalidate(source: unknown): void;
+
 	/**
 	 * Declares state that is _not_ made deeply reactive — instead of mutating it,
 	 * you must reassign it.

packages/svelte/src/compiler/errors.js

@@ -480,6 +480,15 @@ export function state_invalid_placement(node, rune) {
 	e(node, 'state_invalid_placement', `\`${rune}(...)\` can only be used as a variable declaration initializer or a class field\nhttps://svelte.dev/e/state_invalid_placement`);
 }
 
+/**
+ * `$state.invalidate` only takes a variable declared with `$state` or `$state.raw` as its argument
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function state_invalidate_nonreactive_argument(node) {
+	e(node, 'state_invalidate_nonreactive_argument', `\`$state.invalidate\` only takes a variable declared with \`$state\` or \`$state.raw\` as its argument\nhttps://svelte.dev/e/state_invalidate_nonreactive_argument`);
+}
+
 /**
  * Cannot subscribe to stores that are not declared at the top level of the component
  * @param {null | number | NodeLike} node

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

@@ -111,6 +111,24 @@ export function CallExpression(node, context) {
 			break;
 		}
 
+		case '$state.invalidate':
+			if (node.arguments.length !== 1) {
+				e.rune_invalid_arguments_length(node, rune, 'exactly one argument');
+			} else {
+				let arg = node.arguments[0];
+				if (arg.type !== 'Identifier') {
+					e.rune_invalid_arguments(node, rune);
+				}
+				let binding = context.state.scope.get(arg.name);
+				if (binding) {
+					if (binding.kind === 'raw_state' || binding.kind === 'state') {
+						binding.reassigned = true;
+						break;
+					}
+				}
+				e.state_invalidate_nonreactive_argument(node);
+			}
+
 		case '$state':
 		case '$state.raw':
 		case '$derived':

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

@@ -23,6 +23,8 @@ export function CallExpression(node, context) {
 				/** @type {Expression} */ (context.visit(node.arguments[0])),
 				is_ignored(node, 'state_snapshot_uncloneable') && b.true
 			);
+		case '$state.invalidate':
+			return b.call('$.invalidate', node.arguments[0]);
 
 		case '$effect.root':
 			return b.call(

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

@@ -113,7 +113,15 @@ export {
 	user_effect,
 	user_pre_effect
 } from './reactivity/effects.js';
-export { mutable_source, mutate, set, state, update, update_pre } from './reactivity/sources.js';
+export {
+	invalidate,
+	mutable_source,
+	mutate,
+	set,
+	state,
+	update,
+	update_pre
+} from './reactivity/sources.js';
 export {
 	prop,
 	rest_props,

packages/svelte/src/internal/client/reactivity/sources.js

@@ -211,6 +211,49 @@ export function internal_set(source, value) {
 	return value;
 }
 
+/**
+ * @param {Source} source
+ */
+export function invalidate(source) {
+	source.wv = increment_write_version();
+
+	mark_reactions(source, DIRTY);
+
+	// It's possible that the current reaction might not have up-to-date dependencies
+	// whilst it's actively running. So in the case of ensuring it registers the reaction
+	// properly for itself, we need to ensure the current effect actually gets
+	// scheduled. i.e: `$effect(() => x++)`
+	if (
+		is_runes() &&
+		active_effect !== null &&
+		(active_effect.f & CLEAN) !== 0 &&
+		(active_effect.f & (BRANCH_EFFECT | ROOT_EFFECT)) === 0
+	) {
+		if (untracked_writes === null) {
+			set_untracked_writes([source]);
+		} else {
+			untracked_writes.push(source);
+		}
+	}
+
+	if (DEV && inspect_effects.size > 0) {
+		const inspects = Array.from(inspect_effects);
+
+		for (const effect of inspects) {
+			// Mark clean inspect-effects as maybe dirty and then check their dirtiness
+			// instead of just updating the effects - this way we avoid overfiring.
+			if ((effect.f & CLEAN) !== 0) {
+				set_signal_status(effect, MAYBE_DIRTY);
+			}
+			if (check_dirtiness(effect)) {
+				update_effect(effect);
+			}
+		}
+
+		inspect_effects.clear();
+	}
+}
+
 /**
  * @template {number | bigint} T
  * @param {Source<T>} source

packages/svelte/src/utils.js

@@ -430,6 +430,7 @@ export function is_mathml(name) {
 
 const RUNES = /** @type {const} */ ([
 	'$state',
+	'$state.invalidate',
 	'$state.raw',
 	'$state.snapshot',
 	'$props',

packages/svelte/types/index.d.ts

@@ -2760,6 +2760,30 @@ declare namespace $state {
 							: never
 						: never;
 
+	/**
+	 * Forces an update on a `$state` or `$state.raw` variable.
+	 * This is primarily meant as an escape hatch to be able to use external or native classes
+	 * with Svelte's reactivity system.
+	 * If you used Svelte 3 or 4, this is the equivalent of `foo = foo`.
+	 * Example:
+	 * ```svelte
+	 * <script>
+	 *   import Counter from 'external-class';
+	 * 
+	 *   let counter = $state(new Counter());
+	 * 
+	 *   function increment() {
+	 *     counter.increment(); 
+	 *     $state.invalidate(counter);
+	 *   }
+	 * </script>
+	 * <button onclick={increment}>
+	 *   Count is {counter.count}
+	 * </button>
+	 * ```
+	 */
+	export function invalidate(source: unknown): void;
+
 	/**
 	 * Declares state that is _not_ made deeply reactive — instead of mutating it,
 	 * you must reassign it.