@rangojs/router 0.0.0-experimental.78adc454 → 0.0.0-experimental.7dc955ec

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.78adc454",
+  version: "0.0.0-experimental.7dc955ec",
   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.78adc454",
+  "version": "0.0.0-experimental.7dc955ec",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -162,6 +162,38 @@ middleware(async (ctx, next) => {
 });
 ```
 
+## Context Variable Cache Safety
+
+Context variables created with `createVar()` are cacheable by default and can
+be read freely inside `cache()` and `"use cache"` scopes. Non-cacheable vars
+throw at read time to prevent request-specific data from being captured.
+
+There are two ways to mark a value as non-cacheable:
+
+```typescript
+// Var-level policy — inherently request-specific data
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level escalation — this specific write is non-cacheable
+ctx.set(Theme, derivedTheme, { cache: false });
+```
+
+"Least cacheable wins": if either the var definition or the `ctx.set()` call
+specifies `cache: false`, the value is non-cacheable.
+
+**Behavior inside cache scopes:**
+
+| Operation                           | Inside `cache()` / `"use cache"` |
+| ----------------------------------- | -------------------------------- |
+| `ctx.get(cacheableVar)`             | Allowed                          |
+| `ctx.get(nonCacheableVar)`          | Throws                           |
+| `ctx.set(var, value)` (cacheable)   | Allowed                          |
+| `ctx.header()`, `ctx.cookie()`, etc | Throws (response side effects)   |
+
+Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
+Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
+scope and rejects non-cacheable reads.
+
 ## Loaders Are Always Fresh
 
 Loaders are **never cached** by route-level `cache()`. Even on a full cache hit

package/skills/caching/SKILL.md

@@ -173,6 +173,14 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
+## Context Variables Inside Cache Boundaries
+
+Context variables (`createVar`) are cacheable by default and can be read and
+written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
+the var level or write level) throw when read inside a cache scope. Response
+side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
+boundaries. See `/cache-guide` for the full cache safety table.
+
 ## Nested Cache Boundaries
 
 Override cache settings for specific sections:

package/skills/route/SKILL.md

@@ -181,6 +181,37 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
 Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
 and intercepts can only read via `ctx.get()`.
 
+#### Non-cacheable context variables
+
+Mark a var as non-cacheable when it holds inherently request-specific data
+(sessions, auth tokens, per-request IDs). There are two ways:
+
+```typescript
+// Var-level: every value written to this var is non-cacheable
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level: escalate a normally-cacheable var for this specific write
+const Theme = createVar<string>();
+ctx.set(Theme, userTheme, { cache: false });
+```
+
+"Least cacheable wins" — if either the var definition or the write site says
+`cache: false`, the value is non-cacheable.
+
+Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
+runtime. This prevents request-specific data from leaking into cached output:
+
+```typescript
+// This throws — Session is non-cacheable
+async function CachedWidget(ctx) {
+  "use cache";
+  const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
+  return <Widget />;
+}
+```
+
+Cacheable vars (the default) can be read freely inside cache scopes.
+
 ### Revalidation Contracts for Handler Data
 
 Handler-first guarantees apply within a single full render pass. For partial

package/skills/typesafety/SKILL.md

@@ -369,8 +369,18 @@ interface PaginationData {
   perPage: number;
 }
 export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
 ```
 
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
 ### Producer (handler or middleware)
 
 ```typescript

package/src/router/segment-resolution/fresh.ts

@@ -93,6 +93,14 @@ export async function resolveLoaders<TEnv>(
   const loaderEntries = entry.loader ?? [];
   if (loaderEntries.length === 0) return [];
 
+  // DSL loaders are always fresh (never cached), so temporarily clear the
+  // cache scope flag. This allows loaders to read non-cacheable vars even
+  // inside cache() boundaries. Handler ctx.use(loader) does NOT get this
+  // exemption — the handler is cached, so its loader results are too.
+  const store = RSCRouterContext.getStore();
+  const savedCacheScope = store?.insideCacheScope;
+  if (store) store.insideCacheScope = false;
+
   const shortCode = shortCodeOverride ?? entry.shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
@@ -100,9 +108,7 @@ export async function resolveLoaders<TEnv>(
 
   if (!loadingDisabled) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
-    // No per-loader timing here — settlement happens asynchronously during
-    // RSC/SSR stream consumption, after the perf timeline is logged.
-    return loaderEntries.map((loaderEntry, i) => {
+    const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
       const segmentId = `${shortCode}D${i}.${loader.$$id}`;
       return {
@@ -122,16 +128,20 @@ export async function resolveLoaders<TEnv>(
         belongsToRoute,
       };
     });
+    // Restore cache scope after all loader promises are kicked off
+    if (store) store.insideCacheScope = savedCacheScope;
+    return segments;
   }
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  // We can measure actual execution time here since we await all loaders.
   const pendingLoaderData = loaderEntries.map((loaderEntry) => {
     const start = performance.now();
     const promise = resolveLoaderData(loaderEntry, ctx, ctx.pathname);
     return { promise, start, loaderId: loaderEntry.loader.$$id };
   });
+  // Restore cache scope after all loader promises are kicked off
+  if (store) store.insideCacheScope = savedCacheScope;
   await Promise.all(pendingLoaderData.map((p) => p.promise));
 
   return loaderEntries.map((loaderEntry, i) => {

package/src/router/segment-resolution/revalidation.ts

@@ -146,6 +146,12 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   const loaderEntries = entry.loader ?? [];
   if (loaderEntries.length === 0) return { segments: [], matchedIds: [] };
 
+  // DSL loaders are always fresh — temporarily clear cache scope
+  // so non-cacheable var reads are allowed inside loader functions.
+  const store = RSCRouterContext.getStore();
+  const savedCacheScope = store?.insideCacheScope;
+  if (store) store.insideCacheScope = false;
+
   const shortCode = shortCodeOverride ?? entry.shortCode;
 
   const loaderMeta = loaderEntries.map((loaderEntry, i) => ({
@@ -242,6 +248,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
     }),
   );
 
+  // Restore cache scope after all loader promises are kicked off
+  if (store) store.insideCacheScope = savedCacheScope;
+
   return { segments, matchedIds };
 }
 

package/src/server/context.ts

@@ -672,7 +672,8 @@ export function track(label: string, depth?: number): () => void {
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
- * Reads from the RSCRouterContext ALS store (set during segment resolution).
+ * Returns false inside loader execution — loaders are always fresh
+ * (never cached), so non-cacheable reads are safe.
  */
 export function isInsideCacheScope(): boolean {
   return RSCRouterContext.getStore()?.insideCacheScope === true;

package/src/server/request-context.ts

@@ -29,7 +29,7 @@ import {
 } from "../context-var.js";
 import { createHandleStore, type HandleStore } from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track, type MetricsStore } from "./context.js";
+import { track, RSCRouterContext, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
@@ -942,7 +942,6 @@ export function createUseFunction<TEnv>(
       ),
     };
 
-    // Start loader execution with tracking
     const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
       doneLoader();