@rangojs/router 0.0.0-experimental.0b82333f

package/src/router/segment-resolution/helpers.ts

@@ -0,0 +1,263 @@
+/**
+ * Shared Helpers for Segment Resolution
+ *
+ * Common utilities used by both fresh and revalidation resolution paths:
+ * - Handler result processing (Response vs ReactNode)
+ * - Static handler interception (build-time pre-rendered components)
+ * - Layout handler resolution with static fallback
+ * - Error boundary segment creation
+ */
+
+import type { ReactNode } from "react";
+import { DataNotFoundError } from "../../errors";
+import {
+  createErrorInfo,
+  createErrorSegment,
+  createNotFoundInfo,
+  createNotFoundSegment,
+} from "../error-handling.js";
+import { getRequestContext } from "../../server/request-context.js";
+import { DefaultErrorFallback } from "../../default-error-boundary.js";
+import type { EntryData } from "../../server/context";
+import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+import { debugLog } from "../logging.js";
+import { tryStaticLookup } from "./static-store.js";
+import type { TelemetrySink } from "../telemetry.js";
+import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Handler result processing
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle Response returns from handlers.
+ * When a handler returns a Response (e.g., redirect), throw it to trigger
+ * the short-circuit mechanism. Otherwise return the ReactNode.
+ */
+export function handleHandlerResult(
+  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+): ReactNode {
+  if (result instanceof Response) {
+    throw result;
+  }
+  if (result instanceof Promise) {
+    return result.then((resolved) => {
+      if (resolved instanceof Response) {
+        throw resolved;
+      }
+      return resolved;
+    }) as ReactNode;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Static handler interception
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to resolve a component from the build-time static store.
+ * Returns undefined synchronously when the entry is not a static prerender,
+ * avoiding unnecessary promise wrapping on the hot path.
+ */
+export function tryStaticHandler(
+  entry: EntryData,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const entryAny = entry as any;
+  if (entryAny.isStaticPrerender && entryAny.staticHandlerId) {
+    return tryStaticLookup(entryAny.staticHandlerId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Try to resolve a parallel slot component from the build-time static store.
+ * Returns undefined synchronously when no static handler ID exists for the slot.
+ */
+export function tryStaticSlot(
+  parallelEntry: EntryData,
+  slot: string,
+  segmentId: string,
+): Promise<ReactNode | undefined> | undefined {
+  const slotStaticId = (parallelEntry as any).staticHandlerIds?.[slot];
+  if (slotStaticId) {
+    return tryStaticLookup(slotStaticId, segmentId);
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a layout or cache entry's handler component.
+ * Checks build-time static store first, then invokes the handler.
+ */
+export async function resolveLayoutComponent<TEnv>(
+  entry: EntryData,
+  context: HandlerContext<any, TEnv>,
+): Promise<ReactNode> {
+  const component = await tryStaticHandler(entry, entry.shortCode);
+  if (component !== undefined) return component;
+  return typeof entry.handler === "function"
+    ? handleHandlerResult(await entry.handler(context))
+    : (entry.handler as ReactNode);
+}
+
+// ---------------------------------------------------------------------------
+// Error boundary segment creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Context for error reporting in segment resolution.
+ * When provided, callOnError is invoked with this context.
+ */
+export interface ErrorReportContext {
+  request?: Request;
+  url?: URL;
+  routeKey?: string;
+  env?: any;
+  isPartial?: boolean;
+  requestStartTime?: number;
+  telemetry?: TelemetrySink;
+}
+
+/**
+ * Handle a caught error during segment resolution by creating an
+ * error or not-found segment with the nearest boundary.
+ *
+ * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ */
+export function catchSegmentError<TEnv>(
+  error: unknown,
+  entry: EntryData,
+  params: Record<string, string>,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+): ResolvedSegment {
+  const reportError = (
+    handledByBoundary: boolean,
+    metadata?: Record<string, unknown>,
+  ) => {
+    if (!report) return;
+    deps.callOnError(error, "handler", {
+      request: report.request as Request,
+      url: report.url,
+      routeKey: report.routeKey,
+      params,
+      segmentId: entry.shortCode,
+      segmentType: entry.type as any,
+      env: report.env,
+      isPartial: report.isPartial,
+      handledByBoundary,
+      metadata,
+      requestStartTime: report.requestStartTime,
+    });
+    if (report.telemetry) {
+      const errorObj =
+        error instanceof Error ? error : new Error(String(error));
+      safeEmit(resolveSink(report.telemetry), {
+        type: "handler.error",
+        timestamp: performance.now(),
+        requestId: report.request ? getRequestId(report.request) : undefined,
+        segmentId: entry.shortCode,
+        segmentType: entry.type,
+        error: errorObj,
+        handledByBoundary,
+        pathname,
+        routeKey: report.routeKey,
+        params,
+      });
+    }
+  };
+
+  const setResponseStatus = (status: number) => {
+    const reqCtx = getRequestContext();
+    if (reqCtx) {
+      reqCtx._setStatus(status);
+    }
+  };
+
+  if (error instanceof DataNotFoundError) {
+    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+
+    if (notFoundFallback) {
+      const notFoundInfo = createNotFoundInfo(
+        error,
+        entry.shortCode,
+        entry.type,
+        pathname,
+      );
+
+      reportError(true, {
+        notFound: true,
+        message: notFoundInfo.message,
+      });
+
+      debugLog("segment", "notFound boundary handled error", {
+        segmentId: entry.shortCode,
+        message: notFoundInfo.message,
+      });
+
+      setResponseStatus(404);
+
+      return createNotFoundSegment(
+        notFoundInfo,
+        notFoundFallback,
+        entry,
+        params,
+      );
+    }
+  }
+
+  const fallback = deps.findNearestErrorBoundary(entry);
+  const segmentType: ErrorInfo["segmentType"] = entry.type;
+  const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);
+  const effectiveFallback = fallback ?? DefaultErrorFallback;
+
+  reportError(!!effectiveFallback);
+
+  debugLog("segment", "error boundary handled error", {
+    segmentId: entry.shortCode,
+    boundary: fallback ? "custom" : "default",
+    message: errorInfo.message,
+  });
+
+  setResponseStatus(500);
+
+  return createErrorSegment(errorInfo, effectiveFallback, entry, params);
+}
+
+/**
+ * Generic error boundary wrapper for segment resolution.
+ * Catches non-Response errors and produces an error/notFound segment
+ * via catchSegmentError. Response throws (e.g. redirects) are re-thrown.
+ *
+ * The caller provides a `wrapError` callback to shape the error segment
+ * into the expected return type (e.g. ResolvedSegment[] for the fresh
+ * path, or SegmentRevalidationResult for the revalidation path).
+ */
+export async function resolveWithErrorBoundary<TEnv, TResult>(
+  entry: EntryData,
+  params: Record<string, string>,
+  resolveFn: () => Promise<TResult>,
+  wrapError: (segment: ResolvedSegment) => TResult,
+  deps: SegmentResolutionDeps<TEnv>,
+  report?: ErrorReportContext,
+  pathname?: string,
+): Promise<TResult> {
+  try {
+    return await resolveFn();
+  } catch (error) {
+    if (error instanceof Response) throw error;
+    const segment = catchSegmentError(
+      error,
+      entry,
+      params,
+      deps,
+      report,
+      pathname,
+    );
+    return wrapError(segment);
+  }
+}

package/src/router/segment-resolution/loader-cache.ts

@@ -0,0 +1,198 @@
+/**
+ * Loader-Level Caching
+ *
+ * When a LoaderEntry has a cache config (set via loader(Fn, () => [cache({...})])),
+ * this module wraps the loader execution with cache lookup/store using the
+ * getItem()/setItem() methods on SegmentCacheStore.
+ *
+ * Cache key resolution (3-tier, matching CacheScope.resolveKey):
+ *   1. options.key(requestCtx) — full override
+ *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
+ *   3. loader:{loaderId}:{pathname}:{sortedParams} — default
+ *
+ * Values are serialized via RSC Flight (serializeResult/deserializeResult),
+ * supporting ReactNode, Promises, null, and all RSC-serializable types.
+ *
+ * On hit: returns cached data directly, skips loader execution.
+ * On stale hit (SWR): returns stale data, schedules background revalidation.
+ * On miss: executes loader, schedules non-blocking cache write.
+ */
+
+import type { LoaderEntry } from "../../server/context.js";
+import type { HandlerContext } from "../../types.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import { getRequestContext } from "../../server/request-context.js";
+import { sortedRouteParams } from "../../cache/cache-key-utils.js";
+import {
+  resolveTtl,
+  resolveSwrWindow,
+  resolveCacheKey,
+  resolveCacheStore,
+  DEFAULT_ROUTE_TTL,
+} from "../../cache/cache-policy.js";
+import { readThroughItem } from "../../cache/read-through-swr.js";
+// Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
+// import segment-resolution but never use loader caching.
+let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
+let _deserializeResult: typeof import("../../cache/segment-codec.js").deserializeResult;
+async function getCodec() {
+  if (!_serializeResult) {
+    const mod = await import("../../cache/segment-codec.js");
+    _serializeResult = mod.serializeResult;
+    _deserializeResult = mod.deserializeResult;
+  }
+  return {
+    serializeResult: _serializeResult,
+    deserializeResult: _deserializeResult,
+  };
+}
+
+function debugLoaderCacheLog(message: string): void {
+  if (INTERNAL_RANGO_DEBUG) {
+    console.log(message);
+  }
+}
+
+function getDefaultLoaderCacheKey(
+  loaderId: string,
+  pathname: string,
+  params: Record<string, string>,
+): string {
+  const paramStr = sortedRouteParams(params);
+  const base = paramStr ? `${pathname}:${paramStr}` : pathname;
+  return `loader:${loaderId}:${base}`;
+}
+
+/**
+ * Resolve cache key using the shared 3-tier priority.
+ */
+async function resolveLoaderKey(
+  loaderEntry: LoaderEntry,
+  store: import("../../cache/types.js").SegmentCacheStore,
+  loaderId: string,
+  pathname: string,
+  params: Record<string, string>,
+): Promise<string> {
+  const options = loaderEntry.cache!.options;
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
+  if (options === false) return defaultKey;
+  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
+}
+
+/**
+ * Resolve tags from cache options (static array or function).
+ * Fails open: a thrown tag callback falls back to no tags rather than
+ * aborting the request. Tags are additive metadata (not identity), so
+ * a missing tag does not cause cache collisions.
+ */
+function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
+  const options = loaderEntry.cache?.options;
+  if (!options || !options.tags) return undefined;
+
+  if (typeof options.tags === "function") {
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return undefined;
+    try {
+      return options.tags(requestCtx);
+    } catch (error) {
+      console.error(
+        `[LoaderCache] Tags function failed, caching without tags:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+
+  return options.tags;
+}
+
+function getLoaderStore(
+  loaderEntry: LoaderEntry,
+): import("../../cache/types.js").SegmentCacheStore | null {
+  const cacheConfig = loaderEntry.cache;
+  if (!cacheConfig || cacheConfig.options === false) return null;
+  return resolveCacheStore(cacheConfig.options.store);
+}
+
+/**
+ * Resolve loader data with optional caching.
+ *
+ * When the LoaderEntry has no cache config, delegates directly to ctx.use(loader).
+ * When cached, checks store first and stores on miss via waitUntil.
+ */
+export function resolveLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
+): Promise<any> {
+  const cacheConfig = loaderEntry.cache;
+
+  // No cache config or disabled — run fresh (zero overhead path)
+  if (!cacheConfig || cacheConfig.options === false) {
+    return ctx.use(loaderEntry.loader);
+  }
+
+  const store = getLoaderStore(loaderEntry);
+  if (!store?.getItem || !store?.setItem) {
+    return ctx.use(loaderEntry.loader);
+  }
+
+  // Evaluate runtime condition if provided
+  const options = cacheConfig.options;
+  if (options.condition) {
+    const requestCtx = getRequestContext();
+    if (requestCtx && !options.condition(requestCtx)) {
+      return ctx.use(loaderEntry.loader);
+    }
+  }
+
+  const loaderId = loaderEntry.loader.$$id;
+  const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
+  const swrWindow = resolveSwrWindow(options.swr, store.defaults);
+  const swr = swrWindow || undefined;
+  const tags = resolveTags(loaderEntry);
+
+  // Wrap ctx.use() so cache HIT primes the handler's memoization map.
+  // ctx.use() closes over the match context's loaderPromises (not request context's).
+  // By intercepting ctx.use(), we inject cached data into the correct map.
+  const originalUse = ctx.use;
+  const dataPromise = (async () => {
+    const codec = await getCodec();
+    const key = await resolveLoaderKey(
+      loaderEntry,
+      store,
+      loaderId,
+      pathname,
+      ctx.params,
+    );
+
+    return readThroughItem({
+      getItem: (k) => store.getItem!(k),
+      setItem: (k, v, o) => store.setItem!(k, v, o),
+      key,
+      execute: () => originalUse(loaderEntry.loader),
+      serialize: (d) => codec.serializeResult(d),
+      deserialize: (v) => codec.deserializeResult(v),
+      storeOptions: { ttl, swr, tags },
+      onHit: () => debugLoaderCacheLog(`[LoaderCache] HIT: ${key}`),
+      onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
+      onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
+      onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
+      host: getRequestContext(),
+    });
+  })();
+
+  // Temporarily replace ctx.use() so the handler's call returns cached data.
+  // This is needed because ctx.use() closes over the match context's loaderPromises
+  // map which is separate from the request context. By wrapping use(), we intercept
+  // the handler's call and return the shared dataPromise.
+  const wrappedUse = ((item: any) => {
+    if (item === loaderEntry.loader || item?.$$id === loaderId) {
+      return dataPromise;
+    }
+    return originalUse(item);
+  }) as typeof ctx.use;
+  ctx.use = wrappedUse;
+
+  return dataPromise;
+}