react-router-effect 0.3.0 → 0.5.0

package/README.md

@@ -77,11 +77,11 @@ type DomainErrors = FormError | BadInputError | DbError;
 // Curried: pin the domain errors, then the handler types are inferred.
 export const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
   errorHandlers: {
+    // keys autocomplete to your domain-error tags; `error` is typed from its key.
     // recover: short-circuit and hand the reply to the component
-    FormError: (error: FormError) => baseRespond.early({ reply: error.reply }),
+    FormError: (error) => baseRespond.early({ reply: error.reply }),
     // throw: send to the error boundary
-    BadInputError: (error: BadInputError) =>
-      Effect.fail(new Response(error.message, { status: 400 })),
+    BadInputError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
   },
 });
 
@@ -92,8 +92,9 @@ export const Respond = {
 };
 ```
 
-> **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.
+> **No annotations needed.** Handler keys autocomplete to your declared domain-error tags, each
+> `error` parameter is typed from its key, and the precise recover types are derived from each
+> handler's return.
 
 ### 2. Write loaders/actions as effects
 
@@ -177,12 +178,64 @@ 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?, 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.
+- **`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, ManagedRuntime } 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 & {
@@ -76,14 +76,34 @@ type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : ne
  * `DataWithResponseInit<never>` into its return type.
  */
 type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never] ? never : UNSAFE_DataWithResponseInit<ReturnableBodyOf<E>>;
+/** What a handler may return: a library route error or an `Effect` failing with a response. */
+type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
 /**
- * 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`:
+ * The inferred map of handler RETURN types, keyed by domain-error tag. Making the
+ * factory generic over *this* (rather than the whole handler map) is what lets
+ * `errorHandlers` contextually type each handler's `error` param from its key —
+ * no annotation needed — while still capturing precise return types for recovery.
+ */
+type HandlerReturns<DomainError extends Tagged> = Partial<Record<DomainError["_tag"], HandlerReturn>>;
+/**
+ * The `errorHandlers` field shape for a given return map: one entry per registered
+ * tag, whose `error` is the matching domain error (so it autocompletes and types
+ * itself) and whose return is the precise, inferred `Returns[Tag]`.
+ */
+type ErrorHandlers<DomainError extends Tagged, Returns> = { [Tag in keyof Returns]: (error: Extract<DomainError, {
+  readonly _tag: Tag;
+}>) => Returns[Tag] };
+/**
+ * What the registered handlers recover into loader/action data — from each
+ * handler's return type, but only for handlers whose error can actually occur in
+ * `E`:
  *  - a remapped `ReturnableDataError<B>` recovers as `DataWithResponseInit<B>`;
  *  - an `Effect.succeed(value)` recovers as `value`;
  *  - 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];
+type RecoverOf<DomainError extends Tagged, Returns, E> = { [Tag in keyof Returns]: [Extract<E, Extract<DomainError, {
+  readonly _tag: Tag;
+}>>] extends [never] ? never : (Returns[Tag] extends ReturnableDataError<infer B> ? UNSAFE_DataWithResponseInit<B> : never) | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never) }[keyof Returns];
 /**
  * Errors the library deals with on the loader's behalf — so the loader needn't
  * handle them itself:
@@ -100,36 +120,49 @@ type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespo
  */
 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`.
+ * 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 HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] extends [DomainError["_tag"]] ? Handlers extends ValidHandlers<DomainError> ? true : false : false;
+type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
 /**
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
  * 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:
+ * *optional* handler per domain error in `errorHandlers`. The handler keys
+ * autocomplete to your domain-error tags and each `error` parameter is typed from
+ * its key — no annotation needed. It's curried so you can pin the domain errors
+ * while the handler return types are still inferred:
  *
  * ```ts
  * 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 })),
+ *     // `error` is typed as MyDomainError automatically. throw → error boundary
+ *     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
  *     // DbError has no handler → falls through to the 500 default.
  *   },
  * });
@@ -165,13 +198,15 @@ type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] e
  * );
  * ```
  */
-declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Handlers = {}, RServices = never>(config: {
+declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Returns extends HandlerReturns<DomainError> = {}, 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).
+   * An optional handler per declared domain error, keyed by its tag. The keys
+   * autocomplete to your domain-error tags and each handler's `error` parameter
+   * is typed automatically — no annotation needed. A handler *remaps* the error
+   * by returning a library route error (`Respond.early` / `throw` / `redirect`)
+   * or an `Effect` (`Effect.succeed`/`fail`). Omit entirely to register none.
    */
-  errorHandlers?: Handlers;
+  errorHandlers?: ErrorHandlers<DomainError, Returns>;
   /**
    * The app runtime that provides services to loader/action effects. When
    * set, effects may require its services (`RServices`, inferred from here)
@@ -179,9 +214,17 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    * 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>>;
+  /**
+   * A React Router context key (a {@link RequestContextKey}) 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>;
+}) => {
+  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<DomainError, Returns, 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<DomainError, Returns, 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

@@ -52,18 +52,18 @@ const processRouteError = (e) => {
 * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
 *
 * 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:
+* *optional* handler per domain error in `errorHandlers`. The handler keys
+* autocomplete to your domain-error tags and each `error` parameter is typed from
+* its key — no annotation needed. It's curried so you can pin the domain errors
+* while the handler return types are still inferred:
 *
 * ```ts
 * 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 })),
