react-router-effect 0.1.0 → 0.3.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
 
@@ -129,10 +140,49 @@ class NotAuthorizedError extends Data.TaggedError("NotAuthorizedError")<{}> {
 
 A registered handler, if present, still takes precedence over the error's own response.
 
+### Providing services with a runtime
+
+Pass a `runtime` (an effect [`ManagedRuntime`](https://effect.website)) and your loaders/actions
+may require its services directly — no per-call `Effect.provide`. The runtime is built once and
+reused for every request:
+
+```ts
+// app/runtime.server.ts
+import { ManagedRuntime } from "effect";
+export const appRuntime = ManagedRuntime.make(AppLayer); // provides Database, MyService, ...
+
+// app/route.server.ts
+export const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+  runtime: appRuntime,
+  errorHandlers: { ... },
+});
+
+// app/routes/profile.ts — `MyService` is satisfied by the runtime, not provided here:
+const loader = makeLoader((args: Route.LoaderArgs) =>
+  Effect.gen(function* () {
+    const svc = yield* MyService;
+    return { profile: yield* svc.load(args.params.id) };
+  }),
+);
+```
+
+The runtime's services become the effect's allowed requirement channel: requiring a service the
+runtime provides type-checks, while requiring one it _doesn't_ is a compile error. With no
+`runtime`, effects must require nothing.
+
+`errorHandlers` is optional too — configure a factory with just a runtime, or with nothing:
+
+```ts
+makeLoaderOrActionFactory()({ runtime });
+makeLoaderOrActionFactory()({});
+```
+
 ## API
 
-- **`makeLoaderOrActionFactory({ errorHandlers })`** → `{ makeLoader, makeAction, makeLoaderOrAction }`
-  (the three are the same wrapper under different names).
+- **`makeLoaderOrActionFactory<DomainErrors>()({ errorHandlers?, runtime? })`** →
+  `{ makeLoader, makeAction }` (both are the same wrapper). Both config fields are optional. A
+  non-domain error left in a loader/action's error channel — or a required service the `runtime`
+  doesn't provide — 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 { Effect, ManagedRuntime } 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,104 @@ 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).
- *
- * 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.
+ *
+ * Pass a `runtime` (a `ManagedRuntime`, e.g. from `ManagedRuntime.make(AppLayer)`)
+ * to provide your app's services once. Loader/action effects may then require those
+ * services directly — no per-call `Effect.provide`:
+ *
+ * ```ts
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+ *   runtime: getAppRuntime(), // provides Database, MyService, ...
+ *   errorHandlers: { ... },
+ * });
+ *
+ * // `MyService` is satisfied by the runtime, not provided here:
+ * const loader = makeLoader((args: Route.LoaderArgs) =>
+ *   Effect.gen(function* () {
+ *     const svc = yield* MyService;
+ *     return { data: yield* svc.load(args) };
+ *   }),
+ * );
+ * ```
  */
-declare function makeLoaderOrActionFactory<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>>;
+declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Handlers = {}, RServices = never>(config: {
+  /**
+   * An optional handler per declared domain error. Omit entirely to register
+   * none (e.g. when relying on `HttpServerRespondable` / the 500 default, or
+   * when there are no domain errors at all).
+   */
+  errorHandlers?: Handlers;
+  /**
+   * The app runtime that provides services to loader/action effects. When
+   * set, effects may require its services (`RServices`, inferred from here)
+   * without providing layers, and runs go through `runtime.runPromise`. When
+   * omitted, `RServices` is `never` and effects must require nothing.
+   */
+  runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
+}, ..._validate: HandlersAreValid<Handlers, DomainError> extends true ? [] : [eachHandlerMustBeForADeclaredDomainErrorAndReturnARouteErrorOrAnEffect: ValidHandlers<DomainError>]) => {
+  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, RServices>, ..._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, RServices>, ..._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,77 @@ 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.
+*
+* Pass a `runtime` (a `ManagedRuntime`, e.g. from `ManagedRuntime.make(AppLayer)`)
+* to provide your app's services once. Loader/action effects may then require those
+* services directly — no per-call `Effect.provide`:
+*
+* ```ts
+* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+*   runtime: getAppRuntime(), // provides Database, MyService, ...
+*   errorHandlers: { ... },
+* });
+*
+* // `MyService` is satisfied by the runtime, not provided here:
+* const loader = makeLoader((args: Route.LoaderArgs) =>
+*   Effect.gen(function* () {
+*     const svc = yield* MyService;
+*     return { data: yield* svc.load(args) };
+*   }),
+* );
+* ```
 */
-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 runtime = config.runtime;
+		const userHandlers = config.errorHandlers ?? {};
+		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in userHandlers;
+		function makeLoaderOrAction(fn, ..._handle) {
+			return (args) => {
+				const program = 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 runtime ? runtime.runPromise(program) : Effect.runPromise(program);
+			};
+		}
+		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.3.0",
   "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",
@@ -48,7 +48,7 @@
     "playwright": "1.60.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "react-router": "^7.16.0",
+    "react-router": "^8.0.0",
     "typescript": "^6.0.3",
     "vite-plus": "latest",
     "vitest": "4.1.9",
@@ -56,13 +56,13 @@
   },
   "peerDependencies": {
     "effect": "^4.0.0-beta.88",
-    "react-router": "^7.16.0"
+    "react-router": "^7.16.0 || ^8.0.0"
   },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
       "version": "11.9.0",
-      "onFail": "download"
+      "onFail": "warn"
     }
   },
   "scripts": {

package/src/factory.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, type ManagedRuntime } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
 import {
   data,
@@ -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,66 +134,118 @@ 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.
+ *
+ * Pass a `runtime` (a `ManagedRuntime`, e.g. from `ManagedRuntime.make(AppLayer)`)
+ * to provide your app's services once. Loader/action effects may then require those
+ * services directly — no per-call `Effect.provide`:
+ *
+ * ```ts
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+ *   runtime: getAppRuntime(), // provides Database, MyService, ...
+ *   errorHandlers: { ... },
+ * });
+ *
+ * // `MyService` is satisfied by the runtime, not provided here:
+ * const loader = makeLoader((args: Route.LoaderArgs) =>
+ *   Effect.gen(function* () {
+ *     const svc = yield* MyService;
+ *     return { data: yield* svc.load(args) };
+ *   }),
+ * );
+ * ```
  */
-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(
+export function makeLoaderOrActionFactory<DomainError extends Tagged = never>() {
+  return function defineErrorHandlers<const Handlers = {}, RServices = never>(
+    config: {
+      /**
+       * An optional handler per declared domain error. Omit entirely to register
+       * none (e.g. when relying on `HttpServerRespondable` / the 500 default, or
+       * when there are no domain errors at all).
+       */
+      errorHandlers?: Handlers;
+      /**
+       * The app runtime that provides services to loader/action effects. When
+       * set, effects may require its services (`RServices`, inferred from here)
+       * without providing layers, and runs go through `runtime.runPromise`. When
+       * omitted, `RServices` is `never` and effects must require nothing.
+       */
+      runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
+    },
+    // 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 runtime = config.runtime;
+
+    // Uniform call signature for dispatch (the per-tag handler types are narrower).
+    // Defaults to an empty map when `errorHandlers` is omitted.
+    const userHandlers = (config.errorHandlers ?? {}) as unknown as Record<
+      string,
+      ErrorHandler<DomainError>
+    >;
+
+    const isUserError = (e: unknown): e is DomainError =>
+      typeof e === "object" && e !== null && "_tag" in e && (e as Tagged)._tag in userHandlers;
+
+    function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(
+      // The effect may require `RServices` — the services the configured `runtime`
+      // provides (or `never` when no runtime is configured, requiring nothing).
+      fn: (args: Args) => Effect.Effect<A, E, RServices>,
+      // 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.
+        const program = 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.
+          // 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> => {
@@ -185,13 +268,19 @@ export function makeLoaderOrActionFactory<const Handlers>(
               return internalServerError();
             },
           ),
-        ),
-      ) as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
-  }
-
-  return {
-    makeLoaderOrAction,
-    makeLoader: makeLoaderOrAction,
-    makeAction: makeLoaderOrAction,
+        );
+        // Run against the configured runtime so its services satisfy the effect's
+        // `R`; with no runtime, the effect requires nothing and runs standalone.
+        const result = runtime
+          ? runtime.runPromise(program)
+          : Effect.runPromise(program as Effect.Effect<unknown, FailureResponse>);
+        return result as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+      };
+    }
+
+    return {
+      makeLoader: makeLoaderOrAction,
+      makeAction: makeLoaderOrAction,
+    };
   };
 }