react-router-effect 0.5.0 → 0.6.1

package/README.md

@@ -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, Respond as baseRespond } from "react-router-effect";
+import { makeLoaderOrActionFactory } from "react-router-effect";
 
 class FormError extends Data.TaggedError("FormError")<{ reply: SubmissionResponse }> {}
 class BadInputError extends Data.TaggedError("BadInputError")<{ message: string }> {}
@@ -74,27 +76,31 @@ class DbError extends Data.TaggedError("DbError")<{ query: string }> {}
 // so it falls through to the 500 default.
 type DomainErrors = FormError | BadInputError | DbError;
 
-// Curried: pin the domain errors, then the handler types are inferred.
-export const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
-  errorHandlers: {
-    // keys autocomplete to your domain-error tags; `error` is typed from its key.
-    // recover: short-circuit and hand the reply to the component
-    FormError: (error) => baseRespond.early({ reply: error.reply }),
-    // throw: send to the error boundary
-    BadInputError: (error) => 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 }),
-};
+// Curried: pin the domain errors, then the handler types are inferred. The config
+// 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>()(
+  (Respond) => ({
+    // App-specific helpers — merged onto the returned `Respond` (base helpers win):
+    respond: {
+      formError: (reply: SubmissionResponse) => new FormError({ reply }),
+    },
+    errorHandlers: {
+      // keys autocomplete to your domain-error tags; `error` is typed from its key.
+      // recover: short-circuit and hand the reply to the component
+      FormError: (error) => Respond.early({ reply: error.reply }),
+      // throw: send to the error boundary
+      BadInputError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
+    },
+  }),
+);
 ```
 
-> **No annotations needed.** Handler keys autocomplete to your declared domain-error tags, each
-> `error` parameter is typed from its key, and the precise recover types are derived from each
-> handler's return.
+> **One `Respond`, no annotations.** Your routes import the `Respond` returned here — there's
+> no library-level `Respond` to clash with it on auto-import. Handler keys autocomplete to your
+> declared domain-error tags, each `error` parameter is typed from its key, and the precise
+> recover types are derived from each handler's return.
 
 ### 2. Write loaders/actions as effects
 
@@ -153,10 +159,10 @@ 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 } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
   runtime: appRuntime,
   errorHandlers: { ... },
-});
+}));
 
 // app/routes/profile.ts — `MyService` is satisfied by the runtime, not provided here:
 const loader = makeLoader((args: Route.LoaderArgs) =>
@@ -174,8 +180,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()({});
+makeLoaderOrActionFactory()(() => ({ runtime }));
+makeLoaderOrActionFactory()(() => ({}));
 ```
 
 ### Per-request services from middleware
@@ -210,10 +216,10 @@ export const middleware: Route.MiddlewareFunction[] = [
 ];
 
 // app/route.server.ts — wire the same key into the factory:
