Merge branch 'main' into main

Author: teemingc

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

@@ -144,6 +144,38 @@ export async function handleFetch({ event, request, fetch }) {
 }
 ```
 
+### handleValidationError
+
+This hook is called when a remote function is called with an argument that does not match the provided [Standard Schema](https://standardschema.dev/). It must return an object matching the shape of [`App.Error`](types#Error).
+
+Say you have a remote function that expects a string as its argument ...
+
+```js
+/// file: todos.remote.js
+import * as v from 'valibot';
+import { query } from '$app/server';
+
+export const getTodo = query(v.string(), (id) => {
+	// implementation...
+});
+```
+
+...but it is called with something that doesn't match the schema — such as a number (e.g `await getTodos(1)`) — then validation will fail, the server will respond with a [400 status code](https://http.dog/400), and the function will throw with the message 'Bad Request'.
+
+To customise this message and add additional properties to the error object, implement `handleValidationError`:
+
+```js
+/// file: src/hooks.server.js
+/** @type {import('@sveltejs/kit').HandleValidationError} */
+export function handleValidationError({ issues }) {
+	return {
+		message: 'No thank you'
+	};
+}
+```
+
+Be thoughtful about what information you expose here, as the most likely reason for validation to fail is that someone is sending malicious requests to your server.
+
 ## Shared hooks
 
 The following can be added to `src/hooks.server.js` _and_ `src/hooks.client.js`:

apps/svelte.dev/content/docs/kit/30-advanced/20-hooks.md

@@ -118,9 +118,10 @@ function fail(status: number): ActionFailure<undefined>;
 <div class="ts-block">
 
 ```dts
-function fail<
-	T extends Record<string, unknown> | undefined = undefined
->(status: number, data: T): ActionFailure<T>;
+function fail<T = undefined>(
+	status: number,
+	data: T
+): ActionFailure<T>;
 ```
 
 </div>
@@ -305,9 +306,7 @@ type Action<
 <div class="ts-block">
 
 ```dts
