@ivogt/rsc-router 0.0.0-experimental.1

package/src/router/router-context.ts

@@ -0,0 +1,299 @@
+/**
+ * Router Context using AsyncLocalStorage
+ *
+ * Provides clean dependency injection for router middleware without parameter drilling.
+ * All closure functions from createRSCRouter() are made available via getRouterContext().
+ */
+import { AsyncLocalStorage } from "async_hooks";
+import type { CacheScope } from "../cache/cache-scope.js";
+import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+  MetricsStore,
+} from "../server/context.js";
+import type {
+  HandlerContext,
+  ResolvedSegment,
+  ShouldRevalidateFn,
+} from "../types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Revalidation context passed to segment resolution
+ */
+export interface RevalidationContext {
+  clientSegmentIds: Set<string>;
+  prevParams: Record<string, string>;
+  request: Request;
+  prevUrl: URL;
+  nextUrl: URL;
+  routeKey: string;
+  actionContext?: {
+    actionId?: string;
+    actionUrl?: URL;
+    actionResult?: any;
+    formData?: FormData;
+  };
+  stale: boolean;
+}
+
+/**
+ * Result from intercept lookup
+ */
+export interface InterceptResult {
+  intercept: InterceptEntry;
+  entry: EntryData;
+}
+
+/**
+ * Router context available via AsyncLocalStorage
+ *
+ * Contains closure functions from createRSCRouter() that middleware needs access to.
+ * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
+ */
+export interface RouterContext<TEnv = any> {
+  // Route matching
+  findMatch: (pathname: string) => RouteMatchResult | null;
+
+  // Manifest loading
+  loadManifest: (
+    entry: any,
+    routeKey: string,
+    pathname: string,
+    metricsStore?: MetricsStore,
+    isSSR?: boolean
+  ) => Promise<EntryData>;
+
+  // Entry traversal
+  traverseBack: (entry: EntryData) => Generator<EntryData>;
+
+  // Handler context creation
+  createHandlerContext: (
+    params: Record<string, string>,
+    request: Request,
+    searchParams: URLSearchParams,
+    pathname: string,
+    url: URL,
+    env: TEnv
+  ) => HandlerContext<any, TEnv>;
+
+  // Loader setup
+  setupLoaderAccess: (
+    ctx: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>
+  ) => void;
+
+  setupLoaderAccessSilent: (
+    ctx: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>
+  ) => void;
+
+  // Context access
+  getContext: () => {
+    getOrCreateStore: (key: string) => any;
+    runWithStore: <T>(
+      store: any,
+      namespace: string,
+      parent: any,
+      fn: () => T
+    ) => T;
+  };
+
+  // Metrics
+  getMetricsStore: () => MetricsStore | undefined;
+
+  // Cache
+  createCacheScope: (
+    cacheConfig: any,
+    parent: CacheScope | null
+  ) => CacheScope | null;
+
+  // Intercept detection
+  findInterceptForRoute: (
+    routeKey: string,
+    parentEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext,
+    isAction: boolean
+  ) => InterceptResult | null;
+
+  // Segment resolution (with revalidation)
+  resolveAllSegmentsWithRevalidation: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext: any | undefined,
+    interceptResult: InterceptResult | null,
+    localRouteName: string,
+    pathname: string
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+
+  // Generator-based segment resolution (for pipeline)
+  resolveAllSegmentsWithRevalidationGenerator?: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext?: any
+  ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
+
+  // Intercept resolution
+  resolveInterceptEntry: (
+    intercept: InterceptEntry,
+    entry: EntryData,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean,
+    revalidationContext?: RevalidationContext
+  ) => Promise<ResolvedSegment[]>;
+
+  // Collect with markers
+  collectWithMarkers?: <T>(
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>
+  ) => Promise<{ items: T[]; matchedIds: string[] }>;
+
+  // Revalidation evaluation
+  evaluateRevalidation: (params: {
+    segment: ResolvedSegment;
+    prevParams: Record<string, string>;
+    getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
+    request: Request;
+    prevUrl: URL;
+    nextUrl: URL;
+    revalidations: Array<{ name: string; fn: any }>;
+    routeKey: string;
+    context: HandlerContext<any, TEnv>;
+    actionContext?: any;
+    stale?: boolean;
+  }) => Promise<boolean>;
+
+  // Request context
+  getRequestContext: () =>
+    | {
+        waitUntil: (fn: () => Promise<void>) => void;
+        _handleStore?: any;
+      }
+    | undefined;
+
+  // Simple segment resolution (without revalidation - for full match)
+  resolveAllSegments: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>
+  ) => Promise<ResolvedSegment[]>;
+
+  // Generator-based simple resolution
+  resolveAllSegmentsGenerator?: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>
+  ) => AsyncGenerator<ResolvedSegment | { __type: "id"; id: string }>;
+
+  // Collect segments from generator
+  collectSegmentsFromGenerator?: <T>(
+    gen: AsyncGenerator<T | { __type: "id"; id: string }>
+  ) => Promise<T[]>;
+
+  // Handle store
+  createHandleStore: () => any;
+
+  // Loaders-only resolution (for full match cache hit - no revalidation)
+  resolveLoadersOnly?: (
+    entries: EntryData[],
+    handlerContext: HandlerContext<any, TEnv>
+  ) => Promise<ResolvedSegment[]>;
+
+  // Loaders-only resolution (for cache hit scenarios)
+  resolveLoadersOnlyWithRevalidation?: (
+    entries: EntryData[],
+    handlerContext: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: any
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+
+  // Entry revalidation map
+  buildEntryRevalidateMap?: (
+    entries: EntryData[]
+  ) => Map<string, { revalidate: ShouldRevalidateFn[] }>;
+
+  // Intercept loaders only (for cache hit + intercept scenarios)
+  resolveInterceptLoadersOnly?: (
+    intercept: InterceptEntry,
+    entry: EntryData,
+    params: Record<string, string>,
+    handlerContext: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean,
+    revalidationContext: {
+      clientSegmentIds: Set<string>;
+      prevParams: Record<string, string>;
+      request: Request;
+      prevUrl: URL;
+      nextUrl: URL;
+      routeKey: string;
+      actionContext?: any;
+      stale?: boolean;
+    }
+  ) => Promise<{
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+  } | null>;
+}
+
+// AsyncLocalStorage instance for router context
+const routerContext = new AsyncLocalStorage<RouterContext<any>>();
+
+/**
+ * Get router dependencies from AsyncLocalStorage context
+ *
+ * @throws Error if called outside of router context (runWithRouterContext)
+ */
+export function getRouterContext<TEnv = any>(): RouterContext<TEnv> {
+  const deps = routerContext.getStore();
+  if (!deps) {
+    throw new Error(
+      "getRouterContext() called outside of router context. " +
+        "Ensure code is running inside runWithRouterContext()."
+    );
+  }
+  return deps as RouterContext<TEnv>;
+}
+
+/**
+ * Run a function with router dependencies available via getRouterContext()
+ *
+ * All async code within fn() can call getRouterContext() to access router closures.
+ * This works across async boundaries thanks to AsyncLocalStorage.
+ *
+ * @param deps Router dependencies to make available
+ * @param fn Function to run with dependencies available
+ * @returns Result of fn()
+ */
+export function runWithRouterContext<T, TEnv = any>(
+  deps: RouterContext<TEnv>,
+  fn: () => T
+): T {
+  return routerContext.run(deps, fn);
+}
+

