react-router-effect 0.6.1 → 1.0.1

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.
 
@@ -66,7 +66,7 @@ type-check with a message naming the missing service.)
 ```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 }> {}
@@ -80,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: {
@@ -130,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 —
@@ -159,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: { ... },
 }));
@@ -180,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
@@ -216,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,
 }));
@@ -236,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,26 @@ 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.
+ * Read through `Awaited` because react-router declares `next` as an *interface* with a
+ * call signature (`MiddlewareNextFunction`), and a route's own may resolve synchronously.
+ */
+type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> = MiddlewareNextOf<Middleware> extends ((...args: never[]) => infer Result) ? Awaited<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 +119,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 +130,26 @@ 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> = 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>>;
 /**
  * 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
@@ -146,12 +172,24 @@ type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
 type NameError<U> = U extends {
   readonly _tag: infer Tag extends string;
 } ? Tag : U;
-type Diagnose<E, R, DomainError, Provided> = [Unhandled<E, DomainError>] 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.";
+/**
+ * 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/middleware 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>>;
+  "react-router-effect": "This loader/action/middleware 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
@@ -182,7 +220,8 @@ type Diagnose<E, R, DomainError, Provided> = [Unhandled<E, DomainError>] extends
  */
 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
@@ -194,7 +233,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),
@@ -224,7 +263,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: { ... },
  * }));
@@ -237,8 +276,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
@@ -271,8 +329,9 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    */
   respond?: ExtraRespond;
 }) => {
-  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 | RecoverOf<DomainError, Returns, E> | DirectRecover<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 | 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 AnyMiddlewareFunction = MiddlewareFunction, E = LibraryHandled<DomainError, FailureResponse>, R = RServices | ReqServices>(fn: (args: MiddlewareArgsOf<Middleware>, next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>) => Effect.Effect<MiddlewareResultOf<Middleware> | void, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices, FailureResponse>) => (args: MiddlewareArgsOf<Middleware>, next: MiddlewareNextOf<Middleware>) => Promise<MiddlewareResultOf<Middleware> | undefined>;
   Respond: {
     early: <D>(value: D, init?: number | ResponseInit) => ReturnableDataError<D>;
     throw: <D>(value: D, init?: number | ResponseInit) => ThrowableDataError<D>;
@@ -280,4 +339,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,28 +145,66 @@ function makeLoaderOrActionFactory() {
 		};
 		const userHandlers = config.errorHandlers ?? {};
 		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in userHandlers;
+		/**
+		* 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) => {
-				const program = run(args).pipe(Effect.catchIf((_e) => true, (e) => {
-					if (isUserError(e)) {
-						const out = userHandlers[e._tag](e);
-						return isRouteError(out) ? processRouteError(out) : out;
-					}
-					if (isRouteError(e)) return processRouteError(e);
-					if (HttpServerRespondable.isRespondable(e)) return HttpServerRespondable.toResponse(e).pipe(Effect.flatMap((res) => Effect.fail(HttpServerResponse.toWeb(res))));
-					return internalServerError();
-				}));
-				const provided = requestContextKey ? Effect.provideContext(program, args.context.get(requestContextKey)) : program;
-				return runtime ? runtime.runPromise(provided) : Effect.runPromise(provided);
+			return (args) => runProgram(run(args), args.context);
+		}
+		/**
+		* Wraps a middleware function written as an effect. Pin it to the route's generated
+		* `Route.MiddlewareFunction` (a type argument, since middleware has no separate
+		* args-only type) to type `args`, `next` and the result from that route; it defaults
+		* to React Router's own `MiddlewareFunction`.
+		*
+		* The errors the library deals with for a loader/action it deals with here too —
+		* declared domain errors, library route errors and respondables — plus the
+		* `FailureResponse` `next()` fails with. Anything else must be handled in the effect,
+		* as must any service neither the `runtime` nor the `requestContext` provides.
+		*
+		* The wrapper is typed as the route's own middleware — `(args, next) =>
+		* Promise<Result | undefined>` — so it drops straight into a
+		* `Route.MiddlewareFunction[]`. A handler that recovers (`Respond.early`) resolves
+		* with `data(...)`, which react-router's server middleware pipeline turns into the
+		* short-circuit `Response`.
+		*/
+		function makeMiddleware(fn) {
+			const run = fn;
+			return (args, next) => {
+				const effectNext = () => Effect.tryPromise({
+					try: next,
+					catch: (e) => e
+				});
+				const { context } = args;
+				return runProgram(run(args, effectNext), 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.1",
-  "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
+  "version": "1.0.1",
+  "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.102",
     "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": "4.1.10",
     "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,31 @@ 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.
+ * Read through `Awaited` because react-router declares `next` as an *interface* with a
+ * call signature (`MiddlewareNextFunction`), and a route's own may resolve synchronously.
+ */
+type MiddlewareResultOf<Middleware extends AnyMiddlewareFunction> =
+  MiddlewareNextOf<Middleware> extends (...args: never[]) => infer Result ? Awaited<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 +123,32 @@ 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.
@@ -137,17 +175,35 @@ type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
  */
 type NameError<U> = U extends { readonly _tag: infer Tag extends string } ? Tag : U;
 
-type Diagnose<E, R, DomainError, Provided> = [Unhandled<E, DomainError>] extends [never]
-  ? [Exclude<R, Provided>] extends [never]
+/**
+ * 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
-    : {
-        "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>>;
-    };
+    : IsAny<R> extends true
+      ? unknown
+      : [Unhandled<E, DomainError, AlsoHandled>] extends [never]
+        ? [Exclude<R, Provided>] extends [never]
+          ? unknown
+          : {
+              "react-router-effect": "This loader/action/middleware 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/middleware 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.
@@ -156,6 +212,18 @@ type Diagnose<E, R, DomainError, Provided> = [Unhandled<E, DomainError>] extends
 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,
@@ -203,7 +271,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
@@ -215,7 +284,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),
@@ -245,7 +314,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: { ... },
  * }));
@@ -258,8 +327,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,
@@ -322,6 +410,65 @@ 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;
 
+    /**
+     * 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
@@ -338,59 +485,78 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
       const run = fn as unknown as (
         args: Args,
       ) => Effect.Effect<unknown, E, RServices | ReqServices>;
-      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 = run(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>>;
+      return (args: Args) =>
+        runProgram(run(args), args.context) as Promise<
+          A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>
+        >;
+    }
+
+    /**
+     * Wraps a middleware function written as an effect. Pin it to the route's generated
+     * `Route.MiddlewareFunction` (a type argument, since middleware has no separate
+     * args-only type) to type `args`, `next` and the result from that route; it defaults
+     * to React Router's own `MiddlewareFunction`.
+     *
+     * The errors the library deals with for a loader/action it deals with here too —
+     * declared domain errors, library route errors and respondables — plus the
+     * `FailureResponse` `next()` fails with. Anything else must be handled in the effect,
+     * as must any service neither the `runtime` nor the `requestContext` provides.
+     *
+     * The wrapper is typed as the route's own middleware — `(args, next) =>
+     * Promise<Result | undefined>` — so it drops straight into a
+     * `Route.MiddlewareFunction[]`. A handler that recovers (`Respond.early`) resolves
+     * with `data(...)`, which react-router's server middleware pipeline turns into the
+     * short-circuit `Response`.
+     */
+    function makeMiddleware<
+      Middleware extends AnyMiddlewareFunction = MiddlewareFunction,
+      // A pinned call passes an explicit type argument, which makes the whole call
+      // explicit — TypeScript has no partial inference — so these defaults stand in
+      // for what would otherwise be inferred: exactly the errors the library handles
+      // and the services the factory provides.
+      E = LibraryHandled<DomainError, FailureResponse>,
+      R = RServices | ReqServices,
+    >(
+      // 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. The success type is fixed to the route's own
+      // `Result` (plus `void`), which is what react-router accepts back.
+      fn: (
+        args: MiddlewareArgsOf<Middleware>,
+        next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>,
+      ) => Effect.Effect<MiddlewareResultOf<Middleware> | void, E, R> &
+        Diagnose<E, R, DomainError, RServices | ReqServices, FailureResponse>,
+    ): (
+      args: MiddlewareArgsOf<Middleware>,
+      next: MiddlewareNextOf<Middleware>,
+    ) => Promise<MiddlewareResultOf<Middleware> | undefined> {
+      // Inside the body the route's own arg/result types are opaque (they're
+      // `Parameters<Middleware>[...]` of an unresolved type parameter), so dispatch
+      // through the loose shape — as `makeLoaderOrAction` does with its diagnostic.
+      // Sound at runtime: the values produced are exactly the declared types.
+      const run = fn as unknown as (
+        args: MiddlewareArgsOf<Middleware>,
+        next: () => Effect.Effect<unknown, FailureResponse>,
+      ) => Effect.Effect<unknown, E, RServices | ReqServices>;
+      return (args, next) => {
+        const effectNext = () =>
+          Effect.tryPromise({
+            try: next as unknown as () => Promise<unknown>,
+            catch: (e) => e as FailureResponse,
+          });
+        const { context } = args as unknown as { context: Readonly<RouterContextProvider> };
+        return runProgram(run(args, effectNext), context) as Promise<
+          MiddlewareResultOf<Middleware> | undefined
+        >;
       };
     }
 
     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";