react-router-effect 2.1.0 → 2.2.0

package/dist/vite.mjs

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
-import { Effect } from "effect";
-import { HttpServerRequest, HttpServerResponse } from "effect/http";
+import { Effect, Exit, Layer, Option, Predicate, Scope, SynchronizedRef, Tuple } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import * as NodeHttpServerRequest from "@effect/platform-node/NodeHttpServerRequest";
 // src/vite.ts
-var vite_exports = /* @__PURE__ */ __exportAll({ devMiddleware: () => devMiddleware });
+var vite_exports = /* @__PURE__ */ __exportAll({ layer: () => layer });
 /**
 * Runs Vite's middleware on the Node request. Succeeds with `true` when Vite
 * passes the request on, and `false` when Vite answered it, or the client left
@@ -28,19 +28,53 @@ const passThroughVite = (vite, request, response) => Effect.callback((resume) =>
 	}
 });
 /**
-* Passes each request to Vite first, and the requests Vite passes on to the
-* app. Use it in development only, with Vite in middleware mode:
-*
-* ```ts
-* import { ReactRouterVite } from "react-router-effect/vite";
+* Serves the app in development, as the Express template does. Give it to
+* `HttpRouter.serve` in place of the app's `App`:
 *
+* ```js
 * const vite = await createServer({ server: { middlewareMode: true } });
-* HttpServer.serve(Effect.flatten(reactRouterApp).pipe(ReactRouterVite.devMiddleware(vite)));
+* const App = ReactRouterVite.layer(vite, () =>
+*   vite.ssrLoadModule("./server/app.ts").then((module) => module.App),
+* );
 * ```
 *
-* A request Vite answers gets an empty `HttpServerResponse`, which Effect's
-* Node server does not write, since Vite has ended the Node response. A Vite
-* error fails the request as a defect.
+* The layer registers one catch-all route on the server's router. Its
+* handler passes each request to Vite first. For a request that Vite passes
+* on, it calls `loadApp`. When `loadApp` returns a new `App` value, such as
+* after an edit of the app's server code, the layer builds the new `App` with
+* its own router and closes the old one. Concurrent requests share one build
+* of each `App`. Then the request goes through the current `App`.
+*
+* A request that Vite answers gets an empty `HttpServerResponse`, which
+* Effect's Node server does not write, since Vite has ended the Node
+* response. A defect, such as a Vite error, a `loadApp` that rejects or an
+* `App` that fails to build, goes to the app's loggers, after
+* `ssrFixStacktrace` maps its stack, and the client gets an empty 500.
+*
+* @stability unstable
 */
-const devMiddleware = (vite) => (app) => HttpServerRequest.HttpServerRequest.use((request) => passThroughVite(vite, NodeHttpServerRequest.toIncomingMessage(request), NodeHttpServerRequest.toServerResponse(request)).pipe(Effect.flatMap((passed) => passed ? app : Effect.succeed(HttpServerResponse.empty()))));
+const layer = (vite, loadApp) => HttpRouter.use((router) => Effect.gen(function* () {
+	const layerScope = yield* Effect.scope;
+	const services = yield* Effect.context();
+	/** Builds `app` in `scope`. The services of this layer do not replace either. */
+	const build = (app, scope) => HttpRouter.toHttpEffect(app).pipe(Scope.provide(scope), Effect.provideServiceEffect(Layer.CurrentMemoMap, Layer.makeMemoMap), Effect.provideContext(services));
+	const state = yield* SynchronizedRef.make(Option.none());
+	/** The handler of `app`, built once for each `App` value. */
+	const handlerOf = (app) => SynchronizedRef.modifyEffect(state, (previous) => Effect.gen(function* () {
+		if (Option.isSome(previous) && previous.value.app === app) return Tuple.make(previous.value.handler, previous);
+		const scope = yield* Scope.fork(layerScope);
+		const handler = yield* build(app, scope).pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Scope.close(scope, exit)), Effect.orDie);
+		if (Option.isSome(previous)) yield* Scope.close(previous.value.scope, Exit.void);
+		return Tuple.make(handler, Option.some({
+			app,
+			handler,
+			scope
+		}));
+	}).pipe(Effect.uninterruptible));
+	const handler = HttpServerRequest.HttpServerRequest.use((request) => passThroughVite(vite, NodeHttpServerRequest.toIncomingMessage(request), NodeHttpServerRequest.toServerResponse(request)).pipe(Effect.flatMap((passed) => passed ? Effect.promise(loadApp).pipe(Effect.flatMap(handlerOf), Effect.flatten) : Effect.succeed(HttpServerResponse.empty())), Effect.catchDefect((defect) => {
+		if (Predicate.isError(defect)) vite.ssrFixStacktrace?.(defect);
+		return Effect.logError("Request failed in development", defect).pipe(Effect.as(HttpServerResponse.empty({ status: 500 })));
+	})));
+	yield* router.add("*", "*", handler);
+}));
 export { vite_exports as ReactRouterVite };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Wrap React Router framework-mode route modules with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",
