react-router-effect 2.2.0 → 2.3.0

package/README.md

@@ -259,6 +259,79 @@ service-specific error that is not a declared domain error. Catch it or map it.
 defaults for declared errors. The errors of one feature or service need explicit handling.
 [The route check](#the-route-check) reports an unhandled error at compile time.
 
+## Defer data
+
+The route factory returns `defer`. It starts an Effect without waiting for it, and gives a promise
+of the result. Put the promise in the loader data. React Router streams it to `<Await>` after the
+first response. `defer` is unstable: a minor version can change it.
+
+```tsx
+// app/lib/route-factory.server.ts
+export const { Respond, defer } = routeFactory;
+
+// app/routes/product.tsx
+export const loader = Effect.fn("loader.product")(function* ({
+  params,
+}: EffectRouteArgs<Route.LoaderArgs>) {
+  const product = yield* (yield* Products).get(params.id);
+  return {
+    product,
+    reviews: yield* defer((yield* Reviews).list(params.id)),
+    stats: yield* (yield* Stats).load(params.id).pipe(
+      Effect.catchTag("StatsUnavailable", () => Effect.succeed(null)),
+      defer,
+    ),
+  };
+});
+
+export default function Product({ loaderData }: Route.ComponentProps) {
+  return (
+    <Suspense fallback={<p>Loading reviews</p>}>
+      <Await resolve={loaderData.reviews} errorElement={<ReviewsError />}>
+        {(reviews) => <ReviewList reviews={reviews} />}
+      </Await>
+    </Suspense>
+  );
+}
+```
+
+The loader yields `defer`, and the deferred work starts at that point. The work and the rest of the
+loader run at the same time. The work gets the services and the span of the loader, so its spans are in the trace of the request. It
+keeps running after the loader returns. The work stops in two cases:
+
+- The request aborts, for example because the client disconnects.
+- The loader fails after it deferred the work. The response then has no data that waits for it.
+
+A client-side navigation to another page does not abort the request. React Router aborts the request
+of a navigation only while its loaders run. The work then runs until it ends, or until React
+Router's `streamTimeout` ends the stream.
+
+The response starts before the deferred work fails, so a failure cannot redirect or change the
+response. The error handlers of the factory turn a failure into a value or a rejection:
+
+| Failure of the deferred Effect                                  | The promise                                       |
+| --------------------------------------------------------------- | ------------------------------------------------- |
+| A handler recovers it, with `Respond.early` or `Effect.succeed` | resolves with the value → `<Await>`               |
+| `Respond.early(value)` raised directly                          | resolves with `value` → `<Await>`                 |
+| A handler throws it, with `Respond.throw` or `Effect.fail`      | rejects with an `ErrorResponse` → `useAsyncError` |
+| `Respond.throw(value, init)` raised directly                    | rejects with an `ErrorResponse` → `useAsyncError` |
+| A handler redirects, or a domain error has no handler           | rejects with a plain `Error`                      |
+| A defect or an interrupt                                        | rejects with a plain `Error`                      |
+
+The plain `Error` has the message `deferredFailureMessage` (`"Deferred route data failed"`) and no
+stack, in every server mode. The server logs the full cause of a defect. A recovered
+`Respond.early(value, init)` gives `value` without `init`, because a promise has no response.
+
+The deferred Effect can fail only with the factory's domain errors, `Respond.early` and
+`Respond.throw`. Any other error does not compile, and the message names the error tags. Handle
+those errors before `defer`, or make them defects with `Effect.orDie`. In a factory without domain
+errors, the deferred Effect must fail with `never`.
+
+The promise type includes what the handlers recover, so `Route.ComponentProps` types the value that
+`<Await>` renders. The type is `DeferredPromise<A>`, a subtype of `Promise<A>`. The
+`promiseInEffectSuccess` rule of the Effect language service reports only the global `Promise`
+type, so it does not report a `yield* defer(...)`.
+
 ## Provide services
 
 ### App-wide services with a runtime
@@ -378,7 +451,9 @@ routes.
 
 The adapter's API is unstable, and a minor version can change it. Every export of
 `react-router-effect/server` and `react-router-effect/vite` has the JSDoc tag `@stability unstable`.
-The route factory and the other exports of `react-router-effect` are stable.
+The route factory and the other exports of `react-router-effect` are stable, except the route
+metadata. The `routeMeta` configuration, the `Register` key `routeMeta`, `RouteMetaArgs`,
+`WithRouteMeta` and `routeMetaKey` are unstable, and a minor version can change them.
 
 React Router keeps doing what it does for any other server adapter: documents, `.data` requests,
 streamed promises, resource routes, the lazy route manifest and middleware. Before React Router
@@ -628,10 +703,10 @@ export const middleware = [
   `Route.ComponentProps` types the data of an Effect loader or action, including what the factory
   recovers.
   - Hooks that take `typeof loader` or `typeof action`, such as `useFetcher<typeof action>()`,
-    read the data through React Router's `SerializeFrom`. It treats a function as a client
-    function when its argument has the members of client loader args, and gives client functions
-    their raw return value. Typegen's `Route.LoaderArgs` and `Route.ActionArgs` have those same
-    members, so for an Effect the hook would type the data as the Effect itself.
+    read the data through React Router's `SerializeFrom`. If the argument of a function has the
+    members of client loader args, `SerializeFrom` treats it as a client function. It gives a
+    client function its raw return value. Typegen's `Route.LoaderArgs` and `Route.ActionArgs` have
+    those same members, so for an Effect the hook types the data as the Effect itself.
   - Take the args through `EffectRouteArgs<Route.LoaderArgs>`. It makes `pattern` optional, so the
     argument no longer matches and the hook reads the brand. A loader without args needs nothing.
   - `RouteData<typeof loader>` reads the brand directly and applies React Router's serialization.
@@ -641,8 +716,8 @@ export const middleware = [
   and the span that it provides around `next()` reach every route Effect downstream. `context.set`
   keeps working. You cannot annotate a route array with an effect middleware as
   `Route.MiddlewareFunction[]`.
-- Action metadata: `actionMeta` in the factory config is read after every action resolves. The
-  adapter attaches it to the action's data under `__meta`.
+- Route metadata: `routeMeta` in the factory configuration is read after every loader and action
+  resolves. The adapter attaches it to their data under `__meta`.
 - Tests: `routeFactory.handlers.loader(loader)(args)` runs a route function as the server does.
 
 ### Register what the factory recovers
@@ -653,7 +728,7 @@ A plain Effect loader cannot see the factory's handlers. Declare what they recov
 declare module "react-router-effect" {
   interface Register {
     recover: { FormValidationError: { reply: SubmissionResponse } };
-    actionMeta: { realtimeEventIds: ReadonlyArray<string> };
+    routeMeta: { realtimeEventIds: ReadonlyArray<string> };
   }
 }
 ```
@@ -811,8 +886,8 @@ export const loader = makeLoader(() =>
 
 ## API
 
-- `makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond?, actionMeta? }))`
-  returns `{ makeLoader, makeAction, makeMiddleware, Respond, handlers }`. The config is a builder
+- `makeEffectRouteFactory<DomainErrors>()((Respond) => ({ errorHandlers?, runtime?, requestContext?, respond?, routeMeta? }))`
+  returns `{ makeLoader, makeAction, makeMiddleware, Respond, defer, handlers }`. 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, and the base helpers win. `makeLoader` and
   `makeAction` are the same wrapper. `makeMiddleware` wraps a `Route.MiddlewareFunction`, and
@@ -820,6 +895,9 @@ export const loader = makeLoader(() =>
 - `handlers` (`loader`, `action`, `middleware`, `requestContext`) is the runner that the server
   adapter applies to every route module.
 - `Respond` has `early` (recover), `throw` and `redirect`, and the `respond` helpers that you add.
+- `defer` (unstable) starts an Effect and gives a `DeferredPromise` of its result for loader data.
+  Read [Defer data](#defer-data). The types `DeferredPromise`, `DeferDiagnose`, `DeferHandled` and
+  `DeferRecoverOf`, and the constant `deferredFailureMessage`, go with it.
 - `ReturnableDataError`, `ThrowableDataError` and `ThrowableRedirectError` are the library route
   errors. `isRouteError` narrows them.
 - `ErrorHandler<Err>` is the handler signature type.

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { C as ReturnableDataError, D as WithActionMeta, E as isRouteError, O as actionMetaKey, S as AnyRouteError, T as ThrowableRedirectError, a as RegisteredMeta, b as RouteResult, c as Serialize, d as EffectNext, f as ErrorHandler, i as Register, l as ActionMetaArgs, n as EffectData, o as RegisteredRecover, p as FactoryTypes, r as EffectRouteArgs, s as RouteData, t as BrandData, u as EffectMiddlewareArgs, v as RequestContextKey, w as ThrowableDataError, x as makeEffectRouteFactory, y as RouteHandlers } from "./route-data-CWBxnNAA.mjs";
-export { type ActionMetaArgs, type AnyRouteError, type BrandData, type EffectData, type EffectMiddlewareArgs, type EffectNext, type EffectRouteArgs, type ErrorHandler, type FactoryTypes, type Register, type RegisteredMeta, type RegisteredRecover, type RequestContextKey, ReturnableDataError, type RouteData, type RouteHandlers, type RouteResult, type Serialize, ThrowableDataError, ThrowableRedirectError, type WithActionMeta, actionMetaKey, isRouteError, makeEffectRouteFactory };
+import { A as ThrowableRedirectError, C as RouteHandlers, D as AnyRouteError, E as makeEffectRouteFactory, M as WithRouteMeta, N as routeMetaKey, O as ReturnableDataError, S as RequestContextKey, T as RouteResult, _ as FactoryTypes, a as RegisteredMeta, c as Serialize, d as deferredFailureMessage, f as DeferHandled, g as ErrorHandler, h as EffectNext, i as Register, j as isRouteError, k as ThrowableDataError, l as DeferDiagnose, m as EffectMiddlewareArgs, n as EffectData, o as RegisteredRecover, p as DeferRecoverOf, r as EffectRouteArgs, s as RouteData, t as BrandData, u as DeferredPromise, w as RouteMetaArgs } from "./route-data-ByiuG-Yb.mjs";
+export { type AnyRouteError, type BrandData, type DeferDiagnose, type DeferHandled, type DeferRecoverOf, type DeferredPromise, type EffectData, type EffectMiddlewareArgs, type EffectNext, type EffectRouteArgs, type ErrorHandler, type FactoryTypes, type Register, type RegisteredMeta, type RegisteredRecover, type RequestContextKey, ReturnableDataError, type RouteData, type RouteHandlers, type RouteMetaArgs, type RouteResult, type Serialize, ThrowableDataError, ThrowableRedirectError, type WithRouteMeta, deferredFailureMessage, isRouteError, makeEffectRouteFactory, routeMetaKey };

package/dist/index.mjs

@@ -1,12 +1,15 @@
-import { Context, Data, Effect, Predicate } from "effect";
-import { createContext, data, redirect } from "react-router";
+import { Cause, Context, Data, Effect, Exit, Option, Predicate, Scope } from "effect";
+import { UNSAFE_ErrorResponseImpl, createContext, data, redirect } from "react-router";
 import { HttpServerRespondable, HttpServerResponse } from "effect/http";
-// src/action-meta.ts
-/** The key that holds the metadata in action data. */
-const actionMetaKey = "__meta";
-const DataWithResponseInitClass = data(void 0).constructor;
-/** True for a `data(...)` wrapper, never for a business field that looks like one. */
-const isDataWithResponseInit = (value) => value instanceof DataWithResponseInitClass;
+// src/route-meta.ts
+/** The key that holds the metadata in loader and action data. */
+const routeMetaKey = "__meta";
+/**
+* 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) => 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) => {
 	if (!Predicate.isObject(value) || Array.isArray(value)) return false;
@@ -14,21 +17,21 @@ const isPlainRecord = (value) => {
 	return prototype === Object.prototype || prototype === null;
 };
 /**
-* 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.
 */
-const attachActionMeta = (value, meta) => {
+const attachRouteMeta = (value, meta) => {
 	if (isDataWithResponseInit(value)) {
 		if (!isPlainRecord(value.data)) return value;
 		return data({
 			...value.data,
-			[actionMetaKey]: meta
+			[routeMetaKey]: meta
 		}, value.init ?? void 0);
 	}
 	return isPlainRecord(value) ? {
 		...value,
-		[actionMetaKey]: meta
+		[routeMetaKey]: meta
 	} : value;
 };
 // src/errors.ts
@@ -72,6 +75,84 @@ const Respond = {
 };
 /** Narrows an unknown value to one of the library's route errors. */
 const isRouteError = (value) => value instanceof ReturnableDataError || value instanceof ThrowableDataError || value instanceof ThrowableRedirectError;
+// src/defer.ts
+/**
+* The scope that deferred work forks into. The route runner sets it for each
+* loader or action run, and closes it when the request aborts or the route
+* Effect fails. Outside a route runner it is unset, and deferred work runs
+* detached.
+*/
+const DeferScope = Context.Reference("react-router-effect/DeferScope", { defaultValue: () => void 0 });
+/**
+* Gives a route Effect a scope for its deferred work. The scope closes, and
+* interrupts the deferred fibers, when `signal` aborts or the Effect fails: a
+* failed loader sends no data, so no `<Await>` waits for the work.
+*/
+const withDeferScope = (effect, signal) => Effect.suspend(() => {
+	const scope = Scope.makeUnsafe("parallel");
+	const close = (exit) => Scope.close(scope, exit);
+	signal.addEventListener("abort", () => Effect.runFork(close(Exit.interrupt())), { once: true });
+	return effect.pipe(Effect.provideService(DeferScope, scope), Effect.onError((cause) => close(Exit.failCause(cause))));
+});
+/**
+* The message every deferred rejection has. The server logs the cause.
+*
+* @stability unstable
+*/
+const deferredFailureMessage = "Deferred route data failed";
+/**
+* The rejection the browser gets for a defect or an interrupt: a constant
+* message and no stack, in every server mode. React Router removes server
+* details only in production.
+*/
+const deferredFailure = () => {
+	const error = /* @__PURE__ */ new Error(deferredFailureMessage);
+	error.stack = void 0;
+	return error;
+};
+/**
+* Forks `self` into the run's defer scope and gives a promise of its result.
+* A failure rejects the promise with its `ErrorResponse`, which React Router
+* streams to `useAsyncError`. A defect or interrupt rejects it with
+* `deferredFailure`, and the server logs a defect's full cause.
+*/
+const forkDeferred = (self) => Effect.gen(function* () {
+	const scope = yield* DeferScope;
+	const work = self.pipe(Effect.tapCause((cause) => Cause.hasDies(cause) ? Effect.logError(deferredFailureMessage, cause) : Effect.void));
+	const fiber = yield* scope === void 0 ? Effect.forkDetach(work) : Effect.forkIn(work, scope);
+	const promise = new Promise((resolve, reject) => {
+		fiber.addObserver((exit) => {
+			if (Exit.isSuccess(exit)) return resolve(exit.value);
+			reject(Cause.hasDies(exit.cause) ? deferredFailure() : Option.getOrElse(Cause.findErrorOption(exit.cause), deferredFailure));
+		});
+	});
+	promise.catch(() => void 0);
+	return promise;
+});
+/** A thrown `data(...)` as an `ErrorResponse`, with React Router's defaults. */
+const toErrorResponse = (thrown) => new UNSAFE_ErrorResponseImpl(thrown.init?.status ?? 500, thrown.init?.statusText ?? "Internal Server Error", thrown.data);
+/**
+* A library route error raised in deferred work: `Respond.early` resolves the
+* promise with its value, and `Respond.throw` rejects it with an
+* `ErrorResponse`. A redirect cannot happen after the response started, so it
+* is a defect.
+*/
+const deferRouteError = (e) => {
+	if (e instanceof ReturnableDataError) return Effect.succeed(e.data);
+	if (e instanceof ThrowableDataError) return Effect.fail(toErrorResponse(data(e.data, e.init)));
+	return Effect.die(e);
+};
+/**
+* A handler's `Effect.fail(response)` in deferred work, as an `ErrorResponse`:
+* a `data(...)` as React Router converts a thrown one, and a `Response` with
+* its body read as React Router reads it, JSON or text. A redirect is a defect.
+*/
+const deferFailureResponse = (failure) => {
+	if (!(failure instanceof Response)) return Effect.fail(toErrorResponse(failure));
+	if (failure.status >= 300 && failure.status < 400) return Effect.die(failure);
+	const isJson = /\bapplication\/json\b/.test(failure.headers.get("Content-Type") ?? "");
+	return Effect.promise(() => isJson && failure.body !== null ? failure.json() : failure.text()).pipe(Effect.flatMap((body) => Effect.fail(new UNSAFE_ErrorResponseImpl(failure.status, failure.statusText, body))));
+};
 // src/factory.ts
 const internalServerError = () => Effect.fail(new Response("Internal Server Error", { status: 500 }));
 /**
@@ -197,7 +278,7 @@ function makeEffectRouteFactory() {
 		* - they differ only in how they build the effect and what `context` they read.
 		*/
 		function runProgram(effect, context, signal) {
-			const program = effect.pipe(Effect.catchIf((_e) => true, (e) => {
+			const program = withDeferScope(effect, signal).pipe(Effect.catchIf((_e) => true, (e) => {
 				for (const tag of userTags) if (Predicate.isTagged(e, tag)) {
 					const out = userHandlers[tag](e);
 					return isRouteError(out) ? processRouteError(out) : out;
@@ -269,19 +350,74 @@ function makeEffectRouteFactory() {
 		function runResult(result, args) {
 			return Effect.isEffect(result) ? runProgram(result, args.context, args.request.signal) : 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) {
+			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(self) {
+			const work = self.pipe(Effect.catch(dispatchDeferred));
+			return forkDeferred(work);
+		}
+		const routeMeta = config.routeMeta;
+		/** Runs a loader or action's result and attaches the route metadata to its data. */
+		async function withRouteMeta(result, args) {
+			const resolved = await runResult(result, args);
+			return routeMeta === void 0 ? resolved : attachRouteMeta(resolved, routeMeta(args));
+		}
 		return {
 			makeLoader: makeLoaderOrAction,
 			makeAction: makeLoaderOrAction,
 			makeMiddleware,
 			Respond: Respond$1,
+			defer,
 			/** The route runner the server adapter applies to every route module. */
 			handlers: {
-				loader: (fn) => async (args) => runResult(fn(args), args),
-				action: (fn) => async (args) => {
-					const result = await runResult(fn(args), args);
-					return actionMeta === void 0 ? result : attachActionMeta(result, actionMeta(args));
-				},
+				loader: (fn) => async (args) => await withRouteMeta(fn(args), args),
+				action: (fn) => async (args) => await withRouteMeta(fn(args), args),
 				middleware: (fn) => async (args, next) => {
 					const routeArgs = args;
 					return runResult(fn({
@@ -296,4 +432,4 @@ function makeEffectRouteFactory() {
 		};
 	};
 }
-export { ReturnableDataError, ThrowableDataError, ThrowableRedirectError, actionMetaKey, isRouteError, makeEffectRouteFactory };
+export { ReturnableDataError, ThrowableDataError, ThrowableRedirectError, deferredFailureMessage, isRouteError, makeEffectRouteFactory, routeMetaKey };

package/dist/{route-data-CWBxnNAA.d.mts → route-data-ByiuG-Yb.d.mts}

@@ -1,22 +1,22 @@
-import { Context, Effect, ManagedRuntime } from "effect";
+import { Context, Effect, ManagedRuntime, Scope } from "effect";
 import { ActionFunctionArgs, LoaderFunctionArgs, MiddlewareFunction, RouterContext, RouterContextProvider, UNSAFE_DataWithResponseInit, useLoaderData } from "react-router";
 import { HttpServerRespondable } from "effect/http";
-/** The key that holds the metadata in action data. */
-declare const actionMetaKey = "__meta";
+/** The key that holds the metadata in loader and action data. */
+declare const routeMetaKey = "__meta";
 /**
  * Adds optional metadata to a record. Only records get metadata, because a
  * structural type cannot tell a plain object from a class instance, and other
  * 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;
+type RecordWithMeta<T, Meta> = 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.
  */
-type WithActionMeta<T, Meta> = [Meta] extends [never] ? T : T extends UNSAFE_DataWithResponseInit<infer Body> ? UNSAFE_DataWithResponseInit<RecordWithMeta<Body, Meta>> : RecordWithMeta<T, Meta>;
+type WithRouteMeta<T, Meta> = [Meta] extends [never] ? T : T extends UNSAFE_DataWithResponseInit<infer Body> ? UNSAFE_DataWithResponseInit<RecordWithMeta<Body, Meta>> : RecordWithMeta<T, Meta>;
 declare const ReturnableDataError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "ReturnableRouteError";
 } & Readonly<A>;
@@ -144,6 +144,25 @@ type ErrorHandlers<DomainError extends Tagged, Returns> = { [Tag in keyof Return
 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];
+/**
+ * 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
+ */
+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
+ */
+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:
@@ -238,8 +257,8 @@ type Diagnose<E, R, DomainError, Provided, AlsoHandled = never> = IsAny<E> exten
  * ```
  */
 type RequestContextKey<ReqServices> = RouterContext<Context.Context<ReqServices>>;
