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

[elliott-with-the-longest-name-on-github]

Closes #11144
Closes #6009
Closes #11186

This makes redirect and error into functions that return never, meaning we can throw errors from inside of them without making our users do it.

This also adds isHttpError and isRedirect helpers to identify these commands if you've caught them -- for example:

export function withLogging(loadFn): loadFn {
  return () => {
    try {
      return await loadFn();
    } catch (e) {
      if (!isRedirect(e)) {
        logError(e);
      }
      throw e;
    }
  }
}

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
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests

• Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• 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:.

[changeset-bot]

🦋 Changeset detected

Latest commit: 171d25c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[elliott-with-the-longest-name-on-github]

@eltigerchino
I think I broke the JSDoc for error, not sure how -- the written documentation is no longer showing when I hover over the function. I think you'd fixed this before but 🤷🏻 I can't figure it out.

Oh, it's a typescript issue where all the descriptions are ignored when you have the overload tag. You just need to repeat the definitions with the descriptions before the overload tag to get it working again.

e.g.,

/**
* Hello world!
* @params {string} something - Pass me anything
* @overload
* @params {string} something
*/

We have to do this for each overload definition.

Yeah... I just tried this and it's not working. Adding the @throw tags might have broken it once and for all 😅

[eltigerchino]

It's strange because the @throws error types get left out by dts-buddy when generating the sveltekit types. Also, they are not rendered correctly in VSCode even before generating the types, although it's supposedly fixed in TypeScript. microsoft/TypeScript#49323

Curiously, the @throws JSDoc comments don't need to be duplicated, but the others do. Maybe we need to fix something in dts-buddy?
I've pushed a fix but the generated type definition looks like the below. Note the stripped out error types.

	/**
	 * 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 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 body An object that conforms to the App.Error type. If a string is passed, it will be used as the message property.
	 * @throws This error instructs SvelteKit to initiate HTTP error handling.
	 * @throws If the provided status is invalid (not between 400 and 599).
	 */

[dummdidumm]

Should we just revert the @throws change? I don't think it does anything useful other than showing up a tiny bit more prominently when hovering over the method.

[eltigerchino]

Another alternative is to wrap the type in backticks until it gets fixed.

- @throws {HttpError} This error instructs SvelteKit to initiate HTTP error handling.
+ @throws `HttpError` This error instructs SvelteKit to initiate HTTP error handling.

It's also a bit strange that the overload generates duplicate documentation like this with the same href https://kit-svelte-na0lymp17-svelte.vercel.app/docs/modules#sveltejs-kit-error

[benmccann]

It looks like this PR got corrupted with other changes included on it. It's deleting a few changesets and has other changes that I don't think should be included

[Rich-Harris]

I fixed the @throws thing. The duplicate documentation is annoying, but is an issue we already have on the site so I don't think it needs to block this PR