package/src/router/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Router Internal Types
+ *
+ * Shared types for router module utilities.
+ */
+
+import type { ReactNode } from "react";
+import type { EntryData } from "../server/context";
+import type {
+  ResolvedSegment,
+  HandlerContext,
+  ErrorBoundaryHandler,
+  NotFoundBoundaryHandler,
+} from "../types";
+
+/**
+ * Result of resolving loaders with revalidation
+ * Contains both segments to render and all matched segment IDs
+ */
+export interface LoaderRevalidationResult {
+  segments: ResolvedSegment[];
+  matchedIds: string[];
+}
+
+/**
+ * Result of resolving segments with revalidation
+ * Contains both segments to render and all matched segment IDs
+ */
+export interface SegmentRevalidationResult {
+  segments: ResolvedSegment[];
+  matchedIds: string[];
+}
+
+/**
+ * Action context type for revalidation
+ */
+export type ActionContext = {
+  actionId?: string;
+  actionUrl?: URL;
+  actionResult?: any;
+  formData?: FormData;
+};
+
+/**
+ * Dependencies passed to segment resolution functions
+ * These are created within createRSCRouter and passed to extracted utilities
+ */
+export interface RouterDependencies<TEnv> {
+  findNearestErrorBoundary: (
+    entry: EntryData | null
+  ) => ReactNode | ErrorBoundaryHandler | null;
+  findNearestNotFoundBoundary: (
+    entry: EntryData | null
+  ) => ReactNode | NotFoundBoundaryHandler | null;
+}
+
+/**
+ * Title descriptor types for template support
+ */
+export type TitleDescriptor =
+  | string
+  | { template: string; default: string } // For layouts - template applied to child titles
+  | { absolute: string }; // Bypass parent template
+
+/**
+ * Unset descriptor to remove inherited meta
+ * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
+ */
+export type UnsetDescriptor = { unset: string };
+
+/**
+ * Base meta descriptor types (sync values)
+ */
+export type MetaDescriptorBase =
+  | { charSet: "utf-8" }
+  | { title: TitleDescriptor }
+  | { name: string; content: string }
+  | { property: string; content: string }
+  | { httpEquiv: string; content: string }
+  | { "script:ld+json": LdJsonObject }
+  | { tagName: "meta" | "link"; [name: string]: string }
+  | UnsetDescriptor
+  | { [name: string]: unknown };
+
+/**
+ * Meta descriptor that can be sync or async.
+ * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
+ */
+export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
+
+type LdJsonObject = { [Key in string]: LdJsonValue } & {
+  [Key in string]?: LdJsonValue | undefined;
+};
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;