feat: return boolean from submit to indicate submission validity (#15530)

With this PR, a `submit` in an enhanced remote `form` returns a boolean
indicating whether it was valid or not:

```js
try {
  if (await submit()) {
    // success (return or redirect)
  } else {
    // validation error
  }
} catch (e) {
  // something went wrong
}
```

The alternative approach we considered was to throw an error on invalid
data. But that feels more cumbersome, since now you need to
differentiate between different error types:

```js
import { isHttpError } from '@sveltejs/kit';

// later
try {
  await submit();
  // success (return or redirect)
} catch (e) {
  if (isHttpError(e, 400)) {
    // validation error
  } else {
    // something went wrong
  }
}
```

---

### Please don't delete this checklist! Before submitting the PR, please
make sure you do the following:
- [ ] It's really useful if your PR references an issue where it is
discussed ahead of time. In many cases, features are absent for a
reason. For large changes, please create an RFC:
https://github.com/sveltejs/rfcs
- [x] This message body should clearly illustrate what problems it
solves.
- [x] Ideally, include a test that fails without this PR but passes with
it.

### Tests
- [x] Run the tests with `pnpm test` and lint the project with `pnpm
lint` and `pnpm check`

### Changesets
- [x] If your PR makes a change that should be noted in one or more
packages' changelogs, generate a changeset by running `pnpm changeset`
and following the prompts. Changesets that add features should be
`minor` and those that fix bugs should be `patch`. Please prefix
changeset messages with `feat:`, `fix:`, or `chore:`.

### Edits

- [x] Please ensure that 'Allow edits from maintainers' is checked. PRs
without this option may be closed.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Tee Ming <[email protected]>

Author: 3 people

.changeset/twelve-taxis-move.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: return boolean from `submit` to indicate submission validity for enhanced `form` remote functions

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

@@ -713,10 +713,13 @@ We can customize what happens when the form is submitted with the `enhance` meth
 
 <form {...createPost.enhance(async ({ form, data, submit }) => {
 	try {
-		await submit();
-		form.reset();
+		if (await submit()) {
+			form.reset();
 
-		showToast('Successfully published!');
+			showToast('Successfully published!');
+		} else {
+			showToast('Invalid data!');
+		}
 	} catch (error) {
 		showToast('Oh no! Something went wrong');
 	}

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

@@ -2075,10 +2075,10 @@ export type RemoteForm<Input extends RemoteFormInput | void, Output> = {
 		callback: (opts: {
 			form: HTMLFormElement;
 			data: Input;
-			submit: () => Promise<void> & {
-				updates: (...updates: RemoteQueryUpdate[]) => Promise<void>;
+			submit: () => Promise<boolean> & {
+				updates: (...updates: RemoteQueryUpdate[]) => Promise<boolean>;
 			};
-		}) => void | Promise<void>
+		}) => void
 	): {
 		method: 'POST';
 		action: string;

packages/kit/src/runtime/client/remote-functions/form.svelte.js

@@ -156,6 +156,7 @@ export function form(id) {
 			}
 
 			try {
+				// eslint-disable-next-line @typescript-eslint/await-thenable -- `callback` is typed as returning `void` to allow returning e.g. `Promise<boolean>`
 				await callback({
 					form,
 					data,
@@ -172,7 +173,7 @@ export function form(id) {
 
 		/**
 		 * @param {FormData} data
-		 * @returns {Promise<any> & { updates: (...args: any[]) => any }}
+		 * @returns {Promise<boolean> & { updates: (...args: any[]) => Promise<boolean> }}
 		 */
 		function submit(data) {
 			// Store a reference to the current instance and increment the usage count for the duration
@@ -193,7 +194,7 @@ export function form(id) {
 			/** @type {Error | undefined} */
 			let updates_error;
 
-			/** @type {Promise<any> & { updates: (...args: RemoteQueryUpdate[]) => Promise<any> }} */
+			/** @type {Promise<boolean> & { updates: (...args: RemoteQueryUpdate[]) => Promise<boolean> }} */
 			const promise = (async () => {
 				try {
 					await Promise.resolve();
@@ -230,21 +231,25 @@ export function form(id) {
 
 					if (form_result.type === 'result') {
 						({ issues: raw_issues = [], result } = devalue.parse(form_result.result, app.decoders));
+						const succeeded = raw_issues.length === 0;
 
-						if (!issues.$) {
+						if (succeeded) {
 							if (form_result.refreshes) {
 								apply_refreshes(form_result.refreshes);
 							} else {
 								void invalidateAll();
 							}
 						}
+
+						return succeeded;
 					} else if (form_result.type === 'redirect') {
 						const stringified_refreshes = form_result.refreshes ?? '';
 						if (stringified_refreshes) {
 							apply_refreshes(stringified_refreshes);
 						}
 						// Use internal version to allow redirects to external URLs
 						void _goto(form_result.location, { invalidateAll: !stringified_refreshes }, 0);
+						return true;
 					} else {
 						throw new HttpError(form_result.status ?? 500, form_result.error);
 					}
@@ -460,8 +465,8 @@ export function form(id) {
 
 		instance[createAttachmentKey()] = create_attachment(
 			form_onsubmit(({ submit, form }) =>
-				submit().then(() => {
-					if (!issues.$) {
+				submit().then((succeeded) => {
+					if (succeeded) {
 						form.reset();
 					}
 				})

packages/kit/test/apps/async/src/routes/remote/form/[test_name]/+page.svelte

@@ -7,6 +7,8 @@
 
 	const scoped = set_message.for(`scoped:${params.test_name}`);
 	const enhanced = set_message.for(`enhanced:${params.test_name}`);
+
+	let submit_result = $state('none');
 </script>
 
 <p>message.current: {message.current}</p>
@@ -52,7 +54,9 @@
 <form
 	data-enhanced
 	{...enhanced.enhance(async ({ data, submit }) => {
-		await submit().updates(message.withOverride(() => data.message + ' (override)'));
+		submit_result = String(
+			await submit().updates(message.withOverride(() => data.message + ' (override)'))
+		);
 	})}
 >
 	{#if enhanced.fields.message.issues()}
@@ -67,6 +71,7 @@
 <p>enhanced.input.message: {enhanced.fields.message.value()}</p>
 <p>enhanced.pending: {enhanced.pending}</p>
 <p>enhanced.result: {enhanced.result}</p>
+<p>enhanced.submit_result: {submit_result}</p>
 
 <hr />
 

packages/kit/test/apps/async/test/test.js

@@ -284,6 +284,29 @@ test.describe('remote functions', () => {
 		);
 	});
 
+	test('form enhance submit returns boolean', async ({ page, javaScriptEnabled }) => {
+		if (!javaScriptEnabled) return;
+
+		await page.goto('/remote/form/enhanced');
+
+		await expect(page.getByText('enhanced.submit_result:')).toHaveText(
+			'enhanced.submit_result: none'
+		);
+
+		await page.fill('[data-enhanced] input', 'hello');
+		await page.locator('[data-enhanced] span').click();
+		await page.getByText('resolve deferreds').click();
+		await expect(page.getByText('enhanced.submit_result:')).toHaveText(
+			'enhanced.submit_result: true'
+		);
+
+		await page.fill('[data-enhanced] input', 'invalid');
+		await page.locator('[data-enhanced] span').click();
+		await expect(page.getByText('enhanced.submit_result:')).toHaveText(
+			'enhanced.submit_result: false'
+		);
+	});
+
 	test('form preflight works', async ({ page, javaScriptEnabled }) => {
 		if (!javaScriptEnabled) return;
 

packages/kit/test/types/remote.test.ts

@@ -247,9 +247,9 @@ function form_tests() {
 	f.result?.success === true;
 
 	f.enhance(async ({ submit }) => {
-		const x: void = await submit();
+		const x: boolean = await submit();
 		x;
-		const y: void = await submit().updates(
+		const y: boolean = await submit().updates(
 			q,
 			q(),
 			q().withOverride(() => '')

packages/kit/types/index.d.ts

@@ -2049,10 +2049,10 @@ declare module '@sveltejs/kit' {
 			callback: (opts: {
 				form: HTMLFormElement;
 				data: Input;
-				submit: () => Promise<void> & {
-					updates: (...updates: RemoteQueryUpdate[]) => Promise<void>;
+				submit: () => Promise<boolean> & {
+					updates: (...updates: RemoteQueryUpdate[]) => Promise<boolean>;
 				};
-			}) => void | Promise<void>
+			}) => void
 		): {
 			method: 'POST';
 			action: string;