@sveltejs/kit 2.58.0 → 2.59.0

package/src/runtime/app/server/remote/query.js

@@ -1,13 +1,19 @@
-/** @import { RemoteQuery, RemoteQueryFunction } from '@sveltejs/kit' */
-/** @import { RemoteInternals, MaybePromise, RequestState, RemoteQueryBatchInternals, RemoteQueryInternals } from 'types' */
+/** @import { RemoteLiveQuery, RemoteLiveQueryFunction, RemoteQuery, RemoteQueryFunction } from '@sveltejs/kit' */
+/** @import { RemoteInternals, MaybePromise, RequestState, RemoteQueryLiveInternals, RemoteQueryBatchInternals, RemoteQueryInternals, RemoteLiveQueryUserFunctionReturnType } from 'types' */
 /** @import { StandardSchemaV1 } from '@standard-schema/spec' */
 import { get_request_store } from '@sveltejs/kit/internal/server';
 import { create_remote_key, stringify, stringify_remote_arg } from '../../../shared.js';
 import { prerendering } from '__sveltekit/environment';
-import { noop } from '../../../../utils/functions.js';
-import { create_validator, get_cache, get_response, run_remote_function } from './shared.js';
+import {
+	create_validator,
+	get_cache,
+	get_response,
+	run_remote_function,
+	run_remote_generator
+} from './shared.js';
 import { handle_error_and_jsonify } from '../../../server/utils.js';
 import { HttpError, SvelteKitError } from '@sveltejs/kit/internal';
+import { noop } from '../../../../utils/functions.js';
 
 /**
  * Creates a remote query. When called from the browser, the function will be invoked on the server via a `fetch` call.
@@ -98,6 +104,110 @@ export function query(validate_or_fn, maybe_fn) {
 	return wrapper;
 }
 
+/**
+ * Creates a live remote query. When called from the browser, the function will be invoked on the server via a streaming `fetch` call.
+ *
+ * See [Remote functions](https://svelte.dev/docs/kit/remote-functions#query.live) for full documentation.
+ *
+ * @template Output
+ * @overload
+ * @param {(arg: void) => RemoteLiveQueryUserFunctionReturnType<Output>} fn
+ * @returns {RemoteLiveQueryFunction<void, Output>}
+ */
+/**
+ * @template Input
+ * @template Output
+ * @overload
+ * @param {'unchecked'} validate
+ * @param {(arg: Input) => RemoteLiveQueryUserFunctionReturnType<Output>} fn
+ * @returns {RemoteLiveQueryFunction<Input, Output>}
+ */
+/**
+ * @template {StandardSchemaV1} Schema
+ * @template Output
+ * @overload
+ * @param {Schema} schema
+ * @param {(arg: StandardSchemaV1.InferOutput<Schema>) => RemoteLiveQueryUserFunctionReturnType<Output>} fn
+ * @returns {RemoteLiveQueryFunction<StandardSchemaV1.InferInput<Schema>, Output, StandardSchemaV1.InferOutput<Schema>>}
+ */
+/**
+ * @template Input
+ * @template Output
+ * @param {any} validate_or_fn
+ * @param {(args: Input) => RemoteLiveQueryUserFunctionReturnType<Output>} [maybe_fn]
+ * @returns {RemoteLiveQueryFunction<Input, Output>}
+ */
+/*@__NO_SIDE_EFFECTS__*/
+function live(validate_or_fn, maybe_fn) {
+	/** @type {(arg: Input) => RemoteLiveQueryUserFunctionReturnType<Output>} */
+	const fn = maybe_fn ?? validate_or_fn;
+
+	/** @type {(arg?: any) => MaybePromise<Input>} */
+	const validate = create_validator(validate_or_fn, maybe_fn);
+
+	/**
+	 * @param {any} event
+	 * @param {any} state
+	 * @param {any} get_input
+	 */
+	const run = (event, state, get_input) =>
+		run_remote_generator(event, state, false, get_input, fn, __.name);
+
+	/**
+	 * @param {any} generator
+	 * @returns {Promise<any>}
+	 */
+	const first_value = async (generator) => {
+		try {
+			const { value, done } = await generator.next();
+
+			if (done) {
+				throw new Error(`query.live '${__.name}' did not yield a value`);
+			}
+
+			return value;
+		} finally {
+			await generator.return(undefined);
+		}
+	};
+
+	/** @type {RemoteQueryLiveInternals} */
+	const __ = {
+		type: 'query_live',
+		id: '',
+		name: '',
+		run: (event, state, arg) => run(event, state, () => validate(arg)),
+		validate,
+		bind(payload, validated_arg) {
+			const { event, state } = get_request_store();
+
+			return create_live_query_resource(__, payload, state, () =>
+				first_value(run(event, state, () => validated_arg))
+			);
+		}
+	};
+
+	/** @type {RemoteLiveQueryFunction<Input, Output> & { __: RemoteQueryLiveInternals }} */
+	const wrapper = (arg) => {
+		if (prerendering) {
+			throw new Error(
+				`Cannot call query.live '${__.name}' while prerendering, as prerendered pages need static data. Use 'prerender' from $app/server instead`
+			);
+		}
+
+		const { event, state } = get_request_store();
+		const payload = stringify_remote_arg(arg, state.transport);
+
+		return create_live_query_resource(__, payload, state, () =>
+			first_value(run(event, state, () => validate(arg)))
+		);
+	};
+
+	Object.defineProperty(wrapper, '__', { value: __ });
+
+	return wrapper;
+}
+
 /**
  * Creates a batch query function that collects multiple calls and executes them in a single request
  *
@@ -140,11 +250,81 @@ function batch(validate_or_fn, maybe_fn) {
 	/** @type {(arg?: any) => MaybePromise<Input>} */
 	const validate = create_validator(validate_or_fn, maybe_fn);
 
