[feat] custom load dependencies (#4536)

* [feat] custom load dependencies

* [test] custom load dependencies

* [docs] custom load dependencies

* [changeset] custom load dependencies

* [fix] wrong case

* Update documentation/docs/04-loading.md

Co-authored-by: Rich Harris <[email protected]>

.changeset/breezy-mayflies-yawn.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Custom `load` `dependencies` in `LoadOutput`

documentation/docs/04-loading.md

@@ -134,3 +134,9 @@ If the `load` function returns a `props` object, the props will be passed to the
 This will be merged with any existing `stuff` and passed to the `load` functions of subsequent layout and page components.
 
 The combined `stuff` is available to components using the [page store](/docs/modules#$app-stores) as `$page.stuff`, providing a mechanism for pages to pass data 'upward' to layouts.
+
+#### dependencies
+
+An array of strings representing URLs the page depends on, which can subsequently be used with [`invalidate`](/docs/modules#$app-navigation-invalidate) to cause `load` to rerun. You only need to add them to `dependencies` if you're using a custom API client; URLs loaded with the provided `fetch` function are added automatically.
+
+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).

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

@@ -477,6 +477,12 @@ export function create_client({ target, session, base, trailing_slash }) {
 			stuff
 		};
 
+		/** @param dep {string} */
+		function add_dependency(dep) {
+			const { href } = new URL(dep, url);
+			node.uses.dependencies.add(href);
+		}
+
 		if (props) {
 			// shadow endpoint props means we need to mark this URL as a dependency of itself
 			node.uses.dependencies.add(url.href);
@@ -516,8 +522,7 @@ export function create_client({ target, session, base, trailing_slash }) {
 				},
 				fetch(resource, info) {
 					const requested = typeof resource === 'string' ? resource : resource.url;
-					const { href } = new URL(requested, url);
-					node.uses.dependencies.add(href);
+					add_dependency(requested);
 
 					return started ? fetch(resource, info) : initial_fetch(resource, info);
 				},
@@ -542,6 +547,9 @@ export function create_client({ target, session, base, trailing_slash }) {
 
 			node.loaded = normalize(loaded);
 			if (node.loaded.stuff) node.stuff = node.loaded.stuff;
+			if (node.loaded.dependencies) {
+				node.loaded.dependencies.forEach(add_dependency);
+			}
 		} else if (props) {
 			node.loaded = normalize({ props });
 		}

packages/kit/src/runtime/load.js

@@ -9,10 +9,7 @@ export function normalize(loaded) {
 		const status = loaded.status;
 
 		if (!loaded.error && has_error_status) {
-			return {
-				status: status || 500,
-				error: new Error()
-			};
+			return { status: status || 500, error: new Error() };
 		}
 
 		const error = typeof loaded.error === 'string' ? new Error(loaded.error) : loaded.error;
@@ -52,6 +49,18 @@ export function normalize(loaded) {
 		}
 	}
 
+	if (loaded.dependencies) {
+		if (
+			!Array.isArray(loaded.dependencies) ||
+			loaded.dependencies.some((dep) => typeof dep !== 'string')
+		) {
+			return {
+				status: 500,
+				error: new Error('"dependencies" property returned from load() must be of type string[]')
+			};
+		}
+	}
+
 	// TODO remove before 1.0
 	if (/** @type {any} */ (loaded).context) {
 		throw new Error(

packages/kit/test/apps/basics/src/routes/load/change-detection/__layout.svelte

@@ -13,7 +13,8 @@
 			props: {
 				type,
 				loads: count
-			}
+			},
+			dependencies: ['custom:change-detection-layout']
 		};
 	}
 </script>

packages/kit/test/apps/basics/test/test.js

@@ -1197,6 +1197,10 @@ test.describe.parallel('Load', () => {
 			await app.invalidate('/load/change-detection/data.json');
 			expect(await page.textContent('h1')).toBe('layout loads: 3');
 			expect(await page.textContent('h2')).toBe('x: b: 2');
+
+			await app.invalidate('custom:change-detection-layout');
+			expect(await page.textContent('h1')).toBe('layout loads: 4');
+			expect(await page.textContent('h2')).toBe('x: b: 2');
 		}
 	});
 

packages/kit/types/index.d.ts

@@ -208,6 +208,7 @@ export interface LoadOutput<Props extends Record<string, any> = Record<string, a
 	props?: Props;
 	stuff?: Partial<App.Stuff>;
 	maxage?: number;
+	dependencies?: string[];
 }
 
 export interface Navigation {

packages/kit/types/internal.d.ts

@@ -118,6 +118,7 @@ export type NormalizedLoadOutput = {
 	props?: Record<string, any> | Promise<Record<string, any>>;
 	stuff?: Record<string, any>;
 	maxage?: number;
+	dependencies?: string[];
 };
 
 export interface PageData {