@rangojs/router 0.0.0-experimental.2

package/src/server/context.ts

@@ -0,0 +1,417 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ReactNode } from "react";
+import type { PartialCacheOptions, ErrorBoundaryHandler, Handler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ShouldRevalidateFn } from "../types";
+import { invariant } from "../errors";
+
+// ============================================================================
+//  Performance Metrics Types
+// ============================================================================
+
+/**
+ * Performance metric entry for a single measured operation
+ */
+export interface PerformanceMetric {
+  label: string;      // e.g., "route-matching", "loader:UserLoader"
+  duration: number;   // milliseconds
+  startTime: number;  // relative to request start
+}
+
+/**
+ * Request-scoped metrics store
+ */
+export interface MetricsStore {
+  enabled: boolean;
+  requestStart: number;
+  metrics: PerformanceMetric[];
+}
+// ============================================================================
+//  RSC Router Context
+// ============================================================================
+
+/**
+ * Cache configuration for an entry
+ * When set, this entry and its children will use this cache config
+ * unless overridden by a nested cache() call.
+ */
+export type EntryCacheConfig = {
+  /** Cache options (false means caching disabled for this entry) - ttl is optional, uses defaults */
+  options: PartialCacheOptions | false;
+};
+
+/**
+ * Entry data structure for manifest
+ */
+export type EntryPropCommon = {
+  id: string;
+  shortCode: string; // Short identifier for network efficiency (e.g., "L0", "P1", "R2")
+  parent: EntryData | null;
+  /** Cache configuration for this entry (set by cache() DSL) */
+  cache?: EntryCacheConfig;
+};
+export type EntryPropDatas = {
+  middleware: MiddlewareFn<any, any>[];
+  revalidate: ShouldRevalidateFn<any, any>[];
+  errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+  notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+};
+/**
+ * Loader entry stored in EntryData
+ * Contains the loader definition and its revalidation rules
+ */
+export type LoaderEntry = {
+  loader: LoaderDefinition<any>;
+  revalidate: ShouldRevalidateFn<any, any>[];
+  /** Cache config for this specific loader (loaders are NOT cached by default) */
+  cache?: EntryCacheConfig;
+};
+
+/**
+ * Segments state for intercept context
+ * Matches the structure from useSegments() for consistency
+ */
+export type InterceptSegmentsState = {
+  /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+  path: readonly string[];
+  /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+  ids: readonly string[];
+};
+
+/**
+ * Context passed to intercept selector functions (when())
+ * Contains navigation context to determine if interception should occur.
+ *
+ * Note: when() is evaluated during route matching, BEFORE middleware runs.
+ * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
+ */
+export type InterceptSelectorContext<TEnv = any> = {
+  from: URL;                              // Source URL (where user is coming from)
+  to: URL;                                // Destination URL (where user is navigating to)
+  params: Record<string, string>;         // Matched route params
+  request: Request;                       // The HTTP request object
+  env: TEnv;                              // Platform bindings (Cloudflare env, etc.)
+  segments: InterceptSegmentsState;       // Client's current segments (where navigating FROM)
+};
+
+/**
+ * Selector function for conditional interception
+ * Returns true to intercept, false to skip and fall through to route handler
+ */
+export type InterceptWhenFn<TEnv = any> = (ctx: InterceptSelectorContext<TEnv>) => boolean;
+
+/**
+ * Intercept entry stored in EntryData
+ * Contains the slot name, route to intercept, and handler
+ */
+export type InterceptEntry = {
+  slotName: `@${string}`;  // e.g., "@modal"
+  routeName: string;        // e.g., "card"
+  handler: ReactNode | Handler<any, any>;
+  middleware: MiddlewareFn<any, any>[];
+  revalidate: ShouldRevalidateFn<any, any>[];
+  errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
+  notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
+  loader: LoaderEntry[];
+  loading?: ReactNode | false;
+  layout?: ReactNode | Handler<any, any>;  // Wrapper layout with <Outlet /> for content
+  when: InterceptWhenFn[];  // Selector conditions - all must return true to intercept
+};
+
+export type EntryPropSegments = {
+  loader: LoaderEntry[];
+  layout: EntryData[];
+  parallel: EntryData[]; // type: "parallel" entries with their own loaders/revalidate/loading
+  intercept: InterceptEntry[]; // intercept definitions for soft navigation
+};
+
+export type EntryData =
+  | ({
+      type: "route";
+      handler: Handler<any, any>;
+      loading?: ReactNode | false;
+      /** URL pattern for this route (used by path() in urls()) */
+      pattern?: string;
+    } & EntryPropCommon &
+      EntryPropDatas &
+      EntryPropSegments)
+  | ({
+      type: "layout";
+      handler: ReactNode | Handler<any, any>;
+      loading?: ReactNode | false;
+    } & EntryPropCommon &
+      EntryPropDatas &
+      EntryPropSegments)
+  | ({
+      type: "parallel";
+      handler: Record<`@${string}`, Handler<any, any> | ReactNode>;
+      loading?: ReactNode | false;
+    } & EntryPropCommon &
+      EntryPropDatas &
+      EntryPropSegments)
+  | ({
+      type: "cache";
+      /** Cache entries create cache boundaries and render like layouts (with Outlet) */
+      handler: ReactNode | Handler<any, any>;
+      loading?: ReactNode | false;
+    } & EntryPropCommon &
+      EntryPropDatas &
+      EntryPropSegments);
+
+/**
+ * Context stored in AsyncLocalStorage
+ */
+interface HelperContext {
+  manifest: Map<string, EntryData>;
+  namespace: string;
+  parent: EntryData | null;
+  counters: Record<string, number>;
+  forRoute?: string;
+  mountIndex?: number;
+  metrics?: MetricsStore;
+  /** True when rendering for SSR (document requests) */
+  isSSR?: boolean;
+  /** URL patterns map for path() routes (route name -> pattern) */
+  patterns?: Map<string, string>;
+  /** Trailing slash config per route name */
+  trailingSlash?: Map<string, "never" | "always" | "ignore">;
+  /** URL prefix from include() - applied to all path() patterns */
+  urlPrefix?: string;
+  /** Name prefix from include() - applied to all named routes */
+  namePrefix?: string;
+  /** Run helper for cleaner middleware code */
+  run?: <T>(fn: () => T | Promise<T>) => T | Promise<T>;
+}
+export const RSCRouterContext: AsyncLocalStorage<HelperContext> =
+  new AsyncLocalStorage<HelperContext>();
+
+export const getContext = (): {
+  context: AsyncLocalStorage<HelperContext>;
+  getStore: () => HelperContext;
+  getParent: () => EntryData | null;
+  getOrCreateStore: (forRoute?: string) => HelperContext;
+  getNextIndex: (
+    type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate"
+  ) => string;
+  getShortCode: (
+    type: "layout" | "parallel" | "route" | "loader" | "cache"
+  ) => string;
+  run: <T>(
+    namespace: string,
+    parent: EntryData | null,
+    callback: (...args: any[]) => T
+  ) => T;
+  runWithStore: <T>(
+    store: HelperContext,
+    namespace: string,
+    parent: EntryData | null,
+    callback: (...args: any[]) => T
+  ) => T;
+} => {
+  const context = RSCRouterContext;
+
+  return {
+    context,
+    getOrCreateStore: (forRoute?: string): HelperContext => {
+      let store = RSCRouterContext.getStore();
+      if (!store) {
+        store = {
+          manifest: new Map<string, EntryData>(),
+          namespace: "",
+          parent: null,
+          forRoute,
+          counters: {},
+          patterns: new Map<string, string>(),
+          trailingSlash: new Map<string, "never" | "always" | "ignore">(),
+        } satisfies HelperContext;
+      }
+      return store;
+    },
+    getStore: (): HelperContext => {
+      const store = context.getStore();
+      if (!store) {
+        throw new Error(
+          "RSC Router context store is not available. Make sure to run within RSC Router context."
+        );
+      }
+      return store;
+    },
+    getParent: (): EntryData | null => {
+      const store = context.getStore();
+      if (!store) {
+        return null;
+      }
+
+      return store.parent;
+    },
+    getNextIndex: (
+      type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate"
+    ) => {
+      const store = context.getStore();
+      invariant(store, "No context RSCRouterContext available");
+      store.counters[type] ??= 0;
+      const index = store.counters[type];
+      store.counters[type] = index + 1;
+      return `$${type}.${index}`;
+    },
+    getShortCode: (type: "layout" | "parallel" | "route" | "loader" | "cache") => {
+      const store = context.getStore();
+      invariant(store, "No context RSCRouterContext available");
+
+      const parent = store.parent;
+      const prefix = type === "layout" ? "L" : type === "parallel" ? "P" : type === "loader" ? "D" : type === "cache" ? "C" : "R";
+      const mountPrefix = store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
+
+      if (!parent) {
+        // Root entry: prefix with mount index and use mount-scoped counter
+        const counterKey = mountPrefix ? `${mountPrefix}_root_${type}` : `root_${type}`;
+        store.counters[counterKey] ??= 0;
+        const index = store.counters[counterKey];
+        store.counters[counterKey] = index + 1;
+        return `${mountPrefix}${prefix}${index}`;
+      } else {
+        // Child entry: use parent-scoped counter (parent already has M prefix)
+        const counterKey = `${parent.shortCode}_${type}`;
+        store.counters[counterKey] ??= 0;
+        const index = store.counters[counterKey];
+        store.counters[counterKey] = index + 1;
+        return `${parent.shortCode}${prefix}${index}`;
+      }
+    },
+    runWithStore: <T>(
+      store: HelperContext,
+      namespace: string,
+      parent: EntryData | null,
+      callback: (...args: any[]) => T
+    ): T => {
+      return context.run(
+        {
+          manifest: store.manifest,
+          namespace,
+          parent: parent || null,
+          counters: store.counters,
+          forRoute: store.forRoute,
+          mountIndex: store.mountIndex,
+          metrics: store.metrics,
+          isSSR: store.isSSR,
+          patterns: store.patterns,
+          trailingSlash: store.trailingSlash,
+          urlPrefix: store.urlPrefix,
+          namePrefix: store.namePrefix,
+        },
+        callback
+      );
+    },
+    run: <T>(
+      namespace: string,
+      parent: EntryData | null,
+      callback: (...args: any[]) => T
+    ) => {
+      const store = context.getStore();
+      // Preserve parent counters to ensure globally unique shortCodes
+      const counters = store?.counters || {};
+      const manifest = store ? store.manifest : new Map<string, EntryData>();
+      const patterns = store?.patterns || new Map<string, string>();
+      const trailingSlash = store?.trailingSlash || new Map<string, "never" | "always" | "ignore">();
+      return context.run(
+        {
+          manifest,
+          namespace,
+          parent: parent || null,
+          counters,
+          forRoute: store?.forRoute,
+          mountIndex: store?.mountIndex,
+          metrics: store?.metrics,
+          isSSR: store?.isSSR,
+          patterns,
+          trailingSlash,
+          urlPrefix: store?.urlPrefix,
+          namePrefix: store?.namePrefix,
+        },
+        callback
+      );
+    },
+  };
+};
+
+/**
+ * Run a callback with specific URL and name prefixes
+ * Used by include() to apply prefixes to nested patterns
+ */
+export function runWithPrefixes<T>(
+  urlPrefix: string,
+  namePrefix: string | undefined,
+  callback: () => T
+): T {
+  const store = RSCRouterContext.getStore();
+  if (!store) {
+    throw new Error("runWithPrefixes must be called within router context");
+  }
+
+  // Combine prefixes if there are existing ones
+  const combinedUrlPrefix = store.urlPrefix
+    ? `${store.urlPrefix}${urlPrefix}`
+    : urlPrefix;
+  const combinedNamePrefix = namePrefix
+    ? store.namePrefix
+      ? `${store.namePrefix}.${namePrefix}`
+      : namePrefix
+    : store.namePrefix;
+
+  return RSCRouterContext.run(
+    {
+      ...store,
+      urlPrefix: combinedUrlPrefix,
+      namePrefix: combinedNamePrefix,
+    },
+    callback
+  );
+}
+
+/**
+ * Get current URL prefix from context
+ */
+export function getUrlPrefix(): string {
+  const store = RSCRouterContext.getStore();
+  return store?.urlPrefix || "";
+}
+
+/**
+ * Get current name prefix from context
+ */
+export function getNamePrefix(): string | undefined {
+  const store = RSCRouterContext.getStore();
+  return store?.namePrefix;
+}
+
+// Export HelperContext type for use in other modules
+export type { HelperContext };
+
+// ============================================================================
+//  Performance Metrics Helpers
+// ============================================================================
+
+/**
+ * Track performance of a code block (no-op if metrics not enabled)
+ * Returns a done() callback to mark completion and record duration
+ *
+ * @example
+ * ```typescript
+ * const done = track("route-matching");
+ * // ... do work ...
+ * done(); // Records duration
+ * ```
+ */
+export function track(label: string): () => void {
+  const store = RSCRouterContext.getStore();
+
+  // No-op if context unavailable or metrics not enabled
+  if (!store?.metrics?.enabled) {
+    return () => {};
+  }
+
+  const startTime = performance.now() - store.metrics.requestStart;
+
+  return () => {
+    const duration = performance.now() - store.metrics!.requestStart - startTime;
+    store.metrics!.metrics.push({ label, duration, startTime });
+  };
+}

