react-router-effect 2.1.0 → 2.3.0

package/src/factory.ts

@@ -1,10 +1,11 @@
-import { Context, Effect, type ManagedRuntime } from "effect";
+import { Context, Effect, type ManagedRuntime, Predicate } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/http";
 import {
   createContext,
   data,
   redirect,
   type ActionFunctionArgs,
+  type ErrorResponse,
   type UNSAFE_DataWithResponseInit as DataWithResponseInit,
   type LoaderFunctionArgs,
   type MiddlewareFunction,
@@ -12,7 +13,15 @@ import {
   type RouterContextProvider,
 } from "react-router";
 
-import { attachActionMeta, type WithActionMeta } from "./action-meta.ts";
+import { attachRouteMeta, type WithRouteMeta } from "./route-meta.ts";
+import {
+  deferFailureResponse,
+  deferRouteError,
+  forkDeferred,
+  withDeferScope,
+  type DeferDiagnose,
+  type DeferredPromise,
+} from "./defer.ts";
 import {
   isRouteError,
   Respond as baseRespond,
@@ -124,6 +133,40 @@ export type RecoverOf<DomainError extends Tagged, Returns, E> = {
         | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any> ? SuccessValue : never);
 }[keyof Returns];
 
+/**
+ * The errors the factory's `defer` handles in deferred work: the declared
+ * domain errors, and `Respond.early` / `Respond.throw`. A redirect is not one
+ * of them: it cannot happen after the response started.
+ *
+ * @stability unstable
+ */
+export type DeferHandled<DomainError> =
+  | DomainError
+  | ReturnableDataError<unknown>
+  | ThrowableDataError<unknown>;
+
+/**
+ * What a deferred promise resolves with when the work fails with `E`: the
+ * value of a `Respond.early` raised directly, and what the registered
+ * handlers recover. Unlike loader data, a recovered `Respond.early` gives its
+ * value without the `data(...)` wrapper: a promise has no response to set.
+ *
+ * @stability unstable
+ */
+export type DeferRecoverOf<DomainError extends Tagged, Returns, E> =
+  | ReturnableBodyOf<E>
+  | {
+      [Tag in keyof Returns]: [Extract<E, Extract<DomainError, { readonly _tag: Tag }>>] extends [
+        never,
+      ]
+        ? never
+        :
+            | (Returns[Tag] extends ReturnableDataError<infer B> ? B : never)
+            | (Returns[Tag] extends Effect.Effect<infer SuccessValue, any, any>
+                ? SuccessValue
+                : never);
+    }[keyof Returns];
+
 /**
  * Errors the library deals with on the handler's behalf - so the loader/action/
  * middleware needn't handle them itself:
@@ -244,6 +287,12 @@ const processRouteError = (
  * it in middleware and pass it to the factory's `requestContext` - the runner
  * reads it on every request and provides its services to the loader/action.
  *
+ * With the server adapter, do not set it to a new context. The adapter sets it
+ * to the request fiber's context before React Router runs, and a new context
+ * replaces those services, such as `HttpServerRequest` and the server span.
+ * Provide request services with a router middleware on `ReactRouter.routes`.
+ * The middleware below is for an app without the adapter.
+ *
  * It's just a `RouterContext`; create one with React Router's `createContext`:
  *
  * ```ts
@@ -257,7 +306,7 @@ const processRouteError = (
  *
  * export const requestContext: RequestContextKey<RequestContext> = createContext();
  *
- * // middleware:
+ * // middleware, in an app without the server adapter:
  * export const middleware: Route.MiddlewareFunction[] = [
  *   ({ context, request }, next) => {
  *     context.set(requestContext, Context.make(RequestContext, { userId: readUser(request) }));
@@ -274,8 +323,8 @@ export type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqSe
  */
 const defaultRequestContext: RequestContextKey<never> = createContext(Context.empty());
 
-/** What `actionMeta` reads: the request and the router context of the action. */
-export interface ActionMetaArgs {
+/** What `routeMeta` reads: the request and the router context of the loader or action. */
+export interface RouteMetaArgs {
   readonly request: Request;
   readonly context: Readonly<RouterContextProvider>;
 }
@@ -488,13 +537,14 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
        */
       respond?: ExtraRespond;
       /**
-       * Request-scoped metadata to attach to every action's data under `__meta`,
-       * read after the action resolves. The server adapter attaches it to every
-       * action it runs, including plain functions and `makeAction` wrappers. A
-       * thrown result gets none. Only plain records and `data(...)` bodies include
-       * it; other values are returned unchanged.
+       * Request-scoped metadata to attach to the data of every loader and action
+       * under `__meta`, read after the function resolves. The server adapter
+       * attaches it to every loader and action it runs, including plain functions
+       * and `makeLoader` / `makeAction` wrappers. A thrown result gets none. Only
+       * plain records and `data(...)` bodies include it; other values are returned
+       * unchanged.
        */
-      actionMeta?: (args: ActionMetaArgs) => Meta;
+      routeMeta?: (args: RouteMetaArgs) => Meta;
     },
   ) {
     const config = builder(baseRespond);
@@ -511,11 +561,10 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     // Defaults to an empty map when `errorHandlers` is omitted.
     const userHandlers = (config.errorHandlers ?? {}) as unknown as Record<
       string,
-      ErrorHandler<DomainError>
+      ErrorHandler<Tagged>
     >;
-
-    const isUserError = (e: unknown): e is DomainError =>
-      typeof e === "object" && e !== null && "_tag" in e && (e as Tagged)._tag in userHandlers;
+    /** The tags of the registered domain errors. */
+    const userTags = Object.keys(userHandlers);
 
     /**
      * Runs a handler's effect to completion: dispatches its whole error channel
@@ -532,7 +581,10 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       // The internal channel is deliberately loose (`unknown` success); the caller
       // restores the precise resolved type (computed from `E` and the handler map).
       // Sound at runtime - the values produced are exactly those types.
-      const program = effect.pipe(
+      // Deferred work forks into a scope of this run, closed when the request
+      // aborts or the effect fails. It is inside the dispatch, so a failure that
+      // a handler recovers also interrupts the work: its promises are not sent.
+      const program = withDeferScope(effect, signal).pipe(
         // Catch the full 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
@@ -542,9 +594,11 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
           (e): Effect.Effect<unknown, FailureResponse> => {
             // Registered domain error → remap. A library-error return is processed
             // by the internal dispatch; an `Effect` return is used as-is.
-            if (isUserError(e)) {
-              const out = userHandlers[e._tag](e);
-              return isRouteError(out) ? processRouteError(out) : out;
+            for (const tag of userTags) {
+              if (Predicate.isTagged(e, tag)) {
+                const out = userHandlers[tag](e);
+                return isRouteError(out) ? processRouteError(out) : out;
+              }
             }
             // A library route error raised directly in the handler → recover/throw.
             if (isRouteError(e)) return processRouteError(e);
@@ -570,6 +624,7 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       // `provideContext` removes `ReqServices`, and when no `requestContext` is
       // configured `ReqServices` is `never` (nothing removed).
       const store = readRequestStore(context);
+      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the cast is sound, as the comment above explains
       const provided = (
         store === undefined ? program : Effect.provideContext(program, store)
       ) as Effect.Effect<unknown, FailureResponse, RServices>;
@@ -580,7 +635,8 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       // signal and discards its result, so the interrupt rejection is never rendered.
       return runtime
         ? runtime.runPromise(provided, { signal })
-        : Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>, { signal });
+        : // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- with no runtime `RServices` is `never`
+          Effect.runPromise(provided as Effect.Effect<unknown, FailureResponse>, { signal });
     }
 
     function makeLoaderOrAction<Args extends LoaderFunctionArgs | ActionFunctionArgs, A, E, R>(
@@ -593,15 +649,18 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
       fn: (
         args: Args,
       ) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>,
-    ): (args: Args) => Promise<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>> {
+    ): (
+      args: Args,
+    ) => Promise<WithRouteMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>> {
       // 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>;
+      // The server adapter's `handlers` attach the metadata to what this resolves with.
       return (args: Args) =>
         runProgram(run(args), args.context, args.request.signal) as Promise<
-          A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>
+          WithRouteMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>
         >;
     }
 
@@ -705,6 +764,7 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     function runResult(result: unknown, args: RouteArgs): unknown {
       return Effect.isEffect(result)
         ? runProgram(
+            // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context, effecttsgo/unsafe-effect-type-assertion -- a route function's Effect is only known to be an Effect here; `runProgram` dispatches its whole error channel
             result as Effect.Effect<unknown, unknown, RServices | ReqServices>,
             args.context,
             args.request.signal,
@@ -712,7 +772,80 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
         : result;
     }
 
-    const actionMeta = config.actionMeta;
+    /**
+     * A failure of deferred work, through the error handlers: a recovered
+     * value resolves the promise, a thrown response rejects it with an
+     * `ErrorResponse`. Anything else, such as a domain error with no handler,
+     * is a defect: the promise rejects with no server details.
+     */
+    function dispatchDeferred(e: unknown): Effect.Effect<unknown, ErrorResponse> {
+      for (const tag of userTags) {
+        if (Predicate.isTagged(e, tag)) {
+          const out = userHandlers[tag](e);
+          return isRouteError(out)
+            ? deferRouteError(out)
+            : out.pipe(Effect.catch(deferFailureResponse));
+        }
+      }
+      return isRouteError(e) ? deferRouteError(e) : Effect.die(e);
+    }
+
+    /**
+     * Starts an Effect without waiting for it, and gives a promise of its
+     * result for loader data. React Router streams the promise to `<Await>`.
+     *
+     * The work gets the services and the span of the Effect that defers it.
+     * It keeps running after the loader returns, and is interrupted when the
+     * request aborts or the loader fails. A client-side navigation away does
+     * not abort the request, so the work then runs until it ends or the stream
+     * times out.
+     *
+     * The work may fail only with the factory's domain errors,
+     * `Respond.early` and `Respond.throw`. The error handlers turn them into
+     * the promise's value, or an `ErrorResponse` for `useAsyncError`, as they
+     * do for a loader. A handler that redirects, a domain error with no
+     * handler, a defect or an interrupt rejects the promise with an error that
+     * holds no server details, and the server logs the full cause.
+     *
+     * ```ts
+     * export const { Respond, defer } = routeFactory;
+     *
+     * export const loader = Effect.fn("loader")(function* () {
+     *   const user = yield* Users.current;
+     *   return {
+     *     user,
+     *     reviews: yield* defer(Reviews.list(user.id)),
+     *     stats: yield* Stats.load.pipe(
+     *       Effect.catchTag("StatsUnavailable", () => Effect.succeed(null)),
+     *       defer,
+     *     ),
+     *   };
+     * });
+     * ```
+     *
+     * @stability unstable
+     */
+    function defer<A, E, R>(
+      self: Effect.Effect<A, E, R> & DeferDiagnose<E, DeferHandled<DomainError>>,
+    ): Effect.Effect<DeferredPromise<A | DeferRecoverOf<DomainError, Returns, E>>, never, R> {
+      const work: Effect.Effect<unknown, ErrorResponse, R> = self.pipe(
+        Effect.catch(dispatchDeferred),
+      );
+      // The dispatch resolves with what `DeferRecoverOf` computes from the handlers.
+      return forkDeferred(work) as Effect.Effect<
+        DeferredPromise<A | DeferRecoverOf<DomainError, Returns, E>>,
+        never,
+        R
+      >;
+    }
+
+    const routeMeta = config.routeMeta;
+
+    /** Runs a loader or action's result and attaches the route metadata to its data. */
+    async function withRouteMeta(result: unknown, args: RouteArgs): Promise<unknown> {
+      const resolved = await runResult(result, args);
+      return routeMeta === undefined ? resolved : attachRouteMeta(resolved, routeMeta(args));
+    }
 
     // React Router calls every route function with args that include at least
     // `request` and `context`, so each wrapper reads them through `RouteArgs`.
@@ -720,13 +853,9 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
     // or recovered data, or the awaited plain result. `RouteResult` is its type.
     const handlers: RouteHandlers = {
       loader: (fn) => async (args) =>
-        runResult(fn(args), args) as RouteResult<ReturnType<typeof fn>>,
-      action: (fn) => async (args) => {
-        const result = await runResult(fn(args), args);
-        return (
-          actionMeta === undefined ? result : attachActionMeta(result, actionMeta(args))
-        ) as RouteResult<ReturnType<typeof fn>>;
-      },
+        (await withRouteMeta(fn(args), args)) as RouteResult<ReturnType<typeof fn>>,
+      action: (fn) => async (args) =>
+        (await withRouteMeta(fn(args), args)) as RouteResult<ReturnType<typeof fn>>,
       middleware: (fn) => async (args, next) => {
         const routeArgs: RouteArgs = args;
         // The runner supplies `next` as an effect in place of the one `Args`
@@ -742,20 +871,10 @@ export function makeEffectRouteFactory<DomainError extends Tagged = never>() {
 
     return {
       makeLoader: makeLoaderOrAction,
-      makeAction: makeLoaderOrAction as <
-        Args extends LoaderFunctionArgs | ActionFunctionArgs,
-        A,
-        E,
-        R,
-      >(
-        fn: (
-          args: Args,
-        ) => Effect.Effect<A, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices>,
-      ) => (
-        args: Args,
-      ) => Promise<WithActionMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>>,
+      makeAction: makeLoaderOrAction,
       makeMiddleware,
       Respond,
+      defer,
       /** The route runner the server adapter applies to every route module. */
       handlers,
       /** Type-only: what the adapter's route check and `Register` read. */

package/src/index.ts

@@ -1,5 +1,7 @@
-export { actionMetaKey } from "./action-meta.ts";
-export type { WithActionMeta } from "./action-meta.ts";
+export { routeMetaKey } from "./route-meta.ts";
+export type { WithRouteMeta } from "./route-meta.ts";
+export { deferredFailureMessage } from "./defer.ts";
+export type { DeferDiagnose, DeferredPromise } from "./defer.ts";
 export {
   isRouteError,
   ReturnableDataError,
@@ -9,7 +11,9 @@ export {
 export type { AnyRouteError } from "./errors.ts";
 export { makeEffectRouteFactory } from "./factory.ts";
 export type {
-  ActionMetaArgs,
+  DeferHandled,
+  DeferRecoverOf,
+  RouteMetaArgs,
   EffectMiddlewareArgs,
   EffectNext,
   ErrorHandler,

package/src/route-data.ts

@@ -1,7 +1,7 @@
 import type { Effect } from "effect";
 import type { UNSAFE_DataWithResponseInit, useLoaderData } from "react-router";
 
-import type { WithActionMeta } from "./action-meta.ts";
+import type { WithRouteMeta } from "./route-meta.ts";
 import type { ReturnableDataError } from "./errors.ts";
 
 // ---------------------------------------------------------------------------
@@ -28,8 +28,8 @@ import type { ReturnableDataError } from "./errors.ts";
  *   interface Register {
  *     // Each error tag a handler recovers, and the data it recovers into.
  *     recover: { FormValidationError: { reply: SubmissionResponse } };
- *     // What `actionMeta` returns.
- *     actionMeta: { realtimeEventIds: ReadonlyArray<string> };
+ *     // What `routeMeta` returns.
+ *     routeMeta: { realtimeEventIds: ReadonlyArray<string> };
  *   }
  * }
  * ```
@@ -39,8 +39,8 @@ export interface Register {}
 /** The registered recover map: error tag to recovered data. */
 export type RegisteredRecover = Register extends { readonly recover: infer Recover } ? Recover : {};
 
-/** The registered action metadata, or `never` when there is none. */
-export type RegisteredMeta = Register extends { readonly actionMeta: infer Meta } ? Meta : never;
+/** The registered route metadata, or `never` when there is none. */
+export type RegisteredMeta = Register extends { readonly routeMeta: infer Meta } ? Meta : never;
 
 /** What a failure of type `E` recovers into: `Respond.early` bodies and registered handlers. */
 type Recovered<E> =
@@ -59,9 +59,9 @@ export type Serialize<T> = ReturnType<typeof useLoaderData<() => Promise<T>>>;
 /**
  * The data an Effect that succeeds with `A` and fails with `E` gives the
  * component: its success and what its failures recover into, serialized as
- * React Router serializes them, with the registered action metadata.
+ * React Router serializes them, with the registered route metadata.
  */
-export type EffectData<A, E> = WithActionMeta<Serialize<A | Recovered<E>>, RegisteredMeta>;
+export type EffectData<A, E> = WithRouteMeta<Serialize<A | Recovered<E>>, RegisteredMeta>;
 
 /**
  * The route data of a loader or action, for React Router's hooks:
@@ -108,10 +108,10 @@ type Unwrapped<A> = A extends Response
  * declarations. `test/consumer` checks the built package for that.
  */
 export type BrandData<A, E> = [A] extends [never]
-  ? WithActionMeta<Recovered<E>, RegisteredMeta>
+  ? WithRouteMeta<Recovered<E>, RegisteredMeta>
   : [A] extends [void]
     ? unknown
-    : WithActionMeta<Unwrapped<A> | Recovered<E>, RegisteredMeta>;
+    : WithRouteMeta<Unwrapped<A> | Recovered<E>, RegisteredMeta>;
 
 declare module "effect/Effect" {
   // React Router reads loader and action data through this brand, so an

package/src/{action-meta.ts → route-meta.ts}

@@ -2,11 +2,11 @@ import { Predicate } from "effect";
 import { data, type UNSAFE_DataWithResponseInit as DataWithResponseInit } from "react-router";
 
 // ---------------------------------------------------------------------------
-// Action metadata: request-scoped facts attached to every action's data.
+// Route metadata: request-scoped facts attached to every loader and action's data.
 // ---------------------------------------------------------------------------
 
-/** The key that holds the metadata in action data. */
-export const actionMetaKey = "__meta";
+/** The key that holds the metadata in loader and action data. */
+export const routeMetaKey = "__meta";
 
 /**
  * Adds optional metadata to a record. Only records get metadata, because a
@@ -14,27 +14,29 @@ export const actionMetaKey = "__meta";
  * values (strings, arrays, `Response`s) have nowhere to put it.
  */
 type RecordWithMeta<T, Meta> =
-  T extends Record<string, unknown>
-    ? Omit<T, typeof actionMetaKey> & { [actionMetaKey]?: Meta }
-    : T;
+  T extends Record<string, unknown> ? Omit<T, typeof routeMetaKey> & { [routeMetaKey]?: Meta } : T;
 
 /**
- * The type of action data after metadata is attached. A `data(...)` wrapper
+ * The type of loader or action data after metadata is attached. A `data(...)` wrapper
  * gets metadata on its body. With no configured metadata (`Meta` is `never`)
  * the data is unchanged.
  */
-export type WithActionMeta<T, Meta> = [Meta] extends [never]
+export type WithRouteMeta<T, Meta> = [Meta] extends [never]
   ? T
   : T extends DataWithResponseInit<infer Body>
     ? DataWithResponseInit<RecordWithMeta<Body, Meta>>
     : RecordWithMeta<T, Meta>;
 
-// React Router exports the type of the `data(...)` wrapper, but not its class.
-const DataWithResponseInitClass = data(undefined).constructor;
-
-/** True for a `data(...)` wrapper, never for a business field that looks like one. */
+/**
+ * True for a `data(...)` wrapper, by the same test React Router applies. A
+ * class test fails when the app and the adapter load different copies of
+ * React Router, as under the Vite dev server.
+ */
 const isDataWithResponseInit = (value: unknown): value is DataWithResponseInit<unknown> =>
-  value instanceof DataWithResponseInitClass;
+  Predicate.hasProperty(value, "type") &&
+  Predicate.hasProperty(value, "data") &&
+  Predicate.hasProperty(value, "init") &&
+  value.type === "DataWithResponseInit";
 
 /** True for a plain object, which can be copied without losing behavior. */
 const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
@@ -44,15 +46,15 @@ const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
 };
 
 /**
- * Attaches `meta` to the action result. A plain record gets a copy with the
+ * Attaches `meta` to a loader or action result. A plain record gets a copy with the
  * metadata key; a `data(...)` wrapper gets it on its body and keeps its init.
  * Any other value is returned unchanged.
  */
-export const attachActionMeta = <T>(value: T, meta: unknown): T => {
+export const attachRouteMeta = <T>(value: T, meta: unknown): T => {
   if (isDataWithResponseInit(value)) {
     if (!isPlainRecord(value.data)) return value;
     // The copy has the same shape as `value` plus the metadata key.
-    return data({ ...value.data, [actionMetaKey]: meta }, value.init ?? undefined) as T;
+    return data({ ...value.data, [routeMetaKey]: meta }, value.init ?? undefined) as T;
   }
-  return isPlainRecord(value) ? ({ ...value, [actionMetaKey]: meta } as T) : value;
+  return isPlainRecord(value) ? ({ ...value, [routeMetaKey]: meta } as T) : value;
 };

package/src/server-entry.ts

@@ -1,7 +1,8 @@
 /** `react-router-effect/server`: serve React Router from the Effect HTTP server. */
 import "./route-data.ts";
 
-export * as ReactRouterHttp from "./server.ts";
+export { ReactRouter } from "./server.ts";
+export * as ReactRouterAssets from "./assets.ts";
 export type {
   RegisterMismatch,
   RouteEffectCheck,