@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/client.tsx

@@ -13,7 +13,6 @@ import {
   type ClientErrorBoundaryFallbackProps,
   type ErrorInfo,
   type LoaderDefinition,
-  type LoaderFn,
   type ResolvedSegment,
 } from "./types";
 import {
@@ -22,6 +21,83 @@ import {
 } from "./route-content-wrapper.js";
 import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+
+/**
+ * Render the content for a named parallel/intercept slot segment.
+ *
+ * Shared by Outlet (with `name` prop) and ParallelOutlet — both resolve a
+ * segment from context.parallel by slot name and then render it through the
+ * same layout/loader/mountPath wrapping pipeline.
+ */
+function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
+  if (!segment) return null;
+
+  const content: ReactNode =
+    segment.loading || segment.component instanceof Promise ? (
+      <RouteContentWrapper
+        content={getMemoizedContentPromise(segment.component)}
+        fallback={segment.loading}
+        segmentId={segment.id}
+      />
+    ) : (
+      (segment.component ?? null)
+    );
+
+  const hasOwnLoaders = !!(segment.loaderDataPromise && segment.loaderIds);
+  const loaderWrapped = hasOwnLoaders ? (
+    <LoaderBoundary
+      loaderDataPromise={segment.loaderDataPromise!}
+      loaderIds={segment.loaderIds!}
+      fallback={segment.loading}
+      outletKey={segment.id + "-loader"}
+      outletContent={null}
+      segment={segment}
+    >
+      {content}
+    </LoaderBoundary>
+  ) : null;
+
+  let result: ReactNode;
+  if (segment.layout) {
+    // Layout renders immediately; if loaders exist, the LoaderBoundary becomes
+    // the outlet content so layout's <Outlet /> suspends until loaders resolve.
+    result = (
+      <OutletProvider
+        content={hasOwnLoaders ? loaderWrapped : content}
+        segment={segment}
+      >
+        {segment.layout}
+      </OutletProvider>
+    );
+  } else if (hasOwnLoaders) {
+    // No layout but has loaders — wrap content with LoaderBoundary for useLoader context.
+    // Common for intercept routes that use useLoader without a custom layout.
+    result = loaderWrapped;
+  } else {
+    result = content;
+  }
+
+  if (segment.mountPath) {
+    return (
+      <MountContextProvider value={segment.mountPath}>
+        {result}
+      </MountContextProvider>
+    );
+  }
+
+  return result;
+}
+
+function useSlotSegment(
+  context: OutletContextValue | null,
+  name: `@${string}` | undefined,
+): ResolvedSegment | null {
+  return useMemo(() => {
+    if (!name || !context?.parallel) return null;
+    return context.parallel.find((seg) => seg.slot === name) ?? null;
+  }, [context, name]);
+}
 
 /**
  * Outlet component - renders child content in layouts
@@ -62,95 +138,10 @@ import { MountContextProvider } from "./browser/react/mount-context.js";
  */
 export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
   const context = useContext(OutletContext);
+  const namedSegment = useSlotSegment(context, name);
 
-  // If name provided, render parallel/intercept content for that slot
   if (name) {
-    const segment = context?.parallel?.find((seg) => seg.slot === name) ?? null;
-
-    if (!segment) return null;
-
-    // Determine the content to render
-    let content: ReactNode;
-    if (segment.loading || segment.component instanceof Promise) {
-      // Use RouteContentWrapper to handle Suspense wrapping properly
-      content = (
-        <RouteContentWrapper
-          content={
-            segment.component instanceof Promise
-              ? segment.component
-              : Promise.resolve(segment.component)
-          }
-          fallback={segment.loading}
-          segmentId={segment.id}
-        />
-      );
-    } else {
-      content = segment.component ?? null;
-    }
-
-    let result: ReactNode;
-
-    // If segment has a layout, wrap appropriately
-    if (segment.layout) {
-      // Check if this segment has loaders that need streaming
-      // The layout renders immediately, LoaderBoundary becomes the outlet content
-      // When layout renders <Outlet />, it gets the LoaderBoundary which suspends
-      if (segment.loaderDataPromise && segment.loaderIds) {
-        const loaderAwareContent = (
-          <LoaderBoundary
-            loaderDataPromise={segment.loaderDataPromise}
-            loaderIds={segment.loaderIds}
-            fallback={segment.loading}
-            outletKey={segment.id + "-loader"}
-            outletContent={null}
-            segment={segment}
-          >
-            {content}
-          </LoaderBoundary>
-        );
-
-        result = (
-          <OutletProvider content={loaderAwareContent} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      } else {
-        // No loaders - wrap in OutletProvider so layout can use <Outlet />
-        result = (
-          <OutletProvider content={content} segment={segment}>
-            {segment.layout}
-          </OutletProvider>
-        );
-      }
-    } else if (segment.loaderDataPromise && segment.loaderIds) {
-      // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-      // This is common for intercept routes that use useLoader without a custom layout
-      result = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-    } else {
-      result = content;
-    }
-
-    // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-    if (segment.mountPath) {
-      return (
-        <MountContextProvider value={segment.mountPath}>
-          {result}
-        </MountContextProvider>
-      );
-    }
-
-    return result;
+    return renderSlotContent(namedSegment);
   }
 
   // Default: render child content
