@uniflowed/router 0.0.0-alpha.9 → 0.1.0

package/internal/native-tree.js

@@ -0,0 +1,89 @@
+// @flow
+import type { RouteModule, RouteTable } from "./routing.js";
+
+export type NativeLayout = {
+  readonly segment: string,
+  readonly file: string,
+  readonly module: RouteModule<>,
+};
+export type NativeNode = {
+  name: string,
+  module: ?RouteModule<>,
+  layout: boolean,
+  children: Array<NativeNode>,
+};
+export type NativeTree = { root: NativeNode, paths: Map<string, $ReadOnlyArray<string>> };
+
+/** Module identity comes from the generated table; group names never become URLs. */
+export function nativeTree(table: RouteTable<>, layouts: $ReadOnlyArray<NativeLayout>): NativeTree {
+  const rootLayout = layouts.find((layout) => layout.segment === "/");
+  const root: NativeNode = { name: "root", module: rootLayout?.module, layout: true, children: [] };
+  const metadata = new Map(layouts.map((layout) => [layout.module, layout]));
+  const paths = new Map<string, $ReadOnlyArray<string>>();
+  for (const route of table.routes) {
+    if (route.page == null) continue;
+    let parent = root;
+    const path = [];
+    for (const load of route.layouts) {
+      if (load === rootLayout?.module) continue;
+      const layout = metadata.get(load);
+      if (layout == null)
+        throw new Error(`Native navigation: missing layout metadata for ${route.path}`);
+      const name = `layout:${layout.segment}`;
+      let child = parent.children.find((node) => node.name === name);
+      if (child == null) {
+        child = { name, module: load, layout: true, children: [] };
+        parent.children.push(child);
+      }
+      parent = child;
+      path.push(name);
+    }
+    parent.children.push({ name: route.path, module: route.page, layout: false, children: [] });
+    path.push(route.path);
+    paths.set(route.path, path);
+  }
+  return { root, paths };
+}
+
+export type NavigationPayload = {
+  readonly ufHref: string,
+  readonly ufParams: { readonly [string]: string | $ReadOnlyArray<string> },
+};
+export type NavigationState = {
+  readonly key?: string,
+  readonly type?: string,
+  readonly index?: number,
+  readonly routes: $ReadOnlyArray<{
+    readonly name: string,
+    readonly params?: NavigationPayload,
+    readonly state?: NavigationState,
+  }>,
+};
+
+export function stateForPath(
+  names: $ReadOnlyArray<string>,
+  payload: NavigationPayload,
+): NavigationState {
+  const [name, ...rest] = names;
+  if (name == null) throw new Error("Native navigation: an empty screen path cannot be opened");
+  return {
+    routes: [
+      {
+        name,
+        ...(rest.length === 0 ? { params: payload } : { state: stateForPath(rest, payload) }),
+      },
+    ],
+  };
+}
+
+export function hrefFromState(state: NavigationState): string | null {
+  const route = state.routes[state.index ?? state.routes.length - 1];
+  if (route == null) return null;
+  return route.state == null ? (route.params?.ufHref ?? null) : hrefFromState(route.state);
+}
+
+/** React Navigation's nested navigate payload, separate from user route params. */
+export function paramsForPath(names: $ReadOnlyArray<string>, payload: NavigationPayload): mixed {
+  const [screen, ...rest] = names;
+  return screen == null ? payload : { screen, params: paramsForPath(rest, payload) };
+}

package/internal/navigation-cache.js

