@rangojs/router 0.0.0-experimental.135 → 0.0.0-experimental.136

package/dist/vite/index.js

@@ -2297,7 +2297,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.135",
+  version: "0.0.0-experimental.136",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.135",
+  "version": "0.0.0-experimental.136",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/browser/prefetch/cache.ts

@@ -77,13 +77,24 @@ export interface DecodedPrefetch {
 
 let cacheTTL = 300_000;
 
+// Max stored entries before FIFO eviction. Mirrors DEFAULT_PREFETCH_CACHE_SIZE
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code, matching the cacheTTL default above.
+// Overridden at startup by initPrefetchCache from server metadata.
+let maxPrefetchCacheSize = 100;
+
 /**
- * Initialize the prefetch cache with the configured TTL.
- * Called once at app startup with the value from server metadata.
- * A TTL of 0 disables the in-memory cache and all prefetching.
+ * Initialize the prefetch cache with the configured TTL and max size.
+ * Called once at app startup with the values from server metadata. Each
+ * argument is applied only when provided, so a caller can set just the TTL.
+ * A TTL of 0 disables the in-memory cache and all prefetching. A size below 1
+ * is ignored (the default is kept) — disabling prefetch is the TTL's job.
  */
-export function initPrefetchCache(ttlMs: number): void {
-  cacheTTL = ttlMs;
+export function initPrefetchCache(ttlMs?: number, maxSize?: number): void {
+  if (ttlMs !== undefined) cacheTTL = ttlMs;
+  if (maxSize !== undefined && Number.isFinite(maxSize) && maxSize >= 1) {
+    maxPrefetchCacheSize = Math.floor(maxSize);
+  }
 }
 
 /**
@@ -93,7 +104,6 @@ export function initPrefetchCache(ttlMs: number): void {
 export function isPrefetchCacheDisabled(): boolean {
   return cacheTTL <= 0;
 }
-const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
   entry: DecodedPrefetch;
@@ -268,7 +278,7 @@ export function storePrefetch(
   }
 
   // FIFO eviction if at capacity
-  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+  if (cache.size >= maxPrefetchCacheSize) {
     const oldest = cache.keys().next().value;
     if (oldest) cache.delete(oldest);
   }

package/src/browser/prefetch/queue.ts

@@ -16,9 +16,24 @@
 
 import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
 
-const MAX_CONCURRENT = 2;
+// Max prefetches executing at once. Mirrors DEFAULT_PREFETCH_CONCURRENCY
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code. Overridden at startup by
+// setPrefetchConcurrency from server metadata.
+let maxConcurrent = 2;
 const IMAGE_WAIT_TIMEOUT = 2000;
 
+/**
+ * Set the max number of concurrently-executing speculative prefetches.
+ * Called once at app startup with the value from server metadata. A value
+ * below 1 (or non-finite) is ignored, keeping the default.
+ */
+export function setPrefetchConcurrency(n: number): void {
+  if (Number.isFinite(n) && n >= 1) {
+    maxConcurrent = Math.floor(n);
+  }
+}
+
 let active = 0;
 const queue: Array<{
   key: string;
@@ -42,7 +57,7 @@ function startExecution(
     abortControllers.delete(key);
     // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
     // Without this guard, cancelled tasks' .finally() would underflow active
-    // below zero, breaking the MAX_CONCURRENT guarantee.
+    // below zero, breaking the maxConcurrent guarantee.
     if (executing.delete(key)) {
       active--;
     }
@@ -63,7 +78,7 @@ function startExecution(
  */
 function scheduleDrain(): void {
   if (drainScheduled) return;
-  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  if (active >= maxConcurrent || queue.length === 0) return;
   drainScheduled = true;
   const gen = drainGeneration;
   waitForIdle()
@@ -83,7 +98,7 @@ function scheduleDrain(): void {
 }
 
 function drain(): void {
-  while (active < MAX_CONCURRENT && queue.length > 0) {
+  while (active < maxConcurrent && queue.length > 0) {
     const item = queue.shift()!;
     queued.delete(item.key);
     startExecution(item.key, item.execute);

package/src/browser/rsc-router.tsx

@@ -25,6 +25,7 @@ import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setPrefetchConcurrency } from "./prefetch/queue.js";
 import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
 import {
@@ -245,11 +246,17 @@ export async function initBrowserApp(
   initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
-  // Initialize the in-memory prefetch cache TTL from server config.
-  // A value of 0 disables the cache; undefined falls back to the module default.
+  // Initialize the in-memory prefetch cache (TTL + max size) and the prefetch
+  // queue concurrency from server config. A TTL of 0 disables the cache;
+  // undefined values fall back to the module defaults.
   const prefetchCacheTTL = initialPayload.metadata?.prefetchCacheTTL;
-  if (prefetchCacheTTL !== undefined) {
-    initPrefetchCache(prefetchCacheTTL);
+  const prefetchCacheSize = initialPayload.metadata?.prefetchCacheSize;
+  if (prefetchCacheTTL !== undefined || prefetchCacheSize !== undefined) {
+    initPrefetchCache(prefetchCacheTTL, prefetchCacheSize);
+  }
+  const prefetchConcurrency = initialPayload.metadata?.prefetchConcurrency;
+  if (prefetchConcurrency !== undefined) {
+    setPrefetchConcurrency(prefetchConcurrency);
   }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's

package/src/browser/types.ts

@@ -70,6 +70,16 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: number;
+  /**
+   * Max entries in the client-side in-memory prefetch cache (FIFO eviction).
+   * Sent on initial render so the browser can configure its cache capacity.
+   */
+  prefetchCacheSize?: number;
+  /**
+   * Max concurrent speculative prefetch requests on the client.
+   * Sent on initial render so the browser can configure its prefetch queue.
+   */
+  prefetchConcurrency?: number;
   /**
    * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
    * reads it verbatim and binds the rango state cookie to it; composition

package/src/router/prefetch-limits.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve the client-side prefetch limits — the in-memory prefetch cache size
+ * and the speculative-prefetch queue concurrency — once, at router init. Both
+ * are positive-integer counts shipped to the browser in payload metadata; the
+ * browser entry feeds them to the prefetch cache (`initPrefetchCache`) and the
+ * prefetch queue (`setPrefetchConcurrency`) at startup.
+ *
+ * Policy note: this is a SEPARATE policy from resolvePrefetchCacheTTL
+ * (prefetch-cache-ttl.ts). These are counts, not durations, so the disable
+ * paths differ: a TTL of `false`/0 intentionally turns prefetching off, but a
+ * cache size or concurrency of 0 would silently break prefetching while leaving
+ * it nominally enabled — never the intent of passing a number. So any value
+ * that is not a finite integer >= 1 (0, negative, fractional below 1, NaN,
+ * Infinity, undefined) falls back to the default. Finite values >= 1 are
+ * floored. Do not unify this guard with the TTL guard.
+ */
+
+export const DEFAULT_PREFETCH_CACHE_SIZE = 100;
+export const DEFAULT_PREFETCH_CONCURRENCY = 2;
+
+export function resolvePrefetchCacheSize(raw: number | undefined): number {
+  return resolvePositiveCount(raw, DEFAULT_PREFETCH_CACHE_SIZE);
+}
+
+export function resolvePrefetchConcurrency(raw: number | undefined): number {
+  return resolvePositiveCount(raw, DEFAULT_PREFETCH_CONCURRENCY);
+}
+
+function resolvePositiveCount(
+  raw: number | undefined,
+  fallback: number,
+): number {
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 1) {
+    return Math.floor(raw);
+  }
+  return fallback;
+}

package/src/router/router-interfaces.ts

@@ -301,6 +301,20 @@ export interface RangoInternal<
    */
   readonly prefetchCacheTTL: number;
 
+  /**
+   * Maximum number of decoded prefetch payloads the client keeps in its
+   * in-memory prefetch cache (FIFO eviction at capacity). Shipped to the
+   * client in payload metadata. Derived from prefetchCacheSize.
+   */
+  readonly prefetchCacheSize: number;
+
+  /**
+   * Maximum number of speculative prefetch requests the client runs
+   * concurrently. Shipped to the client in payload metadata. Derived from
+   * prefetchConcurrency.
+   */
+  readonly prefetchConcurrency: number;
+
   /**
    * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
    * router init and shipped to the client in payload metadata. The server-side

package/src/router/router-options.ts

@@ -497,6 +497,36 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Maximum number of decoded prefetch payloads the client keeps in its
+   * in-memory prefetch cache. When the cache is full the oldest entry is
+   * evicted (FIFO) to make room for a new prefetch.
+   *
+   * Each entry retains a fully decoded RSC payload (and the route's client
+   * chunks pulled in while decoding), so this is the lever on client-side
+   * prefetch memory: a higher value warms more routes at the cost of more
+   * retained payloads. Staleness is bounded separately by `prefetchCacheTTL`;
+   * this bounds the entry COUNT.
+   *
+   * Values below 1 (or non-finite) fall back to the default. To turn
+   * prefetching off entirely, set `prefetchCacheTTL: false` instead.
+   *
+   * @default 100
+   */
+  prefetchCacheSize?: number;
+
+  /**
+   * Maximum number of speculative prefetch requests (viewport/render strategy)
+   * the client runs concurrently. Hover prefetches bypass this queue and fire
+   * immediately; this caps only the background, idle-gated queue so prefetches
+   * never saturate the browser's connection pool.
+   *
+   * Values below 1 (or non-finite) fall back to the default.
+   *
+   * @default 2
+   */
+  prefetchConcurrency?: number;
+
   /**
    * Prefix for the rango state cookie name. The resolved name is
    * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

package/src/router.ts

@@ -111,6 +111,10 @@ import {
 } from "./router/prerender-match.js";
 import { resolveStateCookieName } from "./router/state-cookie-name.js";
 import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.js";
+import {
+  resolvePrefetchCacheSize,
+  resolvePrefetchConcurrency,
+} from "./router/prefetch-limits.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
@@ -150,6 +154,8 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    prefetchCacheSize: prefetchCacheSizeOption,
+    prefetchConcurrency: prefetchConcurrencyOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
@@ -242,6 +248,14 @@ export function createRouter<TEnv = any>(
   const prefetchCacheControl: string | false =
     resolvedPrefetchCacheTTL.cacheControl;
 
+  // Resolve client-side prefetch limits (in-memory cache size and queue
+  // concurrency). Both are positive-integer counts; sub-1/non-finite inputs
+  // fall back to the defaults. Shipped to the client in payload metadata.
+  const prefetchCacheSize = resolvePrefetchCacheSize(prefetchCacheSizeOption);
+  const prefetchConcurrency = resolvePrefetchConcurrency(
+    prefetchConcurrencyOption,
+  );
+
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
@@ -968,6 +982,8 @@ export function createRouter<TEnv = any>(
     // Expose prefetch cache settings
     prefetchCacheControl,
     prefetchCacheTTL,
+    prefetchCacheSize,
+    prefetchConcurrency,
 
     // Expose the resolved rango state cookie name for the server-side writer
     // (invalidateClientCache) and for shipping to the client in metadata.

package/src/rsc/handler.ts

@@ -1134,6 +1134,8 @@ export function createRSCHandler<
               handles: handleStore.stream(),
               version,
               prefetchCacheTTL: router.prefetchCacheTTL,
+              prefetchCacheSize: router.prefetchCacheSize,
+              prefetchConcurrency: router.prefetchConcurrency,
               stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,

package/src/rsc/rsc-rendering.ts

@@ -81,6 +81,8 @@ async function handleRscRenderingInner<TEnv>(
       handles: handleStore.stream(),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      prefetchCacheSize: ctx.router.prefetchCacheSize,
+      prefetchConcurrency: ctx.router.prefetchConcurrency,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       // Carry warmupEnabled on the initial full-render payload so the client
@@ -141,6 +143,8 @@ async function handleRscRenderingInner<TEnv>(
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+          prefetchCacheSize: ctx.router.prefetchCacheSize,
+          prefetchConcurrency: ctx.router.prefetchConcurrency,
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };

package/src/rsc/types.ts

@@ -43,6 +43,10 @@ export interface RscPayload {
     version?: string;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
+    /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */
+    prefetchCacheSize?: number;
+    /** Max concurrent speculative prefetch requests on the client */
+    prefetchConcurrency?: number;
     /** Server-resolved rango state cookie name; the client reads it verbatim. */
     stateCookieName?: string;
     /** Theme configuration for FOUC prevention */