breaking: deprecate invalidate/invalidateAll

.changeset/refresh-page-state.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': major
+---
+
+breaking: add `refresh`/`refreshAll` and deprecate `invalidate`/`invalidateAll`

documentation/docs/20-core-concepts/20-load.md

@@ -638,18 +638,20 @@ export async function load({ untrack, url }) {
 
 ### Manual invalidation
 
-You can also rerun `load` functions that apply to the current page using [`invalidate(url)`]($app-navigation#invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`]($app-navigation#invalidateAll), which reruns every `load` function. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client.
+You can also rerun `load` functions that apply to the current page using [`refresh(url)`]($app-navigation#refresh), which reruns all `load` functions that depend on `url`, and [`refreshAll()`]($app-navigation#refreshAll), which reruns every `load` function and all active queries. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client.
+
+> [!NOTE] `refresh` and `refreshAll` do _not_ reset `page.state`. This is useful when you're using [shallow routing](shallow-routing) and want to refresh data without losing the current page state. The deprecated `invalidate` and `invalidateAll` functions _do_ reset `page.state` — prefer `refresh` and `refreshAll`.
 
 A `load` function depends on `url` if it calls `fetch(url)` or `depends(url)`. Note that `url` can be a custom identifier that starts with `[a-z]:`:
 
 ```js
 /// file: src/routes/random-number/+page.js
 /** @type {import('./$types').PageLoad} */
 export async function load({ fetch, depends }) {
-	// load reruns when `invalidate('https://api.example.com/random-number')` is called...
+	// load reruns when `refresh('https://api.example.com/random-number')` is called...
 	const response = await fetch('https://api.example.com/random-number');
 
-	// ...or when `invalidate('app:random')` is called
+	// ...or when `refresh('app:random')` is called
 	depends('app:random');
 
 	return {
@@ -661,17 +663,17 @@ export async function load({ fetch, depends }) {
 ```svelte
 <!--- file: src/routes/random-number/+page.svelte --->
 <script>
-	import { invalidate, invalidateAll } from '$app/navigation';
+	import { refresh, refreshAll } from '$app/navigation';
 
 	/** @type {import('./$types').PageProps} */
 	let { data } = $props();
 
 	function rerunLoadFunction() {
 		// any of these will cause the `load` function to rerun
-		invalidate('app:random');
-		invalidate('https://api.example.com/random-number');
-		invalidate(url => url.href.includes('random-number'));
-		invalidateAll();
+		refresh('app:random');
+		refresh('https://api.example.com/random-number');
+		refresh(url => url.href.includes('random-number'));
+		refreshAll();
 	}
 </script>
 
@@ -688,8 +690,8 @@ To summarize, a `load` function will rerun in the following situations:
 - It calls `url.searchParams.get(...)`, `url.searchParams.getAll(...)` or `url.searchParams.has(...)` and the parameter in question changes. Accessing other properties of `url.searchParams` will have the same effect as accessing `url.search`.
 - It calls `await parent()` and a parent `load` function reran
 - A child `load` function calls `await parent()` and is rerunning, and the parent is a server load function
-- It declared a dependency on a specific URL via [`fetch`](#Making-fetch-requests) (universal load only) or [`depends`](@sveltejs-kit#LoadEvent), and that URL was marked invalid with [`invalidate(url)`]($app-navigation#invalidate)
-- All active `load` functions were forcibly rerun with [`invalidateAll()`]($app-navigation#invalidateAll)
+- It declared a dependency on a specific URL via [`fetch`](#Making-fetch-requests) (universal load only) or [`depends`](@sveltejs-kit#LoadEvent), and that URL was marked invalid with [`refresh(url)`]($app-navigation#refresh)
+- All active `load` functions were forcibly rerun with [`refreshAll()`]($app-navigation#refreshAll)
 
 `params` and `url` can change in response to a `<a href="..">` link click, a [`<form>` interaction](form-actions#GET-vs-POST), a [`goto`]($app-navigation#goto) invocation, or a [`redirect`](@sveltejs-kit#redirect).
 

documentation/docs/20-core-concepts/30-form-actions.md

@@ -433,7 +433,7 @@ We can also implement progressive enhancement ourselves, without `use:enhance`,
 ```svelte
 <!--- file: src/routes/login/+page.svelte --->
 <script>
-	import { invalidateAll, goto } from '$app/navigation';
+	import { refreshAll, goto } from '$app/navigation';
 	import { applyAction, deserialize } from '$app/forms';
 
 	/** @type {import('./$types').PageProps} */
@@ -453,8 +453,8 @@ We can also implement progressive enhancement ourselves, without `use:enhance`,
 		const result = deserialize(await response.text());
 
 		if (result.type === 'success') {
-			// rerun all `load` functions, following the successful update
-			await invalidateAll();
+			// rerun all `load` functions and queries, following the successful update
+			await refreshAll();
 		}
 
 		applyAction(result);

packages/kit/src/exports/public.d.ts

@@ -1139,15 +1139,15 @@ export interface LoadEvent<
 	 */
 	parent: () => Promise<ParentData>;
 	/**
-	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](https://svelte.dev/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`refresh()`](https://svelte.dev/docs/kit/$app-navigation#refresh) to cause `load` to rerun.
 	 *
 	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
 	 *
 	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
 	 *
 	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
 	 *
-	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `refresh`ed after a button click, making the `load` function rerun.
 	 *
 	 * ```js
 	 * /// file: src/routes/+page.js
@@ -1162,12 +1162,12 @@ export interface LoadEvent<
 	 * ```html
 	 * /// file: src/routes/+page.svelte
 	 * <script>
-	 * 	import { invalidate } from '$app/navigation';
+	 * 	import { refresh } from '$app/navigation';
 	 *
 	 * 	let { data } = $props();
 	 *
 	 * 	const increase = async () => {
-	 * 		await invalidate('increase:count');
+	 * 		await refresh('increase:count');
 	 * 	}
 	 * </script>
 	 *
@@ -1812,15 +1812,15 @@ export interface ServerLoadEvent<
 	 */
 	parent: () => Promise<ParentData>;
 	/**
-	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](https://svelte.dev/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`refresh()`](https://svelte.dev/docs/kit/$app-navigation#refresh) to cause `load` to rerun.
 	 *
 	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
 	 *
 	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
 	 *
 	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
 	 *
-	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `refresh`ed after a button click, making the `load` function rerun.
 	 *
 	 * ```js
 	 * /// file: src/routes/+page.js
@@ -1835,12 +1835,12 @@ export interface ServerLoadEvent<
 	 * ```html
 	 * /// file: src/routes/+page.svelte
 	 * <script>
-	 * 	import { invalidate } from '$app/navigation';
+	 * 	import { refresh } from '$app/navigation';
 	 *
 	 * 	let { data } = $props();
 	 *
 	 * 	const increase = async () => {
-	 * 		await invalidate('increase:count');
+	 * 		await refresh('increase:count');
 	 * 	}
 	 * </script>
 	 *

packages/kit/src/runtime/app/forms.js

@@ -1,7 +1,7 @@
 import * as devalue from 'devalue';
 import { BROWSER, DEV } from 'esm-env';
 import { noop } from '../../utils/functions.js';
-import { invalidateAll } from './navigation.js';
+import { refreshAll } from './navigation.js';
 import { app as client_app, applyAction, handle_error } from '../client/client.js';
 import { app as server_app } from '../server/app.js';
 
@@ -106,7 +106,7 @@ export function enhance(form_element, submit = noop) {
 				HTMLFormElement.prototype.reset.call(form_element);
 			}
 			if (shouldInvalidateAll) {
-				await invalidateAll();
+				await refreshAll();
 			}
 		}
 

packages/kit/src/runtime/app/navigation.js

@@ -5,6 +5,7 @@ export {
 	goto,
 	invalidate,
 	invalidateAll,
+	refresh,
 	refreshAll,
 	onNavigate,
 	preloadCode,