feat: add remote function query.stream

.changeset/red-waves-give.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: add new remote function `query.batch`

.changeset/smart-nails-allow.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: add remote function `query.stream`

documentation/docs/20-core-concepts/60-remote-functions.md

@@ -172,6 +172,143 @@ Any query can be updated via its `refresh` method:
 
 > [!NOTE] Queries are cached while they're on the page, meaning `getPosts() === getPosts()`. This means you don't need a reference like `const posts = getPosts()` in order to refresh the query.
 
+## query.batch
+
+`query.batch` works like `query` except that it batches requests that happen within the same macrotask. This solves the so-called n+1 problem: rather than each query resulting in a separate database call (for example), simultaneous queries are grouped together.
+
+On the server, the callback receives an array of the arguments the function was called with. It must return a function of the form `(input: Input, index: number) => Output`. SvelteKit will then call this with each of the input arguments to resolve the individual calls with their results.
+
+```js
+/// file: weather.remote.js
+// @filename: ambient.d.ts
+declare module '$lib/server/database' {
+	export function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>;
+}
+// @filename: index.js
+// ---cut---
+import * as v from 'valibot';
+import { query } from '$app/server';
+import * as db from '$lib/server/database';
+
+export const getWeather = query.batch(v.string(), async (cities) => {
+	const weather = await db.sql`
+		SELECT * FROM weather
+		WHERE city = ANY(${cities})
+	`;
+	const weatherMap = new Map(weather.map(w => [w.city, w]));
+
+	return (city) => weatherMap.get(city);
+});
+```
+
+```svelte
+<!--- file: Weather.svelte --->
+<script>
+	import CityWeather from './CityWeather.svelte';
+	import { getWeather } from './weather.remote.js';
+
+	let { cities } = $props();
+	let limit = $state(5);
+</script>
+
+<h2>Weather</h2>
+
+{#each cities.slice(0, limit) as city}
+	<h3>{city.name}</h3>
+	<CityWeather weather={await getWeather(city.id)} />
+{/each}
+
+{#if cities.length > limit}
+	<button onclick={() => limit += 5}>
+		Load more
+	</button>
+{/if}
+```
+
+## query.stream
+
+`query.stream` allows you to stream continuous data from the server to the client.
+
+```js
+/// file: src/routes/time.remote.js
+// @filename: ambient.d.ts
+declare module '$lib/server/database' {
+	export function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>;
+}
+// @filename: index.js
+// ---cut---
+import { query } from '$app/server';
+
+export const time = query.stream(async function* () {
+	while (true) {
+		yield new Date();
+		await new Promise(r => setTimeout(r, 1000))
+	}
+});
+```
+
+You can consume the stream like a promise or via the `current` property. In both cases, if it's used in a reactive context, it will automatically update to the latest version upon retrieving new data.
+
+```svelte
+<!--- file: src/routes/+page.svelte --->
+<script>
+	import { time } from './time.remote.js';
+</script>
+
+<p>{await time()}</p>
+<p>{time().current}</p>
+```
+
+Apart from that you can iterate over it like any other async iterable, including using `for await (...)`.
+
+```svelte
+<!--- file: src/routes/+page.svelte --->
+<script>
+	import { time } from './time.remote.js';
+
+	let times = $state([]);
+
+	async function stream() {
+		times = []
+		let count = 0;
+
+		for await (const entry of time()) {
+			times.push(time);
+			count++;
+			if (count >= 5) {
+				break;
+			}
+		}
+	})
+</script>
+
+<button onclick={stream}>stream for five seconds</button>
+
+{#each times as time}
+	<span>{time}</time>
+{/each}
+```
+
+Unlike other `query` methods, stream requests to the same resource with the same payload are _not_ deduplicated. That means you can start the same stream multiple times in parallel and it will start from the beginning each time.
+
+```svelte
+<!--- file: src/routes/+page.svelte --->
+<script>
+	import { oneToTen } from './count.remote.js';
+
+	const stream = oneToTen();
+</script>
+
+<!-- these are one single ReadableStream request since they share the same stream instance -->
+{#await stream()}
+{#await stream()}
+
+<!-- this is a separate instance and will create a new ReadableStream request to the backend -->
+{await oneToTen()}
+```
+
+> [!NOTE] Be careful when using `query.stream` in combination with service workers. Specifically, make sure to never pass the promise of a `ReadableStream` (which `query.stream` uses) to `event.respondWith(...)`, as the promise never settles.
+
 ## form
 
 The `form` function makes it easy to write data to the server. It takes a callback that receives the current [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)...

packages/kit/src/exports/internal/remote-functions.js

@@ -10,9 +10,16 @@ export function validate_remote_functions(module, file) {
 	}
 
 	for (const name in module) {
-		const type = module[name]?.__?.type;
+		const type = /** @type {import('types').RemoteInfo['type']} */ (module[name]?.__?.type);
 
-		if (type !== 'form' && type !== 'command' && type !== 'query' && type !== 'prerender') {
+		if (
+			type !== 'form' &&
+			type !== 'command' &&
+			type !== 'query' &&
+			type !== 'query_batch' &&
+			type !== 'query_stream' &&
+			type !== 'prerender'
+		) {
 			throw new Error(
 				`\`${name}\` exported from ${file} is invalid — all exports from this file must be remote functions`
 			);

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

@@ -1822,6 +1822,16 @@ export interface RemoteQueryOverride {
 	release(): void;
 }
 
+/**
+ * The return value of a remote `query.stream` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#query-stream) for full documentation.
+ */
+export type RemoteQueryStream<T> = RemoteResource<T> & AsyncIterable<Awaited<T>>;
+
+/**
+ * The return value of a remote `query.stream` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#query-stream) for full documentation.
+ */
+export type RemoteQueryStreamFunction<Input, Output> = (arg: Input) => RemoteQueryStream<Output>;
+
 /**
  * The return value of a remote `prerender` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#prerender) for full documentation.
  */