breaking: allow handleError to influence status code

.changeset/ripe-tires-chew.md

@@ -0,0 +1,6 @@
+---
+"@sveltejs/kit": major
+---
+
+breaking: allow `handleError` to influence status code
+

documentation/docs/30-advanced/25-errors.md

@@ -100,6 +100,27 @@ By default, unexpected errors are printed to the console (or, in production, you
 
 Unexpected errors will go through the [`handleError`](hooks#Shared-hooks-handleError) hook, where you can add your own error handling — for example, sending errors to a reporting service, or returning a custom error object which becomes `page.error`.
 
+You can override the HTTP status code used in the response by returning a `status` property:
+
+```js
+/// file: src/hooks.server.js
+// Assuming you have this ...
+class NotFound extends Error {}
+
+/** @type {import('@sveltejs/kit').HandleServerError} */
+export function handleError({ error, event, status, message }) {
+	// ... you can do this
+	if (error instanceof NotFound) {
+		return {
+			status: 404,
+			message: 'Not found'
+		};
+	}
+
+	return { message: 'Something went wrong' };
+}
+```
+
 ## Rendering errors
 
 Ordinarily, if an error happens during server-side rendering (for example inside a component's `<script>` block or template), SvelteKit will return a 500 error page.

packages/kit/package.json

@@ -71,7 +71,7 @@
 	],
 	"scripts": {
 		"lint": "prettier --config ../../.prettierrc --check .",
-		"check": "tsc && cd ./test/types && tsc",
+		"check": "tsc && cd ./test/types && tsc && cd ./app-error-enhanced && tsc",
 		"check:all": "tsc && pnpm -r --filter=\"./**\" check",
 		"format": "prettier --config ../../.prettierrc --write .",
 		"test": "pnpm test:unit && pnpm test:integration",

packages/kit/src/exports/index.js

@@ -26,10 +26,10 @@ export { VERSION } from '../version.js';
  * return an error response without invoking `handleError`.
  * Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
- * @param {App.Error} body An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
+ * @param {Omit<App.Error, 'status'> & { status?: App.Error['status'] }} body An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
  * @overload
  * @param {number} status
- * @param {App.Error} body
+ * @param {Omit<App.Error, 'status'> & { status?: App.Error['status'] }} body
  * @return {never}
  * @throws {import('./public.js').HttpError} This error instructs SvelteKit to initiate HTTP error handling.
  * @throws {Error} If the provided status is invalid (not between 400 and 599).
@@ -40,10 +40,10 @@ export { VERSION } from '../version.js';
  * return an error response without invoking `handleError`.
  * Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
- * @param {{ message: string } extends App.Error ? App.Error | string | undefined : never} [body] An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
+ * @param {{ status: number; message: string } extends App.Error ? string | void | undefined : never} body The error message.
  * @overload
  * @param {number} status
- * @param {{ message: string } extends App.Error ? App.Error | string | undefined : never} [body]
+ * @param {{ status: number; message: string } extends App.Error ? string | void | undefined : never} body
  * @return {never}
  * @throws {import('./public.js').HttpError} This error instructs SvelteKit to initiate HTTP error handling.
  * @throws {Error} If the provided status is invalid (not between 400 and 599).
@@ -54,17 +54,34 @@ export { VERSION } from '../version.js';
  * return an error response without invoking `handleError`.
  * Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
- * @param {{ message: string } extends App.Error ? App.Error | string | undefined : never} body An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
+ * @param {string} body The error message.
+ * @param {{ status: number; message: string } extends App.Error ? never : Omit<App.Error, 'status' | 'message'>} properties Additional properties of the App.Error type.
+ * @overload
+ * @param {number} status
+ * @param {string} body
+ * @param {{ status: number; message: string } extends App.Error ? never : Omit<App.Error, 'status' | 'message'>} properties
+ * @return {never}
+ * @throws {import('./public.js').HttpError} This error instructs SvelteKit to initiate HTTP error handling.
+ * @throws {Error} If the provided status is invalid (not between 400 and 599).
+ */
+/**
+ * Throws an error with a HTTP status code and an optional message.
+ * When called during request handling, this will cause SvelteKit to
+ * return an error response without invoking `handleError`.
+ * Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
+ * @param {any} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
+ * @param {any} [body] An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
+ * @param {any} [properties] Additional properties of the App.Error type when passing a string message.
  * @return {never}
  * @throws {import('./public.js').HttpError} This error instructs SvelteKit to initiate HTTP error handling.
  * @throws {Error} If the provided status is invalid (not between 400 and 599).
  */
-export function error(status, body) {
+export function error(status, body, properties) {
 	if ((!BROWSER || DEV) && (isNaN(status) || status < 400 || status > 599)) {
 		throw new Error(`HTTP error status codes must be between 400 and 599 — ${status} is invalid`);
 	}
 
-	throw new HttpError(status, body);
+	throw new HttpError(status, body, properties);
 }
 
 /**

packages/kit/src/exports/index.spec.js

@@ -1,4 +1,4 @@
-import { isRedirect, normalizeUrl, redirect } from './index.js';
+import { error, isHttpError, isRedirect, normalizeUrl, redirect } from './index.js';
 import { assert, describe, it } from 'vitest';
 
 describe('normalizeUrl', () => {
@@ -74,3 +74,41 @@ describe('redirect', () => {
 		);
 	});
 });
+
+describe('error', () => {
+	it('adds status to the body', () => {
+		try {
+			error(418, 'teapot');
+			assert.fail('Expected error to throw');
+		} catch (e) {
+			if (!isHttpError(e)) {
+				assert.fail('Expected an HttpError');
+			}
+
+			assert.equal(e.status, 418);
+			assert.deepEqual(e.body, { message: 'teapot', status: 418 });
+		}
+	});
+
+	it('merges additional body properties', () => {
+		try {
+			// @ts-expect-error
+			error(400, 'Bad request', { code: 'bad_request' });
+			assert.fail('Expected error to throw');
+		} catch (e) {
+			if (!isHttpError(e)) {
+				assert.fail('Expected an HttpError');
+			}
+
+			assert.equal(e.status, 400);
+			assert.deepEqual(
+				e.body,
+				/** @type {any} */ ({
+					code: 'bad_request',
+					message: 'Bad request',
+					status: 400
+				})
+			);
+		}
+	});
+});

