react-router-effect 0.1.0 → 0.2.0

package/README.md

@@ -39,18 +39,23 @@ A loader/action effect can short-circuit in three ways, via the `Respond` helper
 | `Respond.throw(value, init?)`  | **throw**   | rejects with `data(value, init)` → error boundary   |
 | `Respond.redirect(url, init?)` | **throw**   | rejects with a redirect `Response`                  |
 
-Your own **domain errors** are mapped to one of those outcomes by handlers you register with
-the factory. A handler _remaps_ an error by returning either:
+You declare your app's **domain errors** as a type argument to the factory, and may register a
+handler per domain error. A handler _remaps_ an error by returning either:
 
 - a library route error — `Respond.early(...)` / `Respond.throw(...)` / `Respond.redirect(...)`; or
 - an `Effect` — `Effect.succeed(value)` to **recover** with `value`, or `Effect.fail(response)`
   to **throw** a `Response` / `DataWithResponseInit`.
 
-Handling is **optional**:
+A **declared domain error** may be left unhandled:
 
-- An **unregistered** error that implements [`HttpServerRespondable`](https://effect.website)
-  is rendered automatically from its own response.
-- Any other unregistered error falls through to a **500**.
+- if it implements [`HttpServerRespondable`](https://effect.website) it's rendered automatically
+  from its own response;
+- otherwise it falls through to a **500**.
+
+**Any other error** a route consumes — a service-specific error that isn't a declared domain
+error — **must be handled** in the loader/action (caught or mapped), or `makeLoader`/`makeAction`
+fails to type-check. This gives app-wide defaults for declared errors while enforcing explicit
+handling of feature/service-specific ones.
 
 ## Usage
 
@@ -63,8 +68,14 @@ import { makeLoaderOrActionFactory, Respond as baseRespond } from "react-router-
 
 class FormError extends Data.TaggedError("FormError")<{ reply: SubmissionResponse }> {}
 class BadInputError extends Data.TaggedError("BadInputError")<{ message: string }> {}
+class DbError extends Data.TaggedError("DbError")<{ query: string }> {}
+
+// Declare every error your app handles app-wide. `DbError` has no handler below,
+// so it falls through to the 500 default.
+type DomainErrors = FormError | BadInputError | DbError;
 
-export const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+// Curried: pin the domain errors, then the handler types are inferred.
+export const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
   errorHandlers: {
     // recover: short-circuit and hand the reply to the component
     FormError: (error: FormError) => baseRespond.early({ reply: error.reply }),
@@ -81,8 +92,8 @@ export const Respond = {
 };
 ```
 
-> **Annotate each handler's parameter.** The registered error set and the precise recover
-> types are derived from the handler map's parameter and return types.
+> **Annotate each handler's parameter.** Handlers must be keyed by a declared domain error, and
+> the precise recover types are derived from the handler map's parameter and return types.
 
 ### 2. Write loaders/actions as effects
 
@@ -131,8 +142,9 @@ A registered handler, if present, still takes precedence over the error's own re
 
 ## API
 
-- **`makeLoaderOrActionFactory({ errorHandlers })`** → `{ makeLoader, makeAction, makeLoaderOrAction }`
-  (the three are the same wrapper under different names).
+- **`makeLoaderOrActionFactory<DomainErrors>()({ errorHandlers })`** → `{ makeLoader, makeAction }`
+  (both are the same wrapper). A non-domain error left in a loader/action's error channel is a
+  compile error.
 - **`Respond`** — `early` (recover), `throw`, `redirect`.
 - **`ReturnableDataError`**, **`ThrowableDataError`**, **`ThrowableRedirectError`** — the library
   route errors, and **`isRouteError`** to narrow them.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { HttpServerRespondable } from "effect/unstable/http";
 import { ActionFunctionArgs, LoaderFunctionArgs, UNSAFE_DataWithResponseInit } from "react-router";
 
 //#region src/errors.d.ts
@@ -49,6 +50,9 @@ declare const Respond: {
 declare const isRouteError: (value: unknown) => value is AnyRouteError;
 //#endregion
 //#region src/factory.d.ts
+type Tagged = {
+  readonly _tag: string;
+};
 /**
  * Everything a failure branch rejects with. React Router routes a thrown
  * `DataWithResponseInit` to the boundary as an `ErrorResponse`, and a thrown
@@ -80,41 +84,73 @@ type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never] ? never : UNSAFE_D
  *  - throwables, redirects and `Effect.fail(...)` contribute nothing.
  */
 type RecoverOf<Handlers, E> = { [Tag in keyof Handlers]: Handlers[Tag] extends ((error: infer Err) => infer R) ? [Extract<E, Err>] extends [never] ? never : (R extends ReturnableDataError<infer B> ? UNSAFE_DataWithResponseInit<B> : never) | (R extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never) : never }[keyof Handlers];
-/** Shape every handler must satisfy: return a library route error or an `Effect` failing with a response. */
-type ValidHandlers = Record<string, (error: never) => AnyRouteError | Effect.Effect<unknown, FailureResponse>>;
+/**
+ * Errors the library deals with on the loader's behalf — so the loader needn't
+ * handle them itself:
+ *  - the app's **declared domain errors** (`DomainError`) — handled by a registered
+ *    handler, or left to the 500 / auto-respond default;
+ *  - **library route errors** raised directly via `Respond`;
+ *  - anything that renders itself via **`HttpServerRespondable`**.
+ */
+type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespondable.Respondable;
+/**
+ * What remains in a loader/action's error channel that the library will NOT handle
+ * — i.e. service-specific errors the route consumes that aren't declared domain
+ * errors. The loader/action must handle these itself (catch or map them).
+ */
+type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
+/**
+ * The shape a handler map must satisfy: an OPTIONAL handler per declared domain
+ * error, keyed by its tag, taking that error and returning a library route error
+ * or an `Effect` failing with a response. Used only as a validation constraint —
+ * the concrete handler types stay precise via the `const Handlers` inference.
+ */
+type ValidHandlers<DomainError extends Tagged> = { [Tag in DomainError["_tag"]]?: (error: Extract<DomainError, {
+  readonly _tag: Tag;
+}>) => AnyRouteError | Effect.Effect<unknown, FailureResponse> };
+/**
+ * True when every registered handler is keyed by a declared domain error's tag and
+ * returns a library route error or a failing `Effect`. A handler for an unknown tag
+ * (`keyof Handlers` escaping the domain tags) or with a bad return makes it `false`.
+ */
+type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] extends [DomainError["_tag"]] ? Handlers extends ValidHandlers<DomainError> ? true : false : false;
 /**
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
- * Register a handler per domain error in `errorHandlers` (**annotate each handler's
- * param** — the registered set and recover types are derived from the map). A
- * handler *remaps* the error by returning either a library route error
- * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
- * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
- * throw). Recovered values become loader/action data, typed precisely (non-generic).
+ * Declare the app's **domain errors** as the type argument, then register an
+ * *optional* handler per domain error in `errorHandlers` (**annotate each handler's
+ * param**). It's curried so you can pin the domain errors while the handler types
+ * are still inferred:
  *
- * Handling is optional: an *unregistered* error is allowed. If it implements
- * `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
- * error boundary as a 500.
- *
- * @example
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+ * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
+ *
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
  *   errorHandlers: {
  *     // throw → error boundary
  *     MyDomainError: (error: MyDomainError) =>
  *       Effect.fail(new Response(error.message, { status: 400 })),
- *     // remap → recover via a library returnable
- *     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+ *     // DbError has no handler → falls through to the 500 default.
  *   },
  * });
  * ```
+ *
+ * A handler *remaps* the error by returning either a library route error
+ * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+ * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+ * throw). Recovered values become loader/action data, typed precisely.
+ *
+ * **Declared domain errors** may be left unhandled: if one implements
+ * `HttpServerRespondable` it's rendered automatically, otherwise it falls through
+ * to a 500. **Any other error** — a service-specific error the route consumes that
+ * isn't a declared domain error — *must* be handled in the loader/action, or
+ * `makeLoader`/`makeAction` fails to type-check.
  */
-declare function makeLoaderOrActionFactory<const Handlers>(config: {
+declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Handlers>(config: {
   errorHandlers: Handlers;
-}, ..._validate: Handlers extends ValidHandlers ? [] : [eachHandlerMustReturnARouteErrorOrAnEffectFailingWithAResponse: ValidHandlers]): {
-  makeLoaderOrAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
-  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
-  makeAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
+}, ..._validate: HandlersAreValid<Handlers, DomainError> extends true ? [] : [eachHandlerMustBeForADeclaredDomainErrorAndReturnARouteErrorOrAnEffect: ValidHandlers<DomainError>]) => {
+  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>, ..._handle: [Unhandled<E, DomainError>] extends [never] ? [] : [theseErrorsAreNotDomainErrorsAndMustBeHandledInTheLoaderOrAction: Exclude<E, LibraryHandled<DomainError>>]) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
+  makeAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>, ..._handle: [Unhandled<E, DomainError>] extends [never] ? [] : [theseErrorsAreNotDomainErrorsAndMustBeHandledInTheLoaderOrAction: Exclude<E, LibraryHandled<DomainError>>]) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
 };
 //#endregion
 export { type AnyRouteError, type ErrorHandler, Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/dist/index.mjs

@@ -51,48 +51,54 @@ const processRouteError = (e) => {
 /**
 * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
 *
-* Register a handler per domain error in `errorHandlers` (**annotate each handler's
-* param** — the registered set and recover types are derived from the map). A
-* handler *remaps* the error by returning either a library route error
-* (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
-* `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
-* throw). Recovered values become loader/action data, typed precisely (non-generic).
+* Declare the app's **domain errors** as the type argument, then register an
+* *optional* handler per domain error in `errorHandlers` (**annotate each handler's
+* param**). It's curried so you can pin the domain errors while the handler types
+* are still inferred:
 *
