feat: imperative form validation (#14624)

* feat: imperative form validation

Not all validation can happen via the schema, this introduces a way to do it imperatively

* fix

* Apply suggestion from @Rich-Harris

Co-authored-by: Rich Harris <[email protected]>

* Apply suggestion from @Rich-Harris

Co-authored-by: Rich Harris <[email protected]>

* tweak `invalid(...)` API (#14625)

* Apply suggestions from code review

---------

Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

.changeset/all-tables-eat.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: imperative form validation

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

@@ -450,6 +450,43 @@ Alternatively, you could use `select` and `select multiple`:
 
 > [!NOTE] As with unchecked `checkbox` inputs, if no selections are made then the data will be `undefined`. For this reason, the `languages` field uses `v.optional(v.array(...), [])` rather than just `v.array(...)`.
 
+### 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:
+
+```js
+/// file: src/routes/shop/data.remote.js
+import * as v from 'valibot';
+import { form } from '$app/server';
+import * as db from '$lib/server/database';
+
+export const buyHotcakes = form(
+	v.object({
+		qty: v.pipe(
+			v.number(),
+			v.minValue(1, 'you must buy at least one hotcake')
+		)
+	}),
+	async (data, invalid) => {
+		try {
+			await db.buy(data.qty);
+		} catch (e) {
+			if (e.code === 'OUT_OF_STOCK') {
+				invalid(
+					invalid.qty(`we don't have enough hotcakes`)
+				);
+			}
+		}
+	}
+);
+```
+
+The `invalid` function works as both a function and a proxy:
+
+- 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()`)
+- Use `invalid.fieldName(message)` to create an issue for a specific field. Like `fields` this is type-safe and you can use regular property access syntax to create issues for deeply nested objects (e.g. `invalid.profile.email('Email already exists')` or `invalid.items[0].qty('Insufficient stock')`)
+
 ### Validation
 
 If the submitted data doesn't pass the schema, the callback will not run. Instead, each invalid field's `issues()` method will return an array of `{ message: string }` objects, and the `aria-invalid` attribute (returned from `as(...)`) will be set to `true`:

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

@@ -1925,7 +1925,7 @@ type RemoteFormFields<T> =
 					: RemoteFormFieldContainer<T> & { [K in keyof T]-?: RemoteFormFields<T[K]> };
 
 // By breaking this out into its own type, we avoid the TS recursion depth limit
-type RecursiveFormFields = RemoteFormField<any> & { [key: string]: RecursiveFormFields };
+type RecursiveFormFields = RemoteFormField<any> & { [key: string | number]: RecursiveFormFields };
 
 type MaybeArray<T> = T | T[];
 
@@ -1945,6 +1945,49 @@ type ExtractId<Input> = Input extends { id: infer Id }
 		: string | number
 	: string | number;
 
+/**
+ * Recursively maps an input type to a structure where each field can create a validation issue.
+ * This mirrors the runtime behavior of the `invalid` proxy passed to form handlers.
+ */
+type InvalidField<T> =
+	WillRecurseIndefinitely<T> extends true
+		? Record<string | number, any>
+		: NonNullable<T> extends string | number | boolean | File
+			? (message: string) => StandardSchemaV1.Issue
+			: NonNullable<T> extends Array<infer U>
+				? {
+						[K in number]: InvalidField<U>;
+					} & ((message: string) => StandardSchemaV1.Issue)
+				: NonNullable<T> extends RemoteFormInput
+					? {
+							[K in keyof T]-?: InvalidField<T[K]>;
+						} & ((message: string) => StandardSchemaV1.Issue)
+					: Record<string, never>;
+
+/**
+ * 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')`.
+ * The type structure mirrors the input data structure for type-safe field access.
+ *
+ * @example
+ * ```ts
+ * invalid('Username or password is invalid');
+ * ```
+ *
+ * @example
+ * ```ts
+ * invalid(
+ *   invalid.username('Username is taken'),
+ *   invalid.items[0].qty('Insufficient stock')
+ * );
+ * ```
+ */
+export type Invalid<Input = any> = ((...issues: Array<string | StandardSchemaV1.Issue>) => never) &
+	InvalidField<Input>;
+
 /**
  * The return value of a remote `form` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#form) for full documentation.
  */

packages/kit/src/runtime/app/server/remote/form.js

@@ -20,7 +20,7 @@ import { get_cache, run_remote_function } from './shared.js';
  *
  * @template Output
  * @overload
- * @param {() => MaybePromise<Output>} fn
+ * @param {(invalid: import('@sveltejs/kit').Invalid<void>) => MaybePromise<Output>} fn
  * @returns {RemoteForm<void, Output>}
  * @since 2.27
  */
@@ -33,7 +33,7 @@ import { get_cache, run_remote_function } from './shared.js';
  * @template Output
  * @overload
  * @param {'unchecked'} validate
