Type-safe errors in loader/action

[lensbart]

Currently, if something goes awry in your loader, the recommendation is to throw a Response so that the error will be handled in the nearest ErrorBoundary. This is convenient, but comes with the downside that the error information can’t be inferred from typeof loader since TypeScript is not “throw-aware” (I’m sure there is a better term for this).

This proposal aims to enable fully type-safe error handling, provided that the developer always returns a response rather than throwing.

• Change SerializeFrom so that it can differentiate between Responses with { status: 200 } and other responses (or whatever the distinction is made by Remix to render the route component or the ErrorBoundary fallback). This would (hopefully) allow useLoaderData to Extract<...> the happy-path data from typeof loader, so that you can just consider that case and ignore any error-associated data, which wouldn’t be passed to the route component anyway
• Make useRouteError generic, so that it can take a typeof loader from which it can Exclude<...> the “OK” responses, basically the complement of the previous bullet point

For this to work properly, it might be necessary (or helpful) to provide separate convenience functions success(...) and error(...), which would wrap json(...).

• These functions could return a branded type, so that the loader return type could be a discriminated union (provided that the developer returns nothing else from loader).
• The second (init) argument argument to these functions could be type-restricted, such that only the appropriate status codes would be allowed

Adapted from responses.ts:

// --- copied from `responses.ts` ---

export type JsonFunction = <Data>(
  data: Data,
  init?: number | ResponseInit
) => TypedResponse<Data>

export type TypedResponse<T = unknown> = Omit<Response, "json"> & {
  json(): Promise<T>;
}

export const json: JsonFunction = (data, init = {}) => {
  return routerJson(data, init);
}

// --- the code below was added ---

export type SuccessJsonFunction = <Data>(
  data: Data,
  init?: number | ResponseInit
) => SuccessTypedResponse<Data>

export type SuccessTypedResponse<T = unknown> = TypedResponse<T> & {
  __REMIX_TYPED_RESPONSE: 'success';
}

export const success = json as SuccessJsonFunction

export type ErrorJsonFunction = <Data>(
  data: Data,
  init?: number | ResponseInit
) => ErrorTypedResponse<Data>

export type ErrorTypedResponse<T = unknown> = TypedResponse<T> & {
  __REMIX_TYPED_RESPONSE: 'error';
}

export const error = json as ErrorJsonFunction

Same line of thought for action.

Would this make sense?