feat: effect-root-rune

feat: add $effect.root rune

update doc

Author: trueadm

.changeset/rare-pears-whisper.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: add $effect.root rune

packages/svelte/src/compiler/errors.js

@@ -176,6 +176,8 @@ const runes = {
 	'invalid-state-location': () =>
 		`$state() can only be used as a variable declaration initializer or a class field`,
 	'invalid-effect-location': () => `$effect() can only be used as an expression statement`,
+	'invalid-effect-root-location': () =>
+		`$effect.root() can only be used as a variable declaration initializer`,
 	/**
 	 * @param {boolean} is_binding
 	 * @param {boolean} show_details

packages/svelte/src/compiler/phases/2-analyze/validation.js

@@ -519,6 +519,14 @@ function validate_call_expression(node, scope, path) {
 			error(node, 'invalid-rune-args-length', '$effect.active', [0]);
 		}
 	}
+
+	if (rune === '$effect.root') {
+		if (node.arguments.length < 1 || node.arguments.length > 2) {
+			error(node, 'invalid-rune-args-length', '$effect.root', [0]);
+		}
+		if (parent.type === 'VariableDeclarator') return;
+		error(node, 'invalid-effect-root-location');
+	}
 }
 
 /**

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

@@ -208,8 +208,18 @@ export const javascript_visitors_runes = {
 				// TODO
 				continue;
 			}
-
 			const args = /** @type {import('estree').CallExpression} */ (declarator.init).arguments;
+
+			if (rune === '$effect.root') {
+				const serialized_args = /** @type {import('estree').Expression[]} */ (
+					args.map((arg) => visit(arg))
+				);
+				declarations.push(
+					b.declarator(declarator.id, b.call('$.user_root_effect', ...serialized_args))
+				);
+				continue;
+			}
+
 			const value =
 				args.length === 0
 					? b.id('undefined')
@@ -292,13 +302,20 @@ export const javascript_visitors_runes = {
 
 		context.next();
 	},
-	CallExpression(node, { state, next }) {
+	CallExpression(node, { state, next, visit }) {
 		const rune = get_rune(node, state.scope);
 
 		if (rune === '$effect.active') {
 			return b.call('$.effect_active');
 		}
 
+		if (rune === '$effect.root') {
+			const args = /** @type {import('estree').Expression[]} */ (
+				node.arguments.map((arg) => visit(arg))
+			);
+			return b.call('$.user_root_effect', ...args);
+		}
+
 		next();
 	}
 };

packages/svelte/src/compiler/phases/constants.js

@@ -70,7 +70,15 @@ export const ElementBindings = [
 	'indeterminate'
 ];
 
-export const Runes = ['$state', '$props', '$derived', '$effect', '$effect.pre', '$effect.active'];
+export const Runes = [
+	'$state',
+	'$props',
+	'$derived',
+	'$effect',
+	'$effect.pre',
+	'$effect.active',
+	'$effect.root'
+];
 
 /**
  * Whitespace inside one of these elements will not result in

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

@@ -1184,6 +1184,21 @@ export function user_effect(init) {
 	return effect;
 }
 
+/**
+ * @param {() => void | (() => void)} init
+ * @param {() => void} [on_parent_cleanup]
+ * @returns {() => void}
+ */
+export function user_root_effect(init, on_parent_cleanup) {
+	const effect = managed_render_effect(init);
+	if (current_effect !== null && typeof on_parent_cleanup === 'function') {
+		push_destroy_fn(current_effect, on_parent_cleanup);
+	}
+	return () => {
+		destroy_signal(effect);
+	};
+}
+
 /**
  * @param {() => void | (() => void)} init
  * @returns {import('./types.js').EffectSignal}

packages/svelte/src/internal/index.js

@@ -36,7 +36,8 @@ export {
 	pop,
 	push,
 	reactive_import,
-	effect_active
+	effect_active,
+	user_root_effect
 } from './client/runtime.js';
 
 export * from './client/validate.js';

packages/svelte/src/main/ambient.d.ts

@@ -90,6 +90,34 @@ declare namespace $effect {
 	 * https://svelte-5-preview.vercel.app/docs/runes#$effect-active
 	 */
 	export function active(): boolean;
+
+	/**
+	 * The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for
+	 * nested effects that you want to manually control. This rune also allows for creation of effects outside of the component
+	 * initialisation phase.
+	 *
+	 * Example:
+	 * ```svelte
+	 * <script>
+	 *   let count = $state(0);
+	 *
+	 *   const cleanup = $effect.root(() => {
+	 *	    $effect(() => {
+	 *				console.log(count);
+	 *			})
+	 *
+	 *      return () => {
+	 *        console.log('effect root cleanup');
+	 * 			}
+	 *   });
+	 * </script>
+	 *
+	 * <button onclick={() => cleanup()}>cleanup</button>
+	 * ```
+	 *
+	 * https://svelte-5-preview.vercel.app/docs/runes#$effect-root
+	 */
+	export function root(fn: () => void | (() => void), fn2?: () => void): () => void;
 }
 
 /**

packages/svelte/tests/runtime-runes/samples/effect-root/_config.js

@@ -0,0 +1,32 @@
+import { flushSync } from 'svelte';
+import { test } from '../../test';
+
+export default test({
+	get props() {
+		return { log: [] };
+	},
+
+	async test({ assert, target, component }) {
+		const [b1, b2, b3] = target.querySelectorAll('button');
+
+		flushSync(() => {
+			b1.click();
+			b2.click();
+		});
+
+		assert.deepEqual(component.log, [0, 1]);
+
+		flushSync(() => {
+			b3.click();
+		});
+
+		assert.deepEqual(component.log, [0, 1, 'cleanup 1', 'cleanup 2']);
+
+		flushSync(() => {
+			b1.click();
+			b2.click();
+		});
+
+		assert.deepEqual(component.log, [0, 1, 'cleanup 1', 'cleanup 2']);
+	}
+});

packages/svelte/tests/runtime-runes/samples/effect-root/main.svelte

@@ -0,0 +1,25 @@
+<script>
+	let { log} = $props();
+
+	let x = $state(0);
+	let y = $state(0);
+
+	const cleanup = $effect.root(() => {
+		$effect(() => {
+			log.push(x);
+		});
+
+		const nested_cleanup = $effect.root(() => {
+			return () => {
+				log.push('cleanup 2')	;
+			}
+		}, () => {
+			log.push('cleanup 1');
+			nested_cleanup();
+		});
+	});
+</script>
+
+<button on:click={() => x++}>{x}</button>
+<button on:click={() => y++}>{y}</button>
+<button on:click={() => cleanup()}>cleanup</button>

sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md

@@ -186,6 +186,44 @@ The `$effect.active` rune is an advanced feature that tells you whether or not t
 
 This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects.
 
+## `$effect.root`
+
+The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for
+nested effects that you want to manually control. This rune also allows for creation of effects outside of the component initialisation phase.
+
+```svelte
+<script>
+	let count = $state(0);
+
+	const cleanup = $effect.root(() => {
+		$effect(() => {
+			console.log(count);
+		});
+
+		return () => {
+			console.log('effect root cleanup');
+		};
+	});
+</script>
+```
+
+If the `$effect.root` was created within within another active effect (such as during component initialisation) then it might
+be desirable to know when that active effect gets disposed and cleaned up. `$effect.root` takes an optional second arugment,
+which is a function callback for when this happens in case. This allows you to cleanup the effect root too if needed.
+
+```svelte
+<script>
+	let count = $state(0);
+
+	const cleanup = $effect.root(() => {
+		// ...
+	}. () => {
+		console.log('parent effect is cleaned up');
+		cleanup();
+	});
+</script>
+```
+
 ## `$props`
 
 To declare component props, use the `$props` rune: