@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/skills/loader/SKILL.md

@@ -1,19 +1,24 @@
 ---
 name: loader
 description: Define data loaders for fetching data in routes with createLoader
-argument-hint: [name]
+argument-hint: [loader]
 ---
 
 # Data Loaders with loader()
 
-Loaders fetch data on the server and stream it to the client.
+Loaders fetch data on the server and stream it to the client. For mutations
+(writes triggered by forms or buttons), use server actions instead — see
+`/server-actions`. Loaders re-resolve after an action runs, so the typical
+flow is _action mutates → loader re-reads → UI updates_.
 
 ## Creating a Loader
 
 ```typescript
 import { createLoader } from "@rangojs/router";
 
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
   const product = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE slug = ?",
   )
@@ -30,19 +35,19 @@ All of the following are equivalent and fully supported by the Vite transform:
 
 ```typescript
 // Direct export (most common)
-export const ProductLoader = createLoader("product", handler);
+export const ProductLoader = createLoader(handler);
 
 // Separate declaration + named export
-const ProductLoader = createLoader("product", handler);
+const ProductLoader = createLoader(handler);
 export { ProductLoader };
 
 // Aliased export
-const InternalLoader = createLoader("product", handler);
+const InternalLoader = createLoader(handler);
 export { InternalLoader as ProductLoader };
 
 // Aliased import
 import { createLoader as cl } from "@rangojs/router";
-export const ProductLoader = cl("product", handler);
+export const ProductLoader = cl(handler);
 ```
 
 The `export const` form and the `const + export { }` form both work for
@@ -63,40 +68,114 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-### In Server Components
+Register loaders with `loader()` in the DSL and consume them in client
+components with `useLoader()`. This is the recommended pattern — it keeps
+data fetching on the server and consumption on the client, with a clean
+separation that works correctly with `cache()`.
 
 ```typescript
-import { useLoader } from "@rangojs/router";
+"use client";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader } from "./loaders/product";
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  return <h1>{product.name}</h1>;
+function ProductDetails() {
+  const { data } = useLoader(ProductLoader);
+  return <div>{data.product.description}</div>;
 }
 ```
 
-### In Client Components
-
 ```typescript
-"use client";
-import { useLoaderData } from "@rangojs/router/client";
-import { ProductLoader } from "./loaders/product";
+// Route definition — loader() registration required
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(ProductLoader),
+]);
+```
 
-function ProductDetails() {
-  const { product } = useLoaderData(ProductLoader);
-  return <div>{product.description}</div>;
-}
+DSL loaders are the **live data layer** — they resolve fresh on every
+request, even when the route is inside a `cache()` boundary. The router
+excludes them from the segment cache at storage time and re-resolves them
+on retrieval. This means `cache()` gives you cached UI + fresh data by
+default.
+
+### Cache safety
+
+DSL loaders can safely read `createVar({ cache: false })` variables
+because they are always resolved fresh. The read guard is bypassed for
+loader functions — they never produce stale data.
+
+### ctx.use(Loader) — escape hatch
+
+For cases where you need loader data in the server handler itself (e.g.,
+to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
+
+```typescript
+path("/product/:slug", async (ctx) => {
+  const { product } = await ctx.use(ProductLoader);
+  ctx.set(Product, product); // make available to children
+  return <ProductPage />;
+}, { name: "product" }, () => [
+  loader(ProductLoader), // still register for client consumption
+])
 ```
 
+When you register with `loader()` in the DSL, `ctx.use()` returns the
+same memoized result — loaders never run twice per request.
+
+**Limitations of ctx.use(Loader):**
+
+- The handler output depends on the loader data. If the route is inside
+  `cache()`, the handler is cached with the loader result baked in —
+  defeating the live data guarantee.
+- Non-cacheable variable reads (`createVar({ cache: false })`) inside the
+  handler still throw, even if the data came from a loader.
+- Prefer DSL `loader()` + client `useLoader()` for data that depends on
+  non-cacheable context variables.
+
+**Never use `useLoader()` in server components** — it is a client-only API.
+
+### Summary
+
+| Pattern                | API                 | Cache-safe | Recommended |
+| ---------------------- | ------------------- | ---------- | ----------- |
+| DSL + client component | `useLoader(Loader)` | Yes        | Yes         |
+| Handler escape hatch   | `ctx.use(Loader)`   | No         | When needed |
+
 ## Loader Context
 
-Loaders receive the same context as route handlers:
+Loaders receive the same context shape as route handlers.
+
+### Full field surface
+
+| Field          | Type                           | Notes                                                                                               |
+| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                 |
+| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                        |
+| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                 |
+| `url`          | `URL`                          | Parsed request URL.                                                                                 |
+| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                     |
+| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                |
+| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                   |
+| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                 |
+| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                     |
+| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
+| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data.      |
+| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.               |
+| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                      |
+| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                     |
+| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).              |
+
+### Example
 
 ```typescript