-/** What `actionMeta` reads: the request and the router context of the action. */
-interface ActionMetaArgs {
+/** What `routeMeta` reads: the request and the router context of the loader or action. */
+interface RouteMetaArgs {
   readonly request: Request;
   readonly context: Readonly<RouterContextProvider>;
 }
@@ -405,27 +424,61 @@ declare 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;
 }) => {
-  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 | DirectRecover<E> | RecoverOf<DomainError, Returns, 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<WithActionMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>>;
+  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<WithRouteMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>>;
+  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<WithRouteMeta<A | DirectRecover<E> | RecoverOf<DomainError, Returns, E>, Meta>>;
   makeMiddleware: <Middleware extends AnyMiddlewareFunction = MiddlewareFunction, E = LibraryHandled<DomainError, FailureResponse>, R = RServices | ReqServices>(fn: (args: MiddlewareArgsOf<Middleware>, next: () => Effect.Effect<MiddlewareResultOf<Middleware>, FailureResponse>) => Effect.Effect<MiddlewareResultOf<Middleware> | void, E, R> & Diagnose<E, R, DomainError, RServices | ReqServices, FailureResponse>) => (args: MiddlewareArgsOf<Middleware>, next: MiddlewareNextOf<Middleware>) => Promise<MiddlewareResultOf<Middleware> | undefined>;
   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;
+  defer: <A, E, R>(self: Effect.Effect<A, E, R> & DeferDiagnose<E, DeferHandled<DomainError>>) => Effect.Effect<DeferredPromise<A | DeferRecoverOf<DomainError, Returns, E>>, never, R>;
   /** The route runner the server adapter applies to every route module. */
   handlers: RouteHandlers;
   /** Type-only: what the adapter's route check and `Register` read. */
   "~types": FactoryTypes<DomainError, Returns, RServices | ReqServices, Meta>;
 };
