react-router-effect 0.2.0 → 0.3.0

package/README.md

@@ -140,11 +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<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? })`** →
+  `{ 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,4 @@
-import { Effect } from "effect";
+import { Effect, ManagedRuntime } from "effect";
 import { HttpServerRespondable } from "effect/unstable/http";
 import { ActionFunctionArgs, LoaderFunctionArgs, UNSAFE_DataWithResponseInit } from "react-router";
 
@@ -145,12 +145,43 @@ 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>(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, 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>, ..._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

@@ -79,21 +79,44 @@ 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 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();
+				}));
+				return runtime ? runtime.runPromise(program) : Effect.runPromise(program);
+			};
 		}
 		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.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,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 { Effect, type ManagedRuntime } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
 import {
   data,
@@ -162,10 +162,43 @@ 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>(
+    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.
@@ -175,20 +208,22 @@ 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;
 
     // 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` — 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
@@ -202,40 +237,45 @@ 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>>;
+        );
+        // 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 {