feat: hydratable and a more consistent remote functions model

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

@@ -2123,6 +2123,12 @@ export type RemoteResource<T> = Promise<Awaited<T>> & {
 	get error(): any;
 	/** `true` before the first result is available and during refreshes */
 	get loading(): boolean;
+	/**
+	 * Returns a plain promise with the result.
+	 * Unlike awaiting the resource directly, this can be used anywhere
+	 * (load functions, event handlers, etc) without requiring a reactive context.
+	 */
+	run(): Promise<Awaited<T>>;
 } & (
 		| {
 				/** The current value of the query. Undefined until `ready` is `true` */

packages/kit/src/runtime/app/server/remote/shared.js

@@ -3,7 +3,7 @@
 import { parse } from 'devalue';
 import { error } from '@sveltejs/kit';
 import { with_request_store, get_request_store } from '@sveltejs/kit/internal/server';
-import { stringify_remote_arg } from '../../../shared.js';
+import { stringify_remote_arg, create_remote_key, unfriendly_hydratable } from '../../../shared.js';
 
 /**
  * @param {any} validate_or_fn
@@ -73,8 +73,21 @@ export async function get_response(info, arg, state, get_result) {
 	await 0;
 
 	const cache = get_cache(info, state);
+	const key = stringify_remote_arg(arg, state.transport);
+	const entry = (cache[key] ??= {
+		serialize: false,
+		data: get_result()
+	});
 
-	return (cache[stringify_remote_arg(arg, state.transport)] ??= get_result());
+	entry.serialize ||= !!state.is_in_universal_load;
+
+	if (state.is_in_render && info.id) {
+		const remote_key = create_remote_key(info.id, key);
+
+		unfriendly_hydratable(remote_key, () => entry.data);
+	}
+
+	return entry.data;
 }
 
 /**

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

@@ -282,7 +282,7 @@ const preload_tokens = new Set();
 export let pending_invalidate;
 
 /**
- * @type {Map<string, {count: number, resource: any}>}
+ * @type {Map<string, { count: number, resource: any }>}
  * A map of id -> query info with all queries that currently exist in the app.
  */
 export const query_map = new Map();
@@ -1535,8 +1535,6 @@ async function navigate({
 	block = noop,
 	event
 }) {
-	remote_responses = {};
-
 	const prev_token = token;
 	token = nav_token;
 
@@ -2177,8 +2175,6 @@ export function refreshAll({ includeLoadFunctions = true } = {}) {
 		throw new Error('Cannot call refreshAll() on the server');
 	}
 
-	remote_responses = {};
-
 	force_invalidation = true;
 	return _invalidate(includeLoadFunctions, false);
 }
@@ -2855,6 +2851,8 @@ async function _hydrate(
 
 		target.textContent = '';
 		hydrate = false;
+	} finally {
+		remote_responses = {};
 	}
 
 	if (result.props.page) {

packages/kit/src/runtime/client/remote-functions/prerender.svelte.js

@@ -1,3 +1,4 @@
+/** @import { RemotePrerenderFunction } from '@sveltejs/kit' */
 import { app_dir, base } from '$app/paths/internal/client';
 import { version } from '__sveltekit/environment';
 import * as devalue from 'devalue';
@@ -8,6 +9,7 @@ import {
 	get_remote_request_headers,
 	remote_request
 } from './shared.svelte.js';
+import { unfriendly_hydratable } from '../../shared.js';
 
 // Initialize Cache API for prerender functions
 const CACHE_NAME = DEV ? `sveltekit:${Date.now()}` : `sveltekit:${version}`;
@@ -32,31 +34,117 @@ const prerender_cache_ready = (async () => {
 	}
 })();
 
+/**
+ * @param {string} url
+ * @param {string} encoded
+ */
+function put(url, encoded) {
+	return /** @type {Cache} */ (prerender_cache)
+		.put(
+			url,
+			// We need to create a new response because the original response is already consumed
+			new Response(encoded, {
+				headers: {
+					'Content-Type': 'application/json'
+				}
+			})
+		)
+		.catch(() => {
+			// Nothing we can do here
+		});
+}
+
+/**
+ * @param {string} id
+ * @returns {RemotePrerenderFunction<any, any>}
+ */
+export function prerender(id) {
+	const fn = create_remote_function(
+		id,
+		({ cache_key, payload }) => {
+			const url = `${base}/${app_dir}/remote/${id}${payload ? `/${payload}` : ''}`;
+
+			return new Prerender(
+				cache_key,
+				(encoded) => put(url, encoded),
+				() => {
+					return unfriendly_hydratable(cache_key, async () => {
+						await prerender_cache_ready;
+						// Do this here, after await Svelte' reactivity context is gone.
+						const headers = get_remote_request_headers();
+
+						// Check the Cache API first
+						if (prerender_cache) {
+							try {
+								const cached_response = await prerender_cache.match(url);
+
+								if (cached_response) {
+									const cached_result = await cached_response.text();
+									return devalue.parse(cached_result, app.decoders);
+								}
+							} catch {
+								// Nothing we can do here
+							}
+						}
+
+						const encoded = await remote_request(url, headers);
+
+						// For successful prerender requests, save to cache
+						if (prerender_cache) {
+							void put(url, encoded);
+						}
+
+						return devalue.parse(encoded, app.decoders);
+					});
+				}
+			);
+		},
+		({ cache_key, get_resource }) => {
+			return new LimitedPrerender(cache_key, get_resource);
+		}
+	);
+
+	return fn;
+}
+
 /**
  * @template T
- * @implements {Partial<Promise<T>>}
+ * @implements {Promise<T>}
  */
 class Prerender {
+	/** @type {string} */
+	_key;
+
 	/** @type {Promise<T>} */
 	#promise;
 
 	#loading = $state(true);
 	#ready = $state(false);
+	/** @type {(encoded: string) => Promise<void>} */
+	#put_to_cache;
+	/** @type {() => Promise<T>} */
+	#fn;
 
 	/** @type {T | undefined} */
 	#current = $state.raw();
 
 	#error = $state.raw(undefined);
 
 	/**
+	 * @param {string} key
+	 * @param {(encoded: string) => Promise<void>} put_to_cache
 	 * @param {() => Promise<T>} fn
 	 */
-	constructor(fn) {
+	constructor(key, put_to_cache, fn) {
+		this._key = key;
+		this.#put_to_cache = put_to_cache;
+		this.#fn = fn;
 		this.#promise = fn().then(
 			(value) => {
 				this.#loading = false;
 				this.#ready = true;
 				this.#current = value;
+				this.#error = undefined;
 				return value;
 			},
 			(error) => {
@@ -67,6 +155,19 @@ class Prerender {
 		);
 	}
 
+	/** @returns {Promise<T>} */
+	async run() {
+		if (Object.hasOwn(remote_responses, this._key)) {
+			const data = remote_responses[this._key];
+
+			if (prerender_cache) {
+				await prerender_cache_ready;
+				void this.#put_to_cache(devalue.stringify(data, app.encoders));
+			}
+		}
+		return this.#fn();
+	}
+
 	/**
 	 *
 	 * @param {((value: any) => any) | null | undefined} onfulfilled
@@ -112,73 +213,80 @@ class Prerender {
 	get ready() {
 		return this.#ready;
 	}
-}
 
-/**
- * @param {string} url
- * @param {string} encoded
- */
-function put(url, encoded) {
-	return /** @type {Cache} */ (prerender_cache)
-		.put(
-			url,
-			// We need to create a new response because the original response is already consumed
-			new Response(encoded, {
-				headers: {
-					'Content-Type': 'application/json'
-				}
-			})
-		)
-		.catch(() => {
-			// Nothing we can do here
-		});
+	get [Symbol.toStringTag]() {
+		return 'Prerender';
+	}
 }
 
 /**
- * @param {string} id
+ * @template T
+ * @implements {Promise<T>}
  */
-export function prerender(id) {
-	return create_remote_function(id, (cache_key, payload) => {
-		return new Prerender(async () => {
-			await prerender_cache_ready;
+class LimitedPrerender {
+	/** @type {string} */
+	_key;
 
-			const url = `${base}/${app_dir}/remote/${id}${payload ? `/${payload}` : ''}`;
+	/** @type {() => { cached: boolean, resource: Prerender<T> }} */
+	#get_prerender;
 
-			if (Object.hasOwn(remote_responses, cache_key)) {
-				const data = remote_responses[cache_key];
+	/** @returns {never} */
+	#limited_error() {
+		throw new Error(
+			'This prerender function was not created in a reactive context and is limited to calling `.run`.'
+		);
+	}
 
-				if (prerender_cache) {
-					void put(url, devalue.stringify(data, app.encoders));
-				}
+	/**
+	 * @param {string} key
+	 * @param {() => { cached: boolean, resource: Prerender<T> }} get_prerender
+	 */
+	constructor(key, get_prerender) {
+		this._key = key;
+		this.#get_prerender = get_prerender;
+	}
 
-				return data;
-			}
+	/** @returns {Promise<T>} */
+	run() {
+		return this.#get_prerender().resource.run();
+	}
 
-			// Do this here, after await Svelte' reactivity context is gone.
-			const headers = get_remote_request_headers();
+	/** @type {Promise<T>['then']} */
+	then() {
+		this.#limited_error();
+	}
 
-			// Check the Cache API first
-			if (prerender_cache) {
-				try {
-					const cached_response = await prerender_cache.match(url);
-
-					if (cached_response) {
-						const cached_result = await cached_response.text();
-						return devalue.parse(cached_result, app.decoders);
-					}
-				} catch {
-					// Nothing we can do here
-				}
-			}
+	/** @type {Promise<T>['catch']} */
+	catch() {
+		this.#limited_error();
+	}
 
-			const encoded = await remote_request(url, headers);
+	/** @type {Promise<T>['finally']} */
+	finally() {
+		this.#limited_error();
+	}
 
-			// For successful prerender requests, save to cache
-			if (prerender_cache) {
-				void put(url, encoded);
-			}
+	/** @type {Prerender<T>['current']} */
+	get current() {
+		return this.#limited_error();
+	}
 
-			return devalue.parse(encoded, app.decoders);
-		});
-	});
+	/** @type {Prerender<T>['error']} */
+	get error() {
+		return this.#limited_error();
+	}
+
+	/** @type {Prerender<T>['loading']} */
+	get loading() {
+		return this.#limited_error();
+	}
+
+	/** @type {Prerender<T>['ready']} */
+	get ready() {
+		return this.#limited_error();
+	}
+
+	get [Symbol.toStringTag]() {
+		return 'LimitedPrerender';
+	}
 }