react-router-effect 0.4.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,26 +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: {
-    // 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 }),
-};
+// 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 })),
+    },
+  }),
+);
 ```
 
-> **Annotate each handler's parameter.** Handlers must be keyed by a declared domain error, and
-> the precise recover types are derived from the handler map's parameter and return types.
+> **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
 
@@ -152,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) =>
@@ -173,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
@@ -209,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(() =>
@@ -229,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;
 };
@@ -76,14 +81,34 @@ type ReturnableBodyOf<E> = E extends ReturnableDataError<infer Body> ? Body : ne
  * `DataWithResponseInit<never>` into its return type.
  */
 type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never] ? never : UNSAFE_DataWithResponseInit<ReturnableBodyOf<E>>;
+/** What a handler may return: a library route error or an `Effect` failing with a response. */
+type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
 /**
- * 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`:
+ * The inferred map of handler RETURN types, keyed by domain-error tag. Making the
+ * factory generic over *this* (rather than the whole handler map) is what lets
+ * `errorHandlers` contextually type each handler's `error` param from its key —
+ * no annotation needed — while still capturing precise return types for recovery.
+ */
+type HandlerReturns<DomainError extends Tagged> = Partial<Record<DomainError["_tag"], HandlerReturn>>;
+/**
+ * The `errorHandlers` field shape for a given return map: one entry per registered
+ * tag, whose `error` is the matching domain error (so it autocompletes and types
+ * itself) and whose return is the precise, inferred `Returns[Tag]`.
+ */
+type ErrorHandlers<DomainError extends Tagged, Returns> = { [Tag in keyof Returns]: (error: Extract<DomainError, {
+  readonly _tag: Tag;
+}>) => Returns[Tag] };
+/**
+ * What the registered handlers recover into loader/action data — from each
+ * handler's return type, but only for handlers whose error can actually occur in
+ * `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];
+type RecoverOf<DomainError extends Tagged, Returns, E> = { [Tag in keyof Returns]: [Extract<E, Extract<DomainError, {
+  readonly _tag: Tag;
+}>>] extends [never] ? never : (Returns[Tag] extends ReturnableDataError<infer B> ? UNSAFE_DataWithResponseInit<B> : never) | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never) }[keyof Returns];
 /**
  * Errors the library deals with on the loader's behalf — so the loader needn't
  * handle them itself:
@@ -99,21 +124,6 @@ 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>>;
-/**
- * The shape a handler map must satisfy: an OPTIONAL handler per declared domain
- * error, keyed by its tag, taking that error and returning a library route error
- * or an `Effect` failing with a response. Used only as a validation constraint —
- * the concrete handler types stay precise via the `const Handlers` inference.
- */
-type ValidHandlers<DomainError extends Tagged> = { [Tag in DomainError["_tag"]]?: (error: Extract<DomainError, {
-  readonly _tag: Tag;
-}>) => AnyRouteError | Effect.Effect<unknown, FailureResponse> };
-/**
- * True when every registered handler is keyed by a declared domain error's tag and
- * returns a library route error or a failing `Effect`. A handler for an unknown tag
- * (`keyof Handlers` escaping the domain tags) or with a bad return makes it `false`.
- */
-type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] extends [DomainError["_tag"]] ? Handlers extends ValidHandlers<DomainError> ? true : false : false;
 /**
  * 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
@@ -146,23 +156,29 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
  * Declare the app's **domain errors** as the type argument, then register an
- * *optional* handler per domain error in `errorHandlers` (**annotate each handler's
- * param**). It's curried so you can pin the domain errors while the handler types
- * are still inferred:
+ * *optional* handler per domain error in `errorHandlers`. The handler keys
+ * autocomplete to your domain-error tags and each `error` parameter is typed from
+ * its key — no annotation needed. It's curried so you can pin the domain errors
+ * while the handler return types are still inferred:
  *
  * ```ts
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
- *   errorHandlers: {
- *     // throw → error boundary
- *     MyDomainError: (error: MyDomainError) =>
- *       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
@@ -179,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) =>
@@ -193,13 +209,15 @@ type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>
  * );
  * ```
  */
-declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>(): <const Handlers = {}, 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. Omit entirely to register
-   * none (e.g. when relying on `HttpServerRespondable` / the 500 default, or
-   * when there are no domain errors at all).
+   * 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?: Handlers;
+  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)
@@ -208,16 +226,29 @@ declare function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
    */
   runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
   /**
-   * A React Router context key (see {@link createRequestContext}) holding a
+   * 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>;
-}, ..._validate: HandlersAreValid<Handlers, DomainError> extends true ? [] : [eachHandlerMustBeForADeclaredDomainErrorAndReturnARouteErrorOrAnEffect: ValidHandlers<DomainError>]) => {
-  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<Handlers, 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<Handlers, E> | DirectRecover<E>>;
+  /**
+   * 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 = {
@@ -52,23 +55,29 @@ const processRouteError = (e) => {
 * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
 *
 * Declare the app's **domain errors** as the type argument, then register an
-* *optional* handler per domain error in `errorHandlers` (**annotate each handler's
-* param**). It's curried so you can pin the domain errors while the handler types
-* are still inferred:
+* *optional* handler per domain error in `errorHandlers`. The handler keys
+* autocomplete to your domain-error tags and each `error` parameter is typed from
+* its key — no annotation needed. It's curried so you can pin the domain errors
+* while the handler return types are still inferred:
 *
 * ```ts
 * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
 *
-* const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
-*   errorHandlers: {
-*     // throw → error boundary
-*     MyDomainError: (error: MyDomainError) =>
-*       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, ..._validate) {
+	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.4.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.
 // ---------------------------------------------------------------------------
@@ -53,22 +57,43 @@ type DirectRecover<E> = [ReturnableBodyOf<E>] extends [never]
   ? never
   : DataWithResponseInit<ReturnableBodyOf<E>>;
 
+/** What a handler may return: a library route error or an `Effect` failing with a response. */
+type HandlerReturn = AnyRouteError | Effect.Effect<unknown, FailureResponse>;
+
+/**
+ * The inferred map of handler RETURN types, keyed by domain-error tag. Making the
+ * factory generic over *this* (rather than the whole handler map) is what lets
+ * `errorHandlers` contextually type each handler's `error` param from its key —
+ * no annotation needed — while still capturing precise return types for recovery.
+ */
+type HandlerReturns<DomainError extends Tagged> = Partial<
+  Record<DomainError["_tag"], HandlerReturn>
+>;
+
 /**
- * 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`:
+ * The `errorHandlers` field shape for a given return map: one entry per registered
+ * tag, whose `error` is the matching domain error (so it autocompletes and types
+ * itself) and whose return is the precise, inferred `Returns[Tag]`.
+ */
+type ErrorHandlers<DomainError extends Tagged, Returns> = {
+  [Tag in keyof Returns]: (error: Extract<DomainError, { readonly _tag: Tag }>) => Returns[Tag];
+};
+
+/**
+ * What the registered handlers recover into loader/action data — from each
+ * handler's return type, but only for handlers whose error can actually occur in
+ * `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];
+type RecoverOf<DomainError extends Tagged, Returns, E> = {
+  [Tag in keyof Returns]: [Extract<E, Extract<DomainError, { readonly _tag: Tag }>>] extends [never]
+    ? never
+    :
+        | (Returns[Tag] extends ReturnableDataError<infer B> ? DataWithResponseInit<B> : never)
+        | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never);
+}[keyof Returns];
 
 /**
  * Errors the library deals with on the loader's behalf — so the loader needn't
@@ -87,31 +112,6 @@ type LibraryHandled<DomainError> = DomainError | AnyRouteError | HttpServerRespo
  */
 type Unhandled<E, DomainError> = Exclude<E, LibraryHandled<DomainError>>;
 
