feat: forking (#17004)

* chore: run boundary async effects in the context of the current batch

* WIP

* reinstate kludge

* fix test

* WIP

* WIP

* WIP

* remove kludge

* restore batch_values after commit

* make private

* tidy up

* fix tests

* update test

* reset #dirty_effects and #maybe_dirty_effects

* add test

* WIP

* add test, fix block resolution

* bring async-effect-after-await test from defer-effects-in-pending-boundary branch

* avoid reawakening committed batches

* changeset

* cheat

* better API

* regenerate

* slightly better approach

* lint

* revert this whatever it is

* add test

* Update feature description for fork API

* error if missing experimental flag

* rename inspect effects to eager effects, run them in prod

* regenerate

* Apply suggestions from code review

Co-authored-by: Simon H <[email protected]>

* tidy up

* add some minimal prose. probably don't need to go super deep here as it's not really meant for non-framework authors

* bit more detail

* add a fork_timing error, regenerate

* unused

* add note

* add fork_discarded error

* require users to discard forks

* add docs

* regenerate

* tweak docs

* fix leak

* fix

* preload on focusin as well

* missed a spot

* reduce nesting

---------

Co-authored-by: Simon H <[email protected]>

Author: Rich-Harris

.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;