@ivogt/rsc-router 0.0.0-experimental.1

package/src/server/loader-registry.ts

@@ -0,0 +1,174 @@
+/**
+ * Server-side loader registry for GET-based fetching
+ *
+ * Loaders are loaded lazily via dynamic imports when first requested.
+ * The RSC handler looks up loaders by $$id to execute them.
+ */
+
+import type { LoaderFn } from "../types.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import { getFetchableLoader } from "../loader.rsc.js";
+
+interface RegisteredLoader {
+  fn: LoaderFn<any, any, any>;
+  middleware: MiddlewareFn[];
+}
+
+// Server-side cache - maps loader $$id to function and middleware
+// This is a CACHE populated by getLoaderLazy() when loaders are first accessed.
+// The source of truth is fetchableLoaderRegistry in loader.ts, which is populated
+// when createLoader() runs. This cache exists to:
+// 1. Avoid repeated lookups/imports for the same loader
+// 2. Support lazy loading in production (loaders imported on-demand)
+// 3. Provide a stable reference for the RSC handler
+const loaderRegistry = new Map<string, RegisteredLoader>();
+
+// Lazy import map - set by the loader manifest
+// Maps loader $$id to a function that imports the loader module
+type LazyLoaderImport = () => Promise<{ $$id: string }>;
+let lazyLoaderImports: Map<string, LazyLoaderImport> | null = null;
+
+/**
+ * Set the lazy loader imports map (called by the loader manifest)
+ */
+export function setLoaderImports(
+  imports: Record<string, LazyLoaderImport>
+): void {
+  lazyLoaderImports = new Map(Object.entries(imports));
+}
+
+/**
+ * Register a fetchable loader by $$id
+ * Called by createLoader when fetchable option is provided
+ */
+export function registerLoader(
+  id: string,
+  fn: LoaderFn<any, any, any>,
+  middleware: MiddlewareFn[] = []
+): void {
+  if (loaderRegistry.has(id)) {
+    // Already registered (can happen during HMR)
+    return;
+  }
+  loaderRegistry.set(id, { fn, middleware });
+}
+
+/**
+ * Get a registered loader by $$id (synchronous)
+ * Returns undefined if loader is not registered
+ */
+export function getLoader(id: string): RegisteredLoader | undefined {
+  return loaderRegistry.get(id);
+}
+
+/**
+ * Get a loader by $$id, loading it lazily if needed
+ * This is the primary method for the RSC handler to get loaders
+ *
+ * In production: IDs are hashed, looked up via the lazy import map
+ * In dev: IDs are "filePath#exportName", resolved via dynamic import
+ */
+export async function getLoaderLazy(
+  id: string
+): Promise<RegisteredLoader | undefined> {
+  // Check if already cached in main registry
+  const existing = loaderRegistry.get(id);
+  if (existing) {
+    return existing;
+  }
+
+  // Check the fetchable loader registry (populated by createLoader)
+  const fetchable = getFetchableLoader(id);
+  if (fetchable) {
+    // Cache in main registry for future requests
+    loaderRegistry.set(id, fetchable);
+    return fetchable;
+  }
+
+  // Try to lazy load from the import map (production mode)
+  if (lazyLoaderImports && lazyLoaderImports.size > 0) {
+    const lazyImport = lazyLoaderImports.get(id);
+    if (lazyImport) {
+      try {
+        // Import the loader module - this triggers createLoader which registers fn
+        await lazyImport();
+
+        // Now try to get from fetchable registry (createLoader registered it)
+        const registered = getFetchableLoader(id);
+        if (registered) {
+          loaderRegistry.set(id, registered);
+          return registered;
+        }
+      } catch (error) {
+        console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+      }
+    }
+  }
+
+  // Dev mode fallback: parse the ID and use Vite's dynamic import
+  // ID format in dev: "src/path/to/file.ts#ExportName"
+  const hashIndex = id.indexOf("#");
+  if (hashIndex !== -1) {
+    const filePath = id.slice(0, hashIndex);
+
+    try {
+      // In dev mode, Vite handles dynamic imports
+      // Just importing the module triggers createLoader which registers the fn
+      await import(/* @vite-ignore */ `/${filePath}`);
+
+      // Now try to get from fetchable registry
+      const registered = getFetchableLoader(id);
+      if (registered) {
+        loaderRegistry.set(id, registered);
+        return registered;
+      }
+    } catch (error) {
+      console.error(`[LoaderRegistry] Failed to load loader "${id}":`, error);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if a loader is registered by $$id
+ */
+export function hasLoader(id: string): boolean {
+  return loaderRegistry.has(id) || getFetchableLoader(id) !== undefined;
+}
+
+/**
+ * Get all registered loader IDs (for debugging)
+ */
+export function getRegisteredLoaderIds(): string[] {
+  return Array.from(loaderRegistry.keys());
+}
+
+/**
+ * Register a loader by its $$id (injected by Vite plugin)
+ * This is called during module loading to cache loaders
+ */
+export function registerLoaderById(loader: {
+  $$id: string;
+  fn?: LoaderFn<any, any, any>;
+}): void {
+  if (!loader.$$id) {
+    return;
+  }
+  if (loaderRegistry.has(loader.$$id)) {
+    // Already registered (can happen during HMR)
+    return;
+  }
+
+  // For fetchable loaders, fn is stored in the fetchable registry by $$id
+  const fetchable = getFetchableLoader(loader.$$id);
+  if (fetchable) {
+    loaderRegistry.set(loader.$$id, fetchable);
+    return;
+  }
+
+  // Fall back to using fn from the loader object (non-fetchable loaders)
+  if (loader.fn) {
+    loaderRegistry.set(loader.$$id, { fn: loader.fn, middleware: [] });
+  }
+}

package/src/server/request-context.ts

@@ -0,0 +1,470 @@
+/**
+ * Request Context - AsyncLocalStorage for passing request-scoped data throughout rendering
+ *
+ * This is the unified context used everywhere:
+ * - Middleware execution
+ * - Route handlers and loaders
+ * - Server components during rendering
+ * - Error boundaries and streaming
+ *
+ * Available via getRequestContext() anywhere in the request lifecycle.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CookieOptions } from "../router/middleware.js";
+import type { LoaderDefinition, LoaderContext } from "../types.js";
+import type { Handle } from "../handle.js";
+import { createHandleStore, type HandleStore } from "./handle-store.js";
+import { isHandle } from "../handle.js";
+import { track } from "./context.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+
+/**
+ * Unified request context available via getRequestContext()
+ *
+ * This is the same context passed to middleware and handlers.
+ * Use this when you need access to request data outside of route handlers.
+ */
+export interface RequestContext<
+  TEnv = unknown,
+  TParams = Record<string, string>,
+> {
+  /** Platform bindings (Cloudflare env, etc.) */
+  env: TEnv;
+  /** Original HTTP request */
+  request: Request;
+  /** Parsed URL (system params like _rsc* are NOT filtered here) */
+  url: URL;
+  /** URL pathname */
+  pathname: string;
+  /** URL search params (system params like _rsc* are NOT filtered here) */
+  searchParams: URLSearchParams;
+  /** Variables set by middleware (same as ctx.var) */
+  var: Record<string, any>;
+  /** Get a variable set by middleware */
+  get: <K extends string>(key: K) => any;
+  /** Set a variable (shared with middleware and handlers) */
+  set: <K extends string>(key: K, value: any) => void;
+  /**
+   * Route params (populated after route matching)
+   * Initially empty, then set to matched params
+   */
+  params: TParams;
+  /**
+   * Stub response for setting headers/cookies
+   * Headers set here are merged into the final response
+   */
+  res: Response;
+
+  /** Get a cookie value from the request */
+  cookie(name: string): string | undefined;
+  /** Get all cookies from the request */
+  cookies(): Record<string, string>;
+  /** Set a cookie on the response */
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  /** Delete a cookie */
+  deleteCookie(name: string, options?: Pick<CookieOptions, "domain" | "path">): void;
+  /** Set a response header */
+  header(name: string, value: string): void;
+
+  /**
+   * Access loader data or push handle data.
+   *
+   * For loaders: Returns a promise that resolves to the loader data.
+   * Loaders are executed in parallel and memoized per request.
+   *
+   * For handles: Returns a push function to add data for this segment.
+   * Handle data accumulates across all matched route segments.
+   *
+   * @example
+   * ```typescript
+   * // Loader usage
+   * const cart = await ctx.use(CartLoader);
+   *
+   * // Handle usage
+   * const push = ctx.use(Breadcrumbs);
+   * push({ label: "Shop", href: "/shop" });
+   * ```
+   */
+  use: {
+    <T, TLoaderParams = any>(loader: LoaderDefinition<T, TLoaderParams>): Promise<T>;
+    <TData, TAccumulated = TData[]>(handle: Handle<TData, TAccumulated>): (
+      data: TData | Promise<TData> | (() => Promise<TData>)
+    ) => void;
+  };
+
+  /** HTTP method (GET, POST, PUT, PATCH, DELETE, etc.) */
+  method: string;
+
+  /** @internal Handle store for tracking handle data across segments */
+  _handleStore: HandleStore;
+
+  /** @internal Cache store for segment caching (optional, used by CacheScope) */
+  _cacheStore?: SegmentCacheStore;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, uses ctx.waitUntil().
+   * On Node.js, runs as fire-and-forget.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Register a callback to run when the response is created.
+   * Callbacks are sync and receive the response. They can:
+   * - Inspect response status/headers
+   * - Return a modified response
+   * - Schedule async work via waitUntil
+   *
+   * @example
+   * ```typescript
+   * ctx.onResponse((res) => {
+   *   if (res.status === 200) {
+   *     ctx.waitUntil(async () => await cacheIt());
+   *   }
+   *   return res;
+   * });
+   * ```
+   */
+  onResponse(callback: (response: Response) => Response): void;
+
+  /** @internal Registered onResponse callbacks */
+  _onResponseCallbacks: Array<(response: Response) => Response>;
+}
+
+// AsyncLocalStorage instance for request context
+const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
+
+/**
+ * Run a function within a request context
+ * Used by the RSC handler to provide context to server actions
+ */
+export function runWithRequestContext<TEnv, T>(
+  context: RequestContext<TEnv>,
+  fn: () => T
+): T {
+  return requestContextStorage.run(context, fn);
+}
+
+/**
+ * Get the current request context
+ * Returns undefined if not running within a request context
+ */
+export function getRequestContext<TEnv = unknown>():
+  | RequestContext<TEnv>
+  | undefined {
+  return requestContextStorage.getStore() as RequestContext<TEnv> | undefined;
+}
+
+/**
+ * Update params on the current request context
+ * Called after route matching to populate route params
+ */
+export function setRequestContextParams(params: Record<string, string>): void {
+  const ctx = requestContextStorage.getStore();
+  if (ctx) {
+    ctx.params = params;
+  }
+}
+
+/**
+ * Get the current request context, throwing if not available
+ * Use this when context is required (e.g., in loader actions)
+ */
+export function requireRequestContext<TEnv = unknown>(): RequestContext<TEnv> {
+  const ctx = getRequestContext<TEnv>();
+  if (!ctx) {
+    throw new Error(
+      "Request context not available. This function must be called from within a server action " +
+        "executed through the RSC handler."
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Cloudflare Workers ExecutionContext (subset we need)
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Options for creating a request context
+ */
+export interface CreateRequestContextOptions<TEnv> {
+  env: TEnv;
+  request: Request;
+  url: URL;
+  variables: Record<string, any>;
+  /** Optional cache store for segment caching (used by CacheScope) */
+  cacheStore?: SegmentCacheStore;
+  /** Optional Cloudflare execution context for waitUntil support */
+  executionContext?: ExecutionContext;
+}
+
+/**
+ * Create a full request context with all methods implemented
+ *
+ * This is used by the RSC handler to create the unified context that's:
+ * - Available via getRequestContext() throughout the request
+ * - Passed to middleware as ctx
+ * - Passed to handlers as ctx
+ */
+export function createRequestContext<TEnv>(
+  options: CreateRequestContextOptions<TEnv>
+): RequestContext<TEnv> {
+  const { env, request, url, variables, cacheStore, executionContext } = options;
+  const cookieHeader = request.headers.get("Cookie");
+  let parsedCookies: Record<string, string> | null = null;
+
+  // Create stub response for collecting headers/cookies
+  const stubResponse = new Response(null, { status: 200 });
+
+  // Create handle store and loader memoization for this request
+  const handleStore = createHandleStore();
+  const loaderPromises = new Map<string, Promise<any>>();
+
+  // Lazy parse cookies
+  const getParsedCookies = (): Record<string, string> => {
+    if (!parsedCookies) {
+      parsedCookies = parseCookiesFromHeader(cookieHeader);
+    }
+    return parsedCookies;
+  };
+
+  // Build the context object first (without use), then add use
+  const ctx: RequestContext<TEnv> = {
+    env,
+    request,
+    url,
+    pathname: url.pathname,
+    searchParams: url.searchParams,
+    var: variables,
+    get: <K extends string>(key: K) => variables[key],
+    set: <K extends string>(key: K, value: any) => {
+      variables[key] = value;
+    },
+    params: {} as Record<string, string>,
+    res: stubResponse,
+
+    cookie(name: string): string | undefined {
+      return getParsedCookies()[name];
+    },
+
+    cookies(): Record<string, string> {
+      return { ...getParsedCookies() };
+    },
+
+    setCookie(name: string, value: string, options?: CookieOptions): void {
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeCookieValue(name, value, options)
+      );
+    },
+
+    deleteCookie(
+      name: string,
+      options?: Pick<CookieOptions, "domain" | "path">
+    ): void {
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeCookieValue(name, "", { ...options, maxAge: 0 })
+      );
+    },
+
+    header(name: string, value: string): void {
+      stubResponse.headers.set(name, value);
+    },
+
+    // Placeholder - will be replaced below
+    use: null as any,
+
+    method: request.method,
+
+    _handleStore: handleStore,
+    _cacheStore: cacheStore,
+
+    waitUntil(fn: () => Promise<void>): void {
+      if (executionContext?.waitUntil) {
+        // Cloudflare Workers: use native waitUntil
+        executionContext.waitUntil(fn());
+      } else {
+        // Node.js: fire-and-forget
+        fn().catch((err) => console.error("[waitUntil]", err));
+      }
+    },
+
+    _onResponseCallbacks: [],
+
+    onResponse(callback: (response: Response) => Response): void {
+      this._onResponseCallbacks.push(callback);
+    },
+  };
+
+  // Now create use() with access to ctx
+  ctx.use = createUseFunction({
+    handleStore,
+    loaderPromises,
+    getContext: () => ctx,
+  });
+
+  return ctx;
+}
+
+/**
+ * Parse cookies from Cookie header
+ */
+function parseCookiesFromHeader(
+  cookieHeader: string | null
+): Record<string, string> {
+  if (!cookieHeader) return {};
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name) {
+      cookies[name] = decodeURIComponent(rest.join("="));
+    }
+  }
+
+  return cookies;
+}
+
+/**
+ * Serialize a cookie for Set-Cookie header
+ */
+function serializeCookieValue(
+  name: string,
+  value: string,
+  options: CookieOptions = {}
+): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+
+  if (options.domain) cookie += `; Domain=${options.domain}`;
+  if (options.path) cookie += `; Path=${options.path}`;
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+  if (options.httpOnly) cookie += "; HttpOnly";
+  if (options.secure) cookie += "; Secure";
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+
+  return cookie;
+}
+
+/**
+ * Options for creating the use() function
+ */
+export interface CreateUseFunctionOptions<TEnv> {
+  handleStore: HandleStore;
+  loaderPromises: Map<string, Promise<any>>;
+  getContext: () => RequestContext<TEnv>;
+}
+
+/**
+ * Create the use() function for loader and handle composition.
+ *
+ * This is the unified implementation used by both RequestContext and HandlerContext.
+ * - For loaders: executes and memoizes loader functions
+ * - For handles: returns a push function to add handle data
+ */
+export function createUseFunction<TEnv>(
+  options: CreateUseFunctionOptions<TEnv>
+): RequestContext["use"] {
+  const { handleStore, loaderPromises, getContext } = options;
+
+  return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+    // Handle case: return a push function
+    if (isHandle(item)) {
+      const handle = item;
+      const ctx = getContext();
+      const segmentId = (ctx as any)._currentSegmentId;
+
+      if (!segmentId) {
+        throw new Error(
+          `Handle "${handle.$$id}" used outside of handler context. ` +
+            `Handles must be used within route/layout handlers.`
+        );
+      }
+
+      // Return a push function bound to this handle and segment
+      return (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+        // If it's a function, call it immediately to get the promise
+        const valueOrPromise = typeof dataOrFn === "function"
+          ? (dataOrFn as () => Promise<unknown>)()
+          : dataOrFn;
+
+        // Push directly - promises will be serialized by RSC and streamed
+        handleStore.push(handle.$$id, segmentId, valueOrPromise);
+      };
+    }
+
+    // Loader case
+    const loader = item as LoaderDefinition<any, any>;
+
+    // Return cached promise if already started
+    if (loaderPromises.has(loader.$$id)) {
+      return loaderPromises.get(loader.$$id);
+    }
+
+    // Get loader function - either from loader object or fetchable registry
+    let loaderFn = loader.fn;
+    if (!loaderFn) {
+      // Lazy import to avoid circular dependency
+      const { getFetchableLoader } = require("../loader.rsc.js");
+      const fetchable = getFetchableLoader(loader.$$id);
+      if (fetchable) {
+        loaderFn = fetchable.fn;
+      }
+    }
+
+    if (!loaderFn) {
+      throw new Error(
+        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`
+      );
+    }
+
+    const ctx = getContext();
+
+    // Create loader context with recursive use() support
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+      params: ctx.params,
+      request: ctx.request,
+      searchParams: ctx.searchParams,
+      pathname: ctx.pathname,
+      url: ctx.url,
+      env: ctx.env as any,
+      var: ctx.var as any,
+      get: ctx.get as any,
+      use: <TDep, TDepParams = any>(
+        dep: LoaderDefinition<TDep, TDepParams>
+      ): Promise<TDep> => {
+        // Recursive call - will start dep loader if not already started
+        return ctx.use(dep);
+      },
+      method: "GET",
+      body: undefined,
+    };
+
+    // Start loader execution with tracking
+    const doneLoader = track(`loader:${loader.$$id}`);
+    const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
+      doneLoader();
+    });
+
+    // Memoize for subsequent calls
+    loaderPromises.set(loader.$$id, promise);
+
+    return promise;
+  }) as RequestContext["use"];
+}

package/src/server/root-layout.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import { Outlet } from "rsc-router/client";
+
+const MapRootLayout = (
+  <>
+    <Outlet />
+  </>
+) as ReactNode;
+
+export default MapRootLayout;

package/src/server/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2020"],
+    "types": ["node", "vite/client"],
+    "typeRoots": ["../../node_modules/@types"],
+    "moduleResolution": "bundler",
+    "rootDir": ".",
+    "outDir": "../../dist/server",
+    "composite": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["./**/*"]
+}