react-router-effect 0.5.0 → 0.6.0

package/README.md

@@ -64,7 +64,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 +74,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 +157,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 +178,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 +214,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 +234,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;
 };
@@ -159,15 +164,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 +195,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 +209,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 +233,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>>;
+  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,9 +109,14 @@ 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) {
@@ -122,9 +136,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.0",
   "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.
 // ---------------------------------------------------------------------------
@@ -173,15 +177,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 +208,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 +227,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.
@@ -327,6 +357,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,