From 6abae27a72900613f31fa2a044e1f3a764789b37 Mon Sep 17 00:00:00 2001 From: "svelte-docs-bot[bot]" <196124396+svelte-docs-bot[bot]@users.noreply.github.com> Date: Thu, 20 Nov 2025 21:33:22 +0000 Subject: [PATCH] sync kit docs --- .../20-core-concepts/60-remote-functions.md | 7 +- .../docs/kit/98-reference/10-@sveltejs-kit.md | 120 ++++++++++++++++-- .../docs/kit/98-reference/20-$app-server.md | 10 +- 3 files changed, 117 insertions(+), 20 deletions(-) diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md index eb6ae2d27..e36bebe81 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/60-remote-functions.md @@ -455,11 +455,12 @@ Alternatively, you could use `select` and `select multiple`: ### Programmatic validation -In addition to declarative schema validation, you can programmatically mark fields as invalid inside the form handler using the `invalid` function. This is useful for cases where you can't know if something is valid until you try to perform some action: +In addition to declarative schema validation, you can programmatically mark fields as invalid inside the form handler using the `invalid` function. This is useful for cases where you can't know if something is valid until you try to perform some action. Just like `redirect` or `error`, `invalid` throws. It expects a list of strings (for issues relating to the form as a whole) or standard-schema-compliant issues (for those relating to a specific field). Use the `issue` parameter for type-safe creation of such issues: ```js /// file: src/routes/shop/data.remote.js import * as v from 'valibot'; +import { invalid } from '@sveltejs/kit'; import { form } from '$app/server'; import * as db from '$lib/server/database'; @@ -470,13 +471,13 @@ export const buyHotcakes = form( v.minValue(1, 'you must buy at least one hotcake') ) }), - async (data, invalid) => { + async (data, issue) => { try { await db.buy(data.qty); } catch (e) { if (e.code === 'OUT_OF_STOCK') { invalid( - invalid.qty(`we don't have enough hotcakes`) + issue.qty(`we don't have enough hotcakes`) ); } } diff --git a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md index 388f54fcf..8f5e98684 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md @@ -12,9 +12,11 @@ import { VERSION, error, fail, + invalid, isActionFailure, isHttpError, isRedirect, + isValidationError, json, normalizeUrl, redirect, @@ -128,6 +130,48 @@ function fail( +## invalid + +
+ +Available since 2.47.3 + +
+ +Use this to throw a validation error to imperatively fail form validation. +Can be used in combination with `issue` passed to form actions to create field-specific issues. + +```ts +import { invalid } from '@sveltejs/kit'; +import { form } from '$app/server'; +import { tryLogin } from '$lib/server/auth'; +import * as v from 'valibot'; + +export const login = form( + v.object({ name: v.string(), _password: v.string() }), + async ({ name, _password }) => { + const success = tryLogin(name, _password); + if (!success) { + invalid('Incorrect username or password'); + } + + // ... + } +); +``` + +
+ +```dts +function invalid( + ...issues: (StandardSchemaV1.Issue | string)[] +): never; +``` + +
+ + + ## isActionFailure Checks whether this is an action failure thrown by `fail`. @@ -175,6 +219,26 @@ function isRedirect(e: unknown): e is Redirect_1; +## isValidationError + +
+ +Available since 2.47.3 + +
+ +Checks whether this is an validation error thrown by `invalid`. + +
+ +```dts +function isValidationError(e: unknown): e is ActionFailure; +``` + +
+ + + ## json Create a JSON `Response` object from the supplied data. @@ -1253,22 +1317,37 @@ The content of the error. -## Invalid +## InvalidField A function and proxy object used to imperatively create validation errors in form handlers. -Call `invalid(issue1, issue2, ...issueN)` to throw a validation error. -If an issue is a `string`, it applies to the form as a whole (and will show up in `fields.allIssues()`) -Access properties to create field-specific issues: `invalid.fieldName('message')`. +Access properties to create field-specific issues: `issue.fieldName('message')`. The type structure mirrors the input data structure for type-safe field access. +Call `invalid(issue.foo(...), issue.nested.bar(...))` to throw a validation error.
```dts -type Invalid = (( - ...issues: Array -) => never) & - InvalidField; +type InvalidField = + WillRecurseIndefinitely extends true + ? Record + : NonNullable extends + | string + | number + | boolean + | File + ? (message: string) => StandardSchemaV1.Issue + : NonNullable extends Array + ? { + [K in number]: InvalidField; + } & ((message: string) => StandardSchemaV1.Issue) + : NonNullable extends RemoteFormInput + ? { + [K in keyof T]-?: InvalidField; + } & (( + message: string + ) => StandardSchemaV1.Issue) + : Record; ```
@@ -2361,8 +2440,6 @@ type RemoteForm< includeUntouched?: boolean; /** Set this to `true` to only run the `preflight` validation. */ preflightOnly?: boolean; - /** Perform validation as if the form was submitted by the given button. */ - submitter?: HTMLButtonElement | HTMLInputElement; }): Promise; /** The result of the form submission */ get result(): Output | undefined; @@ -3641,6 +3718,29 @@ decode: (data: U) => T;
+## ValidationError + +A validation error thrown by `invalid`. + +
+ +```dts +interface ValidationError {/*…*/} +``` + +
+ +```dts +issues: StandardSchemaV1.Issue[]; +``` + +
+ +The validation issues + +
+
+ ## Private types diff --git a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-server.md b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-server.md index edb1a3c3c..fdc1e9886 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/20-$app-server.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/20-$app-server.md @@ -82,9 +82,7 @@ See [Remote functions](/docs/kit/remote-functions#form) for full documentation. ```dts function form( - fn: ( - invalid: import('@sveltejs/kit').Invalid - ) => MaybePromise + fn: () => MaybePromise ): RemoteForm; ``` @@ -97,7 +95,7 @@ function form( validate: 'unchecked', fn: ( data: Input, - invalid: import('@sveltejs/kit').Invalid + issue: InvalidField ) => MaybePromise ): RemoteForm; ``` @@ -117,9 +115,7 @@ function form< validate: Schema, fn: ( data: StandardSchemaV1.InferOutput, - invalid: import('@sveltejs/kit').Invalid< - StandardSchemaV1.InferInput - > + issue: InvalidField> ) => MaybePromise ): RemoteForm, Output>; ```