react-router-effect 2.0.0 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Wrap React Router framework-mode route modules with Effect, with typed recover/throw/redirect error handling.",
   "keywords": [
     "action",
@@ -30,6 +30,8 @@
   "type": "module",
   "exports": {
     ".": "./dist/index.mjs",
+    "./server": "./dist/server.mjs",
+    "./vite": "./dist/vite.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -38,27 +40,37 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
+    "@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.4",
-    "@vitest/browser-playwright": "5.0.4",
-    "effect": "4.0.5",
-    "playwright": "1.60.0",
+    "@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.3.0",
-    "vitest": "5.0.4",
+    "vite-plus": "^1.5.0",
+    "vitest": "5.0.5",
     "vitest-browser-react": "^2.2.0"
   },
   "peerDependencies": {
-    "effect": "^4.0.0",
+    "@effect/platform-node": "^4.1.0",
+    "effect": "^4.1.0",
     "react-router": "^7.16.0 || ^8.3.0"
   },
+  "peerDependenciesMeta": {
+    "@effect/platform-node": {
+      "optional": true
+    }
+  },
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
@@ -66,6 +78,9 @@
       "onFail": "warn"
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
@@ -73,7 +88,8 @@
     "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",
     "changeset:release": "vp run build && changeset publish"

package/src/action-meta.ts

@@ -0,0 +1,58 @@
+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.
+// ---------------------------------------------------------------------------
+
+/** The key that holds the metadata in action data. */
+export const actionMetaKey = "__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 }
+    : T;
+
+/**
+ * The type of 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]
+  ? 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. */
+const isDataWithResponseInit = (value: unknown): value is DataWithResponseInit<unknown> =>
+  value instanceof DataWithResponseInitClass;
+
+/** True for a plain object, which can be copied without losing behavior. */
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (!Predicate.isObject(value) || Array.isArray(value)) return false;
+  const prototype: object | null = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+/**
+ * Attaches `meta` to the 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 => {
+  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 isPlainRecord(value) ? ({ ...value, [actionMetaKey]: meta } as T) : value;
+};

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

@@ -0,0 +1,213 @@
+import type { Effect } from "effect";
+import type { Register as RouterRegister } from "react-router";
+
+import type { ReturnableDataError } from "./errors.ts";
+import type { FactoryTypes, FailureResponse, IsAny, LibraryHandled, NameError } from "./factory.ts";
+import type { RegisteredMeta, RegisteredRecover } from "./route-data.ts";
+
+// ---------------------------------------------------------------------------
+// The route check: every Effect a route module exports must be fully handled.
+// ---------------------------------------------------------------------------
+
+/** The route modules React Router's typegen registers, keyed by route ID. */
+type RegisteredRouteModules = RouterRegister extends { readonly routeModules: infer Modules }
+  ? Modules
+  : {};
+
+/** What an effect middleware may succeed with: React Router's response, or nothing. */
+type MiddlewareResult = Response | void | undefined;
+
+/** What a failure says to do, under its `react-router-effect` key. */
+type FailureMessage =
+  "This route Effect can fail with an error the route factory does not handle, or needs a service it does not provide. Catch the error in the Effect (for example with Effect.catchTag), add it to the factory's domain errors, or provide the service.";
+
+/**
+ * One export that fails the check. `unhandledErrors` lists each error the
+ * effect can fail with that the factory does not handle, by its `_tag`.
+ * `missingServices` lists each service that neither the runtime nor the
+ * request context provides. `invalidResults` lists what a middleware succeeds
+ * with that is not a `Response` or nothing.
+ *
+ * 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;
+  readonly route: Route;
+  readonly export: Export;
+  readonly unhandledErrors: Unhandled;
+  readonly missingServices: Missing;
+  readonly invalidResults: Invalid;
+};
+
+/**
+ * The failure of one route function, or `never` when it does not return an
+ * Effect or when its Effect is fully handled. An Effect whose error or
+ * service type is `any` comes from a mistake TypeScript already reports, so it
+ * is skipped rather than reported a second time.
+ */
+type FunctionFailure<Route, Export, F, Handled, Provided, Result> = F extends (
+  ...args: never[]
+) => Effect.Effect<infer A, infer E, infer R>
+  ? true extends IsAny<E> | IsAny<R>
+    ? never
+    : [Exclude<E, Handled>, Exclude<R, Provided>, Exclude<A, Result>] extends [never, never, never]
+      ? never
+      : {
+          // Inline, not `RouteEffectFailure`, so the compiler prints the fields.
+          readonly "react-router-effect": FailureMessage;
+          readonly route: Route;
+          readonly export: Export;
+          readonly unhandledErrors: NameError<Exclude<E, Handled>>;
+          readonly missingServices: Exclude<R, Provided>;
+          readonly invalidResults: Exclude<A, Result>;
+        }
+  : never;
+
+/** The failures of one route module's loader, action and middleware. */
+type ModuleFailures<Route, Module, Handled, Provided> =
+  | (Module extends { readonly loader: infer F }
+      ? FunctionFailure<Route, "loader", F, Handled, Provided, unknown>
+      : never)
+  | (Module extends { readonly action: infer F }
+      ? FunctionFailure<Route, "action", F, Handled, Provided, unknown>
+      : never)
+  | (Module extends { readonly middleware: ReadonlyArray<infer F> }
+      ? FunctionFailure<
+          Route,
+          "middleware",
+          F,
+          Handled | FailureResponse,
+          Provided,
+          MiddlewareResult
+        >
+      : never);
+
+/** The failures of every registered route module. */
+type AllFailures<Modules, Handled, Provided> = {
+  [Route in keyof Modules]: ModuleFailures<Route, Modules[Route], Handled, Provided>;
+}[keyof Modules];
+
+/** The types of a route factory. */
+type TypesOf<Factory> = Factory extends { readonly "~types": infer Types } ? Types : never;
+
+/** What one error handler's return recovers into, or `never` when it throws. */
+type HandlerRecovered<Return> =
+  Return extends ReturnableDataError<infer Body>
+    ? Body
+    : Return extends Effect.Effect<infer Success, infer _E, infer _R>
+      ? Success
+      : never;
+
+/** The factory's recover map: each error tag whose handler recovers, and its data. */
+type FactoryRecover<Returns> = {
+  [
+    Tag in keyof Returns as [HandlerRecovered<Returns[Tag]>] extends [never] ? never : Tag
+  ]: HandlerRecovered<Returns[Tag]>;
+};
+
+/** True when each type is assignable to the other. */
+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;
+  readonly factory: Factory;
+  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>);
+
+/** 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;
+
+/**
+ * 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,
+  TypesOf<Factory>
+>;
+
+/** A printable name for an error tag or another unhandled error type. */
+type ErrorName<Name> = Name extends string ? Name : "an untagged error";
+
+/** A printable name for a service: its key, such as `"app/Database"`. */
+type ServiceName<Service> = Service extends { readonly key: infer Key extends string }
+  ? Key
+  : "a service without a string key";
+
+/** The diagnostic lines of one failure, one per error, service or result. */
+type FailureLines<Failure> = Failure extends {
+  readonly route: infer Route extends string | number | symbol;
+  readonly export: infer Export extends string;
+  readonly unhandledErrors: infer Unhandled;
+  readonly missingServices: infer Missing;
+  readonly invalidResults: infer Invalid;
+}
+  ?
+      | (Unhandled extends unknown
+          ? `${Route & string}#${Export} must handle ${ErrorName<Unhandled>}`
+          : never)
+      | (Missing extends unknown
+          ? `${Route & string}#${Export} needs a provider for ${ServiceName<Missing>}`
+          : never)
+      | ([Invalid] extends [never]
+          ? never
+          : `${Route & string}#${Export} must succeed with a Response or nothing`)
+  : Failure extends { readonly register: infer Key extends string }
+    ? `the Register of react-router-effect: ${Key} does not match the route factory`
+    : never;
+
+/**
+ * Checks every loader, action and middleware that returns an Effect, across
+ * the route modules React Router's typegen registers. Each failure is a
+ * required property whose name says what to fix, so assigning `{}` fails to
+ * compile with a list such as:
+ *
+ * ```text
+ * Type '{}' is missing the following properties from type ...:
+ *   "routes/billing#loader must handle PlaidApiError",
+ *   "routes/admin#middleware needs a provider for app/Session"
+ * ```
+ *
+ * ```ts
+ * import type { RouteEffectCheck } from "react-router-effect/server";
+ *
+ * export const routeEffects: RouteEffectCheck<typeof routeFactory> = {};
+ * ```
+ *
+ * An Effect may fail with the factory's domain errors, the library's `Respond`
+ * errors, and `HttpServerRespondable` errors, and require the services of the
+ * 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/errors.ts

@@ -1,7 +1,7 @@
 import { Data } from "effect";
 
 // ---------------------------------------------------------------------------
-// Standardized errors — the library translates these out of the box.
+// Standardized errors - the library translates these out of the box.
 // ---------------------------------------------------------------------------
 
 /** Recoverable: short-circuits the loader but returns `data(...)` the component reads. */
@@ -31,7 +31,7 @@ export type AnyRouteError =
 /**
  * The library's base helpers for raising route errors (`early` / `throw` /
  * `redirect`). This is internal: it isn't exported from the package. The factory
- * hands it to your config builder and returns it (merged with any `respond`
+ * passes it to your config builder and returns it (merged with any `respond`
  * extensions) so your app imports a single `Respond`:
  *
  * ```ts
@@ -44,7 +44,7 @@ export type AnyRouteError =
  * ```
  */
 export const Respond = {
-  /** Recover: short-circuit and hand `value` to the component as loader/action data. */
+  /** Recover: short-circuit and pass `value` to the component as loader/action data. */
   early: <D>(value: D, init?: number | ResponseInit) =>
     new ReturnableDataError({ data: value, init }),
   /** Throw: short-circuit to the error boundary with `data(value, init)`. */