@@ -40,22 +40,24 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
-    "@effect/platform-node": "4.1.1",
+    "@effect/platform-node": "4.1.2",
+    "@effect/tsgo": "0.67.5",
     "@react-router/node": "8.4.0",
     "@types/node": "^25.6.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.4",
-    "@vitest/browser": "5.0.5",
-    "@vitest/browser-playwright": "5.0.5",
-    "effect": "4.1.1",
+    "@vitest/browser": "5.1.0",
+    "@vitest/browser-playwright": "5.1.0",
+    "effect": "4.1.2",
+    "miniflare": "5.20261104.0-beta",
     "playwright": "1.64.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-router": "^8.3.0",
     "typescript": "^7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-    "vite-plus": "^1.4.0",
+    "vite-plus": "^1.5.0",
     "vitest": "5.0.5",
     "vitest-browser-react": "^2.2.0"
   },
@@ -76,6 +78,9 @@
       "onFail": "warn"
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
@@ -83,7 +88,7 @@
     "test:unit": "vp test run --project unit",
     "test:browser": "vp test run --project browser",
     "test:browser:install": "vp exec playwright install chromium",
-    "check": "vp check",
+    "check": "effect-tsgo vp check",
     "check:consumer": "tsc -p test/consumer",
     "changeset": "changeset",
     "changeset:version": "changeset version",

package/src/assets.ts

@@ -0,0 +1,212 @@
+/**
+ * Serves the client build of a React Router app from the app's Effect HTTP
+ * router, as the `express.static` lines of React Router's Express template
+ * do.
+ *
+ * Its API is unstable: a minor version can change it.
+ *
+ * @stability unstable
+ * @since 2.2.0
+ */
+import { Array as Arr, Data, Effect, FileSystem, type Layer, Option, Path } from "effect";
+import {
+  type HttpPlatform,
+  HttpRouter,
+  HttpServerRespondable,
+  HttpStaticServer,
+} from "effect/http";
+import type { ServerBuild } from "react-router";
+
+import { ReactRouter } from "./server.ts";
+
+/**
+ * The layer cannot serve the client build: it cannot read the directory, or
+ * a file name has a `*`, which the router cannot match. The build's
+ * `assetsBuildDirectory` is relative to the working directory of the server,
+ * so `directory` is the path that it resolved to.
+ *
+ * @stability unstable
+ * @since 2.2.0
+ */
+export class ClientBuildError extends Data.TaggedError("ClientBuildError")<{
+  readonly message: string;
+  /** The resolved directory of the client build. */
+  readonly directory: string;
+  readonly cause: unknown;
+}> {}
+
+/** The `Cache-Control` of the files in the hashed directory, whose names include a content hash. */
+const hashedCacheControl = "public, max-age=31536000, immutable";
+
+/** The `Cache-Control` of the other files of the client build. */
+const otherCacheControl = "public, max-age=3600";
+
+/**
+ * The index file of a directory. React Router writes a prerendered page as
+ * the `index.html` of its path's directory, and it is the default index of
+ * `HttpStaticServer.make`.
+ */
+const indexFile = "index.html";
+
+/**
+ * The directory of the hashed files, relative to `publicPath`, from the URL
+ * of the manifest that the build plugin writes in it. `None` when the
+ * manifest is not under `publicPath`, or is at its root.
+ */
+const hashedDirectory = (build: ServerBuild, path: Path.Path): Option.Option<string> => {
+  const manifest = build.assets.url;
+  if (!manifest.startsWith(build.publicPath)) return Option.none();
+  const directory = path.dirname(manifest.slice(build.publicPath.length - 1));
+  return directory === "/" ? Option.none() : Option.some(directory);
+};
+
+/**
+ * The handler of a static server. A missing file is a 404. Any other error,
+ * such as a file that the server cannot read, goes to the app's loggers
+ * before the 500.
+ */
+const makeHandler = (options: {
+  readonly root: string;
+  readonly index: string | undefined;
+  readonly cacheControl: string;
+}) =>
+  HttpStaticServer.make(options).pipe(
+    // Making a static server only resolves its root.
+    Effect.orDie,
+    Effect.map((files) =>
+      files.pipe(
+        Effect.catchReason("HttpServerError", "RouteNotFound", HttpServerRespondable.toResponse),
+        Effect.catch((error) =>
+          Effect.logError("Cannot serve a client file", error).pipe(
+            Effect.andThen(HttpServerRespondable.toResponse(error)),
+          ),
+        ),
+      ),
+    ),
+  );
+
+/**
+ * Registers the routes of the client build on the app's router, for GET and
+ * HEAD, under the build's `publicPath`.
+ *
+ * The hashed directory is the directory of the build's manifest URL, such as
+ * `/assets`. The build plugin writes the files with a content hash in their
+ * names there. Its files are cached for a year as immutable, and a request
+ * under it for a file that the directory does not have gets a 404. The
+ * files are served from that directory only, so a path with `..` does not
+ * reach the other files of the client build.
+ *
+ * Each other file gets its own route, and is cached for an hour. A directory
+ * with an `index.html`, such as a prerendered page, gets a route that serves
+ * its `index.html`, and its path without the trailing slash redirects. The
+ * layer serves no path with a segment that starts with a dot, such as
+ * `.vite/`, as `express.static` ignores dotfiles. A root `index.html`, such
+ * as a prerendered home page, gets the route `/`, which wins over the
+ * catch-all of `ReactRouter.routes`. Any other request goes on to the app's
+ * other routes.
+ *
+ * The layer reads the client build when it builds, so a file that something
+ * adds outside the hashed directory later is served after a restart. It
+ * fails with a {@link ClientBuildError} when it cannot read the client build
+ * directory, or when a file name has a `*`, which the router cannot match.
+ * A route of the app with the path of a file fails the server's start.
+ *
+ * The layer registers nothing for a build that loads for each request, such
+ * as a development build, since Vite serves the client there. It also
+ * registers nothing for a `publicPath` on another origin.
+ *
+ * The routes of this layer get the middleware that the app provides to this
+ * layer. To leave the server's request logger out of file requests:
+ *
+ * ```ts
+ * ReactRouterAssets.layer.pipe(Layer.provide(HttpRouter.disableLogger))
+ * ```
+ *
+ * @stability unstable
+ */
+export const layer: Layer.Layer<
+  never,
+  ClientBuildError,
+  | HttpRouter.HttpRouter
+  | ReactRouter
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpPlatform.HttpPlatform
+> = HttpRouter.use((router) =>
+  Effect.gen(function* () {
+    const { build: loaded } = yield* ReactRouter;
+    if (Option.isNone(loaded)) return;
+    const build = loaded.value;
+    if (!build.publicPath.startsWith("/")) return;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const root = path.resolve(build.assetsBuildDirectory);
+    const readError = (cause: unknown) =>
+      new ClientBuildError({
+        message: `Cannot read the client build at ${root}`,
+        directory: root,
+        cause,
+      });
+    const entries = yield* fileSystem
+      .readDirectory(root, { recursive: true })
+      .pipe(Effect.mapError(readError));
+    const hashed = hashedDirectory(build, path);
+
+    if (Option.isSome(hashed)) {
+      const handler = yield* makeHandler({
+        root: path.join(root, hashed.value),
+        index: undefined,
+        cacheControl: hashedCacheControl,
+      });
+      yield* router
+        .prefixed(build.publicPath)
+        .prefixed(hashed.value)
+        .addAll([HttpRouter.route("GET", "/*", handler), HttpRouter.route("HEAD", "/*", handler)]);
+    }
+
+    /** The URL path of an entry of the client build, relative to `publicPath`. */
+    const urlPath = (entry: string): HttpRouter.PathInput => `/${entry.split(path.sep).join("/")}`;
+    const isServed = (url: string) =>
+      !url.split("/").some((segment) => segment.startsWith(".")) &&
+      Option.match(hashed, {
+        onNone: () => true,
+        onSome: (directory) => url !== directory && !url.startsWith(`${directory}/`),
+      });
+    const files = yield* Effect.filter(
+      entries.filter((entry) => isServed(urlPath(entry))),
+      (entry) =>
+        fileSystem.stat(path.join(root, entry)).pipe(
+          Effect.map((info) => info.type === "File"),
+          Effect.mapError(readError),
+        ),
+    );
+    const directories = files
+      .filter((file) => path.basename(file) === indexFile)
+      .map((file) => path.dirname(file));
+    const urls = Arr.appendAll(
+      files.map(urlPath),
+      // The root directory is `.`, whose URL path is `/`.
+      directories.map((directory) => (directory === "." ? "/" : urlPath(directory))),
+    );
+
+    const unmatchable = Arr.findFirst(urls, (url) => url.includes("*"));
+    if (Option.isSome(unmatchable)) {
+      return yield* new ClientBuildError({
+        message: `Cannot serve ${unmatchable.value} of the client build at ${root}: the router cannot match a * in a path`,
+        directory: root,
+        cause: undefined,
+      });
+    }
+
+    const handler = yield* makeHandler({ root, index: indexFile, cacheControl: otherCacheControl });
+    // A prefix of `/` changes the request URL on every request for nothing.
+    const underPublicPath = build.publicPath === "/" ? router : router.prefixed(build.publicPath);
+    yield* underPublicPath.addAll(
+      urls.flatMap((url) => {
+        // The router reads `:` as the start of a parameter, unless it is doubled.
+        const route: HttpRouter.PathInput = `/${url.slice(1).replaceAll(":", "::")}`;
+        return [HttpRouter.route("GET", route, handler), HttpRouter.route("HEAD", route, handler)];
+      }),
+    );
+  }),
+);