-* Handling is optional: an *unregistered* error is allowed. If it implements
-* `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
-* error boundary as a 500.
-*
-* @example
 * ```ts
-* const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+* type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
+*
+* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
 *   errorHandlers: {
 *     // throw → error boundary
 *     MyDomainError: (error: MyDomainError) =>
 *       Effect.fail(new Response(error.message, { status: 400 })),
-*     // remap → recover via a library returnable
-*     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+*     // DbError has no handler → falls through to the 500 default.
 *   },
 * });
 * ```
+*
+* A handler *remaps* the error by returning either a library route error
+* (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+* `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+* throw). Recovered values become loader/action data, typed precisely.
+*
+* **Declared domain errors** may be left unhandled: if one implements
+* `HttpServerRespondable` it's rendered automatically, otherwise it falls through
+* to a 500. **Any other error** — a service-specific error the route consumes that
+* isn't a declared domain error — *must* be handled in the loader/action, or
+* `makeLoader`/`makeAction` fails to type-check.
 */
-function makeLoaderOrActionFactory(config, ..._validate) {
-	const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in config.errorHandlers;
-	const userHandlers = config.errorHandlers;
-	function makeLoaderOrAction(fn) {
-		return (args) => Effect.runPromise(fn(args).pipe(Effect.catchIf((_e) => true, (e) => {
-			if (isUserError(e)) {
-				const out = userHandlers[e._tag](e);
-				return isRouteError(out) ? processRouteError(out) : out;
-			}
-			if (isRouteError(e)) return processRouteError(e);
-			if (HttpServerRespondable.isRespondable(e)) return HttpServerRespondable.toResponse(e).pipe(Effect.flatMap((res) => Effect.fail(HttpServerResponse.toWeb(res))));
-			return internalServerError();
-		})));
-	}
-	return {
-		makeLoaderOrAction,
-		makeLoader: makeLoaderOrAction,
-		makeAction: makeLoaderOrAction
+function makeLoaderOrActionFactory() {
+	return function defineErrorHandlers(config, ..._validate) {
+		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in config.errorHandlers;
+		const userHandlers = config.errorHandlers;
+		function makeLoaderOrAction(fn, ..._handle) {
+			return (args) => Effect.runPromise(fn(args).pipe(Effect.catchIf((_e) => true, (e) => {
+				if (isUserError(e)) {
+					const out = userHandlers[e._tag](e);
+					return isRouteError(out) ? processRouteError(out) : out;
+				}
+				if (isRouteError(e)) return processRouteError(e);
+				if (HttpServerRespondable.isRespondable(e)) return HttpServerRespondable.toResponse(e).pipe(Effect.flatMap((res) => Effect.fail(HttpServerResponse.toWeb(res))));
+				return internalServerError();
+			})));
+		}
+		return {
+			makeLoader: makeLoaderOrAction,
+			makeAction: makeLoaderOrAction
+		};
 	};
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",
@@ -62,7 +62,7 @@
     "packageManager": {
       "name": "pnpm",
       "version": "11.9.0",
-      "onFail": "download"
+      "onFail": "warn"
     }
   },
   "scripts": {

package/src/factory.ts

@@ -52,11 +52,6 @@ type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
   ? never
   : DataWithResponseInit<ReturnableBodyOf<E>>;
 
-/** The domain errors a handler map registers — derived from the handlers' params. */
-type RegisteredError<Handlers> = {
-  [Tag in keyof Handlers]: Handlers[Tag] extends (error: infer Err) => unknown ? Err : never;
-}[keyof Handlers];
-
 /**
  * What the registered handlers recover into loader/action data — derived from the
  * handlers' returns, but only for handlers whose error can actually occur in `E`:
@@ -74,11 +69,47 @@ type RecoverOf<Handlers, E> = {
     : never;
 }[keyof Handlers];
 
-/** Shape every handler must satisfy: return a library route error or an `Effect` failing with a response. */
-type ValidHandlers = Record<
-  string,
-  (error: never) => AnyRouteError | Effect.Effect<unknown, FailureResponse>
->;
+/**
+ * Errors the library deals with on the loader's behalf — so the loader needn't
+ * handle them itself:
+ *  - the app's **declared domain errors** (`DomainError`) — handled by a registered
+ *    handler, or left to the 500 / auto-respond default;
+ *  - **library route errors** raised directly via `Respond`;
+ *  - anything that renders itself via **`HttpServerRespondable`**.
+ */
+type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespondable.Respondable;
+
+/**
+ * What remains in a loader/action's error channel that the library will NOT handle
+ * — i.e. service-specific errors the route consumes that aren't declared domain
+ * errors. The loader/action must handle these itself (catch or map them).
+ */
+type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
+
+/**
+ * The shape a handler map must satisfy: an OPTIONAL handler per declared domain
+ * error, keyed by its tag, taking that error and returning a library route error
+ * or an `Effect` failing with a response. Used only as a validation constraint —
+ * the concrete handler types stay precise via the `const Handlers` inference.
+ */
+type ValidHandlers<DomainError extends Tagged> = {
+  [Tag in DomainError["_tag"]]?: (
+    error: Extract<DomainError, { readonly _tag: Tag }>,
+  ) => AnyRouteError | Effect.Effect<unknown, FailureResponse>;
+};
+
+/**
+ * True when every registered handler is keyed by a declared domain error's tag and
+ * returns a library route error or a failing `Effect`. A handler for an unknown tag
+ * (`keyof Handlers` escaping the domain tags) or with a bad return makes it `false`.
+ */
+type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] extends [
+  DomainError["_tag"],
+]
+  ? Handlers extends ValidHandlers<DomainError>
+    ? true
+    : false
+  : false;
 
 // ---------------------------------------------------------------------------
 // Internal runtime helpers.
@@ -103,95 +134,113 @@ const processRouteError = (
 /**
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
- * Register a handler per domain error in `errorHandlers` (**annotate each handler's
- * param** — the registered set and recover types are derived from the map). A
- * handler *remaps* the error by returning either a library route error
- * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
- * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
- * throw). Recovered values become loader/action data, typed precisely (non-generic).
- *
- * Handling is optional: an *unregistered* error is allowed. If it implements
- * `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
- * error boundary as a 500.
+ * Declare the app's **domain errors** as the type argument, then register an
+ * *optional* handler per domain error in `errorHandlers` (**annotate each handler's
+ * param**). It's curried so you can pin the domain errors while the handler types
+ * are still inferred:
  *
- * @example
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+ * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
+ *
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
  *   errorHandlers: {
  *     // throw → error boundary
  *     MyDomainError: (error: MyDomainError) =>
  *       Effect.fail(new Response(error.message, { status: 400 })),
- *     // remap → recover via a library returnable
- *     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+ *     // DbError has no handler → falls through to the 500 default.
  *   },
  * });
  * ```
+ *
+ * A handler *remaps* the error by returning either a library route error
+ * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+ * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+ * throw). Recovered values become loader/action data, typed precisely.
+ *
+ * **Declared domain errors** may be left unhandled: if one implements
+ * `HttpServerRespondable` it's rendered automatically, otherwise it falls through
+ * to a 500. **Any other error** — a service-specific error the route consumes that
+ * isn't a declared domain error — *must* be handled in the loader/action, or
+ * `makeLoader`/`makeAction` fails to type-check.
  */
-export function makeLoaderOrActionFactory<const Handlers>(
-  config: { errorHandlers: Handlers },
-  // Validation: a handler that doesn't return a route error or a failing `Effect`
-  // makes this rest parameter required, forcing a compile error at the call.
-  ..._validate: Handlers extends ValidHandlers
-    ? []
-    : [eachHandlerMustReturnARouteErrorOrAnEffectFailingWithAResponse: ValidHandlers]
-) {
-  /** Domain errors this factory has handlers for. */
-  type UserError = Extract<RegisteredError<Handlers>, Tagged>;
-
-  const isUserError = (e: unknown): e is UserError =>
-    typeof e === "object" &&
-    e !== null &&
-    "_tag" in e &&
-    (e as Tagged)._tag in (config.errorHandlers as object);
-
-  // Uniform call signature for dispatch (the per-tag handler types are narrower).
-  const userHandlers = config.errorHandlers as unknown as Record<string, ErrorHandler<UserError>>;
-
-  function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(
-    fn: (args: Args) => Effect.Effect<A, E>,
-    // The resolved value: the loader's own success, the body of any `Respond.early`
-    // raised directly, plus everything the registered (and reachable) handlers
-    // recover with.
-  ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>> {
-    return (args: Args) =>
-      // The internal channel is deliberately loose (`unknown` success); the outer
-      // cast restores the precise resolved type (computed from `E` and the handler
-      // map). Sound at runtime — the values produced are exactly those types.
-      Effect.runPromise(
-        fn(args).pipe(
-          // Catch the whole error channel and dispatch. The refinement is `e is E`
-          // (provably ⊆ E, and a *refinement* not a bare predicate — the predicate
-          // overload crashes tsc over a generic `E`). Unregistered, non-respondable
-          // errors fall through to the 500 default.
-          Effect.catchIf(
-            (_e): _e is E => true,
-            (e): Effect.Effect<unknown, FailureResponse> => {
-              // Registered domain error → remap. A library-error return is processed
-              // by the internal dispatch; an `Effect` return is used as-is.
-              if (isUserError(e)) {
-                const out = userHandlers[e._tag](e);
-                return isRouteError(out) ? processRouteError(out) : out;
-              }
-              // A library route error raised directly in the loader → recover/throw.
-              if (isRouteError(e)) return processRouteError(e);
-              // Respondable → render its own response and throw it.
-              if (HttpServerRespondable.isRespondable(e)) {
-                return HttpServerRespondable.toResponse(e).pipe(
-                  Effect.flatMap((res) =>
-                    Effect.fail<FailureResponse>(HttpServerResponse.toWeb(res)),
-                  ),
-                );
-              }
-              return internalServerError();
-            },
+export function makeLoaderOrActionFactory<DomainError extends Tagged = never>() {
+  return function defineErrorHandlers<const Handlers>(
+    config: { errorHandlers: Handlers },
+    // Validation: a handler for a non-domain error, or one that doesn't return a
+    // route error / failing `Effect`, makes this rest parameter required and forces
+    // a compile error at the call.
+    ..._validate: HandlersAreValid<Handlers, DomainError> extends true
+      ? []
+      : [
+          eachHandlerMustBeForADeclaredDomainErrorAndReturnARouteErrorOrAnEffect: ValidHandlers<DomainError>,
+        ]
+  ) {
+    const isUserError = (e: unknown): e is DomainError =>
+      typeof e === "object" &&
+      e !== null &&
+      "_tag" in e &&
+      (e as Tagged)._tag in (config.errorHandlers as object);
+
+    // Uniform call signature for dispatch (the per-tag handler types are narrower).
+    const userHandlers = config.errorHandlers as unknown as Record<
+      string,
+      ErrorHandler<DomainError>
+    >;
+
+    function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(
+      fn: (args: Args) => Effect.Effect<A, E>,
+      // If the effect can still fail with something the library won't handle — a
+      // service-specific error that isn't a declared domain error, a library route
+      // error, or respondable — this rest parameter becomes required and the call
+      // fails to type-check, forcing the loader/action to handle it.
+      ..._handle: [Unhandled<E, DomainError>] extends [never]
+        ? []
+        : [
+            theseErrorsAreNotDomainErrorsAndMustBeHandledInTheLoaderOrAction: Unhandled<
+              E,
+              DomainError
+            >,
+          ]
+    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>> {
+      return (args: Args) =>
+        // The internal channel is deliberately loose (`unknown` success); the outer
+        // cast restores the precise resolved type (computed from `E` and the handler
+        // map). Sound at runtime — the values produced are exactly those types.
+        Effect.runPromise(
+          fn(args).pipe(
+            // Catch the whole error channel and dispatch. The refinement is `e is E`
+            // (provably ⊆ E, and a *refinement* not a bare predicate — the predicate
+            // overload crashes tsc over a generic `E`). A declared domain error with
+            // no handler (and not respondable) falls through to the 500 default.
+            Effect.catchIf(
+              (_e): _e is E => true,
+              (e): Effect.Effect<unknown, FailureResponse> => {
+                // Registered domain error → remap. A library-error return is processed
+                // by the internal dispatch; an `Effect` return is used as-is.
+                if (isUserError(e)) {
+                  const out = userHandlers[e._tag](e);
+                  return isRouteError(out) ? processRouteError(out) : out;
+                }
+                // A library route error raised directly in the loader → recover/throw.
+                if (isRouteError(e)) return processRouteError(e);
+                // Respondable → render its own response and throw it.
+                if (HttpServerRespondable.isRespondable(e)) {
+                  return HttpServerRespondable.toResponse(e).pipe(
+                    Effect.flatMap((res) =>
+                      Effect.fail<FailureResponse>(HttpServerResponse.toWeb(res)),
+                    ),
+                  );
+                }
+                return internalServerError();
+              },
+            ),
           ),
-        ),
-      ) as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
-  }
-
-  return {
-    makeLoaderOrAction,
-    makeLoader: makeLoaderOrAction,
-    makeAction: makeLoaderOrAction,
+        ) as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+    }
+
+    return {
+      makeLoader: makeLoaderOrAction,
+      makeAction: makeLoaderOrAction,
+    };
   };
 }