@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/router/segment-resolution/static-store.ts

@@ -0,0 +1,81 @@
+/**
+ * Static Store
+ *
+ * Lazy-initialized static store for production Static handler interception.
+ * Manages the build-time static manifest lookup for pre-rendered components.
+ */
+
+import type { ReactNode } from "react";
+import { _getRequestContext } from "../../server/request-context.js";
+import type { StaticStore } from "../../prerender/store.js";
+import type { SegmentHandleData } from "../../cache/types.js";
+
+// Lazy-initialized static store for production Static handler interception.
+// Remains undefined until first check; null means checked but no manifest.
+// When no __STATIC_MANIFEST exists (dev mode), set to null eagerly to avoid
+// the dynamic import() in ensureStaticDeps() which disrupts AsyncLocalStorage
+// in workerd/Cloudflare runtime.
+let _staticStore: StaticStore | null | undefined =
+  typeof globalThis !== "undefined" && globalThis.__STATIC_MANIFEST
+    ? undefined
+    : null;
+let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
+let _decodeHandleValue:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandleValue
+  | undefined;
+
+async function ensureStaticDeps(): Promise<void> {
+  if (_staticStore === undefined) {
+    const { createStaticStore } = await import("../../prerender/store.js");
+    _staticStore = createStaticStore();
+  }
+  if (!_deserializeComponent && _staticStore) {
+    const { deserializeComponent } =
+      await import("../../cache/segment-codec.js");
+    _deserializeComponent = deserializeComponent;
+    const { decodeHandleValue } =
+      await import("../../cache/handle-snapshot.js");
+    _decodeHandleValue = decodeHandleValue;
+  }
+}
+
+/**
+ * Try to load a pre-rendered Static component from the build-time store.
+ * Returns the deserialized React element, or undefined if not available.
+ * Also replays any handle data captured at build time into the request's HandleStore.
+ *
+ * @param handlerId - The handler's $$id used to look up the static store entry.
+ * @param segmentId - The runtime segment shortCode. Handle data is replayed under
+ *   this key so that useHandle's segmentOrder matching works correctly.
+ */
+export async function tryStaticLookup(
+  handlerId: string,
+  segmentId: string,
+): Promise<ReactNode | undefined> {
+  // Fast path: already checked and no manifest available (dev mode or no Static handlers).
+  // Avoids await which can disrupt AsyncLocalStorage in workerd/Cloudflare runtime.
+  if (_staticStore === null) return undefined;
+  await ensureStaticDeps();
+  if (!_staticStore || !_deserializeComponent) return undefined;
+  const entry = await _staticStore.get(handlerId);
+  if (!entry) return undefined;
+
+  // Replay handle data captured during build-time rendering. entry.handles is a
+  // Flight-encoded string ("" when none) — decode before replay so
+  // Promise/ReactNode handle values are revived. The data was keyed by handlerId
+  // at build time; replay under segmentId so it matches the segment order used
+  // by useHandle on the client.
+  if (entry.handles && _decodeHandleValue) {
+    const handleStore = _getRequestContext()?._handleStore;
+    if (handleStore) {
+      const segHandles = await _decodeHandleValue<SegmentHandleData>(
+        entry.handles,
+      );
+      if (segHandles) {
+        handleStore.replaySegmentData(segmentId, segHandles);
+      }
+    }
+  }
+
+  return _deserializeComponent(entry.encoded) as Promise<ReactNode>;
+}

package/src/router/segment-resolution/streamed-handler-telemetry.ts

@@ -0,0 +1,52 @@
+/**
+ * Streamed Handler Telemetry
+ *
+ * Shared fire-and-forget rejection observer for streamed handler promises,
+ * used by both the fresh and revalidation segment-resolution paths. Lives in
+ * its own module (never mocked) so the resolution unit tests that mock
+ * helpers.js / telemetry.js with explicit export lists do not resolve it to
+ * undefined.
+ */
+
+import type { ReactNode } from "react";
+import { getRouterContext } from "../router-context.js";
+import { resolveSink, safeEmit } from "../telemetry.js";
+
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+export function observeStreamedHandler(
+  promise: Promise<ReactNode>,
+  segmentId: string,
+  segmentType: string,
+  pathname?: string,
+  routeKey?: string,
+  params?: Record<string, string>,
+): void {
+  let routerCtx;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const sink = resolveSink(routerCtx.telemetry);
+  const reqId = routerCtx.requestId;
+  promise.catch((err: unknown) => {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    safeEmit(sink, {
+      type: "handler.error",
+      timestamp: performance.now(),
+      requestId: reqId,
+      segmentId,
+      segmentType,
+      error: errorObj,
+      handledByBoundary: true,
+      pathname,
+      routeKey,
+      params,
+    });
+  });
+}

package/src/router/segment-resolution/view-transition-default.ts

@@ -0,0 +1,56 @@
+/**
+ * View-transition boundary default resolution.
+ *
+ * Kept in its own module (rather than helpers.ts) because several resolution
+ * tests mock helpers.ts with an explicit export list; a shared util here is
+ * never mocked, so the fresh and revalidation paths always get the real
+ * implementation.
+ */
+
+import type { EntryData } from "../../server/context";
+import { getRequestContext } from "../../server/request-context.js";
+
+/**
+ * Resolve a segment's transition config: stamp the `viewTransition` default and
+ * peel off a transition({ when }) predicate.
+ *
+ * `viewTransition`: the per-segment value (set via the transition() DSL) always
+ * wins. When it is unset, the router-level createRouter({ viewTransition })
+ * default is stamped in so the render gate reads the boundary decision off the
+ * segment — server and client, via the serialized segment — without the router
+ * option being threaded to the client. Only `false` is ever stamped; an unset
+ * (or "auto") value is left untouched because it already means "wrap" at the
+ * gate, which also avoids needless object allocation and payload growth.
+ *
+ * `when`: a server-only predicate. It is STRIPPED from the returned config (a
+ * function cannot cross Flight or the segment cache) and recorded on the request
+ * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
+ * outside any cache scope — and drop this segment's transition when it returns
+ * false. Used by both the fresh and revalidation resolution paths.
+ */
+export function applyViewTransitionDefault(
+  transition: EntryData["transition"],
+  viewTransitionDefault: "auto" | false | undefined,
+  segmentId?: string,
+): EntryData["transition"] {
+  if (!transition) return transition;
+  let result = transition;
+  if (result.when) {
+    if (segmentId !== undefined) {
+      try {
+        const ctx = getRequestContext();
+        (ctx._transitionWhen ??= []).push({ id: segmentId, when: result.when });
+      } catch {
+        // No active request context (e.g. a unit test calling this util
+        // directly). Skip collection; the strip below still applies so the
+        // serialized config never carries the function.
+      }
+    }
+    const { when: _when, ...rest } = result;
+    result = rest;
+  }
+  if (result.viewTransition === undefined && viewTransitionDefault === false) {
+    return { ...result, viewTransition: false };
+  }
+  return result;
+}