@@ -164,6 +155,7 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
 
   return content;
 }
+
 /**
  * ParallelOutlet component - renders content for a named parallel slot
  *
@@ -188,94 +180,9 @@ export function Outlet({ name }: { name?: `@${string}` } = {}): ReactNode {
  */
 export function ParallelOutlet({ name }: { name: `@${string}` }): ReactNode {
   const context = useContext(OutletContext);
-  const segment = useMemo(() => {
-    if (!context?.parallel) return null;
-    return context.parallel.find((seg) => seg.slot === name) ?? null;
-  }, [context, name]);
-
-  if (!segment) return null;
+  const segment = useSlotSegment(context, name);
 
-  // Determine the content to render
-  let content: ReactNode;
-  if (segment.loading || segment.component instanceof Promise) {
-    // Use RouteContentWrapper to handle Suspense wrapping properly
-    content = (
-      <RouteContentWrapper
-        content={
-          segment.component instanceof Promise
-            ? segment.component
-            : Promise.resolve(segment.component)
-        }
-        fallback={segment.loading}
-        segmentId={segment.id}
-      />
-    );
-  } else {
-    content = segment.component ?? null;
-  }
-
-  let result: ReactNode;
-
-  // If segment has a layout, wrap appropriately
-  if (segment.layout) {
-    // Check if this segment has loaders that need streaming
-    // The layout renders immediately, LoaderBoundary becomes the outlet content
-    if (segment.loaderDataPromise && segment.loaderIds) {
-      const loaderAwareContent = (
-        <LoaderBoundary
-          loaderDataPromise={segment.loaderDataPromise}
-          loaderIds={segment.loaderIds}
-          fallback={segment.loading}
-          outletKey={segment.id + "-loader"}
-          outletContent={null}
-          segment={segment}
-        >
-          {content}
-        </LoaderBoundary>
-      );
-
-      result = (
-        <OutletProvider content={loaderAwareContent} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    } else {
-      // No loaders - wrap in OutletProvider so layout can use <Outlet />
-      result = (
-        <OutletProvider content={content} segment={segment}>
-          {segment.layout}
-        </OutletProvider>
-      );
-    }
-  } else if (segment.loaderDataPromise && segment.loaderIds) {
-    // No layout but has loaders - wrap content with LoaderBoundary for useLoader context
-    // This is common for intercept routes that use useLoader without a custom layout
-    result = (
-      <LoaderBoundary
-        loaderDataPromise={segment.loaderDataPromise}
-        loaderIds={segment.loaderIds}
-        fallback={segment.loading}
-        outletKey={segment.id + "-loader"}
-        outletContent={null}
-        segment={segment}
-      >
-        {content}
-      </LoaderBoundary>
-    );
-  } else {
-    result = content;
-  }
-
-  // Wrap with MountContextProvider for include() scoped parallel/intercept slots
-  if (segment.mountPath) {
-    return (
-      <MountContextProvider value={segment.mountPath}>
-        {result}
-      </MountContextProvider>
-    );
-  }
-
-  return result;
+  return renderSlotContent(segment);
 }
 
 // OutletProvider is defined in outlet-provider.tsx to break a circular
@@ -307,63 +214,13 @@ export function useOutlet(): ReactNode {
 export {
   useLoader,
   useFetchLoader,
+  useRefreshLoaders,
   type LoadFunction,
   type UseLoaderResult,
   type UseFetchLoaderResult,
   type UseLoaderOptions,
 } from "./use-loader.js";
 
-/**
- * Client-safe createLoader factory
- *
- * Creates a loader definition that can be used with useLoader().
- * This is the client-side version that only stores the $$id - the function
- * is ignored since loaders only execute on the server.
- *
- * The $$id is injected by the exposeLoaderId Vite plugin. In most cases,
- * you should import the loader directly from the server file rather than
- * creating a reference manually.
- *
- * @param fn - Loader function (ignored on client, kept for API compatibility)
- * @param _fetchable - Optional fetchable flag (ignored on client)
- * @param __injectedId - $$id injected by Vite plugin
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoader } from "rsc-router/client";
- * import { CartLoader } from "../loaders/cart"; // Import from server file
- *
- * export function CartIcon() {
- *   const cart = useLoader(CartLoader);
- *   return <span>Cart ({cart?.items.length ?? 0})</span>;
- * }
- * ```
- */
-// Overload 1: With function only (not fetchable)
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Overload 2: With function and fetchable flag
-export function createLoader<T>(
-  fn: LoaderFn<T, Record<string, string | undefined>, any>,
-  fetchable: true,
-): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
-
-// Implementation - function is ignored at runtime on client
-// The $$id is injected by Vite plugin as hidden third parameter
-export function createLoader(
-  _fn: LoaderFn<any, Record<string, string | undefined>, any>,
-  _fetchable?: true,
-  __injectedId?: string,
-): LoaderDefinition<any, Record<string, string | undefined>> {
-  return {
-    __brand: "loader",
-    $$id: __injectedId || "",
-  };
-}
-
 /**
  * Props for the ErrorBoundary component
  */
@@ -534,10 +391,8 @@ export {
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
 
-// Handle API - for accumulating data across route segments
-export { createHandle, isHandle, type Handle } from "./handle.js";
-
-// Handle data hook
+// Handle data hook (client-side only — createHandle/isHandle are server APIs from the root export)
+export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 // Built-in handles
@@ -555,13 +410,10 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state.js";
 
-// Type-safe href for client-side path validation
-export {
-  href,
-  type ValidPaths,
-  type PatternToPath,
-  type PathResponse,
-} from "./href-client.js";
+// Type-safe href for client-side path validation. The path and response types
+// are ambient as `Rango.Path` / `Rango.PathResponse` (declared in
+// href-client.ts) — no import needed.
+export { href, type PatternToPath } from "./href-client.js";
 
 // Response envelope types for consuming JSON response routes
 export type { ResponseEnvelope, ResponseError } from "./urls.js";
@@ -594,8 +446,12 @@ export { MountContext } from "./browser/react/mount-context.js";
 // Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
+// Mount-aware reverse hook - resolves dot-prefixed names against an imported
+// generated routes map (from a urls() module's .gen.ts).
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Type-safe scoped reverse function for scopedReverse<typeof patterns>()
-export type { ScopedReverseFunction } from "./reverse.js";
+export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 // Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/context-var.ts

@@ -12,6 +12,9 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * export const User = createVar<UserData>({ cache: false });
+ *
  * // handler
  * ctx.set(Pagination, { current: 1, total: 4 });
  *
@@ -23,18 +26,36 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
+  /** When false, ctx.get(var) throws inside a cache() boundary. */
+  readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
 }
 
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+   * inherently request-specific data (user sessions, auth tokens, etc.) that
+   * must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
 /**
  * Create a typed context variable token.
  *
  * The returned object is used with ctx.set(token, value) and ctx.get(token)
  * for compile-time-checked data flow between handlers, layouts, and middleware.
  */
-export function createVar<T>(): ContextVar<T> {
-  return { __brand: "context-var" as const, key: Symbol() };
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
 }
 
 /**
@@ -49,6 +70,36 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
 /**
  * Read a variable from the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -64,6 +115,17 @@ export function contextGet(
 /** Keys that must never be used as string variable names */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
 /**
  * Write a variable to the variables store.
  * Accepts either a string key (legacy) or a ContextVar token (typed).
@@ -72,6 +134,7 @@ export function contextSet(
   variables: any,
   keyOrVar: string | ContextVar<any>,
   value: any,
+  options?: ContextSetOptions,
 ): void {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -80,7 +143,14 @@ export function contextSet(
       );
     }
     variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
   } else {
     variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
   }
 }

package/src/decode-loader-results.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}

package/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification
@@ -27,6 +27,17 @@ export class RouteNotFoundError extends Error {
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
+
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary
@@ -109,6 +120,24 @@ export class BuildError extends Error {
   }
 }
 
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export class DslContextError extends Error {
+  name = "DslContextError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, DslContextError.prototype);
+    this.cause = options?.cause;
+  }
+}
+
 /**
  * Thrown when a network request fails (server unreachable, no internet, etc.)
  * This error triggers the root error boundary with retry capability.