feat: allow for fine grained invalidation of search params

.changeset/strange-eyes-sort.md

@@ -0,0 +1,5 @@
+---
+"@sveltejs/kit": minor
+---
+
+feat: allow for fine grained invalidation of search params

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

@@ -548,6 +548,8 @@ A `load` function that calls `await parent()` will also rerun if a parent `load`
 
 Dependency tracking does not apply _after_ the `load` function has returned — for example, accessing `params.x` inside a nested [promise](#streaming-with-promises) will not cause the function to rerun when `params.x` changes. (Don't worry, you'll get a warning in development if you accidentally do this.) Instead, access the parameter in the main body of your `load` function.
 
+When setting the `fineGrainedSearchParamsInvalidation` option to `true`, accessing a query parameter is tracked independently from the rest of the url. For example, accessing `event.url.searchParams.get("query")` inside a `load` function will make that `load` function rerun only when the `query` search param changes: Navigating from `/search?query=svelte&page=1` to `/search?query=svelte&page=2` will not rerun the load function.
+
 ### Manual invalidation
 
 You can also rerun `load` functions that apply to the current page using [`invalidate(url)`](modules#$app-navigation-invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`](modules#$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.
@@ -597,6 +599,7 @@ To summarize, a `load` function will rerun in the following situations:
 
 - It references a property of `params` whose value has changed
 - It references a property of `url` (such as `url.pathname` or `url.search`) whose value has changed. Properties in `request.url` are _not_ tracked
+- It calls `url.searchParams.get`, `url.searchParams.getAll` or `url.searchParams.has` and the specific search param passed to those functions changes. Accessing other properties of searchParams will have the same effect as accessing `url.search`. When `fineGrainedSearchParamsInvalidation` is `false`, accessing _any_ search param will cause the load function to rerun.
 - It calls `await parent()` and a parent `load` function reran
 - It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) (universal load only) or [`depends`](types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`](modules#$app-navigation-invalidate)
 - All active `load` functions were forcibly rerun with [`invalidateAll()`](modules#$app-navigation-invalidateall)

packages/kit/src/core/config/index.spec.js

@@ -113,7 +113,8 @@ const get_defaults = (prefix = '') => ({
 		version: {
 			name: Date.now().toString(),
 			pollInterval: 0
-		}
+		},
+		fineGrainedSearchParamsInvalidation: false
 	}
 });
 

packages/kit/src/core/config/options.js

@@ -280,7 +280,9 @@ const options = object(
 			version: object({
 				name: string(Date.now().toString()),
 				pollInterval: number(0)
-			})
+			}),
+			// TODO v2: remove this option (always true)
+			fineGrainedSearchParamsInvalidation: boolean(false)
 		})
 	},
 	true

packages/kit/src/core/sync/write_server.js

@@ -24,7 +24,8 @@ const server_template = ({
 	runtime_directory,
 	template,
 	error_page
-}) => `
+}) =>
+	`
 import root from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';
 import { set_building } from '__sveltekit/environment';
 import { set_assets } from '__sveltekit/paths';
@@ -33,6 +34,7 @@ import { set_private_env, set_public_env } from '${runtime_directory}/shared-ser
 export const options = {
 	app_template_contains_nonce: ${template.includes('%sveltekit.nonce%')},
 	csp: ${s(config.kit.csp)},
+	fine_grained_search_params_invalidation: ${config.kit.fineGrainedSearchParamsInvalidation},
 	csrf_check_origin: ${s(config.kit.csrf.checkOrigin)},
 	track_server_fetches: ${s(config.kit.dangerZone.trackServerFetches)},
 	embedded: ${config.kit.embedded},

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

@@ -628,6 +628,12 @@ export interface KitConfig {
 		 */
 		pollInterval?: number;
 	};
+	/**
+	 * When set to `true`, accessing `searchParams` on the `url` object tracks just that specific searchParam and not the whole URL, resulting in less load function reruns.
+	 * This option will be removed and always be `true` in SvelteKit version 2.
+	 * @default false
+	 */
+	fineGrainedSearchParamsInvalidation?: boolean;
 }
 
 /**

packages/kit/src/runtime/client/client.js

@@ -69,9 +69,10 @@ function native_navigation(url) {
 /**
  * @param {import('./types.js').SvelteKitApp} app
  * @param {HTMLElement} target
+ * @param {boolean} fine_grained_search_params_invalidation
  * @returns {import('./types.js').Client}
  */
-export function create_client(app, target) {
+export function create_client(app, target, fine_grained_search_params_invalidation) {
 	const routes = parse(app);
 
 	const default_layout_loader = app.nodes[0];
@@ -443,7 +444,8 @@ export function create_client(app, target) {
 			params: new Set(),
 			parent: false,
 			route: false,
-			url: false
+			url: false,
+			search_params: new Set()
 		};
 
 		const node = await loader();
@@ -478,9 +480,19 @@ export function create_client(app, target) {
 					}
 				}),
 				data: server_data_node?.data ?? null,
-				url: make_trackable(url, () => {
-					uses.url = true;
-				}),
+				url: make_trackable(
+					url,
+					() => {
+						uses.url = true;
+					},
+					(search_param) => {
+						if (fine_grained_search_params_invalidation) {
+							uses.search_params.add(search_param);
+						} else {
+							uses.url = true;
+						}
+					}
+				),
 				async fetch(resource, init) {
 					/** @type {URL | string} */
 					let requested;
@@ -576,10 +588,18 @@ export function create_client(app, target) {
 	 * @param {boolean} parent_changed
 	 * @param {boolean} route_changed
 	 * @param {boolean} url_changed
+	 * @param {Set<string>} search_params_changed
 	 * @param {import('types').Uses | undefined} uses
 	 * @param {Record<string, string>} params
 	 */
-	function has_changed(parent_changed, route_changed, url_changed, uses, params) {
+	function has_changed(
+		parent_changed,
+		route_changed,
+		url_changed,
+		search_params_changed,
+		uses,
+		params
+	) {
 		if (force_invalidation) return true;
 
 		if (!uses) return false;
@@ -588,6 +608,10 @@ export function create_client(app, target) {
 		if (uses.route && route_changed) return true;
 		if (uses.url && url_changed) return true;
 
+		for (const tracked_params of uses.search_params) {
+			if (search_params_changed.has(tracked_params)) return true;
+		}
+
 		for (const param of uses.params) {
 			if (params[param] !== current.params[param]) return true;
 		}
@@ -610,6 +634,35 @@ export function create_client(app, target) {
 		return null;
 	}
 
+	/**
+	 *
+	 * @param {URL} [old_url]
+	 * @param {URL} [new_url]
+	 */
+	function check_search_params_changed(old_url, new_url) {
+		const changed = new Set();
+		const new_search_params = new URLSearchParams(new_url?.searchParams);
+		const old_search_params = old_url?.searchParams;
+		for (const key of new Set(old_search_params?.keys?.() ?? [])) {
+			const new_get_all = new_search_params.getAll(key);
+			const old_get_all = old_search_params?.getAll?.(key) ?? [];
+			if (
+				// check if the two arrays contains the same values
+				!(
+					new_get_all.every((query_param) => old_get_all.includes(query_param)) &&
+					old_get_all.every((query_param) => new_get_all.includes(query_param))
+				)
+			) {
+				changed.add(key);
+			}
+			new_search_params.delete(key);
+		}
+		for (const [key] of new_search_params) {
+			changed.add(key);
+		}
+		return changed;
+	}
+
 	/**
 	 * @param {import('./types.js').NavigationIntent} intent
 	 * @returns {Promise<import('./types.js').NavigationResult>}
@@ -631,9 +684,9 @@ export function create_client(app, target) {
 
 		/** @type {import('types').ServerNodesResponse | import('types').ServerRedirectNode | null} */
 		let server_data = null;
-
 		const url_changed = current.url ? id !== current.url.pathname + current.url.search : false;
 		const route_changed = current.route ? route.id !== current.route.id : false;
+		const search_params_changed = check_search_params_changed(current.url, url);
 
 		let parent_invalid = false;
 		const invalid_server_nodes = loaders.map((loader, i) => {
@@ -642,7 +695,14 @@ export function create_client(app, target) {
 			const invalid =
 				!!loader?.[0] &&
 				(previous?.loader !== loader[1] ||
-					has_changed(parent_invalid, route_changed, url_changed, previous.server?.uses, params));
+					has_changed(
+						parent_invalid,
+						route_changed,
+						url_changed,
+						search_params_changed,
+						previous.server?.uses,
+						params
+					));
 
 			if (invalid) {
 				// For the next one
@@ -685,7 +745,14 @@ export function create_client(app, target) {
 			const valid =
 				(!server_data_node || server_data_node.type === 'skip') &&
 				loader[1] === previous?.loader &&
-				!has_changed(parent_changed, route_changed, url_changed, previous.universal?.uses, params);
+				!has_changed(
+					parent_changed,
+					route_changed,
+					url_changed,
+					search_params_changed,
+					previous.universal?.uses,
+					params
+				);
 			if (valid) return previous;
 
 			parent_changed = true;
@@ -1954,7 +2021,8 @@ function deserialize_uses(uses) {
 		params: new Set(uses?.params ?? []),
 		parent: !!uses?.parent,
 		route: !!uses?.route,
-		url: !!uses?.url
+		url: !!uses?.url,
+		search_params: new Set(uses?.search_params ?? [])
 	};
 }
 

packages/kit/src/runtime/client/start.js

@@ -5,16 +5,17 @@ import { init } from './singletons.js';
 /**
  * @param {import('./types.js').SvelteKitApp} app
  * @param {HTMLElement} target
+ * @param {boolean} fine_grained_search_params_invalidation
  * @param {Parameters<import('./types.js').Client['_hydrate']>[0]} [hydrate]
  */
-export async function start(app, target, hydrate) {
+export async function start(app, target, fine_grained_search_params_invalidation, hydrate) {
 	if (DEV && target === document.body) {
 		console.warn(
 			'Placing %sveltekit.body% directly inside <body> is not recommended, as your app may break for users who have certain browser extensions installed.\n\nConsider wrapping it in an element:\n\n<div style="display: contents">\n  %sveltekit.body%\n</div>'
 		);
 	}
 
-	const client = create_client(app, target);
+	const client = create_client(app, target, fine_grained_search_params_invalidation);
 
 	init({ client });
 

packages/kit/src/runtime/server/data/index.js

@@ -77,7 +77,8 @@ export async function render_data(
 							}
 							return data;
 						},
-						track_server_fetches: options.track_server_fetches
+						track_server_fetches: options.track_server_fetches,
+						fine_grained_search_params_invalidation: options.fine_grained_search_params_invalidation
 					});
 				} catch (e) {
 					aborted = true;

packages/kit/src/runtime/server/page/index.js

@@ -151,7 +151,8 @@ export async function render_page(event, page, options, manifest, state, resolve
 							}
 							return data;
 						},
-						track_server_fetches: options.track_server_fetches
+						track_server_fetches: options.track_server_fetches,
+						fine_grained_search_params_invalidation: options.fine_grained_search_params_invalidation
 					});
 				} catch (e) {
 					load_error = /** @type {Error} */ (e);

packages/kit/src/runtime/server/page/load_data.js

@@ -11,6 +11,7 @@ import { validate_depends } from '../../shared.js';
  *   node: import('types').SSRNode | undefined;
  *   parent: () => Promise<Record<string, any>>;
  *   track_server_fetches: boolean;
+ * 	 fine_grained_search_params_invalidation: boolean | undefined;
  * }} opts
  * @returns {Promise<import('types').ServerDataNode | null>}
  */
@@ -20,7 +21,8 @@ export async function load_server_data({
 	node,
 	parent,
 	// TODO 2.0: Remove this
-	track_server_fetches
+	track_server_fetches,
+	fine_grained_search_params_invalidation
 }) {
 	if (!node?.server) return null;
 
@@ -31,18 +33,34 @@ export async function load_server_data({
 		params: new Set(),
 		parent: false,
 		route: false,
-		url: false
+		url: false,
+		search_params: new Set()
 	};
 
-	const url = make_trackable(event.url, () => {
-		if (DEV && done && !uses.url) {
-			console.warn(
-				`${node.server_id}: Accessing URL properties in a promise handler after \`load(...)\` has returned will not cause the function to re-run when the URL changes`
-			);
-		}
+	const url = make_trackable(
+		event.url,
+		() => {
+			if (DEV && done && !uses.url) {
+				console.warn(
+					`${node.server_id}: Accessing URL properties in a promise handler after \`load(...)\` has returned will not cause the function to re-run when the URL changes`
+				);
+			}
 
-		uses.url = true;
-	});
+			uses.url = true;
+		},
+		(search_params) => {
+			if (DEV && done && uses.search_params.size === 0) {
+				console.warn(
+					`${node.server_id}: Accessing URL properties in a promise handler after \`load(...)\` has returned will not cause the function to re-run when the URL changes`
+				);
+			}
+			if (fine_grained_search_params_invalidation) {
+				uses.search_params.add(search_params);
+			} else {
+				uses.url = true;
+			}
+		}
+	);
 
 	if (state.prerendering) {
 		disable_search(url);

packages/kit/src/runtime/server/page/render.js

@@ -318,7 +318,7 @@ export async function render_response({
 						${properties.join(',\n\t\t\t\t\t\t')}
 					};`);
 
-		const args = ['app', 'element'];
+		const args = ['app', 'element', `${options.fine_grained_search_params_invalidation}`];
 
 		blocks.push('const element = document.currentScript.parentElement;');
 

packages/kit/src/runtime/server/page/respond_with_error.js

@@ -50,7 +50,8 @@ export async function respond_with_error({
 				state,
 				node: default_layout,
 				parent: async () => ({}),
-				track_server_fetches: options.track_server_fetches
+				track_server_fetches: options.track_server_fetches,
+				fine_grained_search_params_invalidation: options.fine_grained_search_params_invalidation
 			});
 
 			const server_data = await server_data_promise;

packages/kit/src/runtime/server/utils.js

@@ -149,6 +149,10 @@ export function stringify_uses(node) {
 		uses.push(`"dependencies":${JSON.stringify(Array.from(node.uses.dependencies))}`);
 	}
 
+	if (node.uses && node.uses.search_params.size > 0) {
+		uses.push(`"search_params":${JSON.stringify(Array.from(node.uses.search_params))}`);
+	}
+
 	if (node.uses && node.uses.params.size > 0) {
 		uses.push(`"params":${JSON.stringify(Array.from(node.uses.params))}`);
 	}

packages/kit/src/types/internal.d.ts

@@ -332,6 +332,7 @@ export type SSRNodeLoader = () => Promise<SSRNode>;
 export interface SSROptions {
 	app_template_contains_nonce: boolean;
 	csp: ValidatedConfig['kit']['csp'];
+	fine_grained_search_params_invalidation?: boolean;
 	csrf_check_origin: boolean;
 	track_server_fetches: boolean;
 	embedded: boolean;
@@ -408,6 +409,7 @@ export interface Uses {
 	parent: boolean;
 	route: boolean;
 	url: boolean;
+	search_params: Set<string>;
 }
 
 export type ValidatedConfig = RecursiveRequired<Config>;