react-router-effect 0.3.0 → 0.4.0

package/README.md

@@ -177,12 +177,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 & {
@@ -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.
  *
@@ -165,7 +193,7 @@ 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 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
@@ -179,9 +207,17 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    * 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, 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>>;
+  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

@@ -102,6 +102,7 @@ const processRouteError = (e) => {
 function makeLoaderOrActionFactory() {
 	return function defineErrorHandlers(config, ..._validate) {
 		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.4.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 {
@@ -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.
 // ---------------------------------------------------------------------------
@@ -183,7 +217,7 @@ const processRouteError = (
  * ```
  */
 export function makeLoaderOrActionFactory<DomainError extends Tagged = never>() {
-  return function defineErrorHandlers<const Handlers = {}, RServices = never>(
+  return function defineErrorHandlers<const Handlers = {}, RServices = never, ReqServices = never>(
     config: {
       /**
        * An optional handler per declared domain error. Omit entirely to register
@@ -198,6 +232,14 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
        * 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
@@ -209,6 +251,7 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
         ]
   ) {
     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 +264,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
@@ -269,11 +314,20 @@ 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>);
+          ? runtime.runPromise(provided)
+          : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>);
         return result as Promise<A | DirectRecover<E> | RecoverOf<Handlers, 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";