react-router-effect 2.0.0 → 2.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemastore.org/package.json",
   "name": "react-router-effect",
-  "version": "2.0.0",
+  "version": "2.1.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,35 @@
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.3",
+    "@effect/platform-node": "4.1.1",
+    "@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.0.5",
+    "@vitest/browser-playwright": "5.0.5",
+    "effect": "4.1.1",
+    "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.4.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",
@@ -74,6 +84,7 @@
     "test:browser": "vp test run --project browser",
     "test:browser:install": "vp exec playwright install chromium",
     "check": "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/check.ts

@@ -0,0 +1,205 @@
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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)`. */