+*     // `error` is typed as MyDomainError automatically. throw → error boundary
+*     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
 *     // DbError has no handler → falls through to the 500 default.
 *   },
 * });
@@ -100,8 +100,9 @@ const processRouteError = (e) => {
 * ```
 */
 function makeLoaderOrActionFactory() {
-	return function defineErrorHandlers(config, ..._validate) {
+	return function defineErrorHandlers(config) {
 		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) {
@@ -115,7 +116,8 @@ function makeLoaderOrActionFactory() {
 					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);
+				const provided = requestContextKey ? Effect.provideContext(program, args.context.get(requestContextKey)) : program;
+				return runtime ? runtime.runPromise(provided) : Effect.runPromise(provided);
 			};
 		}
 		return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",

package/src/factory.ts

@@ -1,4 +1,4 @@
-import { Effect, type ManagedRuntime } 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 {
@@ -52,22 +53,43 @@ type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
   ? never
   : DataWithResponseInit<ReturnableBodyOf<E>>;
 
+/** What a handler may return: a library route error or an `Effect` failing with a response. */
+type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
+
+/**
+ * The inferred map of handler RETURN types, keyed by domain-error tag. Making the
+ * factory generic over *this* (rather than the whole handler map) is what lets
+ * `errorHandlers` contextually type each handler's `error` param from its key —
+ * no annotation needed — while still capturing precise return types for recovery.
+ */
+type HandlerReturns<DomainError extends Tagged> = Partial<
+  Record<DomainError["_tag"], HandlerReturn>
+>;
+
+/**
+ * The `errorHandlers` field shape for a given return map: one entry per registered
+ * tag, whose `error` is the matching domain error (so it autocompletes and types
+ * itself) and whose return is the precise, inferred `Returns[Tag]`.
+ */
+type ErrorHandlers<DomainError extends Tagged, Returns> = {
+  [Tag in keyof Returns]: (error: Extract<DomainError, { readonly _tag: Tag }>) => Returns[Tag];
+};
+
 /**
- * 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`:
+ * What the registered handlers recover into loader/action data — from each
+ * handler's return type, but only for handlers whose error can actually occur in
+ * `E`:
  *  - a remapped `ReturnableDataError<B>` recovers as `DataWithResponseInit<B>`;
  *  - an `Effect.succeed(value)` recovers as `value`;
  *  - 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> ? DataWithResponseInit<B> : never)
-          | (R extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never)
-    : never;
-}[keyof Handlers];
+type RecoverOf<DomainError extends Tagged, Returns, E> = {
+  [Tag in keyof Returns]: [Extract<E, Extract<DomainError, { readonly _tag: Tag }>>] extends [never]
+    ? never
+    :
+        | (Returns[Tag] extends ReturnableDataError<infer B> ? DataWithResponseInit<B> : never)
+        | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never);
+}[keyof Returns];
 
 /**
  * Errors the library deals with on the loader's behalf — so the loader needn't
@@ -86,31 +108,6 @@ type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespo
  */
 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.
 // ---------------------------------------------------------------------------
@@ -127,6 +124,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.
 // ---------------------------------------------------------------------------
@@ -135,18 +165,18 @@ const processRouteError = (
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
  * 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:
+ * *optional* handler per domain error in `errorHandlers`. The handler keys
+ * autocomplete to your domain-error tags and each `error` parameter is typed from
+ * its key — no annotation needed. It's curried so you can pin the domain errors
+ * while the handler return types are still inferred:
  *
  * ```ts
  * 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 })),
+ *     // `error` is typed as MyDomainError automatically. throw → error boundary
+ *     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
  *     // DbError has no handler → falls through to the 500 default.
  *   },
  * });
@@ -183,32 +213,37 @@ const processRouteError = (
  * ```
  */
 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>,
-        ]
-  ) {
+  return function defineErrorHandlers<
+    const Returns extends HandlerReturns<DomainError> = {},
+    RServices = never,
+    ReqServices = never,
+  >(config: {
+    /**
+     * An optional handler per declared domain error, keyed by its tag. The keys
+     * autocomplete to your domain-error tags and each handler's `error` parameter
+     * is typed automatically — no annotation needed. A handler *remaps* the error
+     * by returning a library route error (`Respond.early` / `throw` / `redirect`)
+     * or an `Effect` (`Effect.succeed`/`fail`). Omit entirely to register none.
+     */
+    errorHandlers?: ErrorHandlers<DomainError, Returns>;
+    /**
+     * 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 (a {@link RequestContextKey}) 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>;
+  }) {
     const runtime = config.runtime;
+    const requestContextKey = config.requestContext;
 
     // Uniform call signature for dispatch (the per-tag handler types are narrower).
     // Defaults to an empty map when `errorHandlers` is omitted.
@@ -221,9 +256,11 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
       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>,
+      // 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
@@ -236,7 +273,7 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
               DomainError
             >,
           ]
-    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>> {
+    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, 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
@@ -269,12 +306,21 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
             },
           ),
         );
+        // 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(program)
-          : Effect.runPromise(program as Effect.Effect<unknown, FailureResponse>);
-        return result as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+          ? runtime.runPromise(provided)
+          : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>);
+        return result as Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>>;
       };
     }
 

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";