packages/kit/src/exports/internal/index.js

@@ -3,16 +3,17 @@
 export class HttpError {
 	/**
 	 * @param {number} status
-	 * @param {{message: string} extends App.Error ? (App.Error | string | undefined) : App.Error} body
+	 * @param {Omit<App.Error, 'status'> | string | undefined} body
+	 * @param {Omit<App.Error, 'status' | 'message'>} [properties]
 	 */
-	constructor(status, body) {
+	constructor(status, body, properties) {
 		this.status = status;
 		if (typeof body === 'string') {
-			this.body = { message: body };
+			this.body = { ...properties, message: body, status };
 		} else if (body) {
-			this.body = body;
+			this.body = { ...body, status };
 		} else {
-			this.body = { message: `Error: ${status}` };
+			this.body = { message: `Error: ${status}`, status };
 		}
 	}
 

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

@@ -34,6 +34,8 @@ export { PrerenderOption } from '../types/private.js';
 // @ts-ignore this is an optional peer dependency so could be missing. Written like this so dts-buddy preserves the ts-ignore
 type Span = import('@opentelemetry/api').Span;
 
+type AppErrorWithOptionalStatus = Omit<App.Error, 'status'> & { status?: App.Error['status'] };
+
 /**
  * [Adapters](https://svelte.dev/docs/kit/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing.
  */
@@ -951,34 +953,40 @@ export type Handle = (input: {
  *
  * If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
  * Make sure that this function _never_ throws an error.
+ *
+ * The returned object can include a `status` property to override the HTTP status code used in the response.
+ * If omitted, the status defaults to 500.
  */
 export type HandleServerError = (input: {
 	error: unknown;
 	event: RequestEvent;
 	status: number;
 	message: string;
-}) => MaybePromise<void | App.Error>;
+}) => MaybePromise<void | AppErrorWithOptionalStatus>;
 
 /**
  * The [`handleValidationError`](https://svelte.dev/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`.
  */
 export type HandleValidationError<Issue extends StandardSchemaV1.Issue = StandardSchemaV1.Issue> =
-	(input: { issues: Issue[]; event: RequestEvent }) => MaybePromise<App.Error>;
+	(input: { issues: Issue[]; event: RequestEvent }) => MaybePromise<AppErrorWithOptionalStatus>;
 
 /**
  * The client-side [`handleError`](https://svelte.dev/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while navigating.
  *
  * If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
  * Make sure that this function _never_ throws an error.
+ *
+ * The returned object can include a `status` property to override the HTTP status code used in the response.
+ * If omitted, the status defaults to 500.
  */
 export type HandleClientError = (input: {
 	error: unknown;
 	event: NavigationEvent;
 	status: number;
 	message: string;
-}) => MaybePromise<void | App.Error>;
+}) => MaybePromise<void | AppErrorWithOptionalStatus>;
 
 /**
  * The [`handleFetch`](https://svelte.dev/docs/kit/hooks#Server-hooks-handleFetch) hook allows you to modify (or replace) the result of an [`event.fetch`](https://svelte.dev/docs/kit/load#Making-fetch-requests) call that runs on the server (or during prerendering) inside an endpoint, `load`, `action`, `handle`, `handleError` or `reroute`.
@@ -1834,7 +1842,7 @@ export type ActionResult<
 	| { type: 'success'; status: number; data?: Success }
 	| { type: 'failure'; status: number; data?: Failure }
 	| { type: 'redirect'; status: number; location: string }
-	| { type: 'error'; status?: number; error: any };
+	| { type: 'error'; status?: number; error: App.Error };
 
 /**
  * The object returned by the [`error`](https://svelte.dev/docs/kit/@sveltejs-kit#error) function.

packages/kit/src/runtime/app/forms.js

@@ -2,7 +2,7 @@ import * as devalue from 'devalue';
 import { BROWSER, DEV } from 'esm-env';
 import { noop } from '../../utils/functions.js';
 import { invalidateAll } from './navigation.js';
-import { app as client_app, applyAction } from '../client/client.js';
+import { app as client_app, applyAction, handle_error } from '../client/client.js';
 import { app as server_app } from '../server/app.js';
 
 export { applyAction };
@@ -201,7 +201,14 @@ export function enhance(form_element, submit = noop) {
 			if (result.type === 'error') result.status = response.status;
 		} catch (error) {
 			if (/** @type {any} */ (error)?.name === 'AbortError') return;