+	/** @type {Map<string, { get_validated: () => MaybePromise<any>, resolvers: Array<{resolve: (value: any) => void, reject: (error: any) => void}> }>} */
+	let batching = new Map();
+
+	/**
+	 * Enqueues a single call into the current batch (creating one if necessary)
+	 * and returns a promise that resolves with the result for this entry.
+	 *
+	 * @param {string} payload — the stringified raw argument (cache key)
+	 * @param {() => MaybePromise<any>} get_validated — produces the validated argument for this entry
+	 * @returns {Promise<any>}
+	 */
+	const enqueue = (payload, get_validated) => {
+		const { event, state } = get_request_store();
+
+		return new Promise((resolve, reject) => {
+			const entry = batching.get(payload);
+
+			if (entry) {
+				entry.resolvers.push({ resolve, reject });
+				return;
+			}
+
+			batching.set(payload, {
+				get_validated,
+				resolvers: [{ resolve, reject }]
+			});
+
+			if (batching.size > 1) return;
+
+			setTimeout(async () => {
+				const batched = batching;
+				batching = new Map();
+				const entries = Array.from(batched.values());
+
+				try {
+					return await run_remote_function(
+						event,
+						state,
+						false,
+						async () => Promise.all(entries.map((entry) => entry.get_validated())),
+						async (input) => {
+							const get_result = await fn(input);
+
+							for (let i = 0; i < entries.length; i++) {
+								try {
+									const result = get_result(input[i], i);
+
+									for (const resolver of entries[i].resolvers) {
+										resolver.resolve(result);
+									}
+								} catch (error) {
+									for (const resolver of entries[i].resolvers) {
+										resolver.reject(error);
+									}
+								}
+							}
+						}
+					);
+				} catch (error) {
+					for (const entry of batched.values()) {
+						for (const resolver of entry.resolvers) {
+							resolver.reject(error);
+						}
+					}
+				}
+			}, 0);
+		});
+	};
+
 	/** @type {RemoteQueryBatchInternals} */
 	const __ = {
 		type: 'query_batch',
 		id: '',
 		name: '',
+		validate,
 		run: async (args, options) => {
 			const { event, state } = get_request_store();
 
@@ -175,12 +355,14 @@ function batch(validate_or_fn, maybe_fn) {
 					);
 				}
 			);
