feat: forking

.changeset/small-geckos-camp.md

@@ -0,0 +1,5 @@
+---
+"svelte": patch
+---
+
+feat: experimental `fork` API

documentation/docs/03-template-syntax/19-await-expressions.md

@@ -135,6 +135,54 @@ If a `<svelte:boundary>` with a `pending` snippet is encountered during SSR, tha
 
 > [!NOTE] In the future, we plan to add a streaming implementation that renders the content in the background.
 
+## Forking
+
+The [`fork(...)`](svelte#fork) API, added in 5.42, makes it possible to run `await` expressions that you _expect_ to happen in the near future. This is mainly intended for frameworks like SvelteKit to implement preloading when (for example) users signal an intent to navigate.
+
+```svelte
+<script>
+	import { fork } from 'svelte';
+	import Menu from './Menu.svelte';
+
+	let open = $state(false);
+
+	/** @type {import('svelte').Fork | null} */
+	let pending = null;
+
+	function preload() {
+		pending ??= fork(() => {
+			open = true;
+		});
+	}
+
+	function discard() {
+		pending?.discard();
+		pending = null;
+	}
+</script>
+
+<button
+	onfocusin={preload}
+	onfocusout={discard}
+	onpointerenter={preload}
+	onpointerleave={discard}
+	onclick={() => {
+		pending?.commit();
+		pending = null;
+
+		// in case `pending` didn't exist
+		// (if it did, this is a no-op)
+		open = true;
+	}}
+>open menu</button>
+
+{#if open}
+	<!-- any async work inside this component will start
+	     as soon as the fork is created -->
+	<Menu onclose={() => open = false} />
+{/if}
+```
+
 ## Caveats
 
 As an experimental feature, the details of how `await` is handled (and related APIs like `$effect.pending()`) are subject to breaking changes outside of a semver major release, though we intend to keep such changes to a bare minimum.

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

@@ -130,6 +130,12 @@ $effect(() => {
 
 Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency.
 
+### experimental_async_fork
+
+```
+Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
+```
+
 ### flush_sync_in_effect
 
 ```
@@ -140,6 +146,18 @@ The `flushSync()` function can be used to flush any pending effects synchronousl
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+### fork_discarded
+
+```
+Cannot commit a fork that was already committed or discarded
+```
+
+### fork_timing
+
+```
+Cannot create a fork inside an effect or when state changes are pending
+```
+
 ### get_abort_signal_outside_reaction
 
 ```

packages/svelte/messages/client-errors/errors.md

@@ -100,6 +100,10 @@ $effect(() => {
 
 Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency.
 
+## experimental_async_fork
+
+> Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
+
 ## flush_sync_in_effect
 
 > Cannot use `flushSync` inside an effect
@@ -108,6 +112,14 @@ The `flushSync()` function can be used to flush any pending effects synchronousl
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+## fork_discarded
+
+> Cannot commit a fork that was already committed or discarded
+
+## fork_timing
+
+> Cannot create a fork inside an effect or when state changes are pending
+
 ## get_abort_signal_outside_reaction
 
 > `getAbortSignal()` can only be called inside an effect or derived

packages/svelte/src/index-client.js

@@ -241,7 +241,7 @@ function init_update_callbacks(context) {
 	return (l.u ??= { a: [], b: [], m: [] });
 }
 
-export { flushSync } from './internal/client/reactivity/batch.js';
+export { flushSync, fork } from './internal/client/reactivity/batch.js';
 export {
 	createContext,
 	getContext,

packages/svelte/src/index-server.js

@@ -33,6 +33,10 @@ export function unmount() {
 	e.lifecycle_function_unavailable('unmount');
 }
 
+export function fork() {
+	e.lifecycle_function_unavailable('fork');
+}
+
 export async function tick() {}
 
 export async function settled() {}

packages/svelte/src/index.d.ts

@@ -352,4 +352,20 @@ export type MountOptions<Props extends Record<string, any> = Record<string, any>
 			props: Props;
 		});
 
+/**
+ * Represents work that is happening off-screen, such as data being preloaded
+ * in anticipation of the user navigating
+ * @since 5.42
+ */
+export interface Fork {
+	/**
+	 * Commit the fork. The promise will resolve once the state change has been applied
+	 */
+	commit(): Promise<void>;
+	/**
+	 * Discard the fork
+	 */
+	discard(): void;
+}
+
 export * from './index-client.js';

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

@@ -19,7 +19,7 @@ export const EFFECT_RAN = 1 << 15;
  * This is on a block effect 99% of the time but may also be on a branch effect if its parent block effect was pruned
  */
 export const EFFECT_TRANSPARENT = 1 << 16;
-export const INSPECT_EFFECT = 1 << 17;
+export const EAGER_EFFECT = 1 << 17;
 export const HEAD_EFFECT = 1 << 18;
 export const EFFECT_PRESERVED = 1 << 19;
 export const USER_EFFECT = 1 << 20;

packages/svelte/src/internal/client/dev/inspect.js

@@ -1,6 +1,6 @@
 import { UNINITIALIZED } from '../../../constants.js';
 import { snapshot } from '../../shared/clone.js';
-import { inspect_effect, render_effect, validate_effect } from '../reactivity/effects.js';
+import { eager_effect, render_effect, validate_effect } from '../reactivity/effects.js';
 import { untrack } from '../runtime.js';
 import { get_stack } from './tracing.js';
 
@@ -19,7 +19,7 @@ export function inspect(get_value, inspector, show_stack = false) {
 	// stack traces. As a consequence, reading the value might result
 	// in an error (an `$inspect(object.property)` will run before the
 	// `{#if object}...{/if}` that contains it)
-	inspect_effect(() => {
+	eager_effect(() => {
 		try {
 			var value = get_value();
 		} catch (e) {

packages/svelte/src/internal/client/dom/blocks/branches.js

@@ -1,5 +1,4 @@
 /** @import { Effect, TemplateNode } from '#client' */
-import { is_runes } from '../../context.js';
 import { Batch, current_batch } from '../../reactivity/batch.js';
 import {
 	branch,
@@ -8,7 +7,6 @@ import {
 	pause_effect,
 	resume_effect
 } from '../../reactivity/effects.js';
-import { set_should_intro, should_intro } from '../../render.js';
 import { hydrate_node, hydrating } from '../hydration.js';
 import { create_text, should_defer_append } from '../operations.js';
 
@@ -126,6 +124,22 @@ export class BranchManager {
 		}
 	};
 
+	/**
+	 * @param {Batch} batch
+	 */
+	#discard = (batch) => {
+		this.#batches.delete(batch);
+
+		const keys = Array.from(this.#batches.values());
+
+		for (const [k, branch] of this.#offscreen) {
+			if (!keys.includes(k)) {
+				destroy_effect(branch.effect);
+				this.#offscreen.delete(k);
+			}
+		}
+	};
+
 	/**
 	 *
 	 * @param {any} key
@@ -173,7 +187,8 @@ export class BranchManager {
 				}
 			}
 
-			batch.add_callback(this.#commit);
+			batch.oncommit(this.#commit);
+			batch.ondiscard(this.#discard);
 		} else {
 			if (hydrating) {
 				this.anchor = hydrate_node;

packages/svelte/src/internal/client/dom/blocks/each.js

@@ -310,7 +310,7 @@ export function each(node, flags, get_collection, get_key, render_fn, fallback_f
 					}
 				}
 
-				batch.add_callback(commit);
+				batch.oncommit(commit);
 			} else {
 				commit();
 			}

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

@@ -229,6 +229,22 @@ export function effect_update_depth_exceeded() {
 	}
 }
 
+/**
+ * Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
+ * @returns {never}
+ */
+export function experimental_async_fork() {
+	if (DEV) {
+		const error = new Error(`experimental_async_fork\nCannot use \`fork(...)\` unless the \`experimental.async\` compiler option is \`true\`\nhttps://svelte.dev/e/experimental_async_fork`);
+
+		error.name = 'Svelte error';
+
+		throw error;
+	} else {
+		throw new Error(`https://svelte.dev/e/experimental_async_fork`);
+	}
+}
+
 /**
  * Cannot use `flushSync` inside an effect
  * @returns {never}
@@ -245,6 +261,38 @@ export function flush_sync_in_effect() {
 	}
 }
 
+/**
+ * Cannot commit a fork that was already committed or discarded
+ * @returns {never}
+ */
+export function fork_discarded() {
+	if (DEV) {
+		const error = new Error(`fork_discarded\nCannot commit a fork that was already committed or discarded\nhttps://svelte.dev/e/fork_discarded`);
+
+		error.name = 'Svelte error';
+
+		throw error;
+	} else {
+		throw new Error(`https://svelte.dev/e/fork_discarded`);
+	}
+}
+
+/**
+ * Cannot create a fork inside an effect or when state changes are pending
+ * @returns {never}
+ */
+export function fork_timing() {
+	if (DEV) {
+		const error = new Error(`fork_timing\nCannot create a fork inside an effect or when state changes are pending\nhttps://svelte.dev/e/fork_timing`);
+
+		error.name = 'Svelte error';
+
+		throw error;
+	} else {
+		throw new Error(`https://svelte.dev/e/fork_timing`);
+	}
+}
+
 /**
  * `getAbortSignal()` can only be called inside an effect or derived
  * @returns {never}

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

@@ -19,8 +19,8 @@ import {
 	state as source,
 	set,
 	increment,
-	flush_inspect_effects,
-	set_inspect_effects_deferred
+	flush_eager_effects,
+	set_eager_effects_deferred
 } from './reactivity/sources.js';
 import { PROXY_PATH_SYMBOL, STATE_SYMBOL } from '#client/constants';
 import { UNINITIALIZED } from '../../constants.js';
@@ -421,9 +421,9 @@ function inspectable_array(array) {
 			 * @param {any[]} args
 			 */
 			return function (...args) {
-				set_inspect_effects_deferred();
+				set_eager_effects_deferred();
 				var result = value.apply(this, args);
-				flush_inspect_effects();
+				flush_eager_effects();
 				return result;
 			};
 		}