+/**
+ * The compile-time diagnostic of the factory's `defer`. A deferred Effect
+ * runs after the response started, so a failure cannot change the response.
+ * The Effect must handle every error it can fail with before it is deferred,
+ * except the `Handled` ones, which the error handlers turn into a value or an
+ * `ErrorResponse`. Resolves to `unknown` (a no-op intersection) when every
+ * error is handled.
+ *
+ * @stability unstable
+ */
+type DeferDiagnose<E, Handled> = IsAny<E> extends true ? unknown : [Exclude<E, Handled>] extends [never] ? unknown : {
+  "react-router-effect": "A deferred effect runs after the response started, so it can fail only with the factory's domain errors, Respond.early and Respond.throw. Handle the other errors before defer: recover them into data (e.g. Effect.catchTag), or make them defects with Effect.orDie.";
+  unhandledErrors: NameError<Exclude<E, Handled>>;
+};
+/**
+ * The promise that the factory's `defer` gives: a `Promise` of the deferred Effect's
+ * success, which React Router streams to `<Await>`. The work started when the
+ * Effect was deferred.
+ *
+ * It is a type of its own so that an Effect that succeeds with it states
+ * that the promise is not awaited on purpose. The language service's
+ * `promiseInEffectSuccess` rule reports only the global `Promise` type.
+ *
+ * @stability unstable
+ */
+interface DeferredPromise<A> extends Promise<A> {}
+/**
+ * The message every deferred rejection has. The server logs the cause.
+ *
+ * @stability unstable
+ */
+declare const deferredFailureMessage = "Deferred route data failed";
 /**
  * Registers what the app's route factory turns failures into, so that a
  * loader or action written as a plain `Effect.fn` types its data the way a
@@ -446,8 +499,8 @@ declare function makeEffectRouteFactory<DomainError extends Tagged = never>(): <
  *   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> };
  *   }
  * }
  * ```
@@ -457,9 +510,9 @@ interface Register$1 {}
 type RegisteredRecover = Register$1 extends {
   readonly recover: infer Recover;
 } ? Recover : {};
-/** The registered action metadata, or `never` when there is none. */
+/** The registered route metadata, or `never` when there is none. */
 type RegisteredMeta = Register$1 extends {
-  readonly actionMeta: infer Meta;
+  readonly routeMeta: infer Meta;
 } ? Meta : never;
 /** What a failure of type `E` recovers into: `Respond.early` bodies and registered handlers. */
 type Recovered<E> = (E extends ReturnableDataError<infer Body> ? Body : never) | (E extends {
@@ -474,9 +527,9 @@ 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.
  */
-type EffectData<A, E> = WithActionMeta<Serialize<A | Recovered<E>>, RegisteredMeta>;
+type EffectData<A, E> = WithRouteMeta<Serialize<A | Recovered<E>>, RegisteredMeta>;
 /**
  * The route data of a loader or action, for React Router's hooks:
  * `useFetcher<RouteData<typeof action>>()`. A function that returns an Effect
@@ -513,7 +566,7 @@ type Unwrapped<A> = A extends Response ? never : A extends UNSAFE_DataWithRespon
  * checks library types (`skipLibCheck: false`) then gets TS2636 in Effect's own
  * declarations. `test/consumer` checks the built package for that.
  */
-type BrandData<A, E> = [A] extends [never] ? WithActionMeta<Recovered<E>, RegisteredMeta> : [A] extends [void] ? unknown : WithActionMeta<Unwrapped<A> | Recovered<E>, RegisteredMeta>;
+type BrandData<A, E> = [A] extends [never] ? WithRouteMeta<Recovered<E>, RegisteredMeta> : [A] extends [void] ? unknown : WithRouteMeta<Unwrapped<A> | Recovered<E>, RegisteredMeta>;
 declare module "effect/Effect" {
   interface Effect<out A, out E, out R> {
     readonly unstable__ReactRouter_SerializesTo: [BrandData<A, E>];
@@ -546,4 +599,4 @@ type EffectRouteArgs<Args extends {
 }> = Omit<Args, "pattern"> & {
   readonly pattern?: string;
 };
-export { ReturnableDataError as C, WithActionMeta as D, isRouteError as E, actionMetaKey as O, AnyRouteError as S, ThrowableRedirectError as T, NameError as _, RegisteredMeta as a, RouteResult as b, Serialize as c, EffectNext as d, ErrorHandler as f, LibraryHandled as g, IsAny as h, Register$1 as i, ActionMetaArgs as l, FailureResponse as m, EffectData as n, RegisteredRecover as o, FactoryTypes as p, EffectRouteArgs as r, RouteData as s, BrandData as t, EffectMiddlewareArgs as u, RequestContextKey as v, ThrowableDataError as w, makeEffectRouteFactory as x, RouteHandlers as y };
+export { ThrowableRedirectError as A, RouteHandlers as C, AnyRouteError as D, makeEffectRouteFactory as E, WithRouteMeta as M, routeMetaKey as N, ReturnableDataError as O, RequestContextKey as S, RouteResult as T, FactoryTypes as _, RegisteredMeta as a, LibraryHandled as b, Serialize as c, deferredFailureMessage as d, DeferHandled as f, ErrorHandler as g, EffectNext as h, Register$1 as i, isRouteError as j, ThrowableDataError as k, DeferDiagnose as l, EffectMiddlewareArgs as m, EffectData as n, RegisteredRecover as o, DeferRecoverOf as p, EffectRouteArgs as r, RouteData as s, BrandData as t, DeferredPromise as u, FailureResponse as v, RouteMetaArgs as w, NameError as x, IsAny as y };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { C as ReturnableDataError, _ as NameError, a as RegisteredMeta, g as LibraryHandled, h as IsAny, m as FailureResponse, o as RegisteredRecover, p as FactoryTypes, y as RouteHandlers } from "./route-data-CWBxnNAA.mjs";
+import { C as RouteHandlers, O as ReturnableDataError, _ as FactoryTypes, a as RegisteredMeta, b as LibraryHandled, o as RegisteredRecover, v as FailureResponse, x as NameError, y as IsAny } from "./route-data-ByiuG-Yb.mjs";
 import { Context, Effect, FileSystem, Layer, Option, Path, Scope } from "effect";
 import { Register, RouterContextProvider, ServerBuild } from "react-router";
 import { HttpPlatform, HttpRouter, HttpServerError, HttpServerRequest, HttpServerResponse } from "effect/http";
@@ -227,7 +227,7 @@ interface RegisterMismatch<Key, Factory, Registered> {
   readonly registered: Registered;
 }
 /** The registration mismatches of a factory's types. */
-type RegisterMismatches<Returns, Meta> = (SameType<FactoryRecover<Returns>, RegisteredRecover> extends true ? never : RegisterMismatch<"recover", FactoryRecover<Returns>, RegisteredRecover>) | (SameType<Meta, RegisteredMeta> extends true ? never : RegisterMismatch<"actionMeta", Meta, RegisteredMeta>);
+type RegisterMismatches<Returns, Meta> = (SameType<FactoryRecover<Returns>, RegisteredRecover> extends true ? never : RegisterMismatch<"recover", FactoryRecover<Returns>, RegisteredRecover>) | (SameType<Meta, RegisteredMeta> extends true ? never : RegisterMismatch<"routeMeta", Meta, RegisteredMeta>);
 /** Every failure: the routes', then the registration's. */
 type Failures<Modules, Types> = Types extends FactoryTypes<infer DomainError, infer Returns, infer Services, infer Meta> ? AllFailures<Modules, LibraryHandled<DomainError>, Services> | RegisterMismatches<Returns, Meta> : never;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Wrap React Router framework-mode route modules with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",

package/src/check.ts

@@ -130,7 +130,7 @@ type RegisterMismatches<Returns, Meta> =
       : RegisterMismatch<"recover", FactoryRecover<Returns>, RegisteredRecover>)
   | (SameType<Meta, RegisteredMeta> extends true
       ? never
-      : RegisterMismatch<"actionMeta", Meta, RegisteredMeta>);
+      : RegisterMismatch<"routeMeta", Meta, RegisteredMeta>);
 
 /** Every failure: the routes', then the registration's. */
 type Failures<Modules, Types> =

package/src/defer.ts

@@ -0,0 +1,179 @@
+import { Cause, Context, Effect, Exit, Option, Scope } from "effect";
+import {
+  data,
+  UNSAFE_ErrorResponseImpl as ErrorResponseImpl,
+  type ErrorResponse,
+  type UNSAFE_DataWithResponseInit as DataWithResponseInit,
+} from "react-router";
+
+import { ReturnableDataError, ThrowableDataError, type AnyRouteError } from "./errors.ts";
+import type { FailureResponse, IsAny, NameError } from "./factory.ts";
+
+// ---------------------------------------------------------------------------
+// The scope of deferred work.
+// ---------------------------------------------------------------------------
+
+/**
+ * The scope that deferred work forks into. The route runner sets it for each
+ * loader or action run, and closes it when the request aborts or the route
+ * Effect fails. Outside a route runner it is unset, and deferred work runs
+ * detached.
+ */
+export const DeferScope = Context.Reference<Scope.Scope | undefined>(
+  "react-router-effect/DeferScope",
+  { defaultValue: () => undefined },
+);
+
+/**
+ * Gives a route Effect a scope for its deferred work. The scope closes, and
+ * interrupts the deferred fibers, when `signal` aborts or the Effect fails: a
+ * failed loader sends no data, so no `<Await>` waits for the work.
+ */
+export const withDeferScope = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  signal: AbortSignal,
+): Effect.Effect<A, E, R> =>
+  Effect.suspend(() => {
+    const scope = Scope.makeUnsafe("parallel");
+    const close = <X, Y>(exit: Exit.Exit<X, Y>) => Scope.close(scope, exit);
+    signal.addEventListener("abort", () => Effect.runFork(close(Exit.interrupt())), {
+      once: true,
+    });
+    return effect.pipe(
+      Effect.provideService(DeferScope, scope),
+      Effect.onError((cause) => close(Exit.failCause(cause))),
+    );
+  });
+
+// ---------------------------------------------------------------------------
+// The deferred promise.
+// ---------------------------------------------------------------------------
+
+/**
+ * The compile-time diagnostic of the factory's `defer`. A deferred Effect
+ * runs after the response started, so a failure cannot change the response.
+ * The Effect must handle every error it can fail with before it is deferred,
+ * except the `Handled` ones, which the error handlers turn into a value or an
+ * `ErrorResponse`. Resolves to `unknown` (a no-op intersection) when every
+ * error is handled.
+ *
+ * @stability unstable
+ */
+export type DeferDiagnose<E, Handled> =
+  IsAny<E> extends true
+    ? unknown
+    : [Exclude<E, Handled>] extends [never]
+      ? unknown
+      : {
+          "react-router-effect": "A deferred effect runs after the response started, so it can fail only with the factory's domain errors, Respond.early and Respond.throw. Handle the other errors before defer: recover them into data (e.g. Effect.catchTag), or make them defects with Effect.orDie.";
+          unhandledErrors: NameError<Exclude<E, Handled>>;
+        };
+
+/**
+ * The promise that the factory's `defer` gives: a `Promise` of the deferred Effect's
+ * success, which React Router streams to `<Await>`. The work started when the
+ * Effect was deferred.
+ *
+ * It is a type of its own so that an Effect that succeeds with it states
+ * that the promise is not awaited on purpose. The language service's
+ * `promiseInEffectSuccess` rule reports only the global `Promise` type.
+ *
+ * @stability unstable
+ */
+export interface DeferredPromise<A> extends Promise<A> {}
+
+/**
+ * The message every deferred rejection has. The server logs the cause.
+ *
+ * @stability unstable
+ */
+export const deferredFailureMessage = "Deferred route data failed";
+
+/**
+ * The rejection the browser gets for a defect or an interrupt: a constant
+ * message and no stack, in every server mode. React Router removes server
+ * details only in production.
+ */
+const deferredFailure = (): Error => {
+  const error = new Error(deferredFailureMessage);
+  error.stack = undefined;
+  return error;
+};
+
+/**
+ * Forks `self` into the run's defer scope and gives a promise of its result.
+ * A failure rejects the promise with its `ErrorResponse`, which React Router
+ * streams to `useAsyncError`. A defect or interrupt rejects it with
+ * `deferredFailure`, and the server logs a defect's full cause.
+ */
+export const forkDeferred = <A, R>(
+  self: Effect.Effect<A, ErrorResponse, R>,
+): Effect.Effect<DeferredPromise<A>, never, R> =>
+  Effect.gen(function* () {
+    const scope = yield* DeferScope;
+    const work = self.pipe(
+      Effect.tapCause((cause) =>
+        Cause.hasDies(cause) ? Effect.logError(deferredFailureMessage, cause) : Effect.void,
+      ),
+    );
+    const fiber = yield* scope === undefined ? Effect.forkDetach(work) : Effect.forkIn(work, scope);
+    const promise: DeferredPromise<A> = new Promise<A>((resolve, reject) => {
+      fiber.addObserver((exit) => {
+        if (Exit.isSuccess(exit)) return resolve(exit.value);
+        reject(
+          Cause.hasDies(exit.cause)
+            ? deferredFailure()
+            : Option.getOrElse(Cause.findErrorOption(exit.cause), deferredFailure),
+        );
+      });
+    });
+    // Marks the rejection handled, so a promise that React Router never reads,
+    // because the loader failed after it deferred, is not an unhandled rejection.
+    // `<Await>` still reads the rejection from `promise` itself.
+    promise.catch(() => undefined);
+    return promise;
+  });
+
+// ---------------------------------------------------------------------------
+// Route errors in deferred work.
+// ---------------------------------------------------------------------------
+
+/** A thrown `data(...)` as an `ErrorResponse`, with React Router's defaults. */
+const toErrorResponse = (thrown: DataWithResponseInit<unknown>): ErrorResponse =>
+  new ErrorResponseImpl(
+    thrown.init?.status ?? 500,
+    thrown.init?.statusText ?? "Internal Server Error",
+    thrown.data,
+  );
+
+/**
+ * A library route error raised in deferred work: `Respond.early` resolves the
+ * promise with its value, and `Respond.throw` rejects it with an
+ * `ErrorResponse`. A redirect cannot happen after the response started, so it
+ * is a defect.
+ */
+export const deferRouteError = (e: AnyRouteError): Effect.Effect<unknown, ErrorResponse> => {
+  if (e instanceof ReturnableDataError) return Effect.succeed(e.data);
+  if (e instanceof ThrowableDataError) return Effect.fail(toErrorResponse(data(e.data, e.init)));
+  return Effect.die(e);
+};
+
+/**
+ * A handler's `Effect.fail(response)` in deferred work, as an `ErrorResponse`:
+ * a `data(...)` as React Router converts a thrown one, and a `Response` with
+ * its body read as React Router reads it, JSON or text. A redirect is a defect.
+ */
+export const deferFailureResponse = (
+  failure: FailureResponse,
+): Effect.Effect<never, ErrorResponse> => {
+  if (!(failure instanceof Response)) return Effect.fail(toErrorResponse(failure));
+  if (failure.status >= 300 && failure.status < 400) return Effect.die(failure);
+  const isJson = /\bapplication\/json\b/.test(failure.headers.get("Content-Type") ?? "");
+  return Effect.promise(() =>
+    isJson && failure.body !== null ? failure.json() : failure.text(),
+  ).pipe(
+    Effect.flatMap((body) =>
+      Effect.fail(new ErrorResponseImpl(failure.status, failure.statusText, body)),
+    ),
+  );
+};

package/src/factory.ts

@@ -5,6 +5,7 @@ import {
   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:
@@ -280,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>;
 }
@@ -494,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);
@@ -537,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
@@ -602,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>
         >;
     }
 
@@ -722,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`.
@@ -730,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`
@@ -752,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;
 };