+		},
+		bind(payload, validated_arg) {
+			const { state } = get_request_store();
+
+			return create_query_resource(__, payload, state, () => enqueue(payload, () => validated_arg));
 		}
 	};
 
-	/** @type {Map<string, { arg: any, resolvers: Array<{resolve: (value: any) => void, reject: (error: any) => void}> }>} */
-	let batching = new Map();
-
 	/** @type {RemoteQueryFunction<Input, Output> & { __: RemoteQueryBatchInternals }} */
 	const wrapper = (arg) => {
 		if (prerendering) {
@@ -189,69 +371,14 @@ function batch(validate_or_fn, maybe_fn) {
 			);
 		}
 
-		const { event, state } = get_request_store();
-		// batched queries do not participate in `requested(...)`, so `arg` is
-		// always the raw user-supplied value and can be used for the cache key directly
+		const { state } = get_request_store();
 		const payload = stringify_remote_arg(arg, state.transport);
 
-		return create_query_resource(__, payload, state, () => {
+		return create_query_resource(__, payload, state, () =>
 			// Collect all the calls to the same query in the same macrotask,
 			// then execute them as one backend request.
-			return new Promise((resolve, reject) => {
-				const entry = batching.get(payload);
-
-				if (entry) {
-					entry.resolvers.push({ resolve, reject });
-					return;
-				}
-
-				batching.set(payload, {
-					arg,
-					resolvers: [{ resolve, reject }]
-				});
-
-				if (batching.size > 1) return;
-
-				setTimeout(async () => {
-					const batched = batching;
-					batching = new Map();
-					const entries = Array.from(batched.values());
-					const args = entries.map((entry) => entry.arg);
-
-					try {
-						return await run_remote_function(
-							event,
-							state,
-							false,
-							async () => Promise.all(args.map(validate)),
-							async (input) => {
-								const get_result = await fn(input);
-
-								for (let i = 0; i < entries.length; i++) {
-									try {
-										const result = get_result(input[i], i);
-
-										for (const resolver of entries[i].resolvers) {
-											resolver.resolve(result);
-										}
-									} catch (error) {
-										for (const resolver of entries[i].resolvers) {
-											resolver.reject(error);
-										}
-									}
-								}
-							}
-						);
-					} catch (error) {
-						for (const entry of batched.values()) {
-							for (const resolver of entry.resolvers) {
-								resolver.reject(error);
-							}
-						}
-					}
-				}, 0);
-			});
-		});
+			enqueue(payload, () => validate(arg))
+		);
 	};
 
 	Object.defineProperty(wrapper, '__', { value: __ });
@@ -274,19 +401,38 @@ function create_query_resource(__, payload, state, fn) {
 		return (promise ??= get_response(__, payload, state, fn));
 	};
 
