breaking: turn redirect and error into commands. Export helpers for identifying them when caught

.changeset/clean-cars-kiss.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': major
+---
+
+breaking: Turn `error` and `redirect` into commands

documentation/docs/20-core-concepts/10-routing.md

@@ -61,7 +61,7 @@ export function load({ params }) {
 		};
 	}
 
-	throw error(404, 'Not found');
+	error(404, 'Not found');
 }
 ```
 
@@ -104,7 +104,7 @@ export async function load({ params }) {
 		return post;
 	}
 
-	throw error(404, 'Not found');
+	error(404, 'Not found');
 }
 ```
 
@@ -264,7 +264,7 @@ export function GET({ url }) {
 	const d = max - min;
 
 	if (isNaN(d) || d < 0) {
-		throw error(400, 'min and max must be numbers, and min must be less than max');
+		error(400, 'min and max must be numbers, and min must be less than max');
 	}
 
 	const random = min + Math.random() * d;
@@ -277,7 +277,7 @@ The first argument to `Response` can be a [`ReadableStream`](https://developer.m
 
 You can use the [`error`](modules#sveltejs-kit-error), [`redirect`](modules#sveltejs-kit-redirect) and [`json`](modules#sveltejs-kit-json) methods from `@sveltejs/kit` for convenience (but you don't have to).
 
-If an error is thrown (either `throw error(...)` or an unexpected error), the response will be a JSON representation of the error or a fallback error page — which can be customised via `src/error.html` — depending on the `Accept` header. The [`+error.svelte`](#error) component will _not_ be rendered in this case. You can read more about error handling [here](errors).
+If an error is thrown (either `error(...)` or an unexpected error), the response will be a JSON representation of the error or a fallback error page — which can be customised via `src/error.html` — depending on the `Accept` header. The [`+error.svelte`](#error) component will _not_ be rendered in this case. You can read more about error handling [here](errors).
 
 > When creating an `OPTIONS` handler, note that Vite will inject `Access-Control-Allow-Origin` and `Access-Control-Allow-Methods` headers — these will not be present in production unless you add them.
 

documentation/docs/20-core-concepts/20-load.md

@@ -397,11 +397,11 @@ import { error } from '@sveltejs/kit';
 /** @type {import('./$types').LayoutServerLoad} */
 export function load({ locals }) {
 	if (!locals.user) {
-		throw error(401, 'not logged in');
+		error(401, 'not logged in');
 	}
 
 	if (!locals.user.isAdmin) {
-		throw error(403, 'not an admin');
+		error(403, 'not an admin');
 	}
 }
 ```
@@ -430,12 +430,12 @@ import { redirect } from '@sveltejs/kit';
 /** @type {import('./$types').LayoutServerLoad} */
 export function load({ locals }) {
 	if (!locals.user) {
-		throw redirect(307, '/login');
+		redirect(307, '/login');
 	}
 }
 ```
 
-> Don't use `throw redirect()` from within a try-catch block, as the redirect will immediately trigger the catch statement.
+> Don't use `redirect()` from within a try-catch block, as the redirect will immediately trigger the catch statement.
 
 In the browser, you can also navigate programmatically outside of a `load` function using [`goto`](modules#$app-navigation-goto) from [`$app.navigation`](modules#$app-navigation).
 

documentation/docs/20-core-concepts/30-form-actions.md

@@ -234,7 +234,7 @@ export const actions = {
 		cookies.set('sessionid', await db.createSession(user));
 
 +		if (url.searchParams.has('redirectTo')) {
-+			throw redirect(303, url.searchParams.get('redirectTo'));
++			redirect(303, url.searchParams.get('redirectTo'));
 +		}
 
 		return { success: true };

documentation/docs/30-advanced/10-advanced-routing.md

@@ -57,7 +57,7 @@ import { error } from '@sveltejs/kit';
 
 /** @type {import('./$types').PageLoad} */
 export function load(event) {
-	throw error(404, 'Not Found');
+	error(404, 'Not Found');
 }
 ```
 

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

@@ -31,7 +31,7 @@ export async function load({ params }) {
 	const post = await db.getPost(params.slug);
 
 	if (!post) {
-		throw error(404, {
+		error(404, {
 			message: 'Not found'
 		});
 	}
@@ -54,7 +54,7 @@ This tells SvelteKit to set the response status code to 404 and render an [`+err
 You can add extra properties to the error object if needed...
 
 ```diff
-throw error(404, {
+error(404, {
 	message: 'Not found',
 +	code: 'NOT_FOUND'
 });
@@ -63,8 +63,8 @@ throw error(404, {
 ...otherwise, for convenience, you can pass a string as the second argument:
 
 ```diff
--throw error(404, { message: 'Not found' });
-+throw error(404, 'Not found');
+-error(404, { message: 'Not found' });
++error(404, 'Not found');
 ```
 
 ## Unexpected errors

packages/kit/src/exports/index.js

@@ -8,19 +8,17 @@ export { VERSION } from '../version.js';
  * @overload
  * @param {number} status
  * @param {App.Error} body
- * @return {HttpError}
+ * @return {never}
  */
-
 /**
  * @overload
  * @param {number} status
  * @param {{ message: string } extends App.Error ? App.Error | string | undefined : never} [body]
- * @return {HttpError}
+ * @return {never}
  */
-
 /**
- * Creates an `HttpError` object with an HTTP status code and an optional message.
- * This object, if thrown during request handling, will cause SvelteKit to
+ * 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 {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.
@@ -31,21 +29,46 @@ export function error(status, body) {
 		throw new Error(`HTTP error status codes must be between 400 and 599 — ${status} is invalid`);
 	}
 
-	return new HttpError(status, body);
+	throw new HttpError(status, body);
 }
 
 /**
- * Create a `Redirect` object. If thrown during request handling, SvelteKit will return a redirect response.
+ * Checks whether this is an error thrown by {@link error}.
+ * @template {number} T
+ * @param {unknown} e
+ * @param {T} [status] The status to filter for.
+ * @return {e is (HttpError & { status: T extends undefined ? never : T })}
+ */
+export function isHttpError(e, status) {
+	const isInstance = e instanceof HttpError;
+	if (status) {
+		return isInstance && e.status === status;
+	}
+	return isInstance;
+}
+
+/**
+ * Redirect a request. When called during request handling, SvelteKit will return a redirect response.
  * Make sure you're not catching the thrown redirect, which would prevent SvelteKit from handling it.
  * @param {300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages). Must be in the range 300-308.
  * @param {string | URL} location The location to redirect to.
+ * @return {never}
  */
 export function redirect(status, location) {
 	if ((!BROWSER || DEV) && (isNaN(status) || status < 300 || status > 308)) {
 		throw new Error('Invalid status code');
 	}
 
-	return new Redirect(status, location.toString());
+	throw new Redirect(status, location.toString());
+}
+
+/**
+ * Checks whether this is a redirect thrown by {@link redirect}.
+ * @param {unknown} e The object to check.
+ * @return {e is Redirect}
+ */
+export function isRedirect(e) {
+	return e instanceof Redirect;
 }
 
 /**

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

@@ -28,7 +28,7 @@ function get_raw_body(req, body_size_limit) {
 		if (!length) {
 			length = body_size_limit;
 		} else if (length > body_size_limit) {
-			throw error(
+			error(
 				413,
 				`Received content-length of ${length}, but only accept up to ${body_size_limit} bytes.`
 			);

packages/kit/src/runtime/server/page/actions.js

@@ -231,13 +231,11 @@ async function call_action(event, actions) {
 /** @param {any} data */
 function validate_action_return(data) {
 	if (data instanceof Redirect) {
-		throw new Error('Cannot `return redirect(...)` — use `throw redirect(...)` instead');
+		throw new Error('Cannot `return redirect(...)` — use `redirect(...)` instead');
 	}
 
 	if (data instanceof HttpError) {
-		throw new Error(
-			'Cannot `return error(...)` — use `throw error(...)` or `return fail(...)` instead'
-		);
+		throw new Error('Cannot `return error(...)` — use `error(...)` or `return fail(...)` instead');
 	}
 }
 

packages/kit/test/apps/basics/src/hooks.server.js

@@ -85,7 +85,7 @@ export const handle = sequence(
 		if (event.url.pathname === '/errors/error-in-handle') {
 			throw new Error('Error in handle');
 		} else if (event.url.pathname === '/errors/expected-error-in-handle') {
-			throw error(500, 'Expected error in handle');
+			error(500, 'Expected error in handle');
 		}
 
 		const response = await resolve(event, {
@@ -105,10 +105,10 @@ export const handle = sequence(
 	async ({ event, resolve }) => {
 		if (event.url.pathname.includes('/redirect/in-handle')) {
 			if (event.url.search === '?throw') {
-				throw redirect(307, event.url.origin + '/redirect/c');
+				redirect(307, event.url.origin + '/redirect/c');
 			} else if (event.url.search.includes('cookies')) {
 				event.cookies.delete(COOKIE_NAME, { path: '/cookies' });
-				throw redirect(307, event.url.origin + '/cookies');
+				redirect(307, event.url.origin + '/cookies');
 			} else {
 				return new Response(undefined, { status: 307, headers: { location: '/redirect/c' } });
 			}
@@ -125,7 +125,7 @@ export const handle = sequence(
 	},
 	async ({ event, resolve }) => {
 		if (event.url.pathname === '/actions/redirect-in-handle' && event.request.method === 'POST') {
-			throw redirect(303, '/actions/enhance');
+			redirect(303, '/actions/enhance');
 		}
 
 		return resolve(event);

packages/kit/test/apps/basics/src/routes/+layout.server.js

@@ -25,11 +25,11 @@ export async function load({ cookies, locals, fetch }) {
 	if (should_fail) {
 		cookies.delete('fail-type', { path: '/' });
 		if (should_fail === 'expected') {
-			throw error(401, 'Not allowed');
+			error(401, 'Not allowed');
 		} else if (should_fail === 'unexpected') {
 			throw new Error('Failed to load');
 		} else {
-			throw redirect(307, '/load');
+			redirect(307, '/load');
 		}
 	}
 	// Do NOT make this load function depend on something which would cause it to rerun

packages/kit/test/apps/basics/src/routes/actions/enhance/+page.server.js

@@ -34,7 +34,7 @@ export const actions = {
 		};
 	},
 	error: () => {
-		throw error(400, 'error');
+		error(400, 'error');
 	},
 	echo: async ({ request }) => {
 		const data = await request.formData();

packages/kit/test/apps/basics/src/routes/actions/form-errors/adjacent-error-boundary/+page.server.js

@@ -2,6 +2,6 @@ import { error } from '@sveltejs/kit';
 
 export const actions = {
 	default: async () => {
-		throw error(502, 'something went wrong');
+		error(502, 'something went wrong');
 	}
 };

packages/kit/test/apps/basics/src/routes/actions/redirect/+page.server.js

@@ -10,6 +10,6 @@ export function load() {
 /** @type {import('./$types').Actions} */
 export const actions = {
 	default: async () => {
-		throw redirect(303, '/actions/enhance');
+		redirect(303, '/actions/enhance');
 	}
 };

packages/kit/test/apps/basics/src/routes/cookies/delete/+server.js

@@ -4,5 +4,5 @@ import { COOKIE_NAME } from '../shared';
 /** @type {import('@sveltejs/kit').RequestHandler} */
 export const GET = (event) => {
 	event.cookies.delete(COOKIE_NAME);
-	throw redirect(303, '/cookies');
+	redirect(303, '/cookies');
 };

packages/kit/test/apps/basics/src/routes/cookies/encoding/not-decoded-twice/+server.js

@@ -4,5 +4,5 @@ import { redirect } from '@sveltejs/kit';
 export const GET = (event) => {
 	const sneaky = 'teapot%2C%20jane%20austen';
 	event.cookies.set('encoding', sneaky);
-	throw redirect(303, '/cookies/encoding');
+	redirect(303, '/cookies/encoding');
 };

packages/kit/test/apps/basics/src/routes/cookies/encoding/set/+server.js

@@ -4,5 +4,5 @@ import { redirect } from '@sveltejs/kit';
 export const GET = (event) => {
 	const needsEncoding = 'teapot, jane austen';
 	event.cookies.set('encoding', needsEncoding);
-	throw redirect(303, '/cookies/encoding');
+	redirect(303, '/cookies/encoding');
 };

packages/kit/test/apps/basics/src/routes/cookies/set/+server.js

@@ -4,5 +4,5 @@ import { COOKIE_NAME } from '../shared';
 /** @type {import('@sveltejs/kit').RequestHandler} */
 export const GET = (event) => {
 	event.cookies.set(COOKIE_NAME, 'teapot');
-	throw redirect(303, '/cookies');
+	redirect(303, '/cookies');
 };

packages/kit/test/apps/basics/src/routes/encoded/redirect/+page.js

@@ -2,5 +2,5 @@ import { redirect } from '@sveltejs/kit';
 
 /** @type {import('@sveltejs/kit').Load} */
 export function load() {
-	throw redirect(307, 'redirected?embedded=' + encodeURIComponent('/苗条?foo=bar&fizz=buzz'));
+	redirect(307, 'redirected?embedded=' + encodeURIComponent('/苗条?foo=bar&fizz=buzz'));
 }

packages/kit/test/apps/basics/src/routes/encoded/反应/+page.js

@@ -1,5 +1,5 @@
 import { redirect } from '@sveltejs/kit';
 
 export function load() {
-	throw redirect(307, encodeURI('苗条'));
+	redirect(307, encodeURI('苗条'));
 }

packages/kit/test/apps/basics/src/routes/errors/+layout.js

@@ -4,6 +4,6 @@ import { error } from '@sveltejs/kit';
 export async function load({ fetch, url }) {
 	if (url.pathname.startsWith('/errors/error-in-layout')) {
 		const res = await fetch('/errors/error-in-layout/non-existent');
-		throw error(res.status);
+		error(res.status);
 	}
 }

packages/kit/test/apps/basics/src/routes/errors/endpoint-shadow-not-ok/+page.server.js

@@ -2,5 +2,5 @@ import { error } from '@sveltejs/kit';
 
 /** @type {import('@sveltejs/kit').RequestHandler} */
 export function load() {
-	throw error(555, undefined);
+	error(555, undefined);
 }

packages/kit/test/apps/basics/src/routes/errors/endpoint-throw-error/+server.js

@@ -1,5 +1,5 @@
 import { error } from '@sveltejs/kit';
 
 export function GET() {
-	throw error(401, 'You shall not pass');
+	error(401, 'You shall not pass');
 }

packages/kit/test/apps/basics/src/routes/errors/endpoint-throw-redirect/+server.js

@@ -1,5 +1,5 @@
 import { redirect } from '@sveltejs/kit';
 
 export function GET() {
-	throw redirect(302, '/');
+	redirect(302, '/');
 }

packages/kit/test/apps/basics/src/routes/errors/load-error-client/+page.js

@@ -3,7 +3,7 @@ import { error } from '@sveltejs/kit';
 /** @type {import('./$types').PageLoad} */
 export async function load() {
 	if (typeof window !== 'undefined') {
-		throw error(555, 'Not found');
+		error(555, 'Not found');
 	}
 
 	return {};

packages/kit/test/apps/basics/src/routes/errors/load-error-server/+page.js

@@ -2,5 +2,5 @@ import { error } from '@sveltejs/kit';
 
 /** @type {import('@sveltejs/kit').Load} */
 export async function load() {
-	throw error(555, 'Not found');
+	error(555, 'Not found');
 }

packages/kit/test/apps/basics/src/routes/errors/load-error-string-server/+page.js

@@ -2,5 +2,5 @@ import { error } from '@sveltejs/kit';
 
 /** @type {import('@sveltejs/kit').Load} */
 export async function load() {
-	throw error(555, 'Not found');
+	error(555, 'Not found');
 }

packages/kit/test/apps/basics/src/routes/errors/load-status-without-error-client/+page.js

@@ -2,7 +2,7 @@ import { error } from '@sveltejs/kit';
 
 export async function load() {
 	if (typeof window !== 'undefined') {
-		throw error(401, undefined);
+		error(401, undefined);
 	}
 	return {};
 }

packages/kit/test/apps/basics/src/routes/errors/page-endpoint/get-explicit/+page.server.js

@@ -1,5 +1,5 @@
 import { error } from '@sveltejs/kit';
 
 export const load = () => {
-	throw error(400, 'oops');
+	error(400, 'oops');
 };