react-router-effect 2.1.0 → 2.2.0

package/dist/server.d.mts

@@ -1,55 +1,111 @@
-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-MgSnnR33.mjs";
-import { Cause, Context, Effect, FileSystem, Path } from "effect";
-import { Register, ServerBuild } from "react-router";
-import { HttpPlatform, HttpServerError, HttpServerRequest, HttpServerResponse } from "effect/http";
-declare namespace server_d_exports {
-  export { App, BuildSource, ClientAssetServices, ClientBuildError, Options, make };
-}
+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 { 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";
 /** A React Router server build, or a function that loads it, as in `createRequestHandler`. */
 type BuildSource = ServerBuild | (() => ServerBuild | Promise<ServerBuild>);
-/** The options of {@link make}. */
-interface Options {
-  /** The server build: `() => import("virtual:react-router/server-build")`. */
-  readonly build: BuildSource;
-  /** The route factory whose runner, runtime and error model route Effects use. */
-  readonly factory: {
-    readonly handlers: RouteHandlers;
-  };
-  /** React Router's server mode. Defaults to `process.env.NODE_ENV`. */
-  readonly mode?: string | undefined;
+declare const ReactRouter_base: Context.ServiceClass<ReactRouter, "react-router-effect/ReactRouter", {
+  /**
+   * The build, when the layer loaded it once at startup: a build value, or
+   * a build function in production mode. `None` when the build loads for
+   * each request.
+   */
+  readonly build: Option.Option<ServerBuild>;
   /**
-   * Serves the client build before React Router: the files of the build's
-   * `assetsBuildDirectory`, under its `publicPath`. Files under `assets/` have
-   * hashed names and are cached for a year as immutable, other files for an
-   * hour. It serves like `express.static`: a directory serves its index file,
-   * such as a prerendered page, its path without the trailing slash redirects
-   * to the path with it, dotfiles are not served, and a request it does not
-   * serve goes to React Router. Like `express.static`, it looks each GET and
-   * HEAD request up in the file system. It serves only a build that it loads
-   * once: in production mode, or a build value. A
-   * development build is never served, since Vite serves the client there, nor
-   * is a `publicPath` on another origin. Making the app fails with a
-   * {@link ClientBuildError} when it cannot read the directory. Needs the
-   * platform's file system, which `NodeHttpServer.layer` and the other server
-   * layers provide.
+   * Answers the current request with React Router. The Scope is the
+   * request's scope: the resources that `loadContext` opens close with it.
    */
-  readonly clientAssets?: boolean | undefined;
+  readonly handle: Effect.Effect<HttpServerResponse.HttpServerResponse, HttpServerError.RequestError, HttpServerRequest.HttpServerRequest | Scope.Scope>;
+}>;
+/**
+ * React Router, as a service of the Effect HTTP app. `ReactRouter.layer`
+ * provides it, and `ReactRouter.routes` registers it on the app's router as
+ * the catch-all route.
+ *
+ * ```ts
+ * export const App = ReactRouter.routes.pipe(
+ *   Layer.provide(
+ *     ReactRouter.layer({
+ *       build: () => import("virtual:react-router/server-build"),
+ *       factory: routeFactory,
+ *       mode: import.meta.env.MODE,
+ *     }),
+ *   ),
+ * );
+ * ```
+ *
+ * @stability unstable
+ */
+export declare class ReactRouter extends ReactRouter_base {
+  /**
+   * Provides React Router. A build value, or a build function in production
+   * mode, loads when the layer builds. Provide one value of this layer to
+   * every layer that reads the service: two values load the build twice.
+   *
+   * @stability unstable
+   */
+  static readonly layer: <R = never>(options: ReactRouter.Options<R>) => Layer.Layer<ReactRouter, never, Exclude<R, Scope.Scope>>;
+  /**
+   * Registers React Router as the catch-all route of the app's router, on
+   * `*`, for every method of `HttpMethod.all` but HEAD. A route that the app
+   * registers itself wins over it, also a route on `/`, such as the
+   * prerendered home page of `ReactRouterAssets.layer`. A HEAD request uses
+   * the GET route of its path, React Router's or the app's own, as Express
+   * does. A method outside `HttpMethod.all` gets the router's 404. Register
+   * it at the root of the router: under a prefix, React Router does not get
+   * the path that it expects.
+   *
+   * @stability unstable
+   */
+  static readonly routes: Layer.Layer<never, never, HttpRouter.HttpRouter | ReactRouter | HttpRouter.Request<"Error", HttpServerError.InternalError> | HttpRouter.Request<"Error", HttpServerError.RequestParseError> | HttpRouter.Request<"Error", HttpServerError.RouteNotFound>>;
+}
+export declare namespace ReactRouter {
   /**
-   * Builds the services of one request, before React Router runs. They join
-   * the request's effect context, so every middleware, loader and action sees
-   * them without a middleware that sets them.
+   * The options of {@link ReactRouter.layer}. `R` is the requirement of `loadContext`.
+   *
+   * @stability unstable
    */
-  readonly requestContext?: ((request: Request) => Context.Context<never>) | undefined;
+  interface Options<R = never> {
+    /** The server build: `() => import("virtual:react-router/server-build")`. */
+    readonly build: BuildSource;
+    /** The route factory whose runner, runtime and error model route Effects use. */
+    readonly factory: {
+      readonly handlers: RouteHandlers;
+    };
+    /**
+     * React Router's server mode, such as `import.meta.env.MODE` in a Vite
+     * app. React Router runs in production mode for any mode but
+     * `development` and `test`, and so does the layer: it loads a build
+     * function for each request only in those two modes.
+     */
+    readonly mode: "development" | "production" | "test" | (string & {});
+    /**
+     * Makes React Router's load context for each request, as `getLoadContext`
+     * does for `@react-router/express`. Plain loaders and actions, and
+     * `handleRequest` in `entry.server.tsx`, read its values with
+     * `context.get`. Route Effects read services from their Effect context,
+     * so an app gives them services with router middleware, not here. The
+     * adapter adds its own keys to the provider. The Effect gets the services
+     * of `R` from the layer, and the services of the request, which win over
+     * the services of the layer. A defect answers an empty 500.
+     */
+    readonly loadContext?: ((request: HttpServerRequest.HttpServerRequest) => Effect.Effect<RouterContextProvider, never, R>) | undefined;
+  }
 }
-/** The services that serving the client build needs. */
-type ClientAssetServices = FileSystem.FileSystem | Path.Path | HttpPlatform.HttpPlatform;
-declare const ClientBuildError_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]; }>) => Cause.YieldableError & {
+declare namespace assets_d_exports {
+  export { ClientBuildError, layer };
+}
+declare const ClientBuildError_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: "ClientBuildError";
 } & Readonly<A>;
 /**
- * The app serves the client build, and cannot read its directory. The
- * build's `assetsBuildDirectory` is relative to the working directory of the
- * server, so `directory` is the path it resolved to.
+ * 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
  */
 declare class ClientBuildError extends ClientBuildError_base<{
   readonly message: string;
@@ -57,44 +113,46 @@ declare class ClientBuildError extends ClientBuildError_base<{
   readonly directory: string;
   readonly cause: unknown;
 }> {}
-/** True when the options serve the client build. */
-type ServesClientAssets<O> = O extends {
-  readonly clientAssets: infer Serves;
-} ? [Serves] extends [false | undefined] ? false : true : false;
-/**
- * The Effect HTTP app {@link make} makes. Serving the client build adds the
- * static file server's errors to its errors.
- */
-type App<O extends Options> = Effect.Effect<HttpServerResponse.HttpServerResponse, HttpServerError.RequestError | (ServesClientAssets<O> extends true ? HttpServerError.HttpServerError : never), HttpServerRequest.HttpServerRequest>;
 /**
- * Makes the Effect HTTP app that serves React Router. Run the Effect once,
- * when the server starts. In production it loads the build, and with
- * `clientAssets` it reads the client build's directory, so a missing one fails
- * the server's start with a {@link ClientBuildError} and not its requests.
+ * Registers the routes of the client build on the app's router, for GET and
+ * HEAD, under the build's `publicPath`.
  *
- * ```ts
- * import { ReactRouterHttp } from "react-router-effect/server";
+ * 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.
  *
- * export const reactRouterApp = ReactRouterHttp.make({
- *   build: () => import("virtual:react-router/server-build"),
- *   factory: routeFactory,
- *   clientAssets: true,
- * });
+ * 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.
  *
- * // Serve it like any Effect HTTP app, with the app's own middleware.
- * Layer.unwrap(
- *   Effect.map(reactRouterApp, (app) => HttpServer.serve(app, HttpMiddleware.logger)),
- * );
- * ```
+ * 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.
  *
- * In development, where the build changes, the app loads the build for each
- * request, and making it does nothing else.
+ * 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:
  *
- * The request signal aborts only when the response ends early: when the
- * client leaves while React Router runs or while the body streams. A
- * completed response never aborts it.
+ * ```ts
+ * ReactRouterAssets.layer.pipe(Layer.provide(HttpRouter.disableLogger))
+ * ```
+ *
+ * @stability unstable
  */
-declare const make: <const O extends Options>(options: O) => Effect.Effect<App<O>, ServesClientAssets<O> extends true ? ClientBuildError : never, ServesClientAssets<O> extends true ? ClientAssetServices : never>;
+declare const layer: Layer.Layer<never, ClientBuildError, HttpRouter.HttpRouter | ReactRouter | FileSystem.FileSystem | Path.Path | HttpPlatform.HttpPlatform>;
 /** The route modules React Router's typegen registers, keyed by route ID. */
 type RegisteredRouteModules = Register extends {
   readonly routeModules: infer Modules;
@@ -112,6 +170,8 @@ type FailureMessage = "This route Effect can fail with an error the route factor
  *
  * 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
  */
 type RouteEffectFailure<Route, Export, Unhandled, Missing, Invalid> = {
   readonly "react-router-effect": FailureMessage;
@@ -158,6 +218,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
  */
 interface RegisterMismatch<Key, Factory, Registered> {
   readonly register: Key;
@@ -172,6 +234,8 @@ type Failures<Modules, Types> = Types extends FactoryTypes<infer DomainError, in
  * 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
  */
 type RouteEffectFailures<Factory, Modules = RegisteredRouteModules> = Failures<Modules, TypesOf<Factory>>;
 /** A printable name for an error tag or another unhandled error type. */
@@ -213,6 +277,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
  */
 type RouteEffectCheck<Factory, Modules = RegisteredRouteModules> = { readonly [Line in FailureLines<RouteEffectFailures<Factory, Modules>>]: Line; };
-export { server_d_exports as ReactRouterHttp, type RegisterMismatch, type RouteEffectCheck, type RouteEffectFailure, type RouteEffectFailures };
+export { assets_d_exports as ReactRouterAssets, type RegisterMismatch, type RouteEffectCheck, type RouteEffectFailure, type RouteEffectFailures };