react-router-effect 0.2.0 → 0.4.0

package/README.md

@@ -140,11 +140,101 @@ 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()({});
+```
+
+### Per-request services from middleware
+
+The runtime provides app-wide services. For **request-scoped** services — the current user, a
+request id, a per-request transaction — use [middleware](https://reactrouter.com/how-to/middleware).
+Middleware sets a fresh effect `Context` on a React Router context key each request; the factory's
+`requestContext` reads it and provides those services to the loader/action:
+
+```ts
+// app/request-context.server.ts
+import { Context } from "effect";
+import { createContext } from "react-router";
+import type { RequestContextKey } from "react-router-effect";
+
+class RequestContext extends Context.Service<
+  RequestContext,
+  {
+    readonly userId: string;
+  }
+>()("app/RequestContext") {}
+
+// `requestContext` is a plain React Router context key — `createContext` is RR's own.
+export const requestContext: RequestContextKey<RequestContext> = createContext();
+
+// app/routes/profile.ts — middleware sets a fresh value per request:
+export const middleware: Route.MiddlewareFunction[] = [
+  ({ context, request }, next) => {
+    context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
+    return next();
+  },
+];
+
+// app/route.server.ts — wire the same key into the factory:
+export const { makeLoader } = makeLoaderOrActionFactory<DomainErrors>()({
+  runtime: appRuntime,
+  requestContext,
+});
+
+// the loader requires RequestContext directly — no provide, fresh each request:
+export const loader = makeLoader(() =>
+  Effect.gen(function* () {
+    const { userId } = yield* RequestContext;
+    return { userId };
+  }),
+);
+```
+
+Effects may now require both the runtime's services and the request context's; requiring anything
+else is a compile error. `RequestContextKey<ReqServices>` is a type alias for
+`RouterContext<Context.Context<ReqServices>>` — sugar for annotating the key, nothing more.
+
 ## API
 
-- **`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.
+- **`makeLoaderOrActionFactory<DomainErrors>()({ errorHandlers?, runtime?, requestContext? })`** →
+  `{ makeLoader, makeAction }` (both are the same wrapper). All config fields are optional. A
+  non-domain error left in a loader/action's error channel — or a required service that neither the
+  `runtime` nor the `requestContext` provides — is a compile error.
+- **`RequestContextKey<ReqServices>`** — type of the React Router context key for a per-request
+  effect context (`RouterContext<Context.Context<ReqServices>>`).
 - **`Respond`** — `early` (recover), `throw`, `redirect`.
 - **`ReturnableDataError`**, **`ThrowableDataError`**, **`ThrowableRedirectError`** — the library
   route errors, and **`isRouteError`** to narrow them.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Effect } from "effect";
+import { Context, Effect, ManagedRuntime } from "effect";
 import { HttpServerRespondable } from "effect/unstable/http";
-import { ActionFunctionArgs, LoaderFunctionArgs, UNSAFE_DataWithResponseInit } from "react-router";
+import { ActionFunctionArgs, LoaderFunctionArgs, RouterContext, UNSAFE_DataWithResponseInit } from "react-router";
 
 //#region src/errors.d.ts
 declare const ReturnableDataError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
