@sveltejs/kit 2.54.0 → 2.56.0

package/src/runtime/client/remote-functions/query.svelte.js

@@ -1,16 +1,41 @@
 /** @import { RemoteQueryFunction } from '@sveltejs/kit' */
 /** @import { RemoteFunctionResponse } from 'types' */
 import { app_dir, base } from '$app/paths/internal/client';
-import { app, goto, query_map, remote_responses } from '../client.js';
-import { tick } from 'svelte';
+import { app, goto, query_map, query_responses } from '../client.js';
 import {
-	create_remote_function,
 	get_remote_request_headers,
+	QUERY_FUNCTION_ID,
+	QUERY_OVERRIDE_KEY,
+	QUERY_RESOURCE_KEY,
 	remote_request
 } from './shared.svelte.js';
 import * as devalue from 'devalue';
 import { HttpError, Redirect } from '@sveltejs/kit/internal';
 import { DEV } from 'esm-env';
+import { with_resolvers } from '../../../utils/promise.js';
+import { tick, untrack } from 'svelte';
+import { create_remote_key, stringify_remote_arg, unfriendly_hydratable } from '../../shared.js';
+
+/**
+ * @template T
+ * @typedef {{
+ *   count: number;
+ *   resource: Query<T>;
+ *   cleanup: () => void;
+ * }} RemoteQueryCacheEntry
+ */
+
+/**
+ * @returns {boolean} Returns `true` if we are in an effect
+ */
+function is_in_effect() {
+	try {
+		$effect.pre(() => {});
+		return true;
+	} catch {
+		return false;
+	}
+}
 
 /**
  * @param {string} id
@@ -19,144 +44,152 @@ import { DEV } from 'esm-env';
 export function query(id) {
 	if (DEV) {
 		// If this reruns as part of HMR, refresh the query
-		for (const [key, entry] of query_map) {
-			if (key === id || key.startsWith(id + '/')) {
+		const entries = query_map.get(id);
+
+		if (entries) {
+			for (const entry of entries.values()) {
 				// use optional chaining in case a prerender function was turned into a query
-				entry.resource.refresh?.();
+				void entry.resource.refresh?.();
 			}
 		}
 	}
 
-	return create_remote_function(id, (cache_key, payload) => {
-		return new Query(cache_key, async () => {
-			if (Object.hasOwn(remote_responses, cache_key)) {
-				return remote_responses[cache_key];
-			}
-
+	/** @type {RemoteQueryFunction<any, any>} */
+	const wrapper = (arg) => {
+		return new QueryProxy(id, arg, async (key, payload) => {
 			const url = `${base}/${app_dir}/remote/${id}${payload ? `?payload=${payload}` : ''}`;
 
-			const result = await remote_request(url, get_remote_request_headers());
-			return devalue.parse(result, app.decoders);
+			const serialized = await unfriendly_hydratable(key, () =>
+				remote_request(url, get_remote_request_headers())
+			);
+
+			return devalue.parse(serialized, app.decoders);
 		});
-	});
+	};
+
+	Object.defineProperty(wrapper, QUERY_FUNCTION_ID, { value: id });
+
+	return wrapper;
 }
 
 /**
  * @param {string} id
- * @returns {(arg: any) => Query<any>}
+ * @returns {RemoteQueryFunction<any, any>}
  */
 export function query_batch(id) {
 	/** @type {Map<string, Array<{resolve: (value: any) => void, reject: (error: any) => void}>>} */
-	// eslint-disable-next-line svelte/prefer-svelte-reactivity -- we don't need reactivity for this
 	let batching = new Map();
 
-	return create_remote_function(id, (cache_key, payload) => {
-		return new Query(cache_key, () => {
-			if (Object.hasOwn(remote_responses, cache_key)) {
-				return remote_responses[cache_key];
-			}
-
-			// Collect all the calls to the same query in the same macrotask,
-			// then execute them as one backend request.
-			return new Promise((resolve, reject) => {
-				// create_remote_function caches identical calls, but in case a refresh to the same query is called multiple times this function
-				// is invoked multiple times with the same payload, so we need to deduplicate here
-				const entry = batching.get(payload) ?? [];
-				entry.push({ resolve, reject });
-				batching.set(payload, entry);
-
-				if (batching.size > 1) return;
-
-				// Do this here, after await Svelte' reactivity context is gone.
-				// TODO is it possible to have batches of the same key
-				// but in different forks/async contexts and in the same macrotask?
-				// If so this would potentially be buggy
-				const headers = {
-					'Content-Type': 'application/json',
-					...get_remote_request_headers()
-				};
-
-				// Wait for the next macrotask - don't use microtask as Svelte runtime uses these to collect changes and flush them,
-				// and flushes could reveal more queries that should be batched.
-				setTimeout(async () => {
-					const batched = batching;
-					// eslint-disable-next-line svelte/prefer-svelte-reactivity
-					batching = new Map();
-
-					try {
-						const response = await fetch(`${base}/${app_dir}/remote/${id}`, {
-							method: 'POST',
-							body: JSON.stringify({
-								payloads: Array.from(batched.keys())
-							}),
-							headers
-						});
-
-						if (!response.ok) {
-							throw new Error('Failed to execute batch query');
-						}
+	/** @type {RemoteQueryFunction<any, any>} */
+	const wrapper = (arg) => {
+		return new QueryProxy(id, arg, async (key, payload) => {
+			const serialized = await unfriendly_hydratable(key, () => {
+				return new Promise((resolve, reject) => {
+					// create_remote_function caches identical calls, but in case a refresh to the same query is called multiple times this function
+					// is invoked multiple times with the same payload, so we need to deduplicate here
+					const entry = batching.get(payload) ?? [];
+					entry.push({ resolve, reject });
+					batching.set(payload, entry);
+
+					if (batching.size > 1) return;
+
+					// Do this here, after await Svelte' reactivity context is gone.
+					// TODO is it possible to have batches of the same key
+					// but in different forks/async contexts and in the same macrotask?
+					// If so this would potentially be buggy
+					const headers = {
+						'Content-Type': 'application/json',
+						...get_remote_request_headers()
+					};
+
+					// Wait for the next macrotask - don't use microtask as Svelte runtime uses these to collect changes and flush them,
+					// and flushes could reveal more queries that should be batched.
+					setTimeout(async () => {
+						const batched = batching;
+						batching = new Map();
+
+						try {
+							const response = await fetch(`${base}/${app_dir}/remote/${id}`, {
+								method: 'POST',
+								body: JSON.stringify({
+									payloads: Array.from(batched.keys())
+								}),
+								headers
+							});
+
+							if (!response.ok) {
+								throw new Error('Failed to execute batch query');
+							}
 
-						const result = /** @type {RemoteFunctionResponse} */ (await response.json());
-						if (result.type === 'error') {
-							throw new HttpError(result.status ?? 500, result.error);
-						}
+							const result = /** @type {RemoteFunctionResponse} */ (await response.json());
+							if (result.type === 'error') {
+								throw new HttpError(result.status ?? 500, result.error);
+							}
 
-						if (result.type === 'redirect') {
-							await goto(result.location);
-							throw new Redirect(307, result.location);
-						}
+							if (result.type === 'redirect') {
+								await goto(result.location);
+								throw new Redirect(307, result.location);
+							}
 
-						const results = devalue.parse(result.result, app.decoders);
+							const results = devalue.parse(result.result, app.decoders);
 
-						// Resolve individual queries
-						// Maps guarantee insertion order so we can do it like this
-						let i = 0;
+							// Resolve individual queries
+							// Maps guarantee insertion order so we can do it like this
+							let i = 0;
 
-						for (const resolvers of batched.values()) {
-							for (const { resolve, reject } of resolvers) {
-								if (results[i].type === 'error') {
-									reject(new HttpError(results[i].status, results[i].error));
-								} else {
-									resolve(results[i].data);
+							for (const resolvers of batched.values()) {
+								for (const { resolve, reject } of resolvers) {
+									if (results[i].type === 'error') {
+										reject(new HttpError(results[i].status, results[i].error));
+									} else {
+										resolve(results[i].data);
+									}
 								}
+								i++;
 							}
-							i++;
-						}
-					} catch (error) {
-						// Reject all queries in the batch
-						for (const resolver of batched.values()) {
-							for (const { reject } of resolver) {
-								reject(error);
+						} catch (error) {
+							// Reject all queries in the batch
+							for (const resolver of batched.values()) {
+								for (const { reject } of resolver) {
+									reject(error);
+								}
 							}
 						}
-					}
-				}, 0);
+					}, 0);
+				});
 			});
+
+			return devalue.parse(serialized, app.decoders);
 		});
-	});
+	};
+
+	Object.defineProperty(wrapper, QUERY_FUNCTION_ID, { value: id });
+
+	return wrapper;
 }
 
 /**
+ * The actual query instance. There should only ever be one active query instance per key.
+ *
  * @template T
- * @implements {Partial<Promise<T>>}
+ * @implements {Promise<T>}
  */
 export class Query {
 	/** @type {string} */
-	_key;
+	#key;
 
-	#init = false;
 	/** @type {() => Promise<T>} */
 	#fn;
 	#loading = $state(true);
-	/** @type {Array<() => void>} */
+	/** @type {Array<(value: undefined) => void>} */
 	#latest = [];
 
 	/** @type {boolean} */
 	#ready = $state(false);
 	/** @type {T | undefined} */
 	#raw = $state.raw();
-	/** @type {Promise<void>} */
-	#promise;
+	/** @type {Promise<void> | null} */
+	#promise = $state.raw(null);
 	/** @type {Array<(old: T) => T>} */
 	#overrides = $state([]);
 
@@ -168,21 +201,17 @@ export class Query {
 		return this.#overrides.reduce((v, r) => r(v), /** @type {T} */ (this.#raw));
 	});
 
+	/** @type {any} */
 	#error = $state.raw(undefined);
 
 	/** @type {Promise<T>['then']} */
 	// @ts-expect-error TS doesn't understand that the promise returns something
 	#then = $derived.by(() => {
-		const p = this.#promise;
+		const p = this.#get_promise();
 		this.#overrides.length;
 
 		return (resolve, reject) => {
-			const result = (async () => {
-				await p;
-				// svelte-ignore await_reactivity_loss
-				await tick();
-				return /** @type {T} */ (this.#current);
-			})();
+			const result = p.then(tick).then(() => /** @type {T} */ (this.#current));
 
 			if (resolve || reject) {
 				return result.then(resolve, reject);
@@ -197,34 +226,34 @@ export class Query {
 	 * @param {() => Promise<T>} fn
 	 */
 	constructor(key, fn) {
-		this._key = key;
+		this.#key = key;
 		this.#fn = fn;
-		this.#promise = $state.raw(this.#run());
+	}
+
+	#get_promise() {
+		void untrack(() => (this.#promise ??= this.#run()));
+		return /** @type {Promise<T>} */ (this.#promise);
+	}
+
+	#start() {
+		// there is a really weird bug with untrack and writes and initializations
+		// every time you see this comment, try removing the `tick.then` here and see
+		// if all the tests still pass with the latest svelte version
+		// if they do, congrats, you can remove tick.then
+		void tick().then(() => this.#get_promise());
+	}
+
+	#clear_pending() {
+		this.#latest.forEach((r) => r(undefined));
+		this.#latest.length = 0;
 	}
 
 	#run() {
-		// Prevent state_unsafe_mutation error on first run when the resource is created within the template
-		if (this.#init) {
-			this.#loading = true;
-		} else {
-			this.#init = true;
-		}
+		this.#loading = true;
 
-		// Don't use Promise.withResolvers, it's too new still
-		/** @type {() => void} */
-		let resolve;
-		/** @type {(e?: any) => void} */
-		let reject;
-		/** @type {Promise<void>} */
-		const promise = new Promise((res, rej) => {
-			resolve = res;
-			reject = rej;
-		});
+		const { promise, resolve, reject } = with_resolvers();
 
-		this.#latest.push(
-			// @ts-expect-error it's defined at this point
-			resolve
-		);
+		this.#latest.push(resolve);
 
 		Promise.resolve(this.#fn())
 			.then((value) => {
@@ -232,21 +261,27 @@ export class Query {
 				const idx = this.#latest.indexOf(resolve);
 				if (idx === -1) return;
 
-				this.#latest.splice(0, idx).forEach((r) => r());
-				this.#ready = true;
-				this.#loading = false;
-				this.#raw = value;
-				this.#error = undefined;
+				// Untrack this to not trigger mutation validation errors which can occur if you do e.g. $derived({ a: await queryA(), b: await queryB() })
+				untrack(() => {
+					this.#latest.splice(0, idx).forEach((r) => r(undefined));
+					this.#ready = true;
+					this.#loading = false;
+					this.#raw = value;
+					this.#error = undefined;
+				});
 
-				resolve();
+				resolve(undefined);
 			})
 			.catch((e) => {
 				const idx = this.#latest.indexOf(resolve);
 				if (idx === -1) return;
 
-				this.#latest.splice(0, idx).forEach((r) => r());
-				this.#error = e;
-				this.#loading = false;
+				untrack(() => {
+					this.#latest.splice(0, idx).forEach((r) => r(undefined));
+					this.#error = e;
+					this.#loading = false;
+				});
+
 				reject(e);
 			});
 
@@ -281,10 +316,12 @@ export class Query {
 	}
 
 	get current() {
+		this.#start();
 		return this.#current;
 	}
 
 	get error() {
+		this.#start();
 		return this.#error;
 	}
 
@@ -292,6 +329,7 @@ export class Query {
 	 * Returns true if the resource is loading or reloading.
 	 */
 	get loading() {
+		this.#start();
 		return this.#loading;
 	}
 
@@ -299,6 +337,7 @@ export class Query {
 	 * Returns true once the resource has been loaded for the first time.
 	 */
 	get ready() {
+		this.#start();
 		return this.#ready;
 	}
 
@@ -306,7 +345,7 @@ export class Query {
 	 * @returns {Promise<void>}
 	 */
 	refresh() {
-		delete remote_responses[this._key];
+		delete query_responses[this.#key];
 		return (this.#promise = this.#run());
 	}
 
@@ -314,6 +353,7 @@ export class Query {
 	 * @param {T} value
 	 */
 	set(value) {
+		this.#clear_pending();
 		this.#ready = true;
 		this.#loading = false;
 		this.#error = undefined;
@@ -321,21 +361,251 @@ export class Query {
 		this.#promise = Promise.resolve();
 	}
 
+	/**
+	 * @param {unknown} error
+	 */
+	fail(error) {
+		this.#clear_pending();
+		this.#loading = false;
+		this.#error = error;
+
+		const promise = Promise.reject(error);
+
+		promise.catch(() => {});
+		this.#promise = promise;
+	}
+
 	/**
 	 * @param {(old: T) => T} fn
+	 * @returns {(() => void) & { [QUERY_OVERRIDE_KEY]: string }}
 	 */
 	withOverride(fn) {
 		this.#overrides.push(fn);
 
-		return {
-			_key: this._key,
-			release: () => {
+		const release = /** @type {(() => void) & { [QUERY_OVERRIDE_KEY]: string }} */ (
+			() => {
 				const i = this.#overrides.indexOf(fn);
 
 				if (i !== -1) {
 					this.#overrides.splice(i, 1);
 				}
 			}
+		);
+
+		Object.defineProperty(release, QUERY_OVERRIDE_KEY, { value: this.#key });
+
+		return release;
+	}
+
+	get [Symbol.toStringTag]() {
+		return 'Query';
+	}
+}
+
+/**
+ * Manages the caching layer between the user and the actual {@link Query} instance. This is the thing
+ * the developer actually gets to interact with in their application code.
+ *
+ * @template T
+ * @implements {Promise<T>}
+ */
+class QueryProxy {
+	#id;
+	#key;
+	#payload;
+	#fn;
+	#active = true;
+	/**
+	 * Whether this proxy was created in a tracking context.
+	 * @readonly
+	 */
+	#tracking = is_in_effect();
+
+	/**
+	 * @param {string} id
+	 * @param {any} arg
+	 * @param {(key: string, payload: string) => Promise<T>} fn
+	 */
+	constructor(id, arg, fn) {
+		this.#id = id;
+		this.#payload = stringify_remote_arg(arg, app.hooks.transport);
+		this.#key = create_remote_key(id, this.#payload);
+		Object.defineProperty(this, QUERY_RESOURCE_KEY, { value: this.#key });
+		this.#fn = fn;
+
+		if (!this.#tracking) {
+			this.#active = false;
+			return;
+		}
+
+		const entry = this.#get_or_create_cache_entry();
+
+		$effect.pre(() => () => {
+			const die = this.#release(entry);
+			void tick().then(die);
+		});
+	}
+
+	/** @returns {RemoteQueryCacheEntry<T>} */
+	#get_or_create_cache_entry() {
+		let query_instances = query_map.get(this.#id);
+
+		if (!query_instances) {
+			query_instances = new Map();
+			query_map.set(this.#id, query_instances);
+		}
+
+		let this_instance = query_instances.get(this.#payload);
+
+		if (!this_instance) {
+			const c = (this_instance = {
+				count: 0,
+				resource: /** @type {Query<T>} */ (/** @type {unknown} */ (null)),
+				cleanup: /** @type {() => void} */ (/** @type {unknown} */ (null))
+			});
+
+			c.cleanup = $effect.root(() => {
+				c.resource = new Query(this.#key, () => this.#fn(this.#key, this.#payload));
+			});
+
+			query_instances.set(this.#payload, this_instance);
+		}
+
+		this_instance.count += 1;
+
+		return this_instance;
+	}
+
+	/**
+	 * @param {RemoteQueryCacheEntry<T>} entry
+	 * @param {boolean} [deactivate]
+	 * @returns
+	 */
+	#release(entry, deactivate = true) {
+		this.#active &&= !deactivate;
+		entry.count -= 1;
+
+		return () => {
+			const query_instances = query_map.get(this.#id);
+			const this_instance = query_instances?.get(this.#payload);
+
+			if (this_instance?.count === 0) {
+				this_instance.cleanup();
+				query_instances?.delete(this.#payload);
+			}
+			if (query_instances?.size === 0) {
+				query_map.delete(this.#id);
+			}
 		};
 	}
+
+	#get_cached_query() {
+		// TODO iterate on error messages
+		if (!this.#tracking) {
+			throw new Error(
+				'This query was not created in a reactive context and is limited to calling `.run`, `.refresh`, and `.set`.'
+			);
+		}
+
+		if (!this.#active) {
+			throw new Error(
+				'This query instance is no longer active and can no longer be used for reactive state access. ' +
+					'This typically means you created the query in a tracking context and stashed it somewhere outside of a tracking context.'
+			);
+		}
+
+		const cached = query_map.get(this.#id)?.get(this.#payload);
+
+		if (!cached) {
+			// The only case where `this.#active` can be `true` is when we've added an entry to `query_map`, and the
+			// only way that entry can get removed is if this instance (and all others) have been deactivated.
+			// So if we get here, someone (us, check git blame and point fingers) did `entry.count -= 1` improperly.
+			throw new Error(
+				'No cached query found. This should be impossible. Please file a bug report.'
+			);
+		}
+
+		return cached.resource;
+	}
+
+	#safe_get_cached_query() {
+		return query_map.get(this.#id)?.get(this.#payload)?.resource;
+	}
+
+	get current() {
+		return this.#get_cached_query().current;
+	}
+
+	get error() {
+		return this.#get_cached_query().error;
+	}
+
+	get loading() {
+		return this.#get_cached_query().loading;
+	}
+
+	get ready() {
+		return this.#get_cached_query().ready;
+	}
+
+	run() {
+		if (is_in_effect()) {
+			throw new Error(
+				'On the client, .run() can only be called outside render, e.g. in universal `load` functions and event handlers. In render, await the query directly'
+			);
+		}
+
+		if (Object.hasOwn(query_responses, this.#key)) {
+			return Promise.resolve(query_responses[this.#key]);
+		}
+		return this.#fn(this.#key, this.#payload);
+	}
+
+	refresh() {
+		return this.#safe_get_cached_query()?.refresh() ?? Promise.resolve();
+	}
+
+	/** @type {Query<T>['set']} */
+	set(value) {
+		this.#safe_get_cached_query()?.set(value);
+	}
+
+	/** @type {Query<T>['withOverride']} */
+	withOverride(fn) {
+		const entry = this.#get_or_create_cache_entry();
+		const override = entry.resource.withOverride(fn);
+
+		const release = /** @type {(() => void) & { [QUERY_OVERRIDE_KEY]: string }} */ (
+			() => {
+				override();
+				this.#release(entry, false)();
+			}
+		);
+
+		Object.defineProperty(release, QUERY_OVERRIDE_KEY, { value: override[QUERY_OVERRIDE_KEY] });
+
+		return release;
+	}
+
+	/** @type {Query<T>['then']} */
+	get then() {
+		const cached = this.#get_cached_query();
+		return cached.then.bind(cached);
+	}
+
+	/** @type {Query<T>['catch']} */
+	get catch() {
+		const cached = this.#get_cached_query();
+		return cached.catch.bind(cached);
+	}
+
+	/** @type {Query<T>['finally']} */
+	get finally() {
+		const cached = this.#get_cached_query();
+		return cached.finally.bind(cached);
+	}
+
+	get [Symbol.toStringTag]() {
+		return 'QueryProxy';
+	}
 }