-export const { makeLoader } = makeLoaderOrActionFactory<DomainErrors>()({
+export const { makeLoader } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
   runtime: appRuntime,
   requestContext,
-});
+}));
 
 // the loader requires RequestContext directly — no provide, fresh each request:
 export const loader = makeLoader(() =>
@@ -230,13 +236,16 @@ else is a compile error. `RequestContextKey<ReqServices>` is a type alias for
 
 ## API
 
-- **`makeLoaderOrActionFactory<DomainErrors>()({ errorHandlers?, runtime?, requestContext? })`** →
-  `{ makeLoader, makeAction }` (both are the same wrapper). All config fields are optional. A
-  non-domain error left in a loader/action's error channel — or a required service that neither the
-  `runtime` nor the `requestContext` provides — is a compile error.
+- **`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.
 - **`RequestContextKey<ReqServices>`** — type of the React Router context key for a per-request
   effect context (`RouterContext<Context.Context<ReqServices>>`).
-- **`Respond`** — `early` (recover), `throw`, `redirect`.
+- **`Respond`** (returned from the factory) — `early` (recover), `throw`, `redirect`, plus any
+  `respond` helpers you add.
 - **`ReturnableDataError`**, **`ThrowableDataError`**, **`ThrowableRedirectError`** — the library
   route errors, and **`isRouteError`** to narrow them.
 - **`ErrorHandler<Err>`** — the handler signature type.

package/dist/index.d.mts

@@ -30,15 +30,18 @@ declare class ThrowableRedirectError extends ThrowableRedirectError_base<{
 /** 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:
+ * The library's base helpers for raising route errors (`early` / `throw` /
+ * `redirect`). This is internal: it isn't exported from the package. The factory
+ * hands it to your config builder and returns it (merged with any `respond`
+ * extensions) so your app imports a single `Respond`:
  *
  * ```ts
- * export const Respond = {
- *   ...baseRespond,
- *   formError: (reply) => baseRespond.early({ reply }, 400),
- * };
+ * export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+ *   (Respond) => ({
+ *     respond: { formError: (reply) => new FormError({ reply }) },
+ *     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },
+ *   }),
+ * );
  * ```
  */
 declare const Respond: {
@@ -50,6 +53,8 @@ declare const Respond: {
 declare const isRouteError: (value: unknown) => value is AnyRouteError;
 //#endregion
 //#region src/factory.d.ts
+/** The library's base `Respond` helpers (`early` / `throw` / `redirect`). */
+type BaseRespond = typeof Respond;
 type Tagged = {
   readonly _tag: string;
 };
@@ -119,6 +124,35 @@ type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespo
  * errors. The loader/action must handle these itself (catch or map them).
  */
 type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
+/**
+ * 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;
+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.";
+  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>>;
+};
 /**
  * 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
@@ -159,15 +193,21 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * ```ts
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
- *   errorHandlers: {
- *     // `error` is typed as MyDomainError automatically. throw → error boundary
- *     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
- *     // DbError has no handler → falls through to the 500 default.
- *   },
- * });
+ * export const { makeLoader, makeAction, Respond } =
+ *   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+ *     errorHandlers: {
+ *       // `error` is typed as MyDomainError automatically. throw → error boundary
+ *       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
+ *       // DbError has no handler → falls through to the 500 default.
+ *     },
+ *   }));
  * ```
  *
+ * The inner config is a **builder** — it receives the library's `Respond` helpers so
+ * your handlers can recover/throw with them, and returns the config. `Respond` is
+ * also returned from the factory (extended with any `respond` helpers you add), so
+ * your app imports a *single* `Respond` — no auto-import ambiguity with a library one.
+ *
  * 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
@@ -184,10 +224,10 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * services directly — no per-call `Effect.provide`:
  *
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
  *   runtime: getAppRuntime(), // provides Database, MyService, ...
  *   errorHandlers: { ... },
- * });
+ * }));
  *
  * // `MyService` is satisfied by the runtime, not provided here:
  * const loader = makeLoader((args: Route.LoaderArgs) =>
@@ -198,13 +238,13 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * );
  * ```
  */
-declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Returns extends HandlerReturns<DomainError> = {}, RServices = never, ReqServices = never>(config: {
+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) => {
   /**
    * 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
    * is typed automatically — no annotation needed. A handler *remaps* the error
-   * by returning a library route error (`Respond.early` / `throw` / `redirect`)
-   * or an `Effect` (`Effect.succeed`/`fail`). Omit entirely to register none.
+   * by returning a library route error (the builder's `Respond.early` / `throw`
+   * / `redirect`) or an `Effect` (`Effect.succeed`/`fail`). Omit to register none.
    */
   errorHandlers?: ErrorHandlers<DomainError, Returns>;
   /**
@@ -222,9 +262,22 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    * `ReqServices` (inferred from here) in addition to the runtime's services.
    */
   requestContext?: RequestContextKey<ReqServices>;
+  /**
+   * App-specific `Respond` helpers — merged onto the base `Respond` that the
+   * factory returns, so your app imports one `Respond`. Typically opinionated
+   * error constructors; annotate their parameters, e.g.
+   * `{ formError: (reply: string) => new FormError({ reply }) }`. The base
+   * helpers (`early` / `throw` / `redirect`) always win the merge.
+   */
+  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 | 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>>;
+  Respond: {
+    early: <D>(value: D, init?: number | ResponseInit) => ReturnableDataError<D>;
+    throw: <D>(value: D, init?: number | ResponseInit) => ThrowableDataError<D>;
+    redirect: (url: string, init?: number | ResponseInit) => ThrowableRedirectError;
+  } & ExtraRespond;
 };
 //#endregion
-export { type AnyRouteError, type ErrorHandler, type RequestContextKey, Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };
+export { type AnyRouteError, type ErrorHandler, type RequestContextKey, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/dist/index.mjs

@@ -9,15 +9,18 @@ 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:
+* The library's base helpers for raising route errors (`early` / `throw` /
+* `redirect`). This is internal: it isn't exported from the package. The factory
+* hands it to your config builder and returns it (merged with any `respond`
+* extensions) so your app imports a single `Respond`:
 *
 * ```ts
-* export const Respond = {
-*   ...baseRespond,
-*   formError: (reply) => baseRespond.early({ reply }, 400),
-* };
+* export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+*   (Respond) => ({
+*     respond: { formError: (reply) => new FormError({ reply }) },
+*     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },
+*   }),
+* );
 * ```
 */
 const Respond = {
@@ -60,15 +63,21 @@ const processRouteError = (e) => {
 * ```ts
 * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
 *
-* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
-*   errorHandlers: {
-*     // `error` is typed as MyDomainError automatically. throw → error boundary
-*     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
-*     // DbError has no handler → falls through to the 500 default.
-*   },
-* });
+* export const { makeLoader, makeAction, Respond } =
+*   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+*     errorHandlers: {
+*       // `error` is typed as MyDomainError automatically. throw → error boundary
+*       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
+*       // DbError has no handler → falls through to the 500 default.
+*     },
+*   }));
 * ```
 *
+* The inner config is a **builder** — it receives the library's `Respond` helpers so
+* your handlers can recover/throw with them, and returns the config. `Respond` is
+* also returned from the factory (extended with any `respond` helpers you add), so
+* your app imports a *single* `Respond` — no auto-import ambiguity with a library one.
+*
 * 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
@@ -85,10 +94,10 @@ const processRouteError = (e) => {
 * services directly — no per-call `Effect.provide`:
 *
 * ```ts
-* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
 *   runtime: getAppRuntime(), // provides Database, MyService, ...
 *   errorHandlers: { ... },
-* });
+* }));
 *
 * // `MyService` is satisfied by the runtime, not provided here:
 * const loader = makeLoader((args: Route.LoaderArgs) =>
@@ -100,14 +109,20 @@ const processRouteError = (e) => {
 * ```
 */
 function makeLoaderOrActionFactory() {
-	return function defineErrorHandlers(config) {
+	return function defineErrorHandlers(builder) {
+		const config = builder(Respond);
 		const runtime = config.runtime;
 		const requestContextKey = config.requestContext;
+		const Respond$1 = {
+			...config.respond,
+			...Respond
+		};
 		const userHandlers = config.errorHandlers ?? {};
 		const isUserError = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag in userHandlers;
-		function makeLoaderOrAction(fn, ..._handle) {
+		function makeLoaderOrAction(fn) {
+			const run = fn;
 			return (args) => {
-				const program = fn(args).pipe(Effect.catchIf((_e) => true, (e) => {
+				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;
@@ -122,9 +137,10 @@ function makeLoaderOrActionFactory() {
 		}
 		return {
 			makeLoader: makeLoaderOrAction,
-			makeAction: makeLoaderOrAction
+			makeAction: makeLoaderOrAction,
+			Respond: Respond$1
 		};
 	};
 }
 //#endregion
-export { Respond, ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };
+export { ReturnableDataError, ThrowableDataError, ThrowableRedirectError, isRouteError, makeLoaderOrActionFactory };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Wrap React Router loaders/actions with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",

package/src/errors.ts

@@ -29,15 +29,18 @@ export type AnyRouteError =
   | 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:
+ * The library's base helpers for raising route errors (`early` / `throw` /
+ * `redirect`). This is internal: it isn't exported from the package. The factory
+ * hands it to your config builder and returns it (merged with any `respond`
+ * extensions) so your app imports a single `Respond`:
  *
  * ```ts
- * export const Respond = {
- *   ...baseRespond,
- *   formError: (reply) => baseRespond.early({ reply }, 400),
- * };
+ * export const { makeLoader, Respond } = makeLoaderOrActionFactory<DomainErrors>()(
+ *   (Respond) => ({
+ *     respond: { formError: (reply) => new FormError({ reply }) },
+ *     errorHandlers: { FormError: (e) => Respond.early({ reply: e.reply }) },
+ *   }),
+ * );
  * ```
  */
 export const Respond = {

package/src/factory.ts

@@ -11,11 +11,15 @@ import {
 
 import {
   isRouteError,
+  Respond as baseRespond,
   ReturnableDataError,
   ThrowableDataError,
   type AnyRouteError,
 } from "./errors.ts";
 
+/** The library's base `Respond` helpers (`early` / `throw` / `redirect`). */
+type BaseRespond = typeof baseRespond;
+
 // ---------------------------------------------------------------------------
 // Type-level plumbing.
 // ---------------------------------------------------------------------------
@@ -108,6 +112,43 @@ type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespo
  */
 type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
 
+// ---------------------------------------------------------------------------
+// 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;
+
+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.";
+        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>>;
+    };
+
 // ---------------------------------------------------------------------------
 // Internal runtime helpers.
 // ---------------------------------------------------------------------------
@@ -173,15 +214,21 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * ```ts
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
- *   errorHandlers: {
- *     // `error` is typed as MyDomainError automatically. throw → error boundary
- *     MyDomainError: (error) => Effect.fail(new Response(error.message, { status: 400 })),
- *     // DbError has no handler → falls through to the 500 default.
- *   },
- * });
+ * export const { makeLoader, makeAction, Respond } =
+ *   makeLoaderOrActionFactory<DomainErrors>()((Respond) => ({
+ *     errorHandlers: {
+ *       // `error` is typed as MyDomainError automatically. throw → error boundary
+ *       MyDomainError: (error) => Respond.throw({ message: error.message }, 400),
+ *       // DbError has no handler → falls through to the 500 default.
+ *     },
+ *   }));
  * ```
  *
+ * The inner config is a **builder** — it receives the library's `Respond` helpers so
+ * your handlers can recover/throw with them, and returns the config. `Respond` is
+ * also returned from the factory (extended with any `respond` helpers you add), so
+ * your app imports a *single* `Respond` — no auto-import ambiguity with a library one.
+ *
  * 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
@@ -198,10 +245,10 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * services directly — no per-call `Effect.provide`:
  *
  * ```ts
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
+ * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()(() => ({
  *   runtime: getAppRuntime(), // provides Database, MyService, ...
  *   errorHandlers: { ... },
- * });
+ * }));
  *
  * // `MyService` is satisfied by the runtime, not provided here:
  * const loader = makeLoader((args: Route.LoaderArgs) =>
@@ -217,33 +264,53 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
     const Returns extends HandlerReturns<DomainError> = {},
     RServices = never,
     ReqServices = never,
-  >(config: {
-    /**
-     * 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
-     * is typed automatically — no annotation needed. A handler *remaps* the error
-     * by returning a library route error (`Respond.early` / `throw` / `redirect`)
-     * or an `Effect` (`Effect.succeed`/`fail`). Omit entirely to register none.
-     */
-    errorHandlers?: ErrorHandlers<DomainError, Returns>;
-    /**
-     * The app runtime that provides services to loader/action effects. When
-     * set, effects may require its services (`RServices`, inferred from here)
-     * without providing layers, and runs go through `runtime.runPromise`. When
-     * omitted, `RServices` is `never` and effects must require nothing.
-     */
-    runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
+    const ExtraRespond extends Record<string, (...args: never[]) => unknown> = {},
+  >(
     /**
-     * A React Router context key (a {@link RequestContextKey}) holding a
-     * per-request effect `Context.Context`. Middleware sets it for each request;
-     * the runner reads `args.context.get(requestContext)` and provides those
-     * services to the effect. Loader/action effects may then require
-     * `ReqServices` (inferred from here) in addition to the runtime's services.
+     * Builds the factory config. It receives the library's base `Respond` helpers
+     * (`early` / `throw` / `redirect`) so your `errorHandlers` can recover/throw
+     * with them, and returns the config object.
      */
-    requestContext?: RequestContextKey<ReqServices>;
-  }) {
+    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
+       * is typed automatically — no annotation needed. A handler *remaps* the error
+       * by returning a library route error (the builder's `Respond.early` / `throw`
+       * / `redirect`) or an `Effect` (`Effect.succeed`/`fail`). Omit to register none.
+       */
+      errorHandlers?: ErrorHandlers<DomainError, Returns>;
+      /**
+       * The app runtime that provides services to loader/action effects. When
+       * set, effects may require its services (`RServices`, inferred from here)
+       * without providing layers, and runs go through `runtime.runPromise`. When
+       * omitted, `RServices` is `never` and effects must require nothing.
+       */
+      runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
+      /**
+       * A React Router context key (a {@link RequestContextKey}) holding a
+       * per-request effect `Context.Context`. Middleware sets it for each request;
+       * the runner reads `args.context.get(requestContext)` and provides those
+       * services to the effect. Loader/action effects may then require
+       * `ReqServices` (inferred from here) in addition to the runtime's services.
+       */
+      requestContext?: RequestContextKey<ReqServices>;
+      /**
+       * App-specific `Respond` helpers — merged onto the base `Respond` that the
+       * factory returns, so your app imports one `Respond`. Typically opinionated
+       * error constructors; annotate their parameters, e.g.
+       * `{ formError: (reply: string) => new FormError({ reply }) }`. The base
+       * helpers (`early` / `throw` / `redirect`) always win the merge.
+       */
+      respond?: ExtraRespond;
+    },
+  ) {
+    const config = builder(baseRespond);
     const runtime = config.runtime;
     const requestContextKey = config.requestContext;
+    // The single `Respond` an app uses: base helpers plus any app-specific ones.
+    // Base wins the merge so core helpers can't be shadowed.
+    const Respond = { ...config.respond, ...baseRespond } as BaseRespond & ExtraRespond;
 
     // Uniform call signature for dispatch (the per-tag handler types are narrower).
     // Defaults to an empty map when `errorHandlers` is omitted.
@@ -255,34 +322,31 @@ 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
-            >,
-          ]
+    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>> {
+      // 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) => {
         // 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(
+        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.
+          // 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> => {
@@ -327,6 +391,7 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
     return {
       makeLoader: makeLoaderOrAction,
       makeAction: makeLoaderOrAction,
+      Respond,
     };
   };
 }

package/src/index.ts

@@ -1,6 +1,5 @@
 export {
   isRouteError,
-  Respond,
   ReturnableDataError,
   ThrowableDataError,
   ThrowableRedirectError,