@@ -0,0 +1,181 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the routes a navigation already has.
+//
+// A navigation used to ask the server every time. A `Link` prefetched a route's
+// payload on hover and handed it to exactly one click, and every other way back
+// to a page the reader had just seen, a second visit or the back button, waited
+// on the network again (ubugeeei-prod/uf#960). This module is what a navigation
+// reads first instead: the route it fetched or prefetched, kept for
+// `app.rendering.staleTime` seconds and asked for again after that.
+//
+// # Off until a project says a number
+//
+// uf's caches are opt-in, and this one is too. `staleTime` is `0` until a
+// project writes one, and at `0` nothing is kept, so a navigation shows what the
+// server answered for it just now, which is the guarantee every project had
+// before the setting existed.
+//
+// # What is kept
+//
+// One promise per route, never a copy of what it resolved to:
+//
+// - an application React Server Components render keeps the payload fetch: the
+//   route's state and its tree, with the `$loading.js` fallbacks the tree
+//   carries, so going back to a page that was still streaming shows the loading
+//   shell the first visit did;
+// - an application rendered from its modules keeps the resolved route: the
+//   loader's data, and the page, layouts and loading boundaries it loaded.
+//
+// A promise rather than its value, so a click on a link whose prefetch is still
+// in flight waits on that request instead of making a second one. The router
+// forgets an entry whose fetch failed or turned out not to be a route.
+//
+// # Keyed by the application path
+//
+// The path and query the route table is asked about, without
+// `app.router.basePath`: `/docs/guide?tab=api` under `/docs` is kept as
+// `/guide?tab=api`. A fragment is never part of a key, because a server never
+// sees one.
+//
+// # Cleared, not revalidated in place
+//
+// `router.refresh()` and every server action clear the whole cache. An action
+// is a write, and which pages it changed is the server's to know, so the next
+// navigation to any of them asks again rather than showing what the write made
+// untrue.
+
+import { applicationPathOf } from "./base-path.js";
+import type { FetchedFlight } from "./flight.js";
+import type { ResolvedRoute } from "./resolve.js";
+
+/** How many routes each cache keeps at once. Past it, the oldest is dropped. */
+export const NAVIGATION_CACHE_LIMIT = 32;
+
+let staleTimeMs: number = 0;
+
+/**
+ * Say how long, in seconds, a route a navigation fetched is shown again without
+ * asking. `0`, the default, keeps nothing. Called once, by the entry that
+ * started the application.
+ */
+export function installStaleTime(seconds: number): void {
+  staleTimeMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
+  if (import.meta.hot != null) {
+    Object.defineProperty((globalThis: $FlowFixMe), "__UF_NAVIGATION_CACHE__", {
+      configurable: true,
+      value: inspectNavigationCache,
+    });
+  }
+  if (staleTimeMs === 0) {
+    clearNavigationCache();
+  }
+}
+
+/** Whether navigations keep what they fetch. */
+export function keepsNavigations(): boolean {
+  return staleTimeMs > 0;
+}
+
+/** The key a URL's route is kept under: its application path, then its query. */
+export function navigationKey(pathname: string, search: string): string {
+  return `${applicationPathOf(pathname) ?? pathname}${search}`;
+}
+
+/** One kind of kept route. */
+export type NavigationCache<T> = {|
+  /** The route kept under `key`, while it is fresh. A stale one is dropped. */
+  readonly read: (key: string) => T | null,
+  /** Keep `value` under `key` from now. Nothing is kept while the stale time is `0`. */
+  readonly store: (key: string, value: T) => void,
+  /** Drop what `key` keeps, if it is still `value`. */
+  readonly forget: (key: string, value: T) => void,
+  readonly clear: () => void,
+  /** How many routes are kept, fresh or not. */
+  readonly size: () => number,
+  readonly inspect: () => $ReadOnlyArray<NavigationCacheEntry>,
+|};
+
+/** Metadata only: inspecting the cache never exposes loader or Flight data. */
+export type NavigationCacheEntry = {|
+  readonly key: string,
+  readonly cachedAt: number,
+  readonly staleAt: number,
+  readonly fresh: boolean,
+|};
+
+function createNavigationCache<T>(): NavigationCache<T> {
+  const entries: Map<string, {| readonly value: T, readonly at: number |}> = new Map();
+  return {
+    read(key) {
+      const entry = entries.get(key);
+      if (entry == null) {
+        return null;
+      }
+      if (Date.now() - entry.at >= staleTimeMs) {
+        entries.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    store(key, value) {
+      if (staleTimeMs === 0) {
+        return;
+      }
+      // Deleted first, so a route kept again moves to the young end.
+      entries.delete(key);
+      if (entries.size >= NAVIGATION_CACHE_LIMIT) {
+        const oldest = entries.keys().next();
+        if (oldest.done !== true) {
+          entries.delete(oldest.value);
+        }
+      }
+      entries.set(key, { value, at: Date.now() });
+    },
+    forget(key, value) {
+      if (entries.get(key)?.value === value) {
+        entries.delete(key);
+      }
+    },
+    clear() {
+      entries.clear();
+    },
+    size() {
+      return entries.size;
+    },
+    inspect() {
+      const now = Date.now();
+      return Array.from(entries, ([key, entry]) => ({
+        key,
+        cachedAt: entry.at,
+        staleAt: entry.at + staleTimeMs,
+        fresh: now - entry.at < staleTimeMs,
+      }));
+    },
+  };
+}
+
+/** Payload fetches, for an application React Server Components render. */
+export const flightNavigations: NavigationCache<Promise<FetchedFlight>> = createNavigationCache();
+
+/** Resolved routes, for an application rendered from its modules. */
+export const routeNavigations: NavigationCache<Promise<ResolvedRoute>> = createNavigationCache();
+
+/** A fresh snapshot for the development console, without reading an entry. */
+export function inspectNavigationCache(): {|
+  readonly staleTime: number,
+  readonly flight: $ReadOnlyArray<NavigationCacheEntry>,
+  readonly routes: $ReadOnlyArray<NavigationCacheEntry>,
+|} {
+  return {
+    staleTime: staleTimeMs / 1000,
+    flight: flightNavigations.inspect(),
+    routes: routeNavigations.inspect(),
+  };
+}
+
+/** Forget every kept route. `router.refresh()` and each server action call this. */
+export function clearNavigationCache(): void {
+  flightNavigations.clear();
+  routeNavigations.clear();
+}

package/internal/payload-rows.js

@@ -0,0 +1,270 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: reading the payload's rows out of a
+// streaming document.
+//
+// `./payload.js` is the format and knows nothing about a browser. This is the
+// other half: row 0 arrives in the document's `<script id="__uf_data">` and
+// every later row arrives in a `<script data-uf-row="n">` React inserts when
+// the value it holds resolves — which is *after* the parser reached the end of
+// what had been sent, and usually after `hydrateRoot` has already been called.
+// So a reader that only looked once would see the rows that happened to be
+// early and wait forever for the rest.
+//
+// # A `MutationObserver`, and not an executable script
+//
+// The obvious mechanism is React's own: an inline `<script>` that pushes into
+// a global. `internal/runtime.js` explains at length why uf's data element is
+// `application/json` instead — "a script that is executed is a script a
+// content security policy has to allow" — and the payload inherits the whole
+// of that argument, several times over: there is now one element per deferred
+// value rather than one per document, and each one carries application data
+// that a `script` element with no type would hand to the JavaScript parser.
+//
+// The cost of keeping that property is that nothing calls uf when a row lands,
+// so uf has to watch. A `MutationObserver` on the document, `childList` and
+// `subtree`, is the whole of it. It is installed before `hydrateRoot` and
+// disconnects itself the moment the last row the model named has arrived, so a
+// page with no deferred values never has one and a page with three has one for
+// as long as its slowest value takes.
+//
+// # Why the observer beats React to the row
+//
+// It has to, or a boundary that the server completed would be hydrated while
+// this side still thought the value was pending. It does, for two reasons that
+// are each sufficient. React writes a completed boundary's content into a
+// hidden `<div>` *before* the inline script that moves it into place, so the
+// row element is in the document one mutation earlier than React's own
+// completion path; and a `MutationObserver` callback is a microtask, while
+// React's hydration of a completed boundary is scheduled work in a later task.
+//
+// If it ever lost that race the failure is still bounded rather than wrong:
+// `use` on a pending promise suspends, React keeps the boundary's fallback for
+// one more microtask, and the row resolves it. What must not happen — and
+// cannot, since both sides render the row element from the same value through
+// the same `payloadJson` — is the two sides writing different bytes into it.
+//
+// # Rows nobody asked for
+//
+// Ignored. The ids that matter are the ones row 0 referred to, `resolve` is
+// what records them, and an element carrying any other id is a document that
+// says more than its model does. Refusing the page over it would be a
+// hydration that fails because of something no component rendered; dropping it
+// is the reading this module can defend.
+
+import {
+  type PayloadRowMessage,
+  PAYLOAD_ROW_ATTRIBUTE,
+  PayloadRowError,
+  PayloadValueError,
+  payloadRowId,
+  parseRowMessage,
+} from "./payload.js";
+
+/** The document half of a payload: the promises, and the watch that fills them. */
+export type PayloadReader = {|
+  /**
+   * The value of row `id`, as a promise.
+   *
+   * The `RowResolver` `decodePayload` is handed. Calling it is what tells this
+   * reader that the id is one the page is waiting for.
+   */
+  readonly resolve: (id: number) => Promise<mixed>,
+  /**
+   * Start reading. Applies every row already in the document, then watches for
+   * the rest; returns without waiting for any of them.
+   */
+  readonly watch: () => void,
+  /** Stop watching, whether or not every row arrived. */
+  readonly stop: () => void,
+|};
+
+/** The parts of a `Document` this module uses, so it needs no DOM lib. */
+type DocumentLike = interface {
+  readonly querySelectorAll: (selector: string) => Iterable<ElementLike>,
+  readonly documentElement: mixed,
+};
+
+/** The parts of an `Element` this module uses. */
+type ElementLike = interface {
+  readonly getAttribute: (name: string) => string | null,
+  readonly textContent: string | null,
+};
+
+/** One row the page is waiting for. */
+type Slot = {|
+  readonly promise: Promise<mixed>,
+  readonly settle: (message: PayloadRowMessage) => void,
+  arrived: boolean,
+|};
+
+/**
+ * A reader over one document.
+ *
+ * `observe` is passed in rather than reached for so that this module needs no
+ * `MutationObserver` global to be *loaded* — the tests drive it with a
+ * document they mutate by hand, and a runtime without the constructor gets a
+ * reader that reads what is already there and never watches, which is exactly
+ * what a prerendered document needs.
+ */
+export function createPayloadReader(
+  document: DocumentLike,
+  observe?: ?(callback: () => void) => (() => void) | null,
+): PayloadReader {
+  const slots: Map<number, Slot> = new Map();
+  let disconnect: (() => void) | null = null;
+  let reading = false;
+
+  function slotFor(id: number): Slot {
+    const existing = slots.get(id);
+    if (existing != null) {
+      return existing;
+    }
+    let settle: (message: PayloadRowMessage) => void = () => {};
+    const promise = new Promise<mixed>((fulfil, reject) => {
+      settle = (message) => {
+        if (message.error !== undefined) {
+          // A `PayloadRowError` rather than a plain one, carrying the row's
+          // exact text: the page's error boundary sees an `Error` either way,
+          // and `internal/runtime.js` needs the text back verbatim when it
+          // re-renders this row's element. See `PayloadRowError`.
+          reject(new PayloadRowError(message.error));
+          return;
+        }
+        fulfil(message.value);
+      };
+    });
+    // Marked handled the moment it exists. A row that says the value failed
+    // rejects this promise, and whether anything is listening by then depends
+    // on whether React has rendered the row's element yet — so without this an
+    // ordinary loader failure would arrive as an unhandled rejection, which
+    // recent Node turns into an exit.
+    promise.catch(() => {});
+    const slot: Slot = { promise, settle, arrived: false };
+    slots.set(id, slot);
+    return slot;
+  }
+
+  function apply(element: ElementLike): void {
+    const attribute = element.getAttribute(PAYLOAD_ROW_ATTRIBUTE);
+    if (attribute == null) {
+      return;
+    }
+    const id = payloadRowId(attribute);
+    if (id == null) {
+      return;
+    }
+    const slot = slots.get(id);
+    // A row for an id the model never referred to, or one already applied. See
+    // the header: neither is this reader's to complain about.
+    if (slot == null || slot.arrived) {
+      return;
+    }
+    slot.arrived = true;
+    try {
+      slot.settle(parseRowMessage(element.textContent ?? "", id));
+    } catch (error) {
+      slot.settle({
+        error:
+          error instanceof PayloadValueError
+            ? error.message
+            : `@uniflowed/router: row ${String(id)} could not be read.`,
+      });
+    }
+    if (finished()) {
+      stop();
+    }
+  }
+
+  function sweep(): void {
+    for (const element of document.querySelectorAll(`script[${PAYLOAD_ROW_ATTRIBUTE}]`)) {
+      apply(element);
+    }
+  }
+
+  function finished(): boolean {
+    for (const slot of slots.values()) {
+      if (!slot.arrived) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function stop(): void {
+    reading = false;
+    const off = disconnect;
+    disconnect = null;
+    if (off != null) {
+      off();
+    }
+  }
+
+  function observeRest(): void {
+    if (!reading || disconnect != null || finished() || observe == null) {
+      return;
+    }
+    disconnect = observe(sweep);
+    if (disconnect == null) {
+      reading = false;
+    }
+  }
+
+  return {
+    resolve(id: number): Promise<mixed> {
+      const slot = slotFor(id);
+      // A reference discovered after the watch started — a client navigation
+      // decoding a payload of its own — still gets whatever is already in the
+      // document, so the order the two calls happen in does not matter.
+      if (reading) {
+        sweep();
+        observeRest();
+      }
+      return slot.promise;
+    },
+    watch(): void {
+      if (reading) {
+        return;
+      }
+      reading = true;
+      sweep();
+      if (slots.size > 0 && finished()) {
+        reading = false;
+        return;
+      }
+      observeRest();
+    },
+    stop,
+  };
+}
+
+/**
+ * The `observe` a browser has.
+ *
+ * Separate from [`createPayloadReader`] so the reader itself stays testable
+ * without one, and so the `MutationObserver` global is touched in exactly one
+ * place — a runtime that has no such constructor gets `null` and a reader that
+ * reads the document once, which is the right answer for a prerendered file
+ * where every row is already in it.
+ */
+export function domObserver(
+  document: DocumentLike,
+): ((callback: () => void) => (() => void) | null) | null {
+  if (typeof MutationObserver === "undefined") {
+    return null;
+  }
+  const root = document.documentElement;
+  if (root == null) {
+    return null;
+  }
+  return (callback) => {
+    const observer = new MutationObserver(() => {
+      callback();
+    });
+    // $FlowFixMe[incompatible-call] `documentElement` is a `Node`; the interface above says only what is read.
+    observer.observe(root, { childList: true, subtree: true });
+    return () => {
+      observer.disconnect();
+    };
+  };
+}