@rangojs/router 0.0.0-experimental.74 → 0.0.0-experimental.75

package/dist/vite/index.js

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

package/src/build/route-trie.ts

@@ -98,8 +98,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
@@ -107,14 +113,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      paramNames.push(seg.value);
       if (seg.optional) {
         optionalParams.push(seg.value);
       }
@@ -124,21 +129,15 @@ function insertRoute(
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -218,15 +217,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -235,12 +244,19 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
     if (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +264,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     } else {
       if (!node.p) {
         node.p = { n: segment.value, c: {} };
       }
-      insertSegments(node.p.c, segments, index + 1, leaf);
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
     const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };

package/src/index.ts

@@ -147,24 +147,52 @@ export { createVar, type ContextVar } from "./context-var.js";
 export { nonce } from "./rsc/nonce.js";
 
 /**
- * Error-throwing stub for server-only `Prerender` function.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Prerender(): never {
-  throw serverOnlyStubError("Prerender");
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Passthrough` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Passthrough(): never {
-  throw serverOnlyStubError("Passthrough");
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Static` function.
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Static(): never {
-  throw serverOnlyStubError("Static");
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**

package/src/route-definition/dsl-helpers.ts

@@ -55,6 +55,9 @@ const hasRoutesInItem = (item: AllUseItems): boolean => {
   if (item.type === "layout" && item.uses) {
     return item.uses.some((child) => hasRoutesInItem(child));
   }
+  if (item.type === "middleware" && item.uses) {
+    return item.uses.some((child) => hasRoutesInItem(child));
+  }
   return false;
 };
 
@@ -353,10 +356,37 @@ const cache: RouteHelpers<any, any>["cache"] = (
   return { name: namespace, type: "cache", uses: result } as CacheItem;
 };
 
-const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
+const middleware: RouteHelpers<any, any>["middleware"] = (...args: any[]) => {
+  // Four call forms:
+  //   middleware(fn)                       — single fn, sibling
+  //   middleware(fn, () => [...])          — single fn, wrapping
+  //   middleware([fn1, fn2])              — array, sibling
+  //   middleware([fn1, fn2], () => [...]) — array, wrapping
+  const isArray = Array.isArray(args[0]);
+
+  // Reject the removed variadic form before executing anything.
+  // middleware(fn1, fn2, fn3) — 3+ args, always wrong.
+  // middleware(fn1, fn2) where fn2 is a middleware fn (length >= 1), not a
+  // children callback (length === 0) — legacy two-fn form, reject early.
+  if (
+    args.length > 2 ||
+    (!isArray &&
+      args.length === 2 &&
+      typeof args[1] === "function" &&
+      args[1].length > 0)
+  ) {
+    throw new Error(
+      "middleware() no longer accepts variadic arguments. " +
+        "Use middleware([fn1, fn2, ...]) instead of middleware(fn1, fn2, ...).",
+    );
+  }
+
+  const fns: MiddlewareFn<any>[] = isArray ? args[0] : [args[0]];
+  const children: (() => any[]) | undefined =
+    typeof args[1] === "function" ? args[1] : undefined;
+
   // Prevent "use cache" functions from being used as middleware.
-  // Checked before context validation — this is a static invariant.
-  for (const f of fn) {
+  for (const f of fns) {
     if (isCachedFunction(f)) {
       throw new Error(
         `A "use cache" function cannot be used as middleware. ` +
@@ -367,17 +397,80 @@ const middleware: RouteHelpers<any, any>["middleware"] = (...fn) => {
     }
   }
 
-  const ctx = getContext().getStore();
+  const store = getContext();
+  const ctx = store.getStore();
   if (!ctx) throw new Error("middleware() must be called inside map()");
 
-  // Attach to last entry in stack
-  const parent = ctx.parent;
-  if (!parent || !("middleware" in parent)) {
-    invariant(false, "No parent entry available for middleware()");
+  if (!children) {
+    // Sibling mode: attach to parent entry
+    const parent = ctx.parent;
+    if (!parent || !("middleware" in parent)) {
+      invariant(false, "No parent entry available for middleware()");
+    }
+    const name = `$${store.getNextIndex("middleware")}`;
+    parent.middleware.push(...fns);
+    return { name, type: "middleware" } as MiddlewareItem;
+  }
+
+  // Wrapping mode: create a transparent layout that carries the middleware
+  const mwIndex = store.getNextIndex("middleware");
+  const namespace = `${ctx.namespace}.${mwIndex}`;
+
+  const urlPrefix = getUrlPrefix();
+  const entry = {
+    id: namespace,
+    shortCode: store.getShortCode("layout"),
+    type: "layout",
+    parent: ctx.parent,
+    handler: RootLayout,
+    loading: undefined,
+    middleware: [...fns],
+    revalidate: [],
+    errorBoundary: [],
+    notFoundBoundary: [],
+    layout: [],
+    parallel: {},
+    intercept: [],
+    loader: [],
+    ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+  } as EntryData;
+
+  // Run children callback. If the second arg was actually a middleware fn
+  // (old variadic form: middleware(mw1, mw2)), this will return a non-array
+  // and the invariant below gives a clear migration error.
+  const rawResult = store.run(namespace, entry, children);
+
+  invariant(
+    Array.isArray(rawResult),
+    "middleware(fn, children) expects the second argument to return an array of use items. " +
+      "To pass multiple middleware, use middleware([fn1, fn2]).",
+  );
+
+  const result = rawResult.flat(3);
+
+  invariant(
+    result.every((item: any) => isValidUseItem(item)),
+    `middleware() children callback must return an array of use items [${namespace}]`,
+  );
+
+  const hasRoutes =
+    result &&
+    Array.isArray(result) &&
+    result.some((item) => item != null && hasRoutesInItem(item));
+
+  if (!hasRoutes) {
+    const parent = ctx.parent;
+    if (parent && "layout" in parent) {
+      entry.parent = null;
+      parent.layout.push(entry);
+    }
   }
-  const name = `$${getContext().getNextIndex("middleware")}`;
-  parent.middleware.push(...fn);
-  return { name, type: "middleware" } as MiddlewareItem;
+
+  return {
+    name: namespace,
+    type: "middleware",
+    uses: result,
+  } as MiddlewareItem;
 };
 
 const parallel: RouteHelpers<any, any>["parallel"] = (slots, use) => {

package/src/route-definition/helpers-types.ts

@@ -182,21 +182,41 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
     ): InterceptItem;
   };
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
+   *
+   * **Sibling mode** — attaches middleware to the parent entry:
    * ```typescript
-   * middleware(async (ctx, next) => {
-   *   const session = await getSession(ctx.request);
-   *   if (!session) return redirect("/login");
-   *   ctx.set("user", session.user);
-   *   next();
-   * })
+   * layout(<DashboardShell />, () => [
+   *   middleware(authMiddleware),
+   *   middleware([authMiddleware, loggingMiddleware]),
+   *   path("/", DashboardPage),
+   * ])
+   * ```
+   *
+   * **Wrapping mode** — scopes middleware to the children only:
+   * ```typescript
+   * middleware(authMiddleware, () => [
+   *   path("/dashboard", DashboardPage),
+   *   path("/settings", SettingsPage),
+   * ])
    *
-   * // Chain multiple middleware
-   * middleware(authMiddleware, loggingMiddleware, rateLimitMiddleware)
+   * middleware([authMiddleware, loggingMiddleware], () => [
+   *   path("/admin", AdminPage),
+   * ])
    * ```
-   * @param fns - One or more middleware functions to execute in order
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
   /**
    * Control when a segment should revalidate during navigation
    * ```typescript

package/src/urls/path-helper-types.ts

@@ -264,9 +264,20 @@ export type PathHelpers<TEnv> = {
       ) => InterceptItem;
 
   /**
-   * Attach middleware to the current route/layout
+   * Attach middleware to the current route/layout, or wrap child segments
    */
-  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+  middleware: {
+    (fn: MiddlewareFn<TEnv>): MiddlewareItem;
+    (
+      fn: MiddlewareFn<TEnv>,
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+    (fns: MiddlewareFn<TEnv>[]): MiddlewareItem;
+    (
+      fns: MiddlewareFn<TEnv>[],
+      children: () => UseItems<LayoutUseItem>,
+    ): MiddlewareItem;
+  };
 
   /**
    * Control when a segment should revalidate during navigation