Sync kit docs (#1950)

sync kit docs

Co-authored-by: svelte-docs-bot[bot] <196124396+svelte-docs-bot[bot]@users.noreply.github.com>
Co-authored-by: ComputerGuy <[email protected]>

Author: 3 people

apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md

@@ -1020,8 +1020,8 @@ export const createPost = form(
 	async (data) => {
 		// form logic goes here...
 
-		+++for (const arg of requested(getPosts, 1)) {+++
-		+++	void getPosts(arg).refresh();+++
+		+++for (const { query } of requested(getPosts, 1)) {+++
+		+++	void query.refresh();+++
 		+++}+++
 
 		// Redirect to the newly created page
@@ -1030,7 +1030,9 @@ export const createPost = form(
 );
 ```
 
-`requested` gives you access to the requested query arguments for the supplied query. It returns the *parsed* arguments for the query -- when these arguments are passed back into the query in `getPosts(arg).refresh()`, they will not be parsed again. If parsing an argument fails, that query will error, but the entire command will not fail. `requested`'s second parameter, `limit`, is the maximum number of items it will return. Any refresh requests beyond this limit will fail.
+`requested` gives you access to the queries the client requested to refresh. Each entry is an `{ arg, query }` object: `arg` is the value the query's implementation function received — i.e. the argument *after* the schema has validated and (where applicable) transformed it — and `query` is a `RemoteQuery` already bound to the client's original cache key, so calling `query.refresh()` / `query.set(...)` updates the correct client instance. If parsing an argument fails, that query will error, but the entire command will not fail. `requested`'s second parameter, `limit`, is the maximum number of items it will return. Any refresh requests beyond this limit will fail.
+
+> [!NOTE] `limit` is required because the list of refresh requests is controlled by the client — each entry causes the server to validate an argument and usually re-fetch data, so an unbounded list is a denial-of-service risk. Choose a limit that reflects the worst case you're willing to handle per request. You _can_ pass `Infinity` if you have explicitly decided to accept any number of refreshes, but it is not recommended.
 
 Additionally, `requested` allows a simple shorthand when all you want to do is refresh the requested query instances:
 
@@ -1039,10 +1041,15 @@ import type { RemoteQueryFunction } from '@sveltejs/kit';
 import { requested } from '$app/server';
 declare const getPosts: RemoteQueryFunction<any, any>;
 // ---cut---
-// this is the same as looping over the result and calling `void getPosts(arg).refresh()`.
+// this is the same as looping over the result and calling `void query.refresh()`.
 await requested(getPosts, 1).refreshAll();
 ```
 
+> [!NOTE] Why does the command have to name every query it's willing to refresh? Two reasons:
+>
+> - **Bundle size.** If a command could implicitly refresh *any* query in your app, SvelteKit would have to include every query's code in the command's server bundle, because it can't know ahead of time which ones will be called.
+> - **Denial-of-service.** Any malicious user can inspect their network tab to discover which queries your app uses, then POST a command with a client-supplied list of thousands of refreshes. The only defence is for the server handler to declare which queries it is willing to refresh — and in what quantity (hence the required `limit`).
+
 ## prerender
 
 The `prerender` function is similar to `query`, except that it will be invoked at build time to prerender the result. Use this for data that changes at most once per redeployment.

apps/svelte.dev/content/docs/kit/98-reference/[email protected]

@@ -2687,10 +2687,23 @@ type RemoteQuery<T> = RemoteResource<T> & {
 
 The return value of a remote `query` function. See [Remote functions](/docs/kit/remote-functions#query) for full documentation.
 
+The optional `Validated` generic parameter represents the argument type *after* the
+query's schema has validated and (optionally) transformed it — this is the type the
+query's implementation function receives on the server, and the type yielded by
+[`requested`](/docs/kit/$app-server#requested). For queries declared
+with [Standard Schema](https://standardschema.dev/) it differs from `Input` when the
+schema contains a transform (e.g. `v.pipe(v.number(), v.transform(String))` has
+`Input = number` but `Validated = string`). For `'unchecked'` validators and queries
+without arguments it defaults to `Input`.
+
 <div class="ts-block">
 
 ```dts
-type RemoteQueryFunction<Input, Output> = (
+type RemoteQueryFunction<
+	Input,
+	Output,
+	_Validated = Input
+> = (
 	arg: undefined extends Input ? Input | void : Input
 ) => RemoteQuery<Output>;
 ```
@@ -3046,21 +3059,41 @@ type RequestHandler<
 
 </div>
 
+## RequestedEntry
+
+A single entry yielded by [`requested`](/docs/kit/$app-server#requested).
+`arg` is the validated argument (the input *after* the query's schema validated and
+transformed it, if applicable); `query` is a `RemoteQuery` bound to the client's
+original cache key, so `refresh()` / `set()` will update the correct client entry.
+
+<div class="ts-block">
+
+```dts
+type RequestedEntry<Validated, Output> = {
+	arg: Validated;
+	query: RemoteQuery<Output>;
+};
+```
+
+</div>
+
 ## RequestedResult
 
 <div class="ts-block">
 
 ```dts
-type RequestedResult<T> = Iterable<T> &
-	AsyncIterable<T> & {
+type RequestedResult<Validated, Output> = Iterable<
+	RequestedEntry<Validated, Output>
+> &
+	AsyncIterable<RequestedEntry<Validated, Output>> & {
 		/**
 		 * Call `refresh` on all queries selected by this `requested` invocation.
 		 * This is identical to:
 		 * ```ts
 		 * import { requested } from '$app/server';
 		 *
-		 * for await (const arg of requested(query, ...) {
-		 *   void query(arg).refresh();
+		 * for await (const { query } of requested(getPost, ...)) {
+		 *   void query.refresh();
 		 * }
 		 * ```
 		 */

apps/svelte.dev/content/docs/kit/98-reference/20-$app-server.md

@@ -261,7 +261,8 @@ function query<Schema extends StandardSchemaV1, Output>(
 	) => MaybePromise<Output>
 ): RemoteQueryFunction<
 	StandardSchemaV1.InferInput<Schema>,
-	Output
+	Output,
+	StandardSchemaV1.InferOutput<Schema>
 >;
 ```
 
@@ -301,18 +302,24 @@ function read(asset: string): Response;
 ## requested
 
 In the context of a remote `command` or `form` request, returns an iterable
-of the client-requested refreshes' validated arguments up to the supplied limit.
-Arguments that fail validation or exceed the limit are recorded as failures in
+of `{ arg, query }` entries for the refreshes requested by the client, up to
+the supplied `limit`. Each `query` is a `RemoteQuery` bound to the original
+client-side cache key, so `refresh()` / `set()` propagate correctly even when
+the query's schema transforms the input. `arg` is the *validated* argument,
+i.e. the value after the schema has run (so `InferOutput<Schema>` for queries
+declared with a Standard Schema).
+
+Arguments that fail validation or exceed `limit` are recorded as failures in
 the response to the client.
 
 ```ts
 import { requested } from '$app/server';
 
-for (const arg of requested(getPost, 5)) {
-	// it's safe to throw away this promise -- SvelteKit
-	// will await it for us and handle any errors by sending
-	// them to the client.
-	void getPost(arg).refresh();
+for (const { arg, query } of requested(getPost, 5)) {
+	// `arg` is the validated argument; `query` is bound to the client's
+	// cache key. It's safe to throw away this promise -- SvelteKit will
+	// await it and forward any errors to the client.
+	void query.refresh();
 }
 ```
 
@@ -327,10 +334,10 @@ await requested(getPost, 5).refreshAll();
 <div class="ts-block">
 
 ```dts
-function requested<Input, Output>(
-	query: RemoteQueryFunction<Input, Output>,
-	limit?: number
-): RequestedResult<Input>;
+function requested<Input, Output, Validated = Input>(
+	query: RemoteQueryFunction<Input, Output, Validated>,
+	limit: number
+): RequestedResult<Validated, Output>;
 ```
 
 </div>
@@ -375,7 +382,8 @@ namespace query {
 		>
 	): RemoteQueryFunction<
 		StandardSchemaV1.InferInput<Schema>,
-		Output
+		Output,
+		StandardSchemaV1.InferOutput<Schema>
 	>;
 }
 ```

apps/svelte.dev/package.json

@@ -55,7 +55,7 @@
 		"@supabase/supabase-js": "^2.97.0",
 		"@sveltejs/adapter-vercel": "^6.3.3",
 		"@sveltejs/enhanced-img": "^0.10.3",
-		"@sveltejs/kit": "^2.57.1",
+		"@sveltejs/kit": "^2.58.0",
 		"@sveltejs/site-kit": "workspace:*",
 		"@sveltejs/sv-utils": "^0.2.0",
 		"@sveltejs/vite-plugin-svelte": "^7.0.0",