@@ -114,6 +114,34 @@ type ValidHandlers<DomainError extends Tagged> = { [Tag in DomainError["_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;
+/**
+ * A React Router context key holding a per-request effect `Context.Context`. Set
+ * it in middleware and pass it to the factory's `requestContext` — the runner
+ * reads it on every request and provides its services to the loader/action.
+ *
+ * It's just a `RouterContext`; create one with React Router's `createContext`:
+ *
+ * ```ts
+ * import { createContext } from "react-router";
+ * import { Context } from "effect";
+ * import type { RequestContextKey } from "react-router-effect";
+ *
+ * class RequestContext extends Context.Service<RequestContext, {
+ *   readonly userId: string;
+ * }>()("app/RequestContext") {}
+ *
+ * export const requestContext: RequestContextKey<RequestContext> = createContext();
+ *
+ * // middleware:
+ * export const middleware: Route.MiddlewareFunction[] = [
+ *   ({ context, request }, next) => {
+ *     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
+ *     return next();
+ *   },
+ * ];
+ * ```
+ */
+type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
 /**
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
@@ -145,12 +173,51 @@ type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] e
  * 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<DomainError extends Tagged = never>(): <const Handlers>(config: {
-  errorHandlers: Handlers;
+declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Handlers = {}, RServices = never, ReqServices = 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>;
+  /**
+   * A React Router context key (see {@link createRequestContext}) holding a
+   * per-request effect `Context.Context`. Middleware sets it for each request;
+   * the runner reads `args.context.get(requestContext)` and provides those
+   * services to the effect. Loader/action effects may then require
+   * `ReqServices` (inferred from here) in addition to the runtime's services.
+   */
+  requestContext?: RequestContextKey<ReqServices>;
 }, ..._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>>;
+  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, RServices | ReqServices>, ..._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 | ReqServices>, ..._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 };
+export { type AnyRouteError, type ErrorHandler, type RequestContextKey, Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/dist/index.mjs

@@ -79,21 +79,46 @@ const processRouteError = (e) => {
 * 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() {
 	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;
+		const runtime = config.runtime;
+		const requestContextKey = config.requestContext;
+		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) => 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 (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();
+				}));
+				const provided = requestContextKey ? Effect.provideContext(program, args.context.get(requestContextKey)) : program;
+				return runtime ? runtime.runPromise(provided) : Effect.runPromise(provided);
+			};
 		}
 		return {
 			makeLoader: makeLoaderOrAction,

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "0.2.0",
+  "version": "0.4.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,7 +56,7 @@
   },
   "peerDependencies": {
     "effect": "^4.0.0-beta.88",
-    "react-router": "^7.16.0"
+    "react-router": "^7.16.0 || ^8.0.0"
   },
   "devEngines": {
     "packageManager": {

package/src/factory.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { type Context, Effect, type ManagedRuntime } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
 import {
   data,
@@ -6,6 +6,7 @@ import {
   type ActionFunctionArgs,
   type UNSAFE_DataWithResponseInit as DataWithResponseInit,
   type LoaderFunctionArgs,
+  type RouterContext,
 } from "react-router";
 
 import {
@@ -127,6 +128,39 @@ const processRouteError = (
   return Effect.fail<FailureResponse>(redirect(e.url, e.init));
 };
 
+// ---------------------------------------------------------------------------
+// Per-request context.
+// ---------------------------------------------------------------------------
+
+/**
+ * A React Router context key holding a per-request effect `Context.Context`. Set
+ * it in middleware and pass it to the factory's `requestContext` — the runner
+ * reads it on every request and provides its services to the loader/action.
+ *
+ * It's just a `RouterContext`; create one with React Router's `createContext`:
+ *
+ * ```ts
+ * import { createContext } from "react-router";
+ * import { Context } from "effect";
+ * import type { RequestContextKey } from "react-router-effect";
+ *
+ * class RequestContext extends Context.Service<RequestContext, {
+ *   readonly userId: string;
+ * }>()("app/RequestContext") {}
+ *
+ * export const requestContext: RequestContextKey<RequestContext> = createContext();
+ *
+ * // middleware:
+ * export const middleware: Route.MiddlewareFunction[] = [
+ *   ({ context, request }, next) => {
+ *     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
+ *     return next();
+ *   },
+ * ];
+ * ```
+ */
+export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
+
 // ---------------------------------------------------------------------------
 // Factory.
 // ---------------------------------------------------------------------------
@@ -162,10 +196,51 @@ const processRouteError = (
  * 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<DomainError extends Tagged = never>() {
-  return function defineErrorHandlers<const Handlers>(
-    config: { errorHandlers: Handlers },
+  return function defineErrorHandlers<const Handlers = {}, RServices = never, ReqServices = 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>;
+      /**
+       * A React Router context key (see {@link createRequestContext}) holding a
+       * per-request effect `Context.Context`. Middleware sets it for each request;
+       * the runner reads `args.context.get(requestContext)` and provides those
+       * services to the effect. Loader/action effects may then require
+       * `ReqServices` (inferred from here) in addition to the runtime's services.
+       */
+      requestContext?: RequestContextKey<ReqServices>;
+    },
     // 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.
@@ -175,20 +250,25 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
           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);
+    const runtime = config.runtime;
+    const requestContextKey = config.requestContext;
 
     // Uniform call signature for dispatch (the per-tag handler types are narrower).
-    const userHandlers = config.errorHandlers as unknown as Record<
+    // 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>(
-      fn: (args: Args) => Effect.Effect<A, E>,
+      // The effect may require `RServices` (provided by the configured `runtime`)
+      // and `ReqServices` (provided per-request from `requestContext`). Both are
+      // `never` when their source isn't configured, so the effect must require
+      // nothing extra.
+      fn: (args: Args) => Effect.Effect<A, E, RServices | ReqServices>,
       // 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
@@ -202,40 +282,54 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
             >,
           ]
     ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>> {
-      return (args: Args) =>
+      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();
-              },
-            ),
+        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`). 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>>;
+        );
+        // Provide the per-request context (set by middleware) so `ReqServices` are
+        // satisfied, leaving only the runtime's `RServices` in the requirements.
+        // The cast is sound: `provideContext` removes `ReqServices`, and when no
+        // `requestContext` is configured `ReqServices` is `never` (nothing removed).
+        const provided = (
+          requestContextKey
+            ? Effect.provideContext(program, args.context.get(requestContextKey))
+            : program
+        ) as Effect.Effect<unknown, FailureResponse, RServices>;
+        // 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(provided)
+          : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>);
+        return result as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+      };
     }
 
     return {

package/src/index.ts

@@ -7,4 +7,4 @@ export {
 } from "./errors.ts";
 export type { AnyRouteError } from "./errors.ts";
 export { makeLoaderOrActionFactory } from "./factory.ts";
-export type { ErrorHandler } from "./factory.ts";
+export type { ErrorHandler, RequestContextKey } from "./factory.ts";