+	const populate_hydratable = () => {
+		// accessing data properties needs to kick off the work
+		// so that it gets seeded in the hydration cache
+		// and becomes available on the client
+		void (__.id && state.is_in_render && get_promise());
+	};
+
 	return {
 		/** @type {Promise<any>['catch']} */
 		catch(onrejected) {
 			return get_promise().catch(onrejected);
 		},
-		current: undefined,
-		error: undefined,
+		get current() {
+			populate_hydratable();
+			return undefined;
+		},
+		get error() {
+			populate_hydratable();
+			return undefined;
+		},
 		/** @type {Promise<any>['finally']} */
 		finally(onfinally) {
 			return get_promise().finally(onfinally);
 		},
-		loading: true,
-		ready: false,
+		get loading() {
+			populate_hydratable();
+			return true;
+		},
+		get ready() {
+			populate_hydratable();
+			return false;
+		},
 		refresh() {
 			const refresh_context = get_refresh_context(__, 'refresh', payload);
 			const is_immediate_refresh = !refresh_context.cache[refresh_context.payload];
@@ -321,14 +467,92 @@ function create_query_resource(__, payload, state, fn) {
 	};
 }
 
+/**
+ * @param {RemoteQueryLiveInternals} __
+ * @param {string} payload — the stringified raw argument (i.e. the cache key the client will use)
+ * @param {RequestState} state
+ * @param {() => Promise<any>} get_first_value
+ * @returns {RemoteLiveQuery<any>}
+ */
+function create_live_query_resource(__, payload, state, get_first_value) {
+	/** @type {Promise<any> | null} */
+	let promise = null;
+
+	const get_promise = () => {
+		return (promise ??= get_response(__, payload, state, get_first_value));
+	};
+
+	const populate_hydratable = () => {
+		void (__.id && state.is_in_render && get_promise());
+	};
+
+	return {
+		/** @type {Promise<any>['catch']} */
+		catch(onrejected) {
+			return get_promise().catch(onrejected);
+		},
+		get current() {
+			populate_hydratable();
+			return undefined;
+		},
+		get error() {
+			populate_hydratable();
+			return undefined;
+		},
+		/** @type {Promise<any>['finally']} */
+		finally(onfinally) {
+			return get_promise().finally(onfinally);
+		},
+		get done() {
+			populate_hydratable();
+			return false;
+		},
+		get loading() {
+			populate_hydratable();
+			return true;
+		},
+		get ready() {
+			populate_hydratable();
+			return false;
+		},
+		get connected() {
+			populate_hydratable();
+			return false;
+		},
+		reconnect() {
+			const reconnects = state.remote.reconnects;
+
+			if (!reconnects) {
+				throw new Error(
+					`Cannot call reconnect on query.live '${__.name}' because it is not executed in the context of a command/form remote function`
+				);
+			}
+
+			reconnects.set(create_remote_key(__.id, payload), get_promise());
+			return Promise.resolve();
+		},
+		run() {
+			throw new Error('Cannot call .run() on a live query on the server');
+		},
+		/** @type {Promise<any>['then']} */
+		then(onfulfilled, onrejected) {
+			return get_promise().then(onfulfilled, onrejected);
+		},
+		get [Symbol.toStringTag]() {
+			return 'LiveQueryResource';
+		}
+	};
+}
+
 // Add batch as a property to the query function
 Object.defineProperty(query, 'batch', { value: batch, enumerable: true });
+Object.defineProperty(query, 'live', { value: live, enumerable: true });
 
 /**
  * @param {RemoteInternals} __
  * @param {'set' | 'refresh'} action
- * @param {string} payload — the stringified raw argument
- * @returns {{ __: RemoteInternals; state: any; refreshes: Record<string, Promise<any>>; cache: Record<string, { serialize: boolean; data: any }>; refreshes_key: string; payload: string }}
+ * @param {string} payload — the stringified raw argument (i.e. the cache key the client will use)
+ * @returns {{ __: RemoteInternals; state: any; refreshes: Map<string, Promise<any>>; cache: Record<string, { serialize: boolean; data: any }>; refreshes_key: string; payload: string }}
  */
 function get_refresh_context(__, action, payload) {
 	const { state } = get_request_store();
@@ -348,7 +572,7 @@ function get_refresh_context(__, action, payload) {
 }
 
 /**
- * @param {{ __: RemoteInternals; refreshes: Record<string, Promise<any>>; cache: Record<string, { serialize: boolean; data: any }>; refreshes_key: string; payload: string }} context
+ * @param {{ __: RemoteInternals; refreshes: Map<string, Promise<any>>; cache: Record<string, { serialize: boolean; data: any }>; refreshes_key: string; payload: string }} context
  * @param {any} value
  * @param {boolean} [is_immediate_refresh=false]
  * @returns {Promise<void>}
@@ -365,8 +589,13 @@ function update_refresh_value(
 	}
 
 	if (__.id) {
-		refreshes[refreshes_key] = promise;
+		refreshes.set(refreshes_key, promise);
 	}
 
-	return promise.then(noop, noop);
+	promise.catch(noop);
+
+	// we return an immediately-resolving promise so that the `refresh()` signature is consistent,
+	// but it doesn't delay anything if awaited inside a command. this way, people aren't
+	// penalised if they do `await q1.refresh(); await q2.refresh()`
+	return Promise.resolve();
 }

package/src/runtime/app/server/remote/requested.js

@@ -1,5 +1,5 @@
-/** @import { RemoteQueryFunction, RequestedResult } from '@sveltejs/kit' */
-/** @import { MaybePromise, RemoteQueryInternals } from 'types' */
+/** @import { RemoteLiveQuery, RemoteLiveQueryFunction, RemoteQuery, RemoteQueryFunction, RequestedResult, QueryRequestedResult, LiveQueryRequestedResult } from '@sveltejs/kit' */
+/** @import { MaybePromise, RemoteAnyQueryInternals } from 'types' */
 import { get_request_store } from '@sveltejs/kit/internal/server';
 import { create_remote_key, parse_remote_arg } from '../../../shared.js';
 import { noop } from '../../../../utils/functions.js';
@@ -30,30 +30,104 @@ import { noop } from '../../../../utils/functions.js';
  *
  * As a shorthand for the above, you can also call `refreshAll` on the result:
  *
+ * @example
  * ```ts
  * import { requested } from '$app/server';
  *
  * await requested(getPost, 5).refreshAll();
  * ```
  *
+ * Works with `query.batch` as well — refreshes for individual entries are
+ * collected into a single batched call.
+ *
+ * For live queries, the same applies, but with `reconnect` and `reconnectAll`.
+ *
  * @template Input
  * @template Output
  * @template [Validated=Input]
+ * @overload
  * @param {RemoteQueryFunction<Input, Output, Validated>} query
  * @param {number} limit
+ * @returns {QueryRequestedResult<Validated, Output>}
+ */
+/**
+ * In the context of a remote `command` or `form` request, returns an iterable
+ * of `{ arg, query }` entries for the reconnects requested by the client, up to
+ * the supplied `limit`. Each `query` is a `RemoteLiveQuery` bound to the original
+ * client-side cache key, so `reconnect()` propagates correctly even when
+ * the query's schema transforms the input. `arg` is the *validated* argument.
+ *
+ * Arguments that fail validation or exceed `limit` are recorded as failures in
+ * the response to the client.
+ *
+ * @example
+ * ```ts
+ * import { requested } from '$app/server';
+ *
+ * for (const { query } of requested(getPost, 5)) {
+ * 	void query.reconnect();
+ * }
+ * ```
+ *
+ * As a shorthand, you can also call `reconnectAll` on the result:
+ *
+ * @example
+ * ```ts
+ * import { requested } from '$app/server';
+ *
+ * await requested(getPost, 5).reconnectAll();
+ * ```
+ *
+ * @template Input
+ * @template Output
+ * @template [Validated=Input]
+ * @overload
+ * @param {RemoteLiveQueryFunction<Input, Output, Validated>} query
+ * @param {number} limit
+ * @returns {LiveQueryRequestedResult<Validated, Output>}
+ */
+/**
+ * @template Input
+ * @template Output
+ * @template [Validated=Input]
+ * @param {RemoteQueryFunction<Input, Output, Validated> | RemoteLiveQueryFunction<Input, Output, Validated>} query
+ * @param {number} limit
  * @returns {RequestedResult<Validated, Output>}
  */
 export function requested(query, limit) {
 	const { state } = get_request_store();
-	const internals = /** @type {RemoteQueryInternals | undefined} */ (/** @type {any} */ (query).__);
+	const internals = /** @type {RemoteAnyQueryInternals | undefined} */ (
+		/** @type {any} */ (query).__
+	);
 
-	if (!internals || internals.type !== 'query') {
-		throw new Error('requested(...) expects a query function created with query(...)');
+	if (
+		internals?.type !== 'query' &&
+		internals?.type !== 'query_batch' &&
+		internals?.type !== 'query_live'
+	) {
+		throw new Error(
+			'requested(...) expects a query function created with query(...), query.batch(...), or query.live(...)'
+		);
 	}
 
+	// narrow-stable alias so generator closures below don't lose the narrowing
+	const __ = internals;
+
 	const requested = state.remote.requested;
-	const payloads = requested?.get(internals.id) ?? [];
-	const refreshes = (state.remote.refreshes ??= {});
+	const payloads = requested?.get(__.id) ?? [];
+	// note: don't initialize these maps here -- they will be initialized by the
+	// command/form wrapper when we enter them, and if we initialize them here
+	// we will enable requested(...) in contexts where it shouldn't be allowed,
+	// such as load functions or other server functions
+	const refreshes = state.remote.refreshes;
+	const reconnects = state.remote.reconnects;
+	const store = __.type === 'query_live' ? reconnects : refreshes;
+
+	if (!store) {
+		throw new Error(
+			'requested(...) can only be called in the context of a command/form remote function'
+		);
+	}
 	const [selected, skipped] = split_limit(payloads, limit);
 
 	/**
@@ -64,34 +138,34 @@ export function requested(query, limit) {
 		const promise = Promise.reject(error);
 		promise.catch(noop);
 
-		const key = create_remote_key(internals.id, payload);
-		refreshes[key] = promise;
+		const key = create_remote_key(__.id, payload);
+		store.set(key, promise);
 	};
 
 	for (const payload of skipped) {
 		record_failure(
 			payload,
 			new Error(
-				`Requested refresh was rejected because it exceeded requested(${internals.name}, ${limit}) limit`
+				`Requested refresh was rejected because it exceeded requested(${__.name}, ${limit}) limit`
 			)
 		);
 	}
 
-	return {
+	const result = {
 		*[Symbol.iterator]() {
 			for (const payload of selected) {
 				try {
 					const parsed = parse_remote_arg(payload, state.transport);
-					const validated = internals.validate(parsed);
+					const validated = __.validate(parsed);
 
 					if (is_thenable(validated)) {
 						throw new Error(
 							// TODO improve
-							`requested(${internals.name}, ${limit}) cannot be used with synchronous iteration because the query validator is async. Use \`for await ... of\` instead`
+							`requested(${__.name}, ${limit}) cannot be used with synchronous iteration because the query validator is async. Use \`for await ... of\` instead`
 						);
 					}
 
-					yield { arg: validated, query: internals.bind(payload, validated) };
+					yield { arg: validated, query: __.bind(payload, validated) };
 				} catch (error) {
 					record_failure(payload, error);
 					continue;
@@ -102,20 +176,35 @@ export function requested(query, limit) {
 			yield* race_all(selected, async (payload) => {
 				try {
 					const parsed = parse_remote_arg(payload, state.transport);
-					const validated = await internals.validate(parsed);
-					return { arg: validated, query: internals.bind(payload, validated) };
+					const validated = await __.validate(parsed);
+					return { arg: validated, query: __.bind(payload, validated) };
 				} catch (error) {
 					record_failure(payload, error);
-					throw new Error(`Skipping ${internals.name}(${payload})`, { cause: error });
+					throw new Error(`Skipping ${__.name}(${payload})`, { cause: error });
 				}
 			});
 		},
 		async refreshAll() {
-			for await (const { query } of this) {
-				void query.refresh();
+			if (__.type === 'query_live') {
+				throw new Error('refreshAll() is invalid for live queries. Use reconnectAll() instead.');
+			}
+
+			for await (const { query } of result) {
+				void (/** @type {RemoteQuery<Output>} */ (query).refresh());
+			}
+		},
+		async reconnectAll() {
+			if (__.type !== 'query_live') {
+				throw new Error('reconnectAll() is invalid for regular queries. Use refreshAll() instead.');
+			}
+
+			for await (const { query } of result) {
+				void (/** @type {RemoteLiveQuery<Output>} */ (query).reconnect());
 			}
 		}
 	};
+
+	return /** @type {RequestedResult<Validated, Output>} */ (/** @type {unknown} */ (result));
 }
 
 /**
@@ -163,7 +252,7 @@ async function* race_all(array, fn) {
 			value: result
 		}));
 
-		promise.catch(noop);
+		promise.catch(() => pending.delete(promise));
 		pending.add(promise);
 	}