-			result = { type: 'error', error };
+			result = {
+				type: 'error',
+				error: await handle_error(error, {
+					params: {},
+					route: { id: null },
+					url: new URL(location.href)
+				})
+			};
 		}
 
 		await callback({

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

@@ -14,7 +14,6 @@ import {
 import { noop } from '../../../../utils/functions.js';
 import { SharedIterator } from '../../../../utils/shared-iterator.js';
 import { handle_error_and_jsonify } from '../../../server/utils.js';
-import { HttpError, SvelteKitError } from '@sveltejs/kit/internal';
 
 /**
  * Creates a remote query. When called from the browser, the function will be invoked on the server via a `fetch` call.
@@ -347,13 +346,11 @@ function batch(validate_or_fn, maybe_fn) {
 								const data = get_result(arg, i);
 								return { type: 'result', data };
 							} catch (error) {
+								const transformed = await handle_error_and_jsonify(event, state, options, error);
+
 								return {
 									type: 'error',
-									error: await handle_error_and_jsonify(event, state, options, error),
-									status:
-										error instanceof HttpError || error instanceof SvelteKitError
-											? error.status
-											: 500
+									error: transformed
 								};
 							}
 						})

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

@@ -35,13 +35,11 @@ export function create_validator(validate_or_fn, maybe_fn) {
 
 			// if the `issues` field exists, the validation failed
 			if (result.issues) {
-				error(
-					400,
-					await state.handleValidationError({
-						issues: result.issues,
-						event
-					})
-				);
+				const body = await state.handleValidationError({
+					issues: result.issues,
+					event
+				});
+				error(body.status ?? 400, body);
 			}
 
 			return result.value;