- * @param {(data: Input) => MaybePromise<Output>} fn
+ * @param {(data: Input, invalid: import('@sveltejs/kit').Invalid<Input>) => MaybePromise<Output>} fn
  * @returns {RemoteForm<Input, Output>}
  * @since 2.27
  */
@@ -46,26 +46,27 @@ import { get_cache, run_remote_function } from './shared.js';
  * @template Output
  * @overload
  * @param {Schema} validate
- * @param {(data: StandardSchemaV1.InferOutput<Schema>) => MaybePromise<Output>} fn
+ * @param {(data: StandardSchemaV1.InferOutput<Schema>, invalid: import('@sveltejs/kit').Invalid<StandardSchemaV1.InferOutput<Schema>>) => MaybePromise<Output>} fn
  * @returns {RemoteForm<StandardSchemaV1.InferInput<Schema>, Output>}
  * @since 2.27
  */
 /**
  * @template {RemoteFormInput} Input
  * @template Output
  * @param {any} validate_or_fn
- * @param {(data?: Input) => MaybePromise<Output>} [maybe_fn]
+ * @param {(data_or_invalid: any, invalid?: any) => MaybePromise<Output>} [maybe_fn]
  * @returns {RemoteForm<Input, Output>}
  * @since 2.27
  */
 /*@__NO_SIDE_EFFECTS__*/
 // @ts-ignore we don't want to prefix `fn` with an underscore, as that will be user-visible
 export function form(validate_or_fn, maybe_fn) {
-	/** @type {(data?: Input) => Output} */
+	/** @type {any} */
 	const fn = maybe_fn ?? validate_or_fn;
 
 	/** @type {StandardSchemaV1 | null} */
-	const schema = !maybe_fn || validate_or_fn === 'unchecked' ? null : validate_or_fn;
+	const schema =
+		!maybe_fn || validate_or_fn === 'unchecked' ? null : /** @type {any} */ (validate_or_fn);
 
 	/**
 	 * @param {string | number | boolean} [key]
@@ -152,37 +153,32 @@ export function form(validate_or_fn, maybe_fn) {
 				}
 
 				if (validated?.issues !== undefined) {
-					output.issues = flatten_issues(validated.issues);
-
-					// if it was a progressively-enhanced submission, we don't need
-					// to return the input — it's already there
-					if (!event.isRemoteRequest) {
-						output.input = {};
-
-						for (let key of form_data.keys()) {
-							// redact sensitive fields
-							if (/^[.\]]?_/.test(key)) continue;
-
-							const is_array = key.endsWith('[]');
-							const values = form_data.getAll(key).filter((value) => typeof value === 'string');
-
-							if (is_array) key = key.slice(0, -2);
-
-							output.input = set_nested_value(
-								/** @type {Record<string, any>} */ (output.input),
-								key,
-								is_array ? values : values[0]
-							);
-						}
-					}
+					handle_issues(output, validated.issues, event.isRemoteRequest, form_data);
 				} else {
 					if (validated !== undefined) {
 						data = validated.value;
 					}
 
 					state.refreshes ??= {};
 
-					output.result = await run_remote_function(event, state, true, data, (d) => d, fn);
+					const invalid = create_invalid();
+
+					try {
+						output.result = await run_remote_function(
+							event,
+							state,
+							true,
+							data,
+							(d) => d,
+							(data) => (!maybe_fn ? fn(invalid) : fn(data, invalid))
+						);
+					} catch (e) {
+						if (e instanceof ValidationError) {
+							handle_issues(output, e.issues, event.isRemoteRequest, form_data);
+						} else {
+							throw e;
+						}
+					}
 				}
 
 				// We don't need to care about args or deduplicating calls, because uneval results are only relevant in full page reloads
@@ -290,3 +286,124 @@ export function form(validate_or_fn, maybe_fn) {
 
 	return create_instance();
 }