package/src/server/handle-store.ts

@@ -0,0 +1,230 @@
+/**
+ * Handle data structure: handleName -> segmentId -> entries[]
+ *
+ * @example
+ * ```ts
+ * {
+ *   "breadcrumbs": {
+ *     "$root.layout": [{ label: "Home", href: "/" }],
+ *     "shop.layout": [{ label: "Shop", href: "/shop" }],
+ *   }
+ * }
+ * ```
+ */
+export type HandleData = Record<string, Record<string, unknown[]>>;
+
+/**
+ * Deep clone handle data to create a snapshot.
+ * @internal
+ */
+function cloneHandleData(data: HandleData): HandleData {
+  const clone: HandleData = {};
+  for (const handleName in data) {
+    clone[handleName] = {};
+    for (const segmentId in data[handleName]) {
+      clone[handleName][segmentId] = [...data[handleName][segmentId]];
+    }
+  }
+  return clone;
+}
+
+/**
+ * HandleStore tracks pending handler promises and stores handle data.
+ *
+ * Combines two responsibilities:
+ * 1. Promise tracking - know when all handlers have resolved
+ * 2. Data storage - collect handle data pushed by handlers
+ * 3. Streaming - emit handle data via async iterator on each push
+ */
+export interface HandleStore {
+  /**
+   * Track a handler promise (non-blocking).
+   * Returns the promise unchanged - just registers it for tracking.
+   */
+  track<T>(promise: Promise<T>): Promise<T>;
+
+  /**
+   * Promise that resolves when all tracked handlers have settled.
+   * Does not reject - uses Promise.allSettled internally.
+   */
+  readonly settled: Promise<void>;
+
+  /**
+   * Push handle data for a specific handle and segment.
+   * Multiple pushes to the same handle/segment accumulate in an array.
+   * Each push triggers an emission on the stream.
+   */
+  push(handleName: string, segmentId: string, data: unknown): void;
+
+  /**
+   * Get all collected handle data after all handlers have settled.
+   * Returns a promise that waits for `settled`, then returns the data.
+   * The data may contain unresolved promises which RSC will stream.
+   * @deprecated Use stream() for progressive updates
+   */
+  getData(): Promise<HandleData>;
+
+  /**
+   * Get an async iterator that yields handle data on each push.
+   * The iterator completes when all handlers have settled.
+   * Each yield contains the full accumulated state (not just the delta).
+   */
+  stream(): AsyncGenerator<HandleData, void, unknown>;
+
+  /**
+   * Get handle data for a specific segment (for caching).
+   * Returns data in format: { handleName: [values...] }
+   */
+  getDataForSegment(segmentId: string): Record<string, unknown[]>;
+
+  /**
+   * Replay cached handle data back into the store (for cache hits).
+   * Used to restore handle data when serving cached segments.
+   */
+  replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void;
+}
+
+/**
+ * Create a new HandleStore instance.
+ *
+ * @example
+ * ```ts
+ * const handleStore = createHandleStore();
+ *
+ * // In router - track without awaiting
+ * const component = handleStore.track(entry.handler(context));
+ *
+ * // In handler - push handle data (value, promise, or async callback result)
+ * handleStore.push("breadcrumbs", segmentId, { label: "Home", href: "/" });
+ * handleStore.push("meta", segmentId, fetchMetaAsync()); // promise
+ *
+ * // Stream handle data progressively
+ * for await (const handles of handleStore.stream()) {
+ *   console.log("Handle update:", handles);
+ * }
+ * ```
+ */
+export function createHandleStore(): HandleStore {
+  const pending: Promise<unknown>[] = [];
+  const data: HandleData = {};
+
+  // Queue for pending emissions and resolver for waiting consumer
+  let pendingEmissions: HandleData[] = [];
+  let emissionResolver: (() => void) | null = null;
+  let completed = false;
+
+  // Signal that a new emission is available
+  function signalEmission() {
+    if (emissionResolver) {
+      const resolver = emissionResolver;
+      emissionResolver = null;
+      resolver();
+    }
+  }
+
+  // Wait for the next emission or completion
+  function waitForEmission(): Promise<void> {
+    if (pendingEmissions.length > 0 || completed) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      emissionResolver = resolve;
+    });
+  }
+
+  return {
+    track<T>(promise: Promise<T>): Promise<T> {
+      pending.push(promise);
+      return promise;
+    },
+
+    get settled(): Promise<void> {
+      if (pending.length === 0) {
+        return Promise.resolve();
+      }
+      return Promise.allSettled(pending).then(() => {});
+    },
+
+    push(handleName: string, segmentId: string, value: unknown): void {
+      if (!data[handleName]) {
+        data[handleName] = {};
+      }
+      if (!data[handleName][segmentId]) {
+        data[handleName][segmentId] = [];
+      }
+      data[handleName][segmentId].push(value);
+
+      // Queue a snapshot for emission
+      pendingEmissions.push(cloneHandleData(data));
+      signalEmission();
+    },
+
+    getData(): Promise<HandleData> {
+      return this.settled.then(() => data);
+    },
+
+    async *stream(): AsyncGenerator<HandleData, void, unknown> {
+      // Set up completion handler
+      this.settled.then(() => {
+        completed = true;
+        signalEmission();
+      });
+
+      // Initial small delay to batch rapid synchronous pushes
+      // This allows multiple handles pushing in quick succession to be batched
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      // If we already have data, yield the accumulated state
+      if (Object.keys(data).length > 0) {
+        // Clear pending emissions since we're yielding current state
+        pendingEmissions = [];
+        yield cloneHandleData(data);
+      }
+
+      // Continue streaming on each push
+      while (!completed) {
+        await waitForEmission();
+
+        // Yield all pending emissions (yield latest only)
+        if (pendingEmissions.length > 0) {
+          // Skip intermediate states, yield the latest
+          const latest = pendingEmissions[pendingEmissions.length - 1];
+          pendingEmissions = [];
+          yield latest;
+        }
+      }
+
+      // Final yield only if there are pending emissions that weren't yielded
+      // (handles that pushed after our last yield but before completion)
+      if (pendingEmissions.length > 0) {
+        yield cloneHandleData(data);
+      }
+    },
+
+    getDataForSegment(segmentId: string): Record<string, unknown[]> {
+      const result: Record<string, unknown[]> = {};
+      for (const handleName in data) {
+        if (data[handleName][segmentId]) {
+          result[handleName] = [...data[handleName][segmentId]];
+        }
+      }
+      return result;
+    },
+
+    replaySegmentData(segmentId: string, segmentHandles: Record<string, unknown[]>): void {
+      for (const handleName in segmentHandles) {
+        if (!data[handleName]) {
+          data[handleName] = {};
+        }
+        if (!data[handleName][segmentId]) {
+          data[handleName][segmentId] = [];
+        }
+        // Append replayed data
+        data[handleName][segmentId].push(...segmentHandles[handleName]);
+      }
+      // Trigger emission for streaming
+      pendingEmissions.push(cloneHandleData(data));
+      signalEmission();
+    },
+  };
+}