react-router-effect 2.0.0 → 2.2.0

package/dist/server.d.mts

@@ -0,0 +1,284 @@
+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>);
+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>;
+  /**
+   * Answers the current request with React Router. The Scope is the
+   * request's scope: the resources that `loadContext` opens close with it.
+   */
+  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 {
+  /**
+   * The options of {@link ReactRouter.layer}. `R` is the requirement of `loadContext`.
+   *
+   * @stability unstable
+   */
+  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;
+  }
+}
+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 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;
+  /** The resolved directory of the client build. */
+  readonly directory: string;
+  readonly cause: unknown;
+}> {}
+/**
+ * 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
+ */
+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;
+} ? 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
+ */
+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 : {
+  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
+ */
+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
+ */
+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
+ */
+type RouteEffectCheck<Factory, Modules = RegisteredRouteModules> = { readonly [Line in FailureLines<RouteEffectFailures<Factory, Modules>>]: Line; };
+export { assets_d_exports as ReactRouterAssets, type RegisterMismatch, type RouteEffectCheck, type RouteEffectFailure, type RouteEffectFailures };