+
+/**
+ * @param {{ issues?: Record<string, any>, input?: Record<string, any>, result: any }} output
+ * @param {readonly StandardSchemaV1.Issue[]} issues
+ * @param {boolean} is_remote_request
+ * @param {FormData} form_data
+ */
+function handle_issues(output, issues, is_remote_request, form_data) {
+	output.issues = flatten_issues(issues);
+
+	// if it was a progressively-enhanced submission, we don't need
+	// to return the input — it's already there
+	if (!is_remote_request) {
+		output.input = {};
+
+		for (let key of form_data.keys()) {
+			// redact sensitive fields
+			if (/^[.\]]?_/.test(key)) continue;
+
+			const is_array = key.endsWith('[]');
+			const values = form_data.getAll(key).filter((value) => typeof value === 'string');
+
+			if (is_array) key = key.slice(0, -2);
+
+			output.input = set_nested_value(
+				/** @type {Record<string, any>} */ (output.input),
+				key,
+				is_array ? values : values[0]
+			);
+		}
+	}
+}
+
+/**
+ * Creates an invalid function that can be used to imperatively mark form fields as invalid
+ * @returns {import('@sveltejs/kit').Invalid}
+ */
+function create_invalid() {
+	/**
+	 * @param {...(string | StandardSchemaV1.Issue)} issues
+	 * @returns {never}
+	 */
+	function invalid(...issues) {
+		throw new ValidationError(
+			issues.map((issue) => {
+				if (typeof issue === 'string') {
+					return {
+						path: [],
+						message: issue
+					};
+				}
+
+				return issue;
+			})
+		);
+	}
+
+	return /** @type {import('@sveltejs/kit').Invalid} */ (
+		new Proxy(invalid, {
+			get(target, prop) {
+				if (typeof prop === 'symbol') return /** @type {any} */ (target)[prop];
+
+				/**
+				 * @param {string} message
+				 * @param {(string | number)[]} path
+				 * @returns {StandardSchemaV1.Issue}
+				 */
+				const create_issue = (message, path = []) => ({
+					message,
+					path
+				});
+
+				return create_issue_proxy(prop, create_issue, []);
+			}
+		})
+	);
+}
+
+/**
+ * Error thrown when form validation fails imperatively
+ */
+class ValidationError extends Error {
+	/**
+	 * @param {StandardSchemaV1.Issue[]} issues
+	 */
+	constructor(issues) {
+		super('Validation failed');
+		this.name = 'ValidationError';
+		this.issues = issues;
+	}
+}
+
+/**
+ * Creates a proxy that builds up a path and returns a function to create an issue
+ * @param {string | number} key
+ * @param {(message: string, path: (string | number)[]) => StandardSchemaV1.Issue} create_issue
+ * @param {(string | number)[]} path
+ */
+function create_issue_proxy(key, create_issue, path) {
+	const new_path = [...path, key];
+
+	/**
+	 * @param {string} message
+	 * @returns {StandardSchemaV1.Issue}
+	 */
+	const issue_func = (message) => create_issue(message, new_path);
+
+	return new Proxy(issue_func, {
+		get(target, prop) {
+			if (typeof prop === 'symbol') return /** @type {any} */ (target)[prop];
+
+			// Handle array access like invalid.items[0]
+			if (/^\d+$/.test(prop)) {
+				return create_issue_proxy(parseInt(prop, 10), create_issue, new_path);
+			}
+
+			// Handle property access like invalid.field.nested
+			return create_issue_proxy(prop, create_issue, new_path);
+		}
+	});
+}

packages/kit/test/apps/basics/src/routes/remote/form/validate/+page.svelte

@@ -3,9 +3,9 @@
 	import * as v from 'valibot';
 
 	const schema = v.object({
-		foo: v.picklist(['a', 'b']),
+		foo: v.picklist(['a', 'b', 'c']),
 		bar: v.picklist(['d', 'e']),
-		button: v.literal('submitter')
+		button: v.optional(v.literal('submitter'))
 	});
 	let submitter;
 	$inspect(my_form.fields.allIssues());
@@ -24,6 +24,8 @@
 
 	<input {...my_form.fields.bar.as('text')} />
 
+	<button>submit (imperative validation)</button>
+
 	<button bind:this={submitter} {...my_form.fields.button.as('submit')} value="incorrect_value">
 		submit
 	</button>

packages/kit/test/apps/basics/src/routes/remote/form/validate/form.remote.ts

@@ -5,9 +5,14 @@ export const my_form = form(
 	v.object({
 		foo: v.picklist(['a', 'b', 'c']),
 		bar: v.picklist(['d', 'e', 'f']),
-		button: v.literal('submitter')
+		button: v.optional(v.literal('submitter'))
 	}),
-	async (data) => {
+	async (data, invalid) => {
+		// Test imperative validation
+		if (data.foo === 'c') {
+			invalid(invalid.foo('Imperative: foo cannot be c'));
+		}
+
 		console.log(data);
 	}
 );

packages/kit/test/apps/basics/test/test.js

@@ -1844,6 +1844,7 @@ test.describe('remote functions', () => {
 
 		const foo = page.locator('input[name="foo"]');
 		const bar = page.locator('input[name="bar"]');
+		const submit = page.locator('button:has-text("imperative validation")');
 
 		await foo.fill('a');
 		await expect(page.locator('form')).not.toContainText('Invalid type: Expected');
@@ -1860,6 +1861,12 @@ test.describe('remote functions', () => {
 		await expect(page.locator('form')).toContainText(
 			'Invalid type: Expected "submitter" but received "incorrect_value"'
 		);
+
+		// Test imperative validation
+		await foo.fill('c');
+		await bar.fill('d');
+		await submit.click();
+		await expect(page.locator('form')).toContainText('Imperative: foo cannot be c');
 	});
 
 	test('form inputs excludes underscore-prefixed fields', async ({ page, javaScriptEnabled }) => {