-export const ProductLoader = createLoader("product", async (ctx) => {
-  // URL params
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
+  // URL params (may include client-provided overrides for fetchable loaders)
   const { slug } = ctx.params;
 
+  // Server-trusted route params (from URL pattern matching, cannot be overridden)
+  const { slug: trustedSlug } = ctx.routeParams;
+
   // Query params
   const variant = ctx.url.searchParams.get("variant");
 
@@ -109,7 +188,45 @@ export const ProductLoader = createLoader("product", async (ctx) => {
   // Variables set by middleware (from RSCRouter.Vars augmentation)
   const user = ctx.get("user");
 
-  return { product: await fetchProduct(slug) };
+  // Type-checked URLs for payloads. `.name` resolves within the current
+  // include() scope; a bare `name` resolves globally. See /route and
+  // /typesafety for scope rules and route-name autocomplete.
+  const detailUrl = ctx.reverse(".detail", { slug });
+
+  return {
+    product: await fetchProduct(slug),
+    links: { self: detailUrl },
+  };
+});
+```
+
+See `/route` for the full handler-context contract (shared with loaders) and
+`/typesafety` for route-name typing that powers `ctx.reverse` autocomplete.
+
+### params vs routeParams
+
+- `ctx.params` — merged route params + explicit loader params. For fetchable
+  loaders called with `load(Loader, { params: { ... } })`, explicit params
+  override route-matched params.
+- `ctx.routeParams` — server-trusted route params from URL pattern matching.
+  Cannot be overridden by client-provided params.
+
+Use `ctx.routeParams` when you need trusted route identity for authorization
+or resource scoping:
+
+```typescript
+export const OrderLoader = createLoader(async (ctx) => {
+  "use server";
+
+  // Use routeParams for auth checks — client cannot spoof the URL-matched ID
+  const { orderId } = ctx.routeParams;
+  const user = ctx.get("user");
+
+  const order = await db.orders.get(orderId);
+  if (order.userId !== user.id)
+    throw new Response("Forbidden", { status: 403 });
+
+  return { order };
 });
 ```
 
@@ -134,6 +251,188 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+### `revalidate()` return shapes
+
+A `revalidate(fn)` callback can return one of four shapes. The chain
+processes revalidators in order; each call's return controls how the
+chain continues:
+
+```typescript
+// 1) Hard decision — short-circuits the chain, used as the final answer.
+revalidate(() => true);
+revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
+
+// 2) Soft decision — updates the running suggestion for downstream
+//    revalidators on the same segment, chain continues.
+revalidate(({ defaultShouldRevalidate }) => ({
+  defaultShouldRevalidate: !defaultShouldRevalidate,
+}));
+
+// 3) Defer (no opinion) — leaves the running suggestion unchanged and
+//    continues to the next revalidator. Implicit return / null /
+//    undefined are all equivalent and consumer-friendly.
+revalidate(({ actionId }) => {
+  if (actionId?.includes("Cart")) return true; // hard for this branch only
+  // implicit return — let downstream revalidators or the segment default decide
+});
+revalidate(() => undefined); // explicit defer
+revalidate(() => null); // explicit defer
+```
+
+If every revalidator on a segment defers, the segment-type default
+(e.g. params-changed for routes, `false` for parallels) is used.
+
+### Revalidation Contracts for Loader Dependencies
+
+If a loader reads `ctx.get()` data produced by an outer handler/layout, share
+the same named revalidation contract across producer and consumer segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateAccountScope = ({ actionId }) =>
+  actionId?.includes("src/actions/account.ts#") ?? false;
+
+layout(AccountLayout, () => [
+  revalidate(revalidateAccountScope), // producer reruns
+  path("/account/orders", OrdersPage, { name: "account.orders" }, () => [
+    loader(OrdersLoader, () => [
+      revalidate(revalidateAccountScope), // consumer reruns
+    ]),
+  ]),
+]);
+```
+
+For segments that depend on multiple upstream domains, compose multiple
+contracts on both sides.
+
+To keep loader route trees concise, export helper wrappers:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateAccount = () => [revalidate(revalidateAccountScope)];
+
+layout(AccountLayout, () => [
+  revalidateAccount(),
+  path("/account/orders", OrdersPage, { name: "account.orders" }, () => [
+    loader(OrdersLoader, () => [revalidateAccount()]),
+  ]),
+]);
+```
+
+## Loaders: The Live Data Layer
+
+Loaders are the live data layer of the router. They resolve fresh on every
+request, even when the route's UI segments are served from cache. This is a
+core design principle — route-level `cache()` caches rendered components but
+never caches loader data. Loaders are excluded at storage time and re-resolved
+on retrieval.
+
+This means `cache()` gives you cached UI + fresh data by default. Pre-rendering
+follows the same rule: at build time, loaders are skipped entirely (there is no
+real request context), and at runtime the worker resolves them fresh against
+the live database.
+
+### Opting a Loader into Caching
+
+To cache a specific loader's data, attach a `cache()` child:
+
+```typescript
+loader(ProductLoader, () => [cache({ ttl: 300 })]),
+```
+
+The loader's data is cached independently from the route's segment cache,
+using the same `SegmentCacheStore` (app-level or per-loader override).
+
+Values are serialized through RSC Flight, so loaders can return ReactNode,
+Promises, null, and any RSC-serializable type — all round-trip correctly
+through the cache.
+
+### Cache Key
+
+The default cache key is `loader:{loaderId}:{pathname}:{sortedParams}`.
+This can be customized at two levels:
+
+```typescript
+// Full override — key function replaces the default entirely
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    key: (ctx) => `product:${ctx.params.slug}:${cookies().get("locale")?.value ?? "en"}`,
+  }),
+]),
+
+// Store-level keyGenerator — modifies the default key (e.g., adds a region prefix)
+// Set in the store configuration, applies to all entries in that store
+```
+
+Resolution priority (same as route-level `cache()`):
+
+1. `key(ctx)` from cache options — full override
+2. `store.keyGenerator(ctx, defaultKey)` — store-level modification
+3. Default key — `loader:{id}:{pathname}:{params}`
+
+If a custom key function throws, it falls back to the default key silently
+(logged to console.error).
+
+### Tags for Invalidation
+
+```typescript
+// Static tags
+loader(ProductLoader, () => [
+  cache({ ttl: 300, tags: ["products", "catalog"] }),
+]),
+
+// Dynamic tags
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    tags: (ctx) => [`product:${ctx.params.slug}`, "products"],
+  }),
+]),
+```
+
+### Stale-While-Revalidate
+
+```typescript
+loader(ProductLoader, () => [
+  cache({ ttl: 60, swr: 300 }),
+]),
+```
+
+During the SWR window (60-360s), stale data is returned immediately while
+fresh data is fetched in the background via `waitUntil`. After the SWR window
+expires (360s+), the entry is treated as a cache miss.
+
+### Conditional Caching
+
+Skip the cache at runtime based on request properties:
+
+```typescript
+loader(ProductLoader, () => [
+  cache({
+    ttl: 300,
+    condition: (ctx) => !ctx.request.headers.has("authorization"),
+  }),
+]),
+```
+
+When `condition` returns false, the loader runs fresh and the cache is bypassed
+entirely (no read, no write).
+
+### Per-Loader Store Override
+
+```typescript
+const hotStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
+
+loader(PricingLoader, () => [
+  cache({ store: hotStore }),
+]),
+```
+
+Without an explicit store, the loader uses the app-level store from the
+handler config (`cache.store`).
+
 ## Multiple Loaders
 
 Routes can have multiple loaders that run in parallel:
@@ -232,6 +531,31 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+### Fetchable Loader with Middleware
+
+Pass an options object instead of `true` to attach per-loader middleware.
+This middleware runs only on `_rsc_loader` fetch requests (client-side
+`load()` / `useFetchLoader()` calls), not during SSR `ctx.use()` execution:
+
+```typescript
+import { createLoader } from "@rangojs/router";
+import { authMiddleware } from "../middleware/auth";
+import { rateLimitMiddleware } from "../middleware/rate-limit";
+
+export const ProtectedLoader = createLoader(
+  async (ctx) => {
+    "use server";
+
+    const user = ctx.get("user");
+    return { orders: await db.orders.list(user.id) };
+  },
+  { middleware: [authMiddleware, rateLimitMiddleware] },
+);
+```
+
+The middleware uses the same `MiddlewareFn` signature as route/app middleware,
+so you can reuse existing middleware functions directly.
+
 Fetchable loaders support both GET and POST (PUT, PATCH, DELETE) from the client.
 The `load()` function auto-detects the body type:
 
@@ -288,20 +612,24 @@ Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 // loaders/shop.ts
 import { createLoader } from "@rangojs/router";
 
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+
   const product = await ctx.env.DB
     .prepare("SELECT * FROM products WHERE slug = ?")
     .bind(ctx.params.slug)
     .first();
 
   if (!product) {
-    throw new Response("Product not found", { status: 404 });
+    notFound("Product not found");
   }
 
   return { product };
 });
 
-export const CartLoader = createLoader("cart", async (ctx) => {
+export const CartLoader = createLoader(async (ctx) => {
+  "use server";
+
   const user = ctx.get("user");
   if (!user) return { cart: null };
 
@@ -309,10 +637,9 @@ export const CartLoader = createLoader("cart", async (ctx) => {
   return { cart };
 });
 
-// urls.tsx
+// urls.tsx — register loaders in the DSL
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
-    // Shared cart loader for all shop routes
     loader(CartLoader, () => [
       revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
     ]),
@@ -324,18 +651,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx
-import { useLoader } from "@rangojs/router";
+// components/ProductDetails.tsx — consume in client component
+"use client";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage() {
-  const { product } = await useLoader(ProductLoader);
-  const { cart } = await useLoader(CartLoader);
+function ProductDetails() {
+  const { data: { product } } = useLoader(ProductLoader);
+  const { data: { cart } } = useLoader(CartLoader);
 
   return (
     <div>
       <h1>{product.name}</h1>
-      <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
+      <AddToCartButton
+        productId={product.id}
+        inCart={cart?.items.includes(product.id)}
+      />
     </div>
   );
 }