package/src/check.ts

@@ -30,6 +30,8 @@ type FailureMessage =
  *
  * It is an inline object type, not an interface, so the compiler prints its
  * fields in the error rather than an alias name.
+ *
+ * @stability unstable
  */
 export type RouteEffectFailure<Route, Export, Unhandled, Missing, Invalid> = {
   readonly "react-router-effect": FailureMessage;
@@ -112,6 +114,8 @@ type SameType<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
 /**
  * A disagreement between the `Register` of `react-router-effect` and the
  * factory, which would type plain Effect routes' data wrongly.
+ *
+ * @stability unstable
  */
 export interface RegisterMismatch<Key, Factory, Registered> {
   readonly register: Key;
@@ -140,6 +144,8 @@ type Failures<Modules, Types> =
  * The failures of every Effect route function across the route modules React
  * Router's typegen registers, and the registration mismatches, as objects.
  * `never` when everything is handled. `RouteEffectCheck` reports them.
+ *
+ * @stability unstable
  */
 export type RouteEffectFailures<Factory, Modules = RegisteredRouteModules> = Failures<
   Modules,
@@ -199,6 +205,8 @@ type FailureLines<Failure> = Failure extends {
  * factory's runtime and request context. A middleware may also fail with what
  * its `next()` fails with. The check also fails when the `Register` of
  * `react-router-effect` disagrees with the factory.
+ *
+ * @stability unstable
  */
 export type RouteEffectCheck<Factory, Modules = RegisteredRouteModules> = {
   readonly [Line in FailureLines<RouteEffectFailures<Factory, Modules>>]: Line;

package/src/factory.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, type ManagedRuntime } from "effect";
+import { Context, Effect, type ManagedRuntime, Predicate } from "effect";
 import { HttpServerRespondable, HttpServerResponse } from "effect/http";
 import {
   createContext,
@@ -244,6 +244,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 +263,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) }));
@@ -511,11 +517,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
@@ -542,9 +547,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 +577,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 +588,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>(
@@ -705,6 +714,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,

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,