feat: `$state.eager(value)` (#16849)

* WIP implement `$effect.pending(...)`

* feat: `$state.eager(value)` (#16926)

* runtime-first approach

* revert these

* type safety, lint

* fix: better input cursor restoration for `bind:value` (#16925)

If cursor was at end and new input is longer, move cursor to new end

No test because not possible to reproduce using our test setup.

Follow-up to #14649, helps with #16577

* Version Packages (#16920)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* docs: await no longer need pending (#16900)

* docs: link to custom renderer issue in Svelte Native discussion (#16896)

* fix code block (#16937)

Updated code block syntax from Svelte to JavaScript for clarity.

* fix: unset context on stale promises (#16935)

* fix: unset context on stale promises

When a stale promise is rejected in `async_derived`, and the promise eventually resolves, `d.resolve` will be noop and `d.promise.then(handler, ...)` will never run. That in turns means any restored context (via `(await save(..))()`) will never be unset. We have to handle this case and unset the context to prevent errors such as false-positive state mutation errors

* fix: unset context on stale promises (slightly different approach) (#16936)

* slightly different approach to #16935

* move unset_context call

* get rid of logs

---------

Co-authored-by: Rich Harris <rich.harris@vercel.com>

* fix: svg `radialGradient` `fr` attribute missing in types (#16943)

* fix(svg radialGradient): fr attribute missing in types

* chore: add changeset

* Version Packages (#16940)

* Version Packages

* Update packages/svelte/CHANGELOG.md

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rich Harris <rich.harris@vercel.com>

* chore: simplify `batch.apply()` (#16945)

* chore: simplify `batch.apply()`

* belt and braces

* note to self

* unused

* fix: don't rerun async effects unnecessarily (#16944)

Since #16866, when an async effect runs multiple times, we rebase older batches and rerun those effects. This can have unintended consequences: In a case where an async effect only depends on a single source, and that single source was updated in a later batch, we know that we don't need to / should not rerun the older batch.

This PR makes it so: We collect all the sources of older batches that are not part of the current batch that just committed, and then only mark those async effects as dirty which depend on one of those other sources. Fixes the bug I noticed while working on #16935

* fix: ensure map iteration order is correct (#16947)

quick follow-up to #16944
Resetting a map entry does not change its position in the map when iterating. We need to make sure that reset makes that batch jump "to the front" for the "reject all stale batches" logic below. Edge case for which I can't come up with a test case but it _is_ a possibility.

* feat: add `createContext` utility for type-safe context (#16948)

* feat: add `createContext` utility for type-safe context

* regenerate

* Version Packages (#16946)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* chore: Remove annoying sync-async warning (#16949)

* fix

* use `$state.eager(value)` instead of `$effect.pending(value)`

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Hyunbin Seo <47051820+hyunbinseo@users.noreply.github.com>
Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>
Co-authored-by: Rich Harris <rich.harris@vercel.com>
Co-authored-by: Hannes Rüger <hannes@hannesrueger.de>
Co-authored-by: Elliott Johnson <sejohnson@torchcloudconsulting.com>

* decouple from boundaries

* use queue_micro_task

* add test

* fix

* changeset

* revert

* tidy up

* update docs

* Update packages/svelte/src/internal/client/reactivity/batch.js

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>

* minor tweak

---------

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Hyunbin Seo <47051820+hyunbinseo@users.noreply.github.com>
Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>
Co-authored-by: Hannes Rüger <hannes@hannesrueger.de>
Co-authored-by: Elliott Johnson <sejohnson@torchcloudconsulting.com>

.changeset/shy-boats-protect.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: add `$state.eager(value)` rune

documentation/docs/02-runes/02-$state.md

@@ -166,6 +166,21 @@ To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snaps
 
 This is handy when you want to pass some state to an external library or API that doesn't expect a proxy, such as `structuredClone`.
 
+## `$state.eager`
+
+When state changes, it may not be reflected in the UI immediately if it is used by an `await` expression, because [updates are synchronized](await-expressions#Synchronized-updates).
+
+In some cases, you may want to update the UI as soon as the state changes. For example, you might want to update a navigation bar when the user clicks on a link, so that they get visual feedback while waiting for the new page to load. To do this, use `$state.eager(value)`:
+
+```svelte
+<nav>
+	<a href="/" aria-current={$state.eager(pathname) === '/' ? 'page' : null}>home</a>
+	<a href="/about" aria-current={$state.eager(pathname) === '/about' ? 'page' : null}>about</a>
+</nav>
+```
+
+Use this feature sparingly, and only to provide feedback in response to user action — in general, allowing Svelte to coordinate updates will provide a better user experience.
+
 ## Passing state into functions
 
 JavaScript is a _pass-by-value_ language — when you call a function, the arguments are the _values_ rather than the _variables_. In other words:

packages/svelte/src/ambient.d.ts

@@ -95,6 +95,18 @@ declare namespace $state {
 								: never
 							: never;
 
+	/**
+	 * Returns the latest `value`, even if the rest of the UI is suspending
+	 * while async work (such as data loading) completes.
+	 *
+	 * ```svelte
+	 * <nav>
+	 *   <a href="/" aria-current={$state.eager(pathname) === '/' ? 'page' : null}>home</a>
+	 *   <a href="/about" aria-current={$state.eager(pathname) === '/about' ? 'page' : null}>about</a>
+	 * </nav>
+	 * ```
+	 */
+	export function eager<T>(value: T): T;
 	/**
 	 * Declares state that is _not_ made deeply reactive — instead of mutating it,
 	 * you must reassign it.

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

@@ -226,6 +226,13 @@ export function CallExpression(node, context) {
 			break;
 		}
 
+		case '$state.eager':
+			if (node.arguments.length !== 1) {
+				e.rune_invalid_arguments_length(node, rune, 'exactly one argument');
+			}
+
+			break;
+
 		case '$state.snapshot':
 			if (node.arguments.length !== 1) {
 				e.rune_invalid_arguments_length(node, rune, 'exactly one argument');

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

@@ -49,6 +49,12 @@ export function CallExpression(node, context) {
 			return b.call('$.derived', rune === '$derived' ? b.thunk(fn) : fn);
 		}
 
+		case '$state.eager':
+			return b.call(
+				'$.eager',
+				b.thunk(/** @type {Expression} */ (context.visit(node.arguments[0])))
+			);
+
 		case '$state.snapshot':
 			return b.call(
 				'$.snapshot',

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

@@ -38,6 +38,10 @@ export function CallExpression(node, context) {
 		return b.call('$.derived', rune === '$derived' ? b.thunk(fn) : fn);
 	}
 
+	if (rune === '$state.eager') {
+		return node.arguments[0];
+	}
+
 	if (rune === '$state.snapshot') {
 		return b.call(
 			'$.snapshot',

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

@@ -103,7 +103,7 @@ export {
 	save,
 	track_reactivity_loss
 } from './reactivity/async.js';
-export { flushSync as flush } from './reactivity/batch.js';
+export { eager, flushSync as flush } from './reactivity/batch.js';
 export {
 	async_derived,
 	user_derived as derived,

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

@@ -17,6 +17,7 @@ import { async_mode_flag } from '../../flags/index.js';
 import { deferred, define_property } from '../../shared/utils.js';
 import {
 	active_effect,
+	get,
 	is_dirty,
 	is_updating_effect,
 	set_is_updating_effect,
@@ -27,8 +28,8 @@ import * as e from '../errors.js';
 import { flush_tasks, queue_micro_task } from '../dom/task.js';
 import { DEV } from 'esm-env';
 import { invoke_error_boundary } from '../error-handling.js';
-import { old_values } from './sources.js';
-import { unlink_effect } from './effects.js';
+import { old_values, source, update } from './sources.js';
+import { inspect_effect, unlink_effect } from './effects.js';
 
 /** @type {Set<Batch>} */
 const batches = new Set();
@@ -684,6 +685,65 @@ export function schedule_effect(signal) {
 	queued_root_effects.push(effect);
 }
 
+/** @type {Source<number>[]} */
+let eager_versions = [];
+
+function eager_flush() {
+	try {
+		flushSync(() => {
+			for (const version of eager_versions) {
+				update(version);
+			}
+		});
+	} finally {
+		eager_versions = [];
+	}
+}
+
+/**
+ * Implementation of `$state.eager(fn())`
+ * @template T
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function eager(fn) {
+	var version = source(0);
+	var initial = true;
+	var value = /** @type {T} */ (undefined);
+
+	get(version);
+
+	inspect_effect(() => {
+		if (initial) {
+			// the first time this runs, we create an inspect effect
+			// that will run eagerly whenever the expression changes
+			var previous_batch_values = batch_values;
+
+			try {
+				batch_values = null;
+				value = fn();
+			} finally {
+				batch_values = previous_batch_values;
+			}
+
+			return;
+		}
+
+		// the second time this effect runs, it's to schedule a
+		// `version` update. since this will recreate the effect,
+		// we don't need to evaluate the expression here
+		if (eager_versions.length === 0) {
+			queue_micro_task(eager_flush);
+		}
+
+		eager_versions.push(version);
+	});
+
+	initial = false;
+
+	return value;
+}
+
 /**
  * Forcibly remove all current batches, to prevent cross-talk between tests
  */

packages/svelte/src/utils.js

@@ -436,6 +436,7 @@ const STATE_CREATION_RUNES = /** @type {const} */ ([
 
 const RUNES = /** @type {const} */ ([
 	...STATE_CREATION_RUNES,
+	'$state.eager',
 	'$state.snapshot',
 	'$props',
 	'$props.id',

packages/svelte/tests/runtime-runes/samples/async-state-eager/_config.js

@@ -0,0 +1,36 @@
+import { tick } from 'svelte';
+import { test } from '../../test';
+
+export default test({
+	async test({ assert, target }) {
+		const [count, shift] = target.querySelectorAll('button');
+
+		shift.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>0</button><button>shift</button><p>0</p>`);
+
+		count.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>1</button><button>shift</button><p>0</p>`);
+
+		count.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>2</button><button>shift</button><p>0</p>`);
+
+		count.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>3</button><button>shift</button><p>0</p>`);
+
+		shift.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>3</button><button>shift</button><p>1</p>`);
+
+		shift.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>3</button><button>shift</button><p>2</p>`);
+
+		shift.click();
+		await tick();
+		assert.htmlEqual(target.innerHTML, `<button>3</button><button>shift</button><p>3</p>`);
+	}
+});

packages/svelte/tests/runtime-runes/samples/async-state-eager/main.svelte

@@ -0,0 +1,20 @@
+<script>
+	let count = $state(0);
+
+	let resolvers = [];
+
+	function push(value) {
+		const { promise, resolve } = Promise.withResolvers();
+		resolvers.push(() => resolve(value));
+		return promise;
+	}
+</script>
+
+<button onclick={() => count += 1}>{$state.eager(count)}</button>
+<button onclick={() => resolvers.shift()?.()}>shift</button>
+
+<svelte:boundary>
+	<p>{await push(count)}</p>
+
+	{#snippet pending()}{/snippet}
+</svelte:boundary>

packages/svelte/types/index.d.ts

@@ -3193,6 +3193,18 @@ declare namespace $state {
 								: never
 							: never;
 
+	/**
+	 * Returns the latest `value`, even if the rest of the UI is suspending
+	 * while async work (such as data loading) completes.
+	 *
+	 * ```svelte
+	 * <nav>
+	 *   <a href="/" aria-current={$state.eager(pathname) === '/' ? 'page' : null}>home</a>
+	 *   <a href="/about" aria-current={$state.eager(pathname) === '/about' ? 'page' : null}>about</a>
+	 * </nav>
+	 * ```
+	 */
+	export function eager<T>(value: T): T;
 	/**
 	 * Declares state that is _not_ made deeply reactive — instead of mutating it,
 	 * you must reassign it.