react-router-effect 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# react-router-effect
+
+Wrap [React Router](https://reactrouter.com) framework-mode loaders and actions 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
+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.
+
+```ts
+const loader = makeLoader((args: Route.LoaderArgs) =>
+  Effect.gen(function* () {
+    const user = yield* getUser(args); // may fail with your domain errors
+    if (!user.onboarded) {
+      yield* Respond.redirect("/onboarding"); // throw → redirect
+    }
+    return { user };
+  }),
+);
+// loader: (args) => Promise<{ user: User } /* | recovered shapes */>
+```
+
+## Install
+
+```bash
+vp add react-router-effect effect react-router
+```
+
+`effect` and `react-router` are peer dependencies.
+
+## Concepts
+
+A loader/action effect can short-circuit in three ways, via the `Respond` helpers:
+
+| Helper                         | Outcome     | Where it lands                                      |
+| ------------------------------ | ----------- | --------------------------------------------------- |
+| `Respond.early(value, init?)`  | **recover** | resolves with `data(value, init)` → `useLoaderData` |
+| `Respond.throw(value, init?)`  | **throw**   | rejects with `data(value, init)` → error boundary   |
+| `Respond.redirect(url, init?)` | **throw**   | rejects with a redirect `Response`                  |
+
+Your own **domain errors** are mapped to one of those outcomes by handlers you register with
+the factory. A handler _remaps_ an error by returning either:
+
+- a library route error — `Respond.early(...)` / `Respond.throw(...)` / `Respond.redirect(...)`; or
+- an `Effect` — `Effect.succeed(value)` to **recover** with `value`, or `Effect.fail(response)`
+  to **throw** a `Response` / `DataWithResponseInit`.
+
+Handling is **optional**:
+
+- An **unregistered** error that implements [`HttpServerRespondable`](https://effect.website)
+  is rendered automatically from its own response.
+- Any other unregistered error falls through to a **500**.
+
+## Usage
+
+### 1. Configure the factory once
+
+```ts
+// app/route.server.ts
+import { Data, Effect } from "effect";
+import { makeLoaderOrActionFactory, Respond as baseRespond } from "react-router-effect";
+
+class FormError extends Data.TaggedError("FormError")<{ reply: SubmissionResponse }> {}
+class BadInputError extends Data.TaggedError("BadInputError")<{ message: string }> {}
+
+export const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+  errorHandlers: {
+    // recover: short-circuit and hand the reply to the component
+    FormError: (error: FormError) => baseRespond.early({ reply: error.reply }),
+    // throw: send to the error boundary
+    BadInputError: (error: BadInputError) =>
+      Effect.fail(new Response(error.message, { status: 400 })),
+  },
+});
+
+// Extend Respond with app-specific helpers if you like:
+export const Respond = {
+  ...baseRespond,
+  formError: (reply: SubmissionResponse) => new FormError({ reply }),
+};
+```
+
+> **Annotate each handler's parameter.** The registered error set and the precise recover
+> types are derived from the handler map's parameter and return types.
+
+### 2. Write loaders/actions as effects
+
+```ts
+// app/routes/profile.ts
+import { Effect } from "effect";
+import { makeLoader, Respond } from "../route.server.ts";
+import type { Route } from "./+types/profile";
+
+const loaderEffect = ({ params }: Route.LoaderArgs) =>
+  Effect.gen(function* () {
+    const profile = yield* getProfile(params.id); // may fail with FormError / BadInputError
+    if (!profile.public) {
+      yield* Respond.early({ restricted: true }); // recover with typed data
+    }
+    return { profile };
+  });
+
+export const loader = makeLoader((args: Route.LoaderArgs) => loaderEffect(args));
+```
+
+The resolved type is computed from the effect and your handlers:
+
+```ts
+type LoaderData = Route.ComponentProps["loaderData"];
+// { profile: Profile } | DataWithResponseInit<{ restricted: boolean }>
+//   ( BadInputError throws, so it never appears here )
+```
+
+### Self-rendering domain errors
+
+If a domain error implements `HttpServerRespondable`, you don't need to register a handler —
+it renders its own response:
+
+```ts
+import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
+
+class NotAuthorizedError extends Data.TaggedError("NotAuthorizedError")<{}> {
+  [HttpServerRespondable.symbol]() {
+    return HttpServerResponse.json({ error: "Not authorized" }, { status: 403 }).pipe(Effect.orDie);
+  }
+}
+```
+
+A registered handler, if present, still takes precedence over the error's own response.
+
+## API
+
+- **`makeLoaderOrActionFactory({ errorHandlers })`** → `{ makeLoader, makeAction, makeLoaderOrAction }`
+  (the three are the same wrapper under different names).
+- **`Respond`** — `early` (recover), `throw`, `redirect`.
+- **`ReturnableDataError`**, **`ThrowableDataError`**, **`ThrowableRedirectError`** — the library
+  route errors, and **`isRouteError`** to narrow them.
+- **`ErrorHandler<Err>`** — the handler signature type.
+
+## Development
+
+```bash
+vp install   # install dependencies
+vp test      # run the test suite
+vp check     # format, lint, type-check
+vp pack      # build the library
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+import { Effect } from "effect";
+import { ActionFunctionArgs, LoaderFunctionArgs, 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 & {
+  readonly _tag: "ReturnableRouteError";
+} & Readonly<A>;
+/** Recoverable: short-circuits the loader but returns `data(...)` the component reads. */
+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 & {
+  readonly _tag: "ThrowableRouteError";
+} & Readonly<A>;
+/** Throwable: rejects with `data(...)` → boundary as an `ErrorResponse`. */
+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 & {
+  readonly _tag: "ThrowableRedirectError";
+} & Readonly<A>;
+/** Throwable: rejects with a redirect `Response`. */
+declare class ThrowableRedirectError extends ThrowableRedirectError_base<{
+  url: string;
+  init?: number | ResponseInit;
+}> {}
+/** Every library route error, as a single union. */
+type AnyRouteError = ReturnableDataError<unknown> | ThrowableDataError<unknown> | ThrowableRedirectError;
+/**
+ * Standardized helpers for raising the library's route errors. Consumers extend it
+ * by spreading into their own object — opinionated helpers (e.g. a form-library
+ * `formError`) live in the consumer, not here:
+ *
+ * ```ts
+ * export const Respond = {
+ *   ...baseRespond,
+ *   formError: (reply) => baseRespond.early({ reply }, 400),
+ * };
+ * ```
+ */
+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`. */
+  redirect: (url: string, init?: number | ResponseInit) => ThrowableRedirectError;
+};
+/** Narrows an unknown value to one of the library's route errors. */
+declare const isRouteError: (value: unknown) => value is AnyRouteError;
+//#endregion
+//#region src/factory.d.ts
+/**
+ * Everything a failure branch rejects with. React Router routes a thrown
+ * `DataWithResponseInit` to the boundary as an `ErrorResponse`, and a thrown
+ * `Response` (including `redirect(...)`) as-is. Pinning every `Effect.fail` branch
+ * to this union keeps inference from fixing the error channel to the first one.
+ */
+type FailureResponse = UNSAFE_DataWithResponseInit<unknown> | Response;
+/**
+ * What a handler may return, to *remap* a domain error:
+ *  - a **library route error** — `Respond.early(value)` (recover), `Respond.throw(data)`
+ *    or `Respond.redirect(url)` (throw) — which the library then processes; or
+ *  - an **`Effect`** — `Effect.succeed(value)` to recover with `value`, or
+ *    `Effect.fail(response)` to throw `response`.
+ */
+type ErrorHandler<Err> = (error: Err) => AnyRouteError | Effect.Effect<unknown, FailureResponse>;
+/** The body of every `ReturnableDataError` raised directly in `E` (`Respond.early`). */
+type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : never;
+/**
+ * The recover contribution of a `Respond.early` raised directly in the loader.
+ * Guarded so a loader that never recovers directly doesn't leak
+ * `DataWithResponseInit<never>` into its return type.
+ */
+type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never] ? never : UNSAFE_DataWithResponseInit<ReturnableBodyOf<E>>;
+/**
+ * What the registered handlers recover into loader/action data — derived from the
+ * handlers' returns, but only for handlers whose error can actually occur in `E`:
+ *  - a remapped `ReturnableDataError<B>` recovers as `DataWithResponseInit<B>`;
+ *  - an `Effect.succeed(value)` recovers as `value`;
+ *  - throwables, redirects and `Effect.fail(...)` contribute nothing.
+ */
+type RecoverOf<Handlers, E> = { [Tag in keyof Handlers]: Handlers[Tag] extends ((error: infer Err) => infer R) ? [Extract<E, Err>] extends [never] ? never : (R extends ReturnableDataError<infer B> ? UNSAFE_DataWithResponseInit<B> : never) | (R extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never) : never }[keyof Handlers];
+/** Shape every handler must satisfy: return a library route error or an `Effect` failing with a response. */
+type ValidHandlers = Record<string, (error: never) => AnyRouteError | Effect.Effect<unknown, FailureResponse>>;
+/**
+ * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+ *
+ * Register a handler per domain error in `errorHandlers` (**annotate each handler's
+ * param** — the registered set and recover types are derived from the map). A
+ * handler *remaps* the error by returning either a library route error
+ * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+ * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+ * throw). Recovered values become loader/action data, typed precisely (non-generic).
+ *
+ * Handling is optional: an *unregistered* error is allowed. If it implements
+ * `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
+ * error boundary as a 500.
+ *
+ * @example
+ * ```ts
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+ *   errorHandlers: {
+ *     // throw → error boundary
+ *     MyDomainError: (error: MyDomainError) =>
+ *       Effect.fail(new Response(error.message, { status: 400 })),
+ *     // remap → recover via a library returnable
+ *     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+ *   },
+ * });
+ * ```
+ */
+declare function makeLoaderOrActionFactory<const Handlers>(config: {
+  errorHandlers: Handlers;
+}, ..._validate: Handlers extends ValidHandlers ? [] : [eachHandlerMustReturnARouteErrorOrAnEffectFailingWithAResponse: ValidHandlers]): {
+  makeLoaderOrAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
+  makeLoader: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
+  makeAction: <Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(fn: (args: Args) => Effect.Effect<A, E, never>) => (args: Args) => Promise<A | RecoverOf<Handlers, E> | DirectRecover<E>>;
+};
+//#endregion
+export { type AnyRouteError, type ErrorHandler, Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/dist/index.mjs

@@ -0,0 +1,99 @@
+import { Data, Effect } from "effect";
+import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
+import { data, redirect } from "react-router";
+//#region src/errors.ts
+/** Recoverable: short-circuits the loader but returns `data(...)` the component reads. */
+var ReturnableDataError = class extends Data.TaggedError("ReturnableRouteError") {};
+/** Throwable: rejects with `data(...)` → boundary as an `ErrorResponse`. */
+var ThrowableDataError = class extends Data.TaggedError("ThrowableRouteError") {};
+/** Throwable: rejects with a redirect `Response`. */
+var ThrowableRedirectError = class extends Data.TaggedError("ThrowableRedirectError") {};
+/**
+* Standardized helpers for raising the library's route errors. Consumers extend it
+* by spreading into their own object — opinionated helpers (e.g. a form-library
+* `formError`) live in the consumer, not here:
+*
+* ```ts
+* export const Respond = {
+*   ...baseRespond,
+*   formError: (reply) => baseRespond.early({ reply }, 400),
+* };
+* ```
+*/
+const Respond = {
+	/** Recover: short-circuit and hand `value` to the component as loader/action data. */
+	early: (value, init) => new ReturnableDataError({
+		data: value,
+		init
+	}),
+	/** Throw: short-circuit to the error boundary with `data(value, init)`. */
+	throw: (value, init) => new ThrowableDataError({
+		data: value,
+		init
+	}),
+	/** Throw: short-circuit with a redirect `Response`. */
+	redirect: (url, init) => new ThrowableRedirectError({
+		url,
+		init
+	})
+};
+/** Narrows an unknown value to one of the library's route errors. */
+const isRouteError = (value) => value instanceof ReturnableDataError || value instanceof ThrowableDataError || value instanceof ThrowableRedirectError;
+//#endregion
+//#region src/factory.ts
+const internalServerError = () => Effect.fail(new Response("Internal Server Error", { status: 500 }));
+/** 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));
+	if (e instanceof ThrowableDataError) return Effect.fail(data(e.data, e.init));
+	return Effect.fail(redirect(e.url, e.init));
+};
+/**
+* Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+*
+* Register a handler per domain error in `errorHandlers` (**annotate each handler's
+* param** — the registered set and recover types are derived from the map). A
+* handler *remaps* the error by returning either a library route error
+* (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+* `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+* throw). Recovered values become loader/action data, typed precisely (non-generic).
+*
+* Handling is optional: an *unregistered* error is allowed. If it implements
+* `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
+* error boundary as a 500.
+*
+* @example
+* ```ts
+* const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+*   errorHandlers: {
+*     // throw → error boundary
+*     MyDomainError: (error: MyDomainError) =>
+*       Effect.fail(new Response(error.message, { status: 400 })),
+*     // remap → recover via a library returnable
+*     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+*   },
+* });
+* ```
+*/
+function makeLoaderOrActionFactory(config, ..._validate) {
+	const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in config.errorHandlers;
+	const userHandlers = config.errorHandlers;
+	function makeLoaderOrAction(fn) {
+		return (args) => Effect.runPromise(fn(args).pipe(Effect.catchIf((_e) => true, (e) => {
+			if (isUserError(e)) {
+				const out = userHandlers[e._tag](e);
+				return isRouteError(out) ? processRouteError(out) : out;
+			}
+			if (isRouteError(e)) return processRouteError(e);
+			if (HttpServerRespondable.isRespondable(e)) return HttpServerRespondable.toResponse(e).pipe(Effect.flatMap((res) => Effect.fail(HttpServerResponse.toWeb(res))));
+			return internalServerError();
+		})));
+	}
+	return {
+		makeLoaderOrAction,
+		makeLoader: makeLoaderOrAction,
+		makeAction: makeLoaderOrAction
+	};
+}
+//#endregion
+export { Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://schemastore.org/package.json",
+  "name": "react-router-effect",
+  "version": "0.1.0",
+  "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
+  "keywords": [
+    "action",
+    "effect",
+    "error-handling",
+    "loader",
+    "react-router",
+    "typescript"
+  ],
+  "homepage": "https://github.com/justinwaite/react-router-effect#readme",
+  "bugs": {
+    "url": "https://github.com/justinwaite/react-router-effect/issues"
+  },
+  "license": "MIT",
+  "author": "Justin Waite <justindwaite@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justinwaite/react-router-effect.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
+    "@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",
+    "playwright": "1.60.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-router": "^7.16.0",
+    "typescript": "^6.0.3",
+    "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"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.9.0",
+      "onFail": "download"
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "test:unit": "vp test run --project unit",
+    "test:browser": "vp test run --project browser",
+    "test:browser:install": "vp exec playwright install chromium",
+    "check": "vp check",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:release": "vp run build && changeset publish"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,59 @@
+import { Data } from "effect";
+
+// ---------------------------------------------------------------------------
+// Standardized errors — the library translates these out of the box.
+// ---------------------------------------------------------------------------
+
+/** Recoverable: short-circuits the loader but returns `data(...)` the component reads. */
+export class ReturnableDataError<D> extends Data.TaggedError("ReturnableRouteError")<{
+  data: D;
+  init?: number | ResponseInit;
+}> {}
+
+/** Throwable: rejects with `data(...)` → boundary as an `ErrorResponse`. */
+export class ThrowableDataError<D> extends Data.TaggedError("ThrowableRouteError")<{
+  data: D;
+  init?: number | ResponseInit;
+}> {}
+
+/** Throwable: rejects with a redirect `Response`. */
+export class ThrowableRedirectError extends Data.TaggedError("ThrowableRedirectError")<{
+  url: string;
+  init?: number | ResponseInit;
+}> {}
+
+/** Every library route error, as a single union. */
+export type AnyRouteError =
+  | ReturnableDataError<unknown>
+  | ThrowableDataError<unknown>
+  | ThrowableRedirectError;
+
+/**
+ * Standardized helpers for raising the library's route errors. Consumers extend it
+ * by spreading into their own object — opinionated helpers (e.g. a form-library
+ * `formError`) live in the consumer, not here:
+ *
+ * ```ts
+ * export const Respond = {
+ *   ...baseRespond,
+ *   formError: (reply) => baseRespond.early({ reply }, 400),
+ * };
+ * ```
+ */
+export const Respond = {
+  /** Recover: short-circuit and hand `value` to the component as loader/action data. */
+  early: <D>(value: D, init?: number | ResponseInit) =>
+    new ReturnableDataError({ data: value, init }),
+  /** Throw: short-circuit to the error boundary with `data(value, init)`. */
+  throw: <D>(value: D, init?: number | ResponseInit) =>
+    new ThrowableDataError({ data: value, init }),
+  /** Throw: short-circuit with a redirect `Response`. */
+  redirect: (url: string, init?: number | ResponseInit) =>
+    new ThrowableRedirectError({ url, init }),
+};
+
+/** Narrows an unknown value to one of the library's route errors. */
+export const isRouteError = (value: unknown): value is AnyRouteError =>
+  value instanceof ReturnableDataError ||
+  value instanceof ThrowableDataError ||
+  value instanceof ThrowableRedirectError;

package/src/factory.ts

@@ -0,0 +1,197 @@
+import { Effect } from "effect";
+import { HttpServerRespondable, HttpServerResponse } from "effect/unstable/http";
+import {
+  data,
+  redirect,
+  type ActionFunctionArgs,
+  type UNSAFE_DataWithResponseInit as DataWithResponseInit,
+  type LoaderFunctionArgs,
+} from "react-router";
+
+import {
+  isRouteError,
+  ReturnableDataError,
+  ThrowableDataError,
+  type AnyRouteError,
+} from "./errors.ts";
+
+// ---------------------------------------------------------------------------
+// Type-level plumbing.
+// ---------------------------------------------------------------------------
+
+type Tagged = { readonly _tag: string };
+
+/**
+ * Everything a failure branch rejects with. React Router routes a thrown
+ * `DataWithResponseInit` to the boundary as an `ErrorResponse`, and a thrown
+ * `Response` (including `redirect(...)`) as-is. Pinning every `Effect.fail` branch
+ * to this union keeps inference from fixing the error channel to the first one.
+ */
+type FailureResponse = DataWithResponseInit<unknown> | Response;
+
+/**
+ * What a handler may return, to *remap* a domain error:
+ *  - a **library route error** — `Respond.early(value)` (recover), `Respond.throw(data)`
+ *    or `Respond.redirect(url)` (throw) — which the library then processes; or
+ *  - an **`Effect`** — `Effect.succeed(value)` to recover with `value`, or
+ *    `Effect.fail(response)` to throw `response`.
+ */
+export type ErrorHandler<Err> = (
+  error: Err,
+) => AnyRouteError | Effect.Effect<unknown, FailureResponse>;
+
+/** The body of every `ReturnableDataError` raised directly in `E` (`Respond.early`). */
+type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : never;
+
+/**
+ * The recover contribution of a `Respond.early` raised directly in the loader.
+ * Guarded so a loader that never recovers directly doesn't leak
+ * `DataWithResponseInit<never>` into its return type.
+ */
+type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
+  ? never
+  : DataWithResponseInit<ReturnableBodyOf<E>>;
+
+/** The domain errors a handler map registers — derived from the handlers' params. */
+type RegisteredError<Handlers> = {
+  [Tag in keyof Handlers]: Handlers[Tag] extends (error: infer Err) => unknown ? Err : never;
+}[keyof Handlers];
+
+/**
+ * What the registered handlers recover into loader/action data — derived from the
+ * handlers' returns, but only for handlers whose error can actually occur in `E`:
+ *  - a remapped `ReturnableDataError<B>` recovers as `DataWithResponseInit<B>`;
+ *  - an `Effect.succeed(value)` recovers as `value`;
+ *  - throwables, redirects and `Effect.fail(...)` contribute nothing.
+ */
+type RecoverOf<Handlers, E> = {
+  [Tag in keyof Handlers]: Handlers[Tag] extends (error: infer Err) => infer R
+    ? [Extract<E, Err>] extends [never]
+      ? never
+      :
+          | (R extends ReturnableDataError<infer B> ? DataWithResponseInit<B> : never)
+          | (R extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never)
+    : never;
+}[keyof Handlers];
+
+/** Shape every handler must satisfy: return a library route error or an `Effect` failing with a response. */
+type ValidHandlers = Record<
+  string,
+  (error: never) => AnyRouteError | Effect.Effect<unknown, FailureResponse>
+>;
+
+// ---------------------------------------------------------------------------
+// Internal runtime helpers.
+// ---------------------------------------------------------------------------
+
+const internalServerError = () =>
+  Effect.fail<FailureResponse>(new Response("Internal Server Error", { status: 500 }));
+
+/** The internal dispatch for a library route error: recover, throw, or redirect. */
+const processRouteError = (
+  e: AnyRouteError,
+): Effect.Effect<DataWithResponseInit<unknown>, FailureResponse> => {
+  if (e instanceof ReturnableDataError) return Effect.succeed(data(e.data, e.init));
+  if (e instanceof ThrowableDataError) return Effect.fail<FailureResponse>(data(e.data, e.init));
+  return Effect.fail<FailureResponse>(redirect(e.url, e.init));
+};
+
+// ---------------------------------------------------------------------------
+// Factory.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
+ *
+ * Register a handler per domain error in `errorHandlers` (**annotate each handler's
+ * param** — the registered set and recover types are derived from the map). A
+ * handler *remaps* the error by returning either a library route error
+ * (`Respond.early` to recover; `Respond.throw` / `Respond.redirect` to throw) or an
+ * `Effect` (`Effect.succeed(value)` to recover `value`; `Effect.fail(response)` to
+ * throw). Recovered values become loader/action data, typed precisely (non-generic).
+ *
+ * Handling is optional: an *unregistered* error is allowed. If it implements
+ * `HttpServerRespondable` it's rendered automatically; otherwise it rejects to the
+ * error boundary as a 500.
+ *
+ * @example
+ * ```ts
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory({
+ *   errorHandlers: {
+ *     // throw → error boundary
+ *     MyDomainError: (error: MyDomainError) =>
+ *       Effect.fail(new Response(error.message, { status: 400 })),
+ *     // remap → recover via a library returnable
+ *     FormError: (error: FormError) => Respond.early({ reply: error.reply }),
+ *   },
+ * });
+ * ```
+ */
+export function makeLoaderOrActionFactory<const Handlers>(
+  config: { errorHandlers: Handlers },
+  // Validation: a handler that doesn't return a route error or a failing `Effect`
+  // makes this rest parameter required, forcing a compile error at the call.
+  ..._validate: Handlers extends ValidHandlers
+    ? []
+    : [eachHandlerMustReturnARouteErrorOrAnEffectFailingWithAResponse: ValidHandlers]
+) {
+  /** Domain errors this factory has handlers for. */
+  type UserError = Extract<RegisteredError<Handlers>, Tagged>;
+
+  const isUserError = (e: unknown): e is UserError =>
+    typeof e === "object" &&
+    e !== null &&
+    "_tag" in e &&
+    (e as Tagged)._tag in (config.errorHandlers as object);
+
+  // Uniform call signature for dispatch (the per-tag handler types are narrower).
+  const userHandlers = config.errorHandlers as unknown as Record<string, ErrorHandler<UserError>>;
+
+  function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E>(
+    fn: (args: Args) => Effect.Effect<A, E>,
+    // The resolved value: the loader's own success, the body of any `Respond.early`
+    // raised directly, plus everything the registered (and reachable) handlers
+    // recover with.
+  ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, 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.
+      Effect.runPromise(
+        fn(args).pipe(
+          // Catch the whole error channel and dispatch. The refinement is `e is E`
+          // (provably ⊆ E, and a *refinement* not a bare predicate — the predicate
+          // overload crashes tsc over a generic `E`). Unregistered, non-respondable
+          // errors fall through to the 500 default.
+          Effect.catchIf(
+            (_e): _e is E => true,
+            (e): Effect.Effect<unknown, FailureResponse> => {
+              // Registered domain error → remap. A library-error return is processed
+              // by the internal dispatch; an `Effect` return is used as-is.
+              if (isUserError(e)) {
+                const out = userHandlers[e._tag](e);
+                return isRouteError(out) ? processRouteError(out) : out;
+              }
+              // A library route error raised directly in the loader → recover/throw.
+              if (isRouteError(e)) return processRouteError(e);
+              // Respondable → render its own response and throw it.
+              if (HttpServerRespondable.isRespondable(e)) {
+                return HttpServerRespondable.toResponse(e).pipe(
+                  Effect.flatMap((res) =>
+                    Effect.fail<FailureResponse>(HttpServerResponse.toWeb(res)),
+                  ),
+                );
+              }
+              return internalServerError();
+            },
+          ),
+        ),
+      ) as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+  }
+
+  return {
+    makeLoaderOrAction,
+    makeLoader: makeLoaderOrAction,
+    makeAction: makeLoaderOrAction,
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+  isRouteError,
+  Respond,
+  ReturnableDataError,
+  ThrowableDataError,
+  ThrowableRedirectError,
+} from "./errors.ts";
+export type { AnyRouteError } from "./errors.ts";
+export { makeLoaderOrActionFactory } from "./factory.ts";
+export type { ErrorHandler } from "./factory.ts";