react-router-effect 0.6.0 → 1.0.0

package/README.md

@@ -1,10 +1,10 @@
 # react-router-effect
 
-Wrap [React Router](https://reactrouter.com) framework-mode loaders and actions with
+Wrap [React Router](https://reactrouter.com) framework-mode loaders, actions, and middleware with
 [Effect](https://effect.website), and get **typed, declarative error handling** for free.
 
-Write your loader/action as an `Effect`. When it short-circuits with a tagged error, the
-library decides — based on handlers you register once — whether to **recover** (return data
+Write your loader/action/middleware as an `Effect`. When it short-circuits with a tagged error,
+the library decides — based on handlers you register once — whether to **recover** (return data
 the component reads via `useLoaderData`) or **throw** (send it to the error boundary or issue
 a redirect). The resolved type of every loader/action reflects exactly what it can return.
 
@@ -54,8 +54,10 @@ A **declared domain error** may be left unhandled:
 
 **Any other error** a route consumes — a service-specific error that isn't a declared domain
 error — **must be handled** in the loader/action (caught or mapped), or `makeLoader`/`makeAction`
-fails to type-check. This gives app-wide defaults for declared errors while enforcing explicit
-handling of feature/service-specific ones.
+fails to type-check with a message naming the unhandled error(s). This gives app-wide defaults for
+declared errors while enforcing explicit handling of feature/service-specific ones. (Likewise, an
+effect that requires a service neither the `runtime` nor the `requestContext` provides fails to
+type-check with a message naming the missing service.)
 
 ## Usage
 
@@ -64,7 +66,7 @@ handling of feature/service-specific ones.
 ```ts
 // app/route.server.ts
 import { Data, Effect } from "effect";
-import { makeLoaderOrActionFactory } from "react-router-effect";
+import { makeEffectRouteFactory } from "react-router-effect";
 
 class FormError extends Data.TaggedError("FormError")<{ reply: SubmissionResponse }> {}
 class BadInputError extends Data.TaggedError("BadInputError")<{ message: string }> {}
@@ -78,7 +80,7 @@ type DomainErrors = FormError | BadInputError | DbError;
 // is a *builder* — it receives `Respond` (the library's `early`/`throw`/`redirect`)
 // so your handlers can recover/throw, and the factory hands back a single `Respond`
 // for your routes to import (no auto-import ambiguity with a library export).
-export const { makeLoader, makeAction, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+export const { makeLoader, makeAction, Respond } = makeEffectRouteFactory<DomainErrors>()(
   (Respond) => ({
     // App-specific helpers — merged onto the returned `Respond` (base helpers win):
     respond: {
@@ -128,6 +130,36 @@ type LoaderData = Route.ComponentProps["loaderData"];
 //   ( BadInputError throws, so it never appears here )
 ```
 
+### 3. Write middleware as effects
+
+`makeMiddleware` wraps a [middleware](https://reactrouter.com/how-to/middleware) function the
+same way, wired to the same `errorHandlers`. Pin it to the route's generated
+`Route.MiddlewareFunction` — middleware has no separate args-only type, so the whole function
+type is the type argument — or omit it to default to React Router's own `MiddlewareFunction`:
+
+```ts
+// app/routes/profile.ts
+import { Effect } from "effect";
+import { makeMiddleware, Respond } from "../route.server.ts";
+import type { Route } from "./+types/profile";
+
+export const middleware: Route.MiddlewareFunction[] = [
+  makeMiddleware<Route.MiddlewareFunction>(({ request }, next) =>
+    Effect.gen(function* () {
+      const user = yield* getUser(request); // may fail with FormError / BadInputError
+      if (!user) yield* Respond.redirect("/login"); // throw → redirect, same as a loader
+      return yield* next(); // run the rest of the chain
+    }),
+  ),
+];
+```
+
+`next` is handed to the effect as `() => Effect.Effect<Result, FailureResponse>` (React Router's
+own `next: () => Promise<Result>`, wrapped) — call it with `yield*` to run downstream
+loaders/middleware. A downstream throw (e.g. a nested loader's redirect) surfaces as a typed
+failure rather than a rejected promise, so it flows through the same recover/throw handling as
+a loader or action.
+
 ### Self-rendering domain errors
 
 If a domain error implements `HttpServerRespondable`, you don't need to register a handler —
@@ -157,7 +189,7 @@ import { ManagedRuntime } from "effect";
 export const appRuntime = ManagedRuntime.make(AppLayer); // provides Database, MyService, ...
 
 // app/route.server.ts
-export const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
+export const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
   runtime: appRuntime,
   errorHandlers: { ... },
 }));
@@ -178,8 +210,8 @@ runtime provides type-checks, while requiring one it _doesn't_ is a compile erro
 `errorHandlers` is optional too — configure a factory with just a runtime, or with nothing:
 
 ```ts
-makeLoaderOrActionFactory()(() => ({ runtime }));
-makeLoaderOrActionFactory()(() => ({}));
+makeEffectRouteFactory()(() => ({ runtime }));
+makeEffectRouteFactory()(() => ({}));
 ```
 
 ### Per-request services from middleware
@@ -214,7 +246,7 @@ export const middleware: Route.MiddlewareFunction[] = [
 ];
 
 // app/route.server.ts — wire the same key into the factory:
-export const { makeLoader } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
+export const { makeLoader } = makeEffectRouteFactory<DomainErrors>()(() => ({
   runtime: appRuntime,
   requestContext,
 }));
@@ -234,12 +266,13 @@ else is a compile error. `RequestContextKey<ReqServices>` is a type alias for
 
 ## API
 
-- **`makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond? }))`**
-  → `{ makeLoader, makeAction, Respond }` (the two makers are the same wrapper). The config is a
-  _builder_ that receives the base `Respond`; all its fields are optional. The returned `Respond` is
-  the base helpers merged with your `respond` extensions (base helpers win). 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.
+- **`makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond? }))`**
+  → `{ makeLoader, makeAction, makeMiddleware, Respond }` (`makeLoader`/`makeAction` are the same
+  wrapper; `makeMiddleware` wraps a `Route.MiddlewareFunction`, defaulting to react-router's own
+  `MiddlewareFunction`). The config is a _builder_ that receives the base `Respond`; all its fields
+  are optional. The returned `Respond` is the base helpers merged with your `respond` extensions
+  (base helpers win). A non-domain error left in a handler'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`** (returned from the factory) — `early` (recover), `throw`, `redirect`, plus any

package/dist/index.d.mts

@@ -1,9 +1,8 @@
 import { Context, Effect, ManagedRuntime } from "effect";
 import { HttpServerRespondable } from "effect/unstable/http";
-import { ActionFunctionArgs, LoaderFunctionArgs, RouterContext, UNSAFE_DataWithResponseInit } from "react-router";
-
+import { ActionFunctionArgs, LoaderFunctionArgs, MiddlewareFunction, 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 & {
+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 & {
   readonly _tag: "ReturnableRouteError";
 } & Readonly<A>;
 /** Recoverable: short-circuits the loader but returns `data(...)` the component reads. */
@@ -11,7 +10,7 @@ declare class ReturnableDataError<D> extends ReturnableDataError_base<{
   data: D;
   init?: number | ResponseInit;
 }> {}
-declare const ThrowableDataError_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 & {
+declare const ThrowableDataError_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 & {
   readonly _tag: "ThrowableRouteError";
 } & Readonly<A>;
 /** Throwable: rejects with `data(...)` → boundary as an `ErrorResponse`. */
@@ -19,7 +18,7 @@ declare class ThrowableDataError<D> extends ThrowableDataError_base<{
   data: D;
   init?: number | ResponseInit;
 }> {}
-declare const ThrowableRedirectError_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 & {
+declare const ThrowableRedirectError_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 & {
   readonly _tag: "ThrowableRedirectError";
 } & Readonly<A>;
 /** Throwable: rejects with a redirect `Response`. */
@@ -36,7 +35,7 @@ type AnyRouteError = ReturnableDataError<unknown> | ThrowableDataError<unknown>
  * extensions) so your app imports a single `Respond`:
  *
  * ```ts
- * export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+ * export const { makeLoader, Respond } = makeEffectRouteFactory<DomainErrors>()(
  *   (Respond) => ({
  *     respond: { formError: (reply) => new FormError({ reply }) },
  *     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },
@@ -45,8 +44,11 @@ type AnyRouteError = ReturnableDataError<unknown> | ThrowableDataError<unknown>
  * ```
  */
 declare const Respond: {
-  /** Recover: short-circuit and hand `value` to the component as loader/action data. */early: <D>(value: D, init?: number | ResponseInit) => ReturnableDataError<D>; /** Throw: short-circuit to the error boundary with `data(value, init)`. */
-  throw: <D>(value: D, init?: number | ResponseInit) => ThrowableDataError<D>; /** Throw: short-circuit with a redirect `Response`. */
+  /** Recover: short-circuit and hand `value` to the component as loader/action data. */
+  early: <D>(value: D, init?: number | ResponseInit) => ReturnableDataError<D>;
+  /** Throw: short-circuit to the error boundary with `data(value, init)`. */
+  throw: <D>(value: D, init?: number | ResponseInit) => ThrowableDataError<D>;
+  /** Throw: short-circuit with a redirect `Response`. */
   redirect: (url: string, init?: number | ResponseInit) => ThrowableRedirectError;
 };
 /** Narrows an unknown value to one of the library's route errors. */
@@ -83,6 +85,24 @@ type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : ne
 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>;
+/** A `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) — `(args, next) => ...`. */
+type AnyMiddlewareFunction = (...args: never[]) => unknown;
+/**
+ * The `args` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
+ * with — inferred from the type argument so `makeMiddleware` can be pinned to a specific
+ * generated route's middleware type.
+ */
+type MiddlewareArgsOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[0];
+/**
+ * The `next` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
+ * with — react-router's own `() => Promise<Result>`, not exported under its own name.
+ */
+type MiddlewareNextOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[1];
+/**
+ * The `Result` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) resolves
+ * with — i.e. what its `next()` resolves to, and what the middleware itself may return.
+ */
+type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> = MiddlewareNextOf<Middleware> extends (() => Promise<infer Result>) ? Result : never;
 /**
  * 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
@@ -97,7 +117,7 @@ type HandlerReturns<DomainError extends Tagged> = Partial<Record<DomainError["_t
  */
 type ErrorHandlers<DomainError extends Tagged, Returns> = { [Tag in keyof Returns]: (error: Extract<DomainError, {
   readonly _tag: Tag;
-}>) => Returns[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
@@ -108,22 +128,67 @@ type ErrorHandlers<DomainError extends Tagged, Returns> = { [Tag in keyof Return
  */
 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];
+}>>] 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:
+ * Errors the library deals with on the handler's behalf — so the loader/action/
+ * middleware needn't handle them itself:
  *  - the app's **declared domain errors** (`DomainError`) — handled by a registered
  *    handler, or left to the 500 / auto-respond default;
  *  - **library route errors** raised directly via `Respond`;
- *  - anything that renders itself via **`HttpServerRespondable`**.
+ *  - anything that renders itself via **`HttpServerRespondable`**;
+ *  - `AlsoHandled` — extra, call-site-specific already-handled errors. Only
+ *    `makeMiddleware` uses this, to admit the `FailureResponse` its `next()`
+ *    fails with (a downstream throw, already a finished response — the library
+ *    re-throws it as-is, so the middleware needn't catch it just to re-raise it).
+ */
+type LibraryHandled<DomainError, AlsoHandled = never> = DomainError | AnyRouteError | HttpServerRespondable.Respondable | AlsoHandled;
+/**
+ * What remains in a handler's error channel that the library will NOT handle —
+ * i.e. service-specific errors the route consumes that aren't declared domain
+ * errors. The loader/action/middleware must handle these itself (catch or map them).
+ */
+type Unhandled<E, DomainError, AlsoHandled = never> = Exclude<E, LibraryHandled<DomainError, AlsoHandled>>;
+/**
+ * A readable compile-time diagnostic. It's intersected onto the *effect return type*
+ * of `fn` — so the effect's `A`/`E`/`R` still infer directly (naked), while a mismatch
+ * reports this message, and the offending types, *at the `makeLoader`/`makeAction`
+ * call* instead of the opaque "Expected 2 arguments". Resolves to `unknown` (a no-op
+ * intersection) when the effect is fully handled and all its requirements are provided:
+ *
+ *  - **Unhandled error** — the effect can fail with something that isn't a declared
+ *    domain error, a library route error, or respondable; `unhandledErrors` names them.
+ *  - **Missing requirement** — the effect requires a service that neither the
+ *    `runtime` nor the `requestContext` provides; `missingRequirements` names them.
+ *
+ * The message lives in an *inline* object literal (no named alias) so tsc/tsgo print
+ * its text verbatim rather than collapsing it to an alias name.
+ */
+/**
+ * Names the unhandled errors for the diagnostic: a tagged error becomes its `_tag`
+ * (the string you'd pass to `Effect.catchTag`), anything untagged stays as its type.
  */
-type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespondable.Respondable;
+type NameError<U> = U extends {
+  readonly _tag: infer Tag extends string;
+} ? Tag : U;
 /**
- * What remains in a loader/action's error channel that the library will NOT handle
- * — i.e. service-specific errors the route consumes that aren't declared domain
- * errors. The loader/action must handle these itself (catch or map them).
+ * True exactly when `T` is (or, for a union, includes) `any` — not `unknown`, not
+ * `never`, not any other type. An unrelated mistake elsewhere in the effect (a typo,
+ * a call with the wrong number of arguments, a genuine syntax error) commonly makes
+ * TypeScript infer `any` for `E`/`R` instead of reporting a clean type; running
+ * `Diagnose` on that `any` produces a confusing "unhandled errors: any" message that
+ * buries the real mistake. Guarding on this and bailing to `unknown` lets tsc's own,
+ * on-site error surface instead. (`1 & T` is `any` when `T` is `any` — including when
+ * `any` only appears as a union member, since intersection distributes over unions —
+ * and `0` is assignable to `any` but not to any concrete type built from `1 & T`.)
  */
-type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> = IsAny<E> extends true ? unknown : IsAny<R> extends true ? unknown : [Unhandled<E, DomainError, AlsoHandled>] extends [never] ? [Exclude<R, Provided>] extends [never] ? unknown : {
+  "react-router-effect": "This loader/action requires a service the factory does not provide. Add it to your runtime or requestContext, or handle it in the effect.";
+  missingRequirements: Exclude<R, Provided>;
+} : {
+  "react-router-effect": "This loader/action can fail with an error the library does not handle. Catch it in the effect (e.g. Effect.catchTag), make it Respondable, or add it to your DomainError union.";
+  unhandledErrors: NameError<Unhandled<E, DomainError, AlsoHandled>>;
+};
 /**
  * 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
@@ -153,7 +218,8 @@ type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
  */
 type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
 /**
- * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+ * Build `makeLoader` / `makeAction` / `makeMiddleware` 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`. The handler keys
@@ -165,7 +231,7 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
  * export const { makeLoader, makeAction, Respond } =
- *   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+ *   makeEffectRouteFactory<DomainErrors>()((Respond) => ({
  *     errorHandlers: {
  *       // `error` is typed as MyDomainError automatically. throw → error boundary
  *       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
@@ -195,7 +261,7 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * services directly — no per-call `Effect.provide`:
  *
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
+ * const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
  *   runtime: getAppRuntime(), // provides Database, MyService, ...
  *   errorHandlers: { ... },
  * }));
@@ -208,8 +274,27 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  *   }),
  * );
  * ```
+ *
+ * `makeMiddleware` wraps a `Route.MiddlewareFunction` the same way: write it as an
+ * effect, and register the same domain errors/handlers. Pin it to the route's
+ * generated `Route.MiddlewareFunction` (a type argument, since middleware has no
+ * separate args-only type) to type `args` and `next`'s result from that route; it
+ * defaults to React Router's own `MiddlewareFunction`. The `next` handed to the
+ * effect is `() => Effect.Effect<Result, FailureResponse>` — call it with `yield*`
+ * to run the rest of the chain, and a downstream throw (e.g. a nested loader's
+ * redirect) surfaces as a typed failure instead of a rejected promise:
+ *
+ * ```ts
+ * const middleware = makeMiddleware<Route.MiddlewareFunction>((args, next) =>
+ *   Effect.gen(function* () {
+ *     const user = yield* getUser(args); // may fail with a declared domain error
+ *     if (!user) yield* Respond.redirect("/login");
+ *     return yield* next();
+ *   }),
+ * );
+ * ```
  */
-declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Returns extends HandlerReturns<DomainError> = {}, RServices = never, ReqServices = never, const ExtraRespond extends Record<string, (...args: never[]) => unknown> = {}>(builder: (respond: BaseRespond) => {
+declare function makeEffectRouteFactory<DomainError extends Tagged = never>(): <const Returns extends HandlerReturns<DomainError> = {}, RServices = never, ReqServices = never, const ExtraRespond extends Record<string, (...args: never[]) => unknown> = {}>(builder: (respond: BaseRespond) => {
   /**
    * 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
@@ -242,8 +327,9 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    */
   respond?: ExtraRespond;
 }) => {
-  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>>;
+  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E, R>(fn: (args: Args) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>) => (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>>;
+  makeAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E, R>(fn: (args: Args) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>) => (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>>;
+  makeMiddleware: <Middleware extends MiddlewareFunction<any> = MiddlewareFunction, A = MiddlewareResultOf<Middleware>, E = never, R = never>(fn: (args: MiddlewareArgsOf<Middleware>, next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices, FailureResponse>) => (args: MiddlewareArgsOf<Middleware>, next: MiddlewareNextOf<Middleware>) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>>;
   Respond: {
     early: <D>(value: D, init?: number | ResponseInit) => ReturnableDataError<D>;
     throw: <D>(value: D, init?: number | ResponseInit) => ThrowableDataError<D>;
@@ -251,4 +337,4 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
   } & ExtraRespond;
 };
 //#endregion
-export { type AnyRouteError, type ErrorHandler, type RequestContextKey, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };
+export { type AnyRouteError, type ErrorHandler, type RequestContextKey, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeEffectRouteFactory };

package/dist/index.mjs

@@ -15,7 +15,7 @@ var ThrowableRedirectError = class extends Data.TaggedError("ThrowableRedirectEr
 * extensions) so your app imports a single `Respond`:
 *
 * ```ts
-* export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+* export const { makeLoader, Respond } = makeEffectRouteFactory<DomainErrors>()(
 *   (Respond) => ({
 *     respond: { formError: (reply) => new FormError({ reply }) },
 *     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },
@@ -45,6 +45,12 @@ const isRouteError = (value) => value instanceof ReturnableDataError || value in
 //#endregion
 //#region src/factory.ts
 const internalServerError = () => Effect.fail(new Response("Internal Server Error", { status: 500 }));
+/**
+* A raw `FailureResponse` — a downstream `next()`'s rejection, in `makeMiddleware` —
+* is already a finished response; re-throwing it as-is (rather than 500ing it) lets
+* a nested loader's redirect/thrown response pass back up through the middleware chain.
+*/
+const isFailureResponse = (e) => e instanceof Response || typeof e === "object" && e !== null && "type" in e && e.type === "DataWithResponseInit";
 /** The internal dispatch for a library route error: recover, throw, or redirect. */
 const processRouteError = (e) => {
 	if (e instanceof ReturnableDataError) return Effect.succeed(data(e.data, e.init));
@@ -52,7 +58,8 @@ const processRouteError = (e) => {
 	return Effect.fail(redirect(e.url, e.init));
 };
 /**
-* Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+* Build `makeLoader` / `makeAction` / `makeMiddleware` 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`. The handler keys
@@ -64,7 +71,7 @@ const processRouteError = (e) => {
 * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
 *
 * export const { makeLoader, makeAction, Respond } =
-*   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+*   makeEffectRouteFactory<DomainErrors>()((Respond) => ({
 *     errorHandlers: {
 *       // `error` is typed as MyDomainError automatically. throw → error boundary
 *       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
@@ -94,7 +101,7 @@ const processRouteError = (e) => {
 * services directly — no per-call `Effect.provide`:
 *
 * ```ts
-* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
+* const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
 *   runtime: getAppRuntime(), // provides Database, MyService, ...
 *   errorHandlers: { ... },
 * }));
@@ -107,8 +114,27 @@ const processRouteError = (e) => {
 *   }),
 * );
 * ```
+*
+* `makeMiddleware` wraps a `Route.MiddlewareFunction` the same way: write it as an
+* effect, and register the same domain errors/handlers. Pin it to the route's
+* generated `Route.MiddlewareFunction` (a type argument, since middleware has no
+* separate args-only type) to type `args` and `next`'s result from that route; it
+* defaults to React Router's own `MiddlewareFunction`. The `next` handed to the
+* effect is `() => Effect.Effect<Result, FailureResponse>` — call it with `yield*`
+* to run the rest of the chain, and a downstream throw (e.g. a nested loader's
+* redirect) surfaces as a typed failure instead of a rejected promise:
+*
+* ```ts
+* const middleware = makeMiddleware<Route.MiddlewareFunction>((args, next) =>
+*   Effect.gen(function* () {
+*     const user = yield* getUser(args); // may fail with a declared domain error
+*     if (!user) yield* Respond.redirect("/login");
+*     return yield* next();
+*   }),
+* );
+* ```
 */
-function makeLoaderOrActionFactory() {
+function makeEffectRouteFactory() {
 	return function defineErrorHandlers(builder) {
 		const config = builder(Respond);
 		const runtime = config.runtime;
@@ -119,27 +145,48 @@ function makeLoaderOrActionFactory() {
 		};
 		const userHandlers = config.errorHandlers ?? {};
 		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in userHandlers;
-		function makeLoaderOrAction(fn, ..._handle) {
-			return (args) => {
-				const program = fn(args).pipe(Effect.catchIf((_e) => true, (e) => {
-					if (isUserError(e)) {
-						const out = userHandlers[e._tag](e);
-						return isRouteError(out) ? processRouteError(out) : out;
-					}
-					if (isRouteError(e)) return processRouteError(e);
-					if (HttpServerRespondable.isRespondable(e)) return HttpServerRespondable.toResponse(e).pipe(Effect.flatMap((res) => Effect.fail(HttpServerResponse.toWeb(res))));
-					return internalServerError();
-				}));
-				const provided = requestContextKey ? Effect.provideContext(program, args.context.get(requestContextKey)) : program;
-				return runtime ? runtime.runPromise(provided) : Effect.runPromise(provided);
+		/**
+		* Runs a handler's effect to completion: dispatches its whole error channel
+		* (registered domain errors, library route errors, respondables, or the 500
+		* default), provides the per-request context, and executes against the
+		* configured runtime. Shared by `makeLoader`/`makeAction` and `makeMiddleware`
+		* — they differ only in how they build the effect and what `context` they read.
+		*/
+		function runProgram(effect, context) {
+			const program = effect.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))));
+				if (isFailureResponse(e)) return Effect.fail(e);
+				return internalServerError();
+			}));
+			const provided = requestContextKey ? Effect.provideContext(program, context.get(requestContextKey)) : program;
+			return runtime ? runtime.runPromise(provided) : Effect.runPromise(provided);
+		}
+		function makeLoaderOrAction(fn) {
+			const run = fn;
+			return (args) => runProgram(run(args), args.context);
+		}
+		function makeMiddleware(fn) {
+			const run = fn;
+			return (args, next) => {
+				const effectNext = () => Effect.tryPromise({
+					try: next,
+					catch: (e) => e
+				});
+				return runProgram(run(args, effectNext), args.context);
 			};
 		}
 		return {
 			makeLoader: makeLoaderOrAction,
 			makeAction: makeLoaderOrAction,
+			makeMiddleware,
 			Respond: Respond$1
 		};
 	};
 }
 //#endregion
-export { ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };
+export { ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeEffectRouteFactory };

package/package.json

@@ -1,13 +1,14 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "0.6.0",
-  "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
+  "version": "1.0.0",
+  "description": "Wrap React Router framework-mode route modules with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",
     "effect",
     "error-handling",
     "loader",
+    "middleware",
     "react-router",
     "typescript"
   ],
@@ -36,27 +37,26 @@
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.0",
+    "@changesets/cli": "^2.31.1",
     "@types/node": "^25.6.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "7.0.0-dev.20260509.2",
-    "@vitejs/plugin-react": "^6.0.1",
-    "@vitest/browser": "4.1.9",
-    "@vitest/browser-playwright": "4.1.9",
-    "effect": "4.0.0-beta.88",
+    "@vitejs/plugin-react": "^6.0.4",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "4.1.10",
+    "effect": "4.0.0-beta.101",
     "playwright": "1.60.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "react-router": "^8.0.0",
-    "typescript": "^6.0.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-router": "^8.3.0",
+    "typescript": "^7.0.2",
     "vite-plus": "latest",
     "vitest": "4.1.9",
     "vitest-browser-react": "^2.2.0"
   },
   "peerDependencies": {
-    "effect": "^4.0.0-beta.88",
-    "react-router": "^7.16.0 || ^8.0.0"
+    "effect": "^4.0.0-beta.101",
+    "react-router": "^7.16.0 || ^8.3.0"
   },
   "devEngines": {
     "packageManager": {

package/src/errors.ts

@@ -35,7 +35,7 @@ export type AnyRouteError =
  * extensions) so your app imports a single `Respond`:
  *
  * ```ts
- * export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+ * export const { makeLoader, Respond } = makeEffectRouteFactory<DomainErrors>()(
  *   (Respond) => ({
  *     respond: { formError: (reply) => new FormError({ reply }) },
  *     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },

package/src/factory.ts

@@ -6,7 +6,9 @@ import {
   type ActionFunctionArgs,
   type UNSAFE_DataWithResponseInit as DataWithResponseInit,
   type LoaderFunctionArgs,
+  type MiddlewareFunction,
   type RouterContext,
+  type RouterContextProvider,
 } from "react-router";
 
 import {
@@ -60,6 +62,29 @@ type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
 /** What a handler may return: a library route error or an `Effect` failing with a response. */
 type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
 
+/** A `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) — `(args, next) => ...`. */
+type AnyMiddlewareFunction = (...args: never[]) => unknown;
+
+/**
+ * The `args` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
+ * with — inferred from the type argument so `makeMiddleware` can be pinned to a specific
+ * generated route's middleware type.
+ */
+type MiddlewareArgsOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[0];
+
+/**
+ * The `next` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) is called
+ * with — react-router's own `() => Promise<Result>`, not exported under its own name.
+ */
+type MiddlewareNextOf<Middleware extends AnyMiddlewareFunction> = Parameters<Middleware>[1];
+
+/**
+ * The `Result` a `Route.MiddlewareFunction` (or the base `MiddlewareFunction`) resolves
+ * with — i.e. what its `next()` resolves to, and what the middleware itself may return.
+ */
+type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> =
+  MiddlewareNextOf<Middleware> extends () => Promise<infer Result> ? Result : never;
+
 /**
  * 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
@@ -96,21 +121,87 @@ type RecoverOf<DomainError extends Tagged, Returns, E> = {
 }[keyof Returns];
 
 /**
- * Errors the library deals with on the loader's behalf — so the loader needn't
- * handle them itself:
+ * Errors the library deals with on the handler's behalf — so the loader/action/
+ * middleware needn't handle them itself:
  *  - the app's **declared domain errors** (`DomainError`) — handled by a registered
  *    handler, or left to the 500 / auto-respond default;
  *  - **library route errors** raised directly via `Respond`;
- *  - anything that renders itself via **`HttpServerRespondable`**.
+ *  - anything that renders itself via **`HttpServerRespondable`**;
+ *  - `AlsoHandled` — extra, call-site-specific already-handled errors. Only
+ *    `makeMiddleware` uses this, to admit the `FailureResponse` its `next()`
+ *    fails with (a downstream throw, already a finished response — the library
+ *    re-throws it as-is, so the middleware needn't catch it just to re-raise it).
  */
-type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespondable.Respondable;
+type LibraryHandled<DomainError, AlsoHandled = never> =
+  | DomainError
+  | AnyRouteError
+  | HttpServerRespondable.Respondable
+  | AlsoHandled;
 
 /**
- * What remains in a loader/action's error channel that the library will NOT handle
- * — i.e. service-specific errors the route consumes that aren't declared domain
- * errors. The loader/action must handle these itself (catch or map them).
+ * What remains in a handler's error channel that the library will NOT handle —
+ * i.e. service-specific errors the route consumes that aren't declared domain
+ * errors. The loader/action/middleware must handle these itself (catch or map them).
  */
-type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
+type Unhandled<E, DomainError, AlsoHandled = never> = Exclude<
+  E,
+  LibraryHandled<DomainError, AlsoHandled>
+>;
+
+// ---------------------------------------------------------------------------
+// The call-site diagnostic.
+// ---------------------------------------------------------------------------
+
+/**
+ * A readable compile-time diagnostic. It's intersected onto the *effect return type*
+ * of `fn` — so the effect's `A`/`E`/`R` still infer directly (naked), while a mismatch
+ * reports this message, and the offending types, *at the `makeLoader`/`makeAction`
+ * call* instead of the opaque "Expected 2 arguments". Resolves to `unknown` (a no-op
+ * intersection) when the effect is fully handled and all its requirements are provided:
+ *
+ *  - **Unhandled error** — the effect can fail with something that isn't a declared
+ *    domain error, a library route error, or respondable; `unhandledErrors` names them.
+ *  - **Missing requirement** — the effect requires a service that neither the
+ *    `runtime` nor the `requestContext` provides; `missingRequirements` names them.
+ *
+ * The message lives in an *inline* object literal (no named alias) so tsc/tsgo print
+ * its text verbatim rather than collapsing it to an alias name.
+ */
+/**
+ * Names the unhandled errors for the diagnostic: a tagged error becomes its `_tag`
+ * (the string you'd pass to `Effect.catchTag`), anything untagged stays as its type.
+ */
+type NameError<U> = U extends { readonly _tag: infer Tag extends string } ? Tag : U;
+
+/**
+ * True exactly when `T` is (or, for a union, includes) `any` — not `unknown`, not
+ * `never`, not any other type. An unrelated mistake elsewhere in the effect (a typo,
+ * a call with the wrong number of arguments, a genuine syntax error) commonly makes
+ * TypeScript infer `any` for `E`/`R` instead of reporting a clean type; running
+ * `Diagnose` on that `any` produces a confusing "unhandled errors: any" message that
+ * buries the real mistake. Guarding on this and bailing to `unknown` lets tsc's own,
+ * on-site error surface instead. (`1 & T` is `any` when `T` is `any` — including when
+ * `any` only appears as a union member, since intersection distributes over unions —
+ * and `0` is assignable to `any` but not to any concrete type built from `1 & T`.)
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> =
+  IsAny<E> extends true
+    ? unknown
+    : IsAny<R> extends true
+      ? unknown
+      : [Unhandled<E, DomainError, AlsoHandled>] extends [never]
+        ? [Exclude<R, Provided>] extends [never]
+          ? unknown
+          : {
+              "react-router-effect": "This loader/action requires a service the factory does not provide. Add it to your runtime or requestContext, or handle it in the effect.";
+              missingRequirements: Exclude<R, Provided>;
+            }
+        : {
+            "react-router-effect": "This loader/action can fail with an error the library does not handle. Catch it in the effect (e.g. Effect.catchTag), make it Respondable, or add it to your DomainError union.";
+            unhandledErrors: NameError<Unhandled<E, DomainError, AlsoHandled>>;
+          };
 
 // ---------------------------------------------------------------------------
 // Internal runtime helpers.
@@ -119,6 +210,18 @@ type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
 const internalServerError = () =>
   Effect.fail<FailureResponse>(new Response("Internal Server Error", { status: 500 }));
 
+/**
+ * A raw `FailureResponse` — a downstream `next()`'s rejection, in `makeMiddleware` —
+ * is already a finished response; re-throwing it as-is (rather than 500ing it) lets
+ * a nested loader's redirect/thrown response pass back up through the middleware chain.
+ */
+const isFailureResponse = (e: unknown): e is FailureResponse =>
+  e instanceof Response ||
+  (typeof e === "object" &&
+    e !== null &&
+    "type" in e &&
+    (e as { type?: unknown }).type === "DataWithResponseInit");
+
 /** The internal dispatch for a library route error: recover, throw, or redirect. */
 const processRouteError = (
   e: AnyRouteError,
@@ -166,7 +269,8 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
 // ---------------------------------------------------------------------------
 
 /**
- * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+ * Build `makeLoader` / `makeAction` / `makeMiddleware` 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`. The handler keys
@@ -178,7 +282,7 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
  * export const { makeLoader, makeAction, Respond } =
- *   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+ *   makeEffectRouteFactory<DomainErrors>()((Respond) => ({
  *     errorHandlers: {
  *       // `error` is typed as MyDomainError automatically. throw → error boundary
  *       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
@@ -208,7 +312,7 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * services directly — no per-call `Effect.provide`:
  *
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
+ * const { makeLoader, makeAction } = makeEffectRouteFactory<DomainErrors>()(() => ({
  *   runtime: getAppRuntime(), // provides Database, MyService, ...
  *   errorHandlers: { ... },
  * }));
@@ -221,8 +325,27 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  *   }),
  * );
  * ```
+ *
+ * `makeMiddleware` wraps a `Route.MiddlewareFunction` the same way: write it as an
+ * effect, and register the same domain errors/handlers. Pin it to the route's
+ * generated `Route.MiddlewareFunction` (a type argument, since middleware has no
+ * separate args-only type) to type `args` and `next`'s result from that route; it
+ * defaults to React Router's own `MiddlewareFunction`. The `next` handed to the
+ * effect is `() => Effect.Effect<Result, FailureResponse>` — call it with `yield*`
+ * to run the rest of the chain, and a downstream throw (e.g. a nested loader's
+ * redirect) surfaces as a typed failure instead of a rejected promise:
+ *
+ * ```ts
+ * const middleware = makeMiddleware<Route.MiddlewareFunction>((args, next) =>
+ *   Effect.gen(function* () {
+ *     const user = yield* getUser(args); // may fail with a declared domain error
+ *     if (!user) yield* Respond.redirect("/login");
+ *     return yield* next();
+ *   }),
+ * );
+ * ```
  */
-export function makeLoaderOrActionFactory<DomainError extends Tagged = never>() {
+export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
   return function defineErrorHandlers<
     const Returns extends HandlerReturns<DomainError> = {},
     RServices = never,
@@ -285,78 +408,124 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
     const isUserError = (e: unknown): e is DomainError =>
       typeof e === "object" && e !== null && "_tag" in e && (e as Tagged)._tag in userHandlers;
 
-    function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(
-      // The effect may require `RServices` (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
-      // fails to type-check, forcing the loader/action to handle it.
-      ..._handle: [Unhandled<E, DomainError>] extends [never]
-        ? []
-        : [
-            theseErrorsAreNotDomainErrorsAndMustBeHandledInTheLoaderOrAction: Unhandled<
-              E,
-              DomainError
-            >,
-          ]
+    /**
+     * Runs a handler's effect to completion: dispatches its whole error channel
+     * (registered domain errors, library route errors, respondables, or the 500
+     * default), provides the per-request context, and executes against the
+     * configured runtime. Shared by `makeLoader`/`makeAction` and `makeMiddleware`
+     * — they differ only in how they build the effect and what `context` they read.
+     */
+    function runProgram<E>(
+      effect: Effect.Effect<unknown, E, RServices | ReqServices>,
+      context: Readonly<RouterContextProvider>,
+    ): Promise<unknown> {
+      // The internal channel is deliberately loose (`unknown` success); the caller
+      // restores the precise resolved type (computed from `E` and the handler map).
+      // Sound at runtime — the values produced are exactly those types.
+      const program = effect.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 handler → 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)),
+                ),
+              );
+            }
+            // Already a finished response (e.g. a downstream `next()` rejection in
+            // `makeMiddleware`) → re-throw as-is, rather than 500ing it.
+            if (isFailureResponse(e)) return Effect.fail(e);
+            return internalServerError();
+          },
+        ),
+      );
+      // 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, 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.
+      return runtime
+        ? runtime.runPromise(provided)
+        : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>);
+    }
+
+    function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E, R>(
+      // `A`/`E`/`R` infer directly from the effect (naked, so inference stays robust).
+      // The diagnostic is intersected onto the effect's return type: when the effect
+      // requires a service the factory doesn't provide (`R` ⊄ runtime+requestContext),
+      // or can fail with something the library won't handle, `Diagnose` becomes a
+      // message object the effect isn't assignable to — so this argument fails to
+      // type-check with a readable explanation, and the offending types, right here.
+      fn: (
+        args: Args,
+      ) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>,
     ): (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
-        // map). Sound at runtime — the values produced are exactly those types.
-        const program = fn(args).pipe(
-          // Catch the whole error channel and dispatch. The refinement is `e is E`
-          // (provably ⊆ E, and a *refinement* not a bare predicate — the predicate
-          // overload crashes tsc over a generic `E`). 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();
-            },
-          ),
-        );
-        // 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<DomainError, Returns, E>>;
+      // The diagnostic is irrelevant inside the body (it's `unknown` for any valid
+      // call); treat `fn` as the plain effect-returning function it is.
+      const run = fn as unknown as (
+        args: Args,
+      ) => Effect.Effect<unknown, E, RServices | ReqServices>;
+      return (args: Args) =>
+        runProgram(run(args), args.context) as Promise<
+          A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>
+        >;
+    }
+
+    function makeMiddleware<
+      Middleware extends MiddlewareFunction<any> = MiddlewareFunction,
+      A = MiddlewareResultOf<Middleware>,
+      E = never,
+      R = never,
+    >(
+      // Same shape as `makeLoaderOrAction`'s `fn`, but middleware also receives
+      // `next` — wrapped as an effect (rather than react-router's raw
+      // `() => Promise<Result>`) so downstream failures (e.g. a nested loader's
+      // redirect) surface as a typed `FailureResponse`, consistent with the rest
+      // of the library's error model.
+      fn: (
+        args: MiddlewareArgsOf<Middleware>,
+        next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>,
+      ) => Effect.Effect<A, E, R> &
+        Diagnose<E, R, DomainError, RServices | ReqServices, FailureResponse>,
+    ): (
+      args: MiddlewareArgsOf<Middleware>,
+      next: MiddlewareNextOf<Middleware>,
+    ) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>> {
+      const run = fn as unknown as (
+        args: MiddlewareArgsOf<Middleware>,
+        next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>,
+      ) => Effect.Effect<unknown, E, RServices | ReqServices>;
+      return (args, next) => {
+        const effectNext = () =>
+          Effect.tryPromise({ try: next, catch: (e) => e as FailureResponse });
+        return runProgram(run(args, effectNext), args.context) as Promise<
+          A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>
+        >;
       };
     }
 
     return {
       makeLoader: makeLoaderOrAction,
       makeAction: makeLoaderOrAction,
+      makeMiddleware,
       Respond,
     };
   };

package/src/index.ts

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