-/**
- * The shape a handler map must satisfy: an OPTIONAL handler per declared domain
- * error, keyed by its tag, taking that error and returning a library route error
- * or an `Effect` failing with a response. Used only as a validation constraint —
- * the concrete handler types stay precise via the `const Handlers` inference.
- */
-type ValidHandlers<DomainError extends Tagged> = {
-  [Tag in DomainError["_tag"]]?: (
-    error: Extract<DomainError, { readonly _tag: Tag }>,
-  ) => AnyRouteError | Effect.Effect<unknown, FailureResponse>;
-};
-
-/**
- * True when every registered handler is keyed by a declared domain error's tag and
- * returns a library route error or a failing `Effect`. A handler for an unknown tag
- * (`keyof Handlers` escaping the domain tags) or with a bad return makes it `false`.
- */
-type HandlersAreValid<Handlers, DomainError extends Tagged> = [keyof Handlers] extends [
-  DomainError["_tag"],
-]
-  ? Handlers extends ValidHandlers<DomainError>
-    ? true
-    : false
-  : false;
-
 // ---------------------------------------------------------------------------
 // Internal runtime helpers.
 // ---------------------------------------------------------------------------
@@ -169,23 +169,29 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * Build `makeLoader` / `makeAction` for an application, wired to its domain errors.
  *
  * Declare the app's **domain errors** as the type argument, then register an
- * *optional* handler per domain error in `errorHandlers` (**annotate each handler's
- * param**). It's curried so you can pin the domain errors while the handler types
- * are still inferred:
+ * *optional* handler per domain error in `errorHandlers`. The handler keys
+ * autocomplete to your domain-error tags and each `error` parameter is typed from
+ * its key — no annotation needed. It's curried so you can pin the domain errors
+ * while the handler return types are still inferred:
  *
  * ```ts
  * type DomainErrors = MyDomainError | DbError | NotAuthorizedError;
  *
- * const { makeLoader, makeAction } = makeLoaderOrActionFactory<DomainErrors>()({
- *   errorHandlers: {
- *     // throw → error boundary
- *     MyDomainError: (error: MyDomainError) =>
- *       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
@@ -202,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,14 +223,26 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  * ```
  */
 export function makeLoaderOrActionFactory<DomainError extends Tagged = never>() {
-  return function defineErrorHandlers<const Handlers = {}, RServices = never, ReqServices = never>(
-    config: {
+  return function defineErrorHandlers<
+    const Returns extends HandlerReturns<DomainError> = {},
+    RServices = never,
+    ReqServices = never,
+    const ExtraRespond extends Record<string, (...args: never[]) => unknown> = {},
+  >(
+    /**
+     * 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.
+     */
+    builder: (respond: BaseRespond) => {
       /**
-       * An optional handler per declared domain error. Omit entirely to register
-       * none (e.g. when relying on `HttpServerRespondable` / the 500 default, or
-       * when there are no domain errors at all).
+       * 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?: Handlers;
+      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)
@@ -233,25 +251,29 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
        */
       runtime?: ManagedRuntime.ManagedRuntime<RServices, any>;
       /**
-       * A React Router context key (see {@link createRequestContext}) holding a
+       * 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;
     },
-    // Validation: a handler for a non-domain error, or one that doesn't return a
-    // route error / failing `Effect`, makes this rest parameter required and forces
-    // a compile error at the call.
-    ..._validate: HandlersAreValid<Handlers, DomainError> extends true
-      ? []
-      : [
-          eachHandlerMustBeForADeclaredDomainErrorAndReturnARouteErrorOrAnEffect: ValidHandlers<DomainError>,
-        ]
   ) {
+    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.
@@ -281,7 +303,7 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
               DomainError
             >,
           ]
-    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>> {
+    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>> {
       return (args: Args) => {
         // The internal channel is deliberately loose (`unknown` success); the outer
         // cast restores the precise resolved type (computed from `E` and the handler
@@ -328,13 +350,14 @@ export function makeLoaderOrActionFactory<DomainError extends Tagged = never>()
         const result = runtime
           ? runtime.runPromise(provided)
           : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>);
-        return result as Promise<A | DirectRecover<E> | RecoverOf<Handlers, E>>;
+        return result as Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>>;
       };
     }
 
     return {
       makeLoader: makeLoaderOrAction,
       makeAction: makeLoaderOrAction,
+      Respond,
     };
   };
 }

package/src/index.ts

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