-interface ActionFailure<
-	T extends Record<string, unknown> | undefined = undefined
-> {/*…*/}
+interface ActionFailure<T = undefined> {/*…*/}
 ```
 
 <div class="ts-block-property">
@@ -1142,6 +1141,26 @@ type HandleServerError = (input: {
 
 </div>
 
+## HandleValidationError
+
+The [`handleValidationError`](/docs/kit/hooks#Server-hooks-handleValidationError) hook runs when the argument to a remote function fails validation.
+
+It will be called with the validation issues and the event, and must return an object shape that matches `App.Error`.
+
+<div class="ts-block">
+
+```dts
+type HandleValidationError<
+	Issue extends
+		StandardSchemaV1.Issue = StandardSchemaV1.Issue
+> = (input: {
+	issues: Issue[];
+	event: RequestEvent;
+}) => MaybePromise<App.Error>;
+```
+
+</div>
+
 ## HttpError
 
 The object returned by the [`error`](/docs/kit/@sveltejs-kit#error) function.
@@ -1908,6 +1927,227 @@ The location to redirect to.
 </div>
 </div></div>
 
+## RemoteCommand
+
+The return value of a remote `command` function. See [Remote functions](/docs/kit/remote-functions#command) for full documentation.
+
+<div class="ts-block">
+
+```dts
+type RemoteCommand<Input, Output> = (arg: Input) => Promise<
+	Awaited<Output>
+> & {
+	updates(
+		...queries: Array<
+			RemoteQuery<any> | RemoteQueryOverride
+		>
+	): Promise<Awaited<Output>>;
+};
+```
+
+</div>
+
+## RemoteForm
+
+The return value of a remote `form` function. See [Remote functions](/docs/kit/remote-functions#form) for full documentation.
+
+<div class="ts-block">
+
+```dts
+type RemoteForm<Result> = {
+	method: 'POST';
+	/** The URL to send the form to. */
+	action: string;
+	/** Event handler that intercepts the form submission on the client to prevent a full page reload */
+	onsubmit: (event: SubmitEvent) => void;
+	/** Use the `enhance` method to influence what happens when the form is submitted. */
+	enhance(
+		callback: (opts: {
+			form: HTMLFormElement;
+			data: FormData;
+			submit: () => Promise<void> & {
+				updates: (
+					...queries: Array<
+						RemoteQuery<any> | RemoteQueryOverride
+					>
+				) => Promise<void>;
+			};
+		}) => void
+	): {
+		method: 'POST';
+		action: string;
+		onsubmit: (event: SubmitEvent) => void;
+	};
+	/**
+	 * Create an instance of the form for the given key.
+	 * The key is stringified and used for deduplication to potentially reuse existing instances.
+	 * Useful when you have multiple forms that use the same remote form action, for example in a loop.
+	 * ```svelte
+	 * {#each todos as todo}
+	 *	{@const todoForm = updateTodo.for(todo.id)}
+	 *	<form {...todoForm}>
+	 *		{#if todoForm.result?.invalid}<p>Invalid data</p>{/if}
+	 *		...
+	 *	</form>
+	 *	{/each}
+	 * ```
+	 */
+	for(
+		key: string | number | boolean
+	): Omit<RemoteForm<Result>, 'for'>;
+	/** The result of the form submission */
+	get result(): Result | undefined;
+	/** Spread this onto a `<button>` or `<input type="submit">` */
+	buttonProps: {
+		type: 'submit';
+		formmethod: 'POST';
+		formaction: string;
+		onclick: (event: Event) => void;
+		/** Use the `enhance` method to influence what happens when the form is submitted. */
+		enhance(
+			callback: (opts: {
+				form: HTMLFormElement;
+				data: FormData;
+				submit: () => Promise<void> & {
+					updates: (
+						...queries: Array<
+							RemoteQuery<any> | RemoteQueryOverride
+						>
+					) => Promise<void>;
+				};
+			}) => void
+		): {
+			type: 'submit';
+			formmethod: 'POST';
+			formaction: string;
+			onclick: (event: Event) => void;
+		};
+	};
+};
+```
+
+</div>
+
+## RemotePrerenderFunction
+
+The return value of a remote `prerender` function. See [Remote functions](/docs/kit/remote-functions#prerender) for full documentation.
+
+<div class="ts-block">
+
+```dts
+type RemotePrerenderFunction<Input, Output> = (
+	arg: Input
+) => RemoteResource<Output>;
+```
+
+</div>
+
+## RemoteQuery
+
+<div class="ts-block">
+
+```dts
+type RemoteQuery<T> = RemoteResource<T> & {
+	/**
+	 * On the client, this function will re-fetch the query from the server.
+	 *
+	 * On the server, this can be called in the context of a `command` or `form` and the refreshed data will accompany the action response back to the client.
+	 * This prevents SvelteKit needing to refresh all queries on the page in a second server round-trip.
+	 */
+	refresh(): Promise<void>;
+	/**
+	 * Temporarily override the value of a query. This is used with the `updates` method of a [command](https://svelte.dev/docs/kit/remote-functions#command-Single-flight-mutations) or [enhanced form submission](https://svelte.dev/docs/kit/remote-functions#form-enhance) to provide optimistic updates.
+	 *
+	 * ```svelte
+	 * <script>
+	 *   import { getTodos, addTodo } from './todos.remote.js';
+	 *   const todos = getTodos();
+	 * </script>
+	 *
+	 * <form {...addTodo.enhance(async ({ data, submit }) => {
+	 *   await submit().updates(
+	 *     todos.withOverride((todos) => [...todos, { text: data.get('text') }])
+	 *   );
+	 * }}>
+	 *   <input type="text" name="text" />
+	 *   <button type="submit">Add Todo</button>
+	 * </form>
+	 * ```
+	 */
+	withOverride(
+		update: (current: Awaited<T>) => Awaited<T>
+	): RemoteQueryOverride;
+};
+```
+
+</div>
+
+## RemoteQueryFunction
+
+The return value of a remote `query` function. See [Remote functions](/docs/kit/remote-functions#query) for full documentation.
+
+<div class="ts-block">
+
+```dts
+type RemoteQueryFunction<Input, Output> = (
+	arg: Input
+) => RemoteQuery<Output>;
+```
+
+</div>
+
+## RemoteQueryOverride
+
+<div class="ts-block">
+
+```dts
+interface RemoteQueryOverride {/*…*/}
+```
+
+<div class="ts-block-property">
+
+```dts
+_key: string;
+```
+
+<div class="ts-block-property-details"></div>
+</div>
+
+<div class="ts-block-property">
+
+```dts
+release(): void;
+```
+
+<div class="ts-block-property-details"></div>
+</div></div>
+
+## RemoteResource
+
+<div class="ts-block">
+
+```dts
+type RemoteResource<T> = Promise<Awaited<T>> & {
+	/** The error in case the query fails. Most often this is a [`HttpError`](https://svelte.dev/docs/kit/@sveltejs-kit#HttpError) but it isn't guaranteed to be. */
+	get error(): any;
+	/** `true` before the first result is available and during refreshes */
+	get loading(): boolean;
+} & (
+		| {
+				/** The current value of the query. Undefined until `ready` is `true` */
+				get current(): undefined;
+				ready: false;
+		  }
+		| {
+				/** The current value of the query. Undefined until `ready` is `true` */
+				get current(): Awaited<T>;
+				ready: true;
+		  }
+	);
+```
+
+</div>
+
 ## RequestEvent
 
 <div class="ts-block">
@@ -2115,6 +2355,20 @@ isSubRequest: boolean;
 
 `true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server.
 
+</div>
+</div>
+
+<div class="ts-block-property">
+
+```dts
+isRemoteRequest: boolean;
+```
+
+<div class="ts-block-property-details">
+
+`true` if the request comes from the client via a remote function. The `url` property will be stripped of the internal information
+related to the data request in this case. Use this property instead if the distinction is important to you.
+
 </div>
 </div></div>
 
@@ -2389,6 +2643,18 @@ nodes: SSRNodeLoader[];
 </div>
 <div class="ts-block-property">
 
+```dts
+remotes: Record<string, () => Promise<any>>;
+```
+
+<div class="ts-block-property-details">
+
+hashed filename -> import to that file
+
+</div>
+</div>
+<div class="ts-block-property">
+
 ```dts
 routes: SSRRoute[];
 ```

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

@@ -18,6 +18,7 @@ import {
 	preloadCode,
 	preloadData,
 	pushState,
+	refreshAll,
 	replaceState
 } from '$app/navigation';
 ```
@@ -248,6 +249,27 @@ function pushState(
 
 
 
+## refreshAll
+
+Causes all currently active remote functions to refresh, and all `load` functions belonging to the currently active page to re-run (unless disabled via the option argument).
+Returns a `Promise` that resolves when the page is subsequently updated.
+
+<div class="ts-block">
+
+```dts
+function refreshAll({
+	includeLoadFunctions
+}?:
+	| {
+			includeLoadFunctions?: boolean;
+	  }
+	| undefined): Promise<void>;
+```
+
+</div>
+
+
+
 ## replaceState
 
 Programmatically replace the current history entry with the given `page.state`. To use the current URL, you can pass `''` as the first argument. Used for [shallow routing](/docs/kit/shallow-routing).