@uniflowed/router 0.5.0 → 0.6.0

package/action.js

@@ -273,66 +273,102 @@ export function registerServerAction<T>(fn: T, id: string): T {
   return fn;
 }
 
+/**
+ * Call the server reference a Flight payload handed a client component.
+ *
+ * A Server Component may pass a `"use server"` function to a Client Component
+ * as a prop. In the rsc graph each callable export is registered with React's
+ * `registerServerReference` under its action id (`registerServerFunction` in
+ * `./rsc.js`), so Flight writes it as a server reference rather than refusing a
+ * function. React's browser client decodes that reference into a function
+ * that calls back here with the reference's id and the arguments, including
+ * any `.bind(null, …)` bound on the server, which React has already placed
+ * first. `hydrateFlight` installs this as that callback.
+ *
+ * `reference` is what `registerServerReference` wrote: the action id, `#`, and
+ * the `module#export` name. The call is the same one an imported reference
+ * makes, over the same JSON wire, with the same grammar, `Origin` check and
+ * deployment header. There is no second wire. An argument outside the grammar,
+ * a bound one included, is an `ActionValueError` before anything is sent. See
+ * ubugeeei-prod/uf#1359.
+ */
+export function callServerReference(
+  reference: string,
+  args: $ReadOnlyArray<mixed>,
+): Promise<ActionValue | void> {
+  const hash = reference.indexOf("#");
+  const id = hash === -1 ? reference : reference.slice(0, hash);
+  const name = hash === -1 ? reference : reference.slice(hash + 1);
+  return sendServerAction(id, name, args);
+}
+
 /** The network call one reference makes. */
 function callServerActionFor(id: string, name: string): ServerActionFunction {
-  return async function callServerAction(
-    ...args: Array<ActionArgument>
-  ): Promise<ActionValue | void> {
-    const body = encodeActionArguments(args);
-    // The page the call is made from, kept for the answer: a relative redirect
-    // means relative to this page, whatever the visitor has done since.
-    const from = currentUrl();
-    // Built rather than written as a literal, because the header's name is a
-    // constant and a computed key in an object literal is a shape Flow
-    // declines to track.
-    const headers: { [string]: string } = { "content-type": ACTION_CONTENT_TYPE };
-    headers[ACTION_HEADER] = id;
-    // Which build this page is, so a server on another build refuses the call
-    // rather than looking this id up in a table it was never in.
-    withDeployment(headers);
-    const response = await fetch(from, {
-      method: "POST",
-      // Stated rather than left to the default, because the default is what a
-      // reader has to look up and because this one is load-bearing: the
-      // endpoint's `Origin` check is only meaningful for a request that
-      // carries the visitor's cookies in the first place.
-      credentials: "same-origin",
-      // Never a cached answer, and never one written to a cache: an action is
-      // a side effect, and `POST` responses are outside HTTP caching by
-      // default only until something decides otherwise.
-      cache: "no-store",
-      headers,
-      body,
-    });
-    // A route a navigation kept may no longer show what this action wrote, and
-    // which routes is the server's to know, so every kept route is asked for
-    // again. Whatever the status: an action that failed part-way may have
-    // written before it failed. See `./internal/navigation-cache.js`.
-    clearNavigationCache();
-    // The server is on another build: nothing ran, and nothing on this page
-    // can be called correctly any more. Load the page again, from the build
-    // that is live, and never settle — a rejection here would reach an error
-    // boundary for the moment before the document is replaced, and a result
-    // would be a lie. See `./internal/deployment.js`.
-    if (refusedAsAnotherDeployment(response)) {
-      loadDocument(currentUrl());
-      return new Promise<ActionValue | void>(() => {});
-    }
-    // The action called `redirect()`, `notFound()`, `unauthorized()` or
-    // `forbidden()`. Checked before the status, because three of the four are
-    // not `ok` and none of them is a failure.
-    const outcome = response.headers.get(ACTION_OUTCOME_HEADER);
-    if (outcome != null) {
-      void response.body?.cancel();
-      return followOutcome(name, outcome, response, from);
-    }
-    if (!response.ok) {
-      throw new ServerActionError(name, response.status);
-    }
-    return decodeActionResult(await response.text());
+  return function callServerAction(...args: Array<ActionArgument>): Promise<ActionValue | void> {
+    return sendServerAction(id, name, args);
   };
 }
 
+/** Call action `id`, named `name` in an error, with `args`. */
+async function sendServerAction(
+  id: string,
+  name: string,
+  args: $ReadOnlyArray<mixed>,
+): Promise<ActionValue | void> {
+  const body = encodeActionArguments(args);
+  // The page the call is made from, kept for the answer: a relative redirect
+  // means relative to this page, whatever the visitor has done since.
+  const from = currentUrl();
+  // Built rather than written as a literal, because the header's name is a
+  // constant and a computed key in an object literal is a shape Flow
+  // declines to track.
+  const headers: { [string]: string } = { "content-type": ACTION_CONTENT_TYPE };
+  headers[ACTION_HEADER] = id;
+  // Which build this page is, so a server on another build refuses the call
+  // rather than looking this id up in a table it was never in.
+  withDeployment(headers);
+  const response = await fetch(from, {
+    method: "POST",
+    // Stated rather than left to the default, because the default is what a
+    // reader has to look up and because this one is load-bearing: the
+    // endpoint's `Origin` check is only meaningful for a request that
+    // carries the visitor's cookies in the first place.
+    credentials: "same-origin",
+    // Never a cached answer, and never one written to a cache: an action is
+    // a side effect, and `POST` responses are outside HTTP caching by
+    // default only until something decides otherwise.
+    cache: "no-store",
+    headers,
+    body,
+  });
+  // A route a navigation kept may no longer show what this action wrote, and
+  // which routes is the server's to know, so every kept route is asked for
+  // again. Whatever the status: an action that failed part-way may have
+  // written before it failed. See `./internal/navigation-cache.js`.
+  clearNavigationCache();
+  // The server is on another build: nothing ran, and nothing on this page
+  // can be called correctly any more. Load the page again, from the build
+  // that is live, and never settle — a rejection here would reach an error
+  // boundary for the moment before the document is replaced, and a result
+  // would be a lie. See `./internal/deployment.js`.
+  if (refusedAsAnotherDeployment(response)) {
+    loadDocument(currentUrl());
+    return new Promise<ActionValue | void>(() => {});
+  }
+  // The action called `redirect()`, `notFound()`, `unauthorized()` or
+  // `forbidden()`. Checked before the status, because three of the four are
+  // not `ok` and none of them is a failure.
+  const outcome = response.headers.get(ACTION_OUTCOME_HEADER);
+  if (outcome != null) {
+    void response.body?.cancel();
+    return followOutcome(name, outcome, response, from);
+  }
+  if (!response.ok) {
+    throw new ServerActionError(name, response.status);
+  }
+  return decodeActionResult(await response.text());
+}
+
 /**
  * Do in the browser what the action's routing call asked for.
  *
@@ -344,8 +380,9 @@ function callServerActionFor(id: string, name: string): ServerActionFunction {
  * - `not-found`, `unauthorized`, `forbidden`: throw the same error the server
  *   caught. React hands an error thrown by an action to the nearest error
  *   boundary, and uf's route boundary already tells `unauthorized()` and
- *   `forbidden()` apart. `notFound()` arrives as a `NotFoundError`, which an
- *   `$error.js` can test for.
+ *   `forbidden()` apart. `notFound()` arrives as a `NotFoundError`, which the
+ *   boundary answers with the URL's not-found page rather than its error view
+ *   (ubugeeei-prod/uf#1489).
  *
  * Any other value is a server this reference does not understand, and it is
  * the same `ServerActionError` as any other failure.

package/index.js

@@ -31,6 +31,8 @@
 
 import * as React from "react";
 
+import type { InferOutput } from "@uniflowed/validator";
+
 import type { RouteError } from "./internal/runtime.js";
 
 export type {
@@ -59,6 +61,8 @@ export type {
   Router,
   ResolvedSlot,
   SearchParams,
+  SearchParamsAll,
+  SearchParamsIssue,
   SlotRecord,
   SlotRouteRecord,
   TemplateModule,
@@ -72,6 +76,7 @@ export {
   RedirectError,
   RouteView,
   RouterProvider,
+  SearchParamsError,
   UnauthorizedError,
   basePath,
   buildRoute,
@@ -80,6 +85,7 @@ export {
   matchRoute,
   notFound,
   parseSearch,
+  parseSearchAll,
   permanentRedirect,
   redirect,
   resolveFailure,
@@ -96,16 +102,34 @@ export {
   useSeo,
 } from "./internal/runtime.js";
 
-/** Props a page receives. */
+/**
+ * Props a page receives.
+ *
+ * `TSearchParams` is the query string as the page is given it: the string map
+ * — one value per key, the last of a repeated one — unless the page exports a
+ * `searchParams` schema, when it is that schema's output. Spell it with
+ * [`SearchParamsOf`] so the prop and the export cannot drift apart:
+ *
+ *     export const searchParams = object({ page: number(), tag: array(string()) });
+ *     export component Page(...props: PageProps<{}, void, SearchParamsOf<typeof searchParams>>)
+ */
 export type PageProps<
   TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
   TData = void,
+  TSearchParams = { readonly [string]: string },
 > = {|
   readonly params: TParams,
-  readonly searchParams: { readonly [string]: string },
+  readonly searchParams: TSearchParams,
   readonly data: TData,
 |};
 
+/**
+ * What a page that exports `searchParams = schema` is given as its
+ * `searchParams` prop: the schema's output, the same type
+ * `@uniflowed/validator`'s `InferOutput` reads off it.
+ */
+export type SearchParamsOf<TSchema> = InferOutput<TSchema>;
+
 /** Props an `$error.js` component receives. */
 export type ErrorProps = {|
   readonly error: RouteError,

package/internal/error-view.js

@@ -17,7 +17,8 @@ import * as React from "react";
 import type { RouteError } from "./routing.js";
 import type { ErrorModule } from "./resolve.js";
 import { errorTitle, renderable, routeErrorFor } from "./resolve.js";
-import { useRouterState } from "./runtime.js";
+import { NotFoundError } from "./routing.js";
+import { showNotFoundPage, useRouterState } from "./runtime.js";
 
 /**
  * The framework's error page, for a project that declares no `$error.js`.
@@ -32,6 +33,7 @@ import { useRouterState } from "./runtime.js";
 component DefaultRouteError(error: RouteError, reset: () => void) {
   const title = errorTitle(error);
   const detail = match (error) {
+    {kind: "badRequest", ...} => "This page cannot answer the query in its address.",
     {kind: "unauthorized"} => "This page needs you to be signed in.",
     {kind: "forbidden"} => "You do not have access to this page.",
     {kind: "thrown", ...} => "This page could not be rendered.",
@@ -143,7 +145,20 @@ type RouteErrorBoundaryProps = {|
   readonly children: React.Node,
 |};
 
-type RouteErrorBoundaryState = {| readonly error: ?RouteError |};
+type RouteErrorBoundaryState = {|
+  readonly error: ?RouteError,
+  /**
+   * The subtree threw `NotFoundError`, and the router has been asked for the
+   * not-found page of the URL on screen. See [`RouteErrorBoundary`].
+   */
+  readonly notFound: boolean,
+  /**
+   * How many times the boundary has let go of a `NotFoundError`: the key of the
+   * subtree, so what renders after it is mounted afresh. See
+   * [`RouteErrorBoundary`].
+   */
+  readonly generation: number,
+|};
 
 /**
  * The boundary that catches a throw while the browser renders the subtree.
@@ -157,6 +172,20 @@ type RouteErrorBoundaryState = {| readonly error: ?RouteError |};
  * navigation, error or not, and everything below the boundary goes with it —
  * which is the layouts, whose whole purpose is to survive navigation with
  * their scroll position and their open sections intact.
+ *
+ * # `notFound()` is not an error to show
+ *
+ * A loader's `notFound()` shows the project's not-found page because the
+ * resolver resolves the route again as that page, not because a boundary
+ * catches it. A `NotFoundError` that reaches this boundary — a hydrated server
+ * action that called `notFound()`, which React hands to the nearest boundary —
+ * gets the same page: the boundary renders nothing while the router resolves
+ * the not-found page for the URL on screen (`showNotFoundPage`), and lets go of
+ * the error in the transition that commits it (ubugeeei-prod/uf#1489). Letting
+ * go remounts the subtree, because a component that threw an action's error
+ * — a `useActionState` — throws it again on every render until it is
+ * remounted. Where the router has no not-found page to show, the error view is
+ * what renders, as it did before.
  */
 export class RouteErrorBoundary extends React.Component<
   RouteErrorBoundaryProps,
@@ -164,13 +193,35 @@ export class RouteErrorBoundary extends React.Component<
 > {
   constructor(props: RouteErrorBoundaryProps) {
     super(props);
-    this.state = { error: null };
+    this.state = { error: null, notFound: false, generation: 0 };
   }
 
-  static getDerivedStateFromError(error: mixed): RouteErrorBoundaryState {
+  static getDerivedStateFromError(error: mixed): Partial<RouteErrorBoundaryState> {
+    if (error instanceof NotFoundError) {
+      return { error: null, notFound: true };
+    }
     return { error: routeErrorFor(error) };
   }
 
+  componentDidCatch(error: mixed) {
+    if (!(error instanceof NotFoundError)) {
+      return;
+    }
+    const recover = () => {
+      this.setState((state) => ({
+        error: null,
+        notFound: false,
+        generation: state.generation + 1,
+      }));
+    };
+    const giveUp = (failure: mixed) => {
+      this.setState({ error: routeErrorFor(failure), notFound: false });
+    };
+    showNotFoundPage(recover).then((shown) => {
+      if (!shown) giveUp(error);
+    }, giveUp);
+  }
+
   componentDidUpdate(previous: RouteErrorBoundaryProps) {
     if (this.state.error != null && previous.resetKey !== this.props.resetKey) {
       this.setState({ error: null });
@@ -178,9 +229,12 @@ export class RouteErrorBoundary extends React.Component<
   }
 
   render(): React.Node {
-    const { error } = this.state;
+    const { error, notFound, generation } = this.state;
+    if (notFound) {
+      return null;
+    }
     if (error == null) {
-      return this.props.children;
+      return <React.Fragment key={generation}>{this.props.children}</React.Fragment>;
     }
     return (
       <RouteErrorView

package/internal/flight-browser.js

@@ -23,13 +23,19 @@
 // and turning it into an `import()` would be letting bytes decide which script
 // runs.
 
-import { createFromFetch, createFromReadableStream } from "react-server-dom-parcel/client.browser";
+import {
+  createFromFetch,
+  createFromReadableStream,
+  setServerCallback,
+} from "react-server-dom-parcel/client.browser";
 
+import { callServerReference } from "../action.js";
 import { withDeployment } from "./deployment.js";
 import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.js";
 import {
   FLIGHT_CONTENT_TYPE,
   INTERCEPTED_FROM_HEADER,
+  NOT_FOUND_HEADER,
   type FetchedFlight,
   type FlightFetchOptions,
   type FlightRoot,
@@ -44,6 +50,21 @@ type ModuleNamespace = { readonly [string]: mixed };
 /** The entry a refusal names: the one an application reaches this module through. */
 const ENTRY = "@uniflowed/router/rsc/client";
 
+/**
+ * Install the call React's Flight client makes for a server reference.
+ *
+ * A Server Component that passes a `"use server"` function to a Client
+ * Component as a prop sends a server reference, and React's browser client
+ * decodes it into a function that calls this one callback with the reference's
+ * id and its arguments, bound ones first. uf answers with the call an imported
+ * reference makes, over the same JSON action wire (`callServerReference` in
+ * `../action.js`). See ubugeeei-prod/uf#1359.
+ */
+export function installServerCallback(): void {
+  requireServerComponentsReact(ENTRY);
+  setServerCallback(callServerReference);
+}
+
 /**
  * Install the module hook React's Flight client resolves references through.
  *
@@ -213,6 +234,9 @@ export async function fetchFlight(
   if (interceptedFrom != null) {
     headers.set(INTERCEPTED_FROM_HEADER, interceptedFrom);
   }
+  if (options?.notFound === true) {
+    headers.set(NOT_FOUND_HEADER, "1");
+  }
   let response: Response;
   try {
     response = await fetch(flightUrl(url), {

package/internal/flight.js

@@ -50,7 +50,7 @@ export type RouteState = {|
   readonly deferred: ?Promise<mixed>,
   readonly metadata: Metadata,
   readonly viewTransition: ?string,
-  readonly status: 200 | 401 | 403 | 404 | 500,
+  readonly status: 200 | 400 | 401 | 403 | 404 | 500,
   readonly error: ?RouteError,
   readonly interception?: ?FlightInterception,
 |};
@@ -80,6 +80,13 @@ export type FlightInterception = {|
 /** What the browser may send with a payload request. */
 export type FlightFetchOptions = {|
   readonly interceptedFrom?: string,
+  /**
+   * Ask for the URL's not-found page rather than its route: the payload a
+   * loader's `notFound()` would have answered with. What a route's error
+   * boundary asks for when a hydrated server action called `notFound()`
+   * (ubugeeei-prod/uf#1489).
+   */
+  readonly notFound?: boolean,
 |};
 
 /**
@@ -125,7 +132,8 @@ export type FetchedFlight =
  * shows and which a production payload drops along with every other `Error`
  * message. The original value is still what the server reported: this is
  * applied only to the copy that crosses. `unauthorized` and `forbidden` carry
- * nothing and pass through as they are.
+ * nothing and pass through as they are, and so does `badRequest`: its issues
+ * describe the query the visitor sent, not anything of the server's.
  */
 export function crossableRouteError(error: ?RouteError): ?RouteError {
   if (error == null || error.kind !== "thrown" || error.error instanceof Error) {
@@ -189,6 +197,12 @@ export const FLIGHT_CONTENT_TYPE: string = "text/x-component";
 /** The request header that carries the page an intercepted payload is rendered over. */
 export const INTERCEPTED_FROM_HEADER: string = "uf-intercepted-from";
 
+/**
+ * The request header that asks for a URL's not-found payload instead of its
+ * route. Its one value is `1`; see [`FlightFetchOptions`].
+ */
+export const NOT_FOUND_HEADER: string = "uf-not-found";
+
 /**
  * The URL of `url`'s payload: its pathname with [`FLIGHT_SEGMENT`] appended,
  * and its query string unchanged.

package/internal/resolve.js

@@ -24,10 +24,12 @@
 import * as React from "react";
 
 import { ResolvedErrorPage } from "./error-view.js";
+import { parseSearchParams } from "./search-params.js";
 import {
   ForbiddenError,
   NotFoundError,
   RedirectError,
+  SearchParamsError,
   UnauthorizedError,
   matchIn,
   matchRoute,
@@ -50,6 +52,7 @@ import type {
   SlotRouteRecord as RoutingSlotRouteRecord,
   TemplateRecord as RoutingTemplateRecord,
 } from "./routing.js";
+import type { Schema } from "@uniflowed/validator";
 
 /**
  * A component found in a route module.
@@ -88,7 +91,8 @@ export type RouteComponent = React.ComponentType<empty>;
  */
 export type PageRenderProps = {|
   readonly params: RouteParams,
-  readonly searchParams: SearchParams,
+  /** The string map, or the output of the page's `searchParams` schema. */
+  readonly searchParams: mixed,
   readonly data: mixed,
 |};
 
@@ -116,6 +120,13 @@ export type PageModule = {
   readonly default?: RouteComponent,
   readonly Page?: RouteComponent,
   readonly loader?: (args: LoaderArgs) => mixed | Promise<mixed>,
+  /**
+   * A `@uniflowed/validator` schema for the query string. The page is then
+   * given its output as `searchParams` rather than the string map, and a
+   * query that does not fit it is the error boundary with a `400`. See
+   * `./search-params.js`.
+   */
+  readonly searchParams?: Schema<mixed, mixed>,
   readonly metadata?: Metadata,
   readonly generateMetadata?: (args: MetadataArgs) => Metadata | Promise<Metadata>,
   readonly generateStaticParams?: () =>
@@ -460,6 +471,11 @@ export type ResolvedRoute = {|
   readonly path: string,
   readonly params: RouteParams,
   readonly searchParams: SearchParams,
+  /**
+   * What the page's `searchParams` schema made of the query, when it exports
+   * one; absent otherwise. [`pageSearchParams`] is what the page is given.
+   */
+  readonly parsedSearchParams?: mixed,
   readonly page: PageModule,
   readonly layouts: $ReadOnlyArray<LayoutModule>,
   /** What the loader returned, once it has. `undefined` while `deferred` is set. */
@@ -490,7 +506,7 @@ export type ResolvedRoute = {|
    * carries it and never reads it; see "View transitions".
    */
   readonly viewTransition: ?string,
-  readonly status: 200 | 401 | 403 | 404 | 500,
+  readonly status: 200 | 400 | 401 | 403 | 404 | 500,
   /**
    * Set when this resolution *is* the error page: the loader threw, or the
    * server render did and the renderer resolved again. `null` on the ordinary
@@ -762,6 +778,12 @@ async function resolveRoute(
     loadOnce(load),
     Promise.all(matched.route.layouts.map((layout) => loadOnce(layout))),
   ]);
+  // Before anything else is started, and before the loader above all: a query
+  // the page's schema refuses is a `400`, and nothing the page does should run
+  // on a request it has said it cannot answer. The throw is a
+  // `SearchParamsError`, which `resolveMatch` hands to the error boundary.
+  const schema = page.searchParams;
+  const parsed = schema == null ? null : { value: await parseSearchParams(schema, search) };
   // Started here and awaited at the end: the boundary's module does not depend
   // on the loader, so importing it alongside costs a navigation nothing. It
   // never rejects, so an early throw below leaves no unhandled rejection.
@@ -832,6 +854,7 @@ async function resolveRoute(
     path: matched.route.path,
     params: matched.params,
     searchParams,
+    ...(parsed == null ? {} : { parsedSearchParams: parsed.value }),
     page,
     layouts,
     data,
@@ -1299,9 +1322,20 @@ export function routeErrorFor(error: mixed): RouteError {
   if (error instanceof ForbiddenError) {
     return { kind: "forbidden" };
   }
+  if (error instanceof SearchParamsError) {
+    return { kind: "badRequest", issues: error.issues };
+  }
   return { kind: "thrown", error };
 }
 
+/**
+ * The `searchParams` a resolved route's page is given: its schema's output when
+ * it exports one, and the query's string map when it does not.
+ */
+export function pageSearchParams(resolved: ResolvedRoute): mixed {
+  return resolved.page.searchParams != null ? resolved.parsedSearchParams : resolved.searchParams;
+}
+
 /**
  * The error boundary a route renders inside, loaded with the route rather than
  * when it is needed.
@@ -1591,6 +1625,7 @@ component DefaultNotFound() {
 /** The document title an error page gets when nothing declared one. */
 export function errorTitle(error: RouteError): string {
   return match (error) {
+    {kind: "badRequest", ...} => "Bad request",
     {kind: "unauthorized"} => "Sign in required",
     {kind: "forbidden"} => "Not allowed",
     {kind: "thrown", ...} => "Something went wrong",

package/internal/resolved-summary.js

@@ -6,12 +6,12 @@ import { routeBoundaries, suspenseId } from "./boundary-data.js";
 import type { RouteBoundary } from "./boundary-data.js";
 import type { RouteParams, SearchParams } from "./routing.js";
 
-type RouteStatus = 200 | 401 | 403 | 404 | 500;
+type RouteStatus = 200 | 400 | 401 | 403 | 404 | 500;
 
 type RouteMetadata = { readonly [string]: mixed, ... };
 
 type RouteErrorLike = {
-  readonly kind: "thrown" | "unauthorized" | "forbidden",
+  readonly kind: "thrown" | "unauthorized" | "forbidden" | "badRequest",
   ...
 };
 
@@ -71,7 +71,8 @@ export type ResolvedTemplateSummary = {|
 export type ResolvedRouteErrorSummary =
   | {| readonly kind: "thrown" |}
   | {| readonly kind: "unauthorized" |}
-  | {| readonly kind: "forbidden" |};
+  | {| readonly kind: "forbidden" |}
+  | {| readonly kind: "badRequest" |};
 
 export type ResolvedErrorBoundarySummary = {|
   readonly above: number,
@@ -195,5 +196,8 @@ function summarizeError(error: ?RouteErrorLike): ?ResolvedRouteErrorSummary {
   if (error.kind === "forbidden") {
     return { kind: "forbidden" };
   }
+  if (error.kind === "badRequest") {
+    return { kind: "badRequest" };
+  }
   return { kind: "thrown" };
 }