@ivogt/rsc-router 0.0.0-experimental.13 → 0.0.0-experimental.14

package/dist/vite/index.js

@@ -675,7 +675,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@ivogt/rsc-router",
-  version: "0.0.0-experimental.13",
+  version: "0.0.0-experimental.14",
   type: "module",
   description: "Type-safe RSC router with partial rendering support",
   author: "Ivo Todorov",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivogt/rsc-router",
-  "version": "0.0.0-experimental.13",
+  "version": "0.0.0-experimental.14",
   "type": "module",
   "description": "Type-safe RSC router with partial rendering support",
   "author": "Ivo Todorov",

package/src/href.ts

@@ -8,19 +8,22 @@ export type SanitizePrefix<T extends string> = T extends `/${infer P}` ? P : T;
 
 /**
  * Helper type to merge multiple route definitions into a single accumulated type.
- * Use this to define your app's complete route map for type-safe router.href().
+ * Note: When using createRSCRouter, types accumulate automatically through the
+ * builder chain, so this type is typically not needed.
  *
  * @example
  * ```typescript
- * import { homeRoutes, blogRoutes, shopRoutes } from "./routes";
- *
+ * // Manual type merging (rarely needed):
  * type AppRoutes = MergeRoutes<[
  *   typeof homeRoutes,
- *   PrefixedRoutes<typeof blogRoutes, "blog">,
- *   PrefixedRoutes<typeof shopRoutes, "shop">,
+ *   PrefixRoutePatterns<typeof blogRoutes, "/blog">,
  * ]>;
  *
- * export const router = createRSCRouter<AppEnv>() as RSCRouter<AppEnv, AppRoutes>;
+ * // Preferred: Let router accumulate types automatically
+ * const router = createRSCRouter<AppEnv>()
+ *   .routes(homeRoutes).map(...)
+ *   .routes("/blog", blogRoutes).map(...);
+ * type AppRoutes = typeof router.routeMap;
  * ```
  */
 export type MergeRoutes<T extends Record<string, string>[]> = T extends [
@@ -111,9 +114,10 @@ export type HrefFunction<TRoutes extends Record<string, string>> = {
  *
  * @example
  * ```typescript
- * const href = createHref(mergedRouteMap);
- * href("shop.cart"); // "/shop/cart"
- * href("shop.products.detail", { slug: "my-product" }); // "/shop/product/my-product"
+ * // Given routes: { cart: "/shop/cart", detail: "/shop/product/:slug" }
+ * const href = createHref(routeMap);
+ * href("cart"); // "/shop/cart"
+ * href("detail", { slug: "my-product" }); // "/shop/product/my-product"
  * ```
  */
 export function createHref<TRoutes extends Record<string, string>>(

package/src/route-definition.ts

@@ -1248,6 +1248,30 @@ export function map<const T extends RouteDefinition, TEnv = DefaultEnv>(
   };
 }
 
+/**
+ * Create RouteHelpers for inline route definitions
+ * Used internally by router.map() for inline handler syntax
+ */
+export function createRouteHelpers<
+  T extends RouteDefinition,
+  TEnv,
+>(): RouteHelpers<T, TEnv> {
+  return {
+    route: createRouteHelper<T, TEnv>(),
+    layout: createLayoutHelper<TEnv>(),
+    parallel: createParallelHelper<TEnv>(),
+    intercept: createInterceptHelper<T, TEnv>(),
+    middleware: createMiddlewareHelper<TEnv>(),
+    revalidate: createRevalidateHelper<TEnv>(),
+    loader: createLoaderHelper<TEnv>(),
+    loading: createLoadingHelper(),
+    errorBoundary: createErrorBoundaryHelper<TEnv>(),
+    notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
+    when: createWhenHelper(),
+    cache: createCacheHelper(),
+  };
+}
+
 /**
  * Create a loader definition
  *

package/src/route-map-builder.ts

@@ -23,7 +23,7 @@
  * ```
  */
 
-import type { PrefixedRoutes } from "./href.js";
+import type { PrefixRoutePatterns } from "./href.js";
 
 /**
  * Route map builder interface
@@ -37,12 +37,14 @@ export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
   add<T extends Record<string, string>>(routes: T): RouteMapBuilder<TRoutes & T>;
 
   /**
-   * Add routes with prefix
+   * Add routes with prefix (only URL patterns are prefixed, keys stay unchanged)
+   * @param routes - Route definitions to add
+   * @param prefix - URL prefix WITHOUT leading slash (e.g., "blog" not "/blog")
    */
   add<T extends Record<string, string>, P extends string>(
     routes: T,
     prefix: P
-  ): RouteMapBuilder<TRoutes & PrefixedRoutes<T, P>>;
+  ): RouteMapBuilder<TRoutes & PrefixRoutePatterns<T, `/${P}`>>;
 
   /**
    * The accumulated route map (for typeof extraction in module augmentation)
@@ -52,25 +54,29 @@ export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
 
 /**
  * Add routes to a map with optional prefix
+ * Keys stay unchanged for composability - only URL patterns get prefixed.
  *
  * @param routeMap - The map to add routes to
  * @param routes - Routes to add
- * @param prefix - Optional prefix for keys and paths
+ * @param prefix - Optional prefix for URL paths WITHOUT leading slash (keys stay unchanged)
  */
 function addRoutes(
   routeMap: Record<string, string>,
   routes: Record<string, string>,
   prefix: string = ""
 ): void {
+  // Normalize prefix: remove leading slash if accidentally provided
+  const normalizedPrefix = prefix.startsWith("/") ? prefix.slice(1) : prefix;
+
   for (const [key, pattern] of Object.entries(routes)) {
-    const prefixedKey = prefix ? `${prefix}.${key}` : key;
     const prefixedPattern =
-      prefix && pattern !== "/"
-        ? `/${prefix}${pattern}`
-        : prefix && pattern === "/"
-          ? `/${prefix}`
+      normalizedPrefix && pattern !== "/"
+        ? `/${normalizedPrefix}${pattern}`
+        : normalizedPrefix && pattern === "/"
+          ? `/${normalizedPrefix}`
           : pattern;
-    routeMap[prefixedKey] = prefixedPattern;
+    // Use original key - enables reusable route modules
+    routeMap[key] = prefixedPattern;
   }
 }
 

package/src/router/manifest.ts

@@ -5,7 +5,9 @@
  */
 
 import { invariant, RouteNotFoundError } from "../errors";
+import { createRouteHelpers } from "../route-definition";
 import { getContext, type EntryData, type MetricsStore } from "../server/context";
+import MapRootLayout from "../server/root-layout";
 import type { RouteEntry } from "../types";
 
 /**
@@ -63,19 +65,39 @@ export async function loadManifest(
       Store.namespace || namespaceWithMount,
       Store.parent,
       async () => {
-        const load = await entry.handler();
-        if (
-          load &&
-          load !== null &&
-          typeof load === "object" &&
-          "default" in load
-        ) {
-          return load.default();
-        }
-        if (typeof load === "function") {
-          return load();
+        // Create helpers - inline handlers use them, lazy handlers ignore them
+        const helpers = createRouteHelpers();
+
+        // Call handler with helpers - works for both inline and lazy
+        const result = entry.handler(helpers);
+
+        // Handle based on return type
+        if (result instanceof Promise) {
+          // Lazy: () => import(...) - returns Promise
+          const load = await result;
+          if (
+            load &&
+            load !== null &&
+            typeof load === "object" &&
+            "default" in load
+          ) {
+            // Promise<{ default: () => Array }> - e.g., dynamic import
+            // Pass helpers - functions that need them will use them,
+            // functions from route-definition's map() will ignore them
+            return load.default(helpers);
+          }
+          if (typeof load === "function") {
+            // Promise<() => Array>
+            return load(helpers);
+          }
+          // Promise<Array> - direct array from async handler
+          return load;
         }
-        return load;
+
+        // Inline: ({ route }) => [...] - returns Array directly
+        // Wrap with layout (like map() from route-definition does)
+        // Flatten nested arrays from layout/route definitions
+        return [helpers.layout(MapRootLayout, () => result)].flat(3);
       }
     );
 

package/src/router.ts

@@ -14,10 +14,14 @@ import {
 import {
   createHref,
   type HrefFunction,
-  type PrefixedRoutes,
-  type SanitizePrefix,
+  type PrefixRoutePatterns,
 } from "./href.js";
 import { registerRouteMap } from "./route-map-builder.js";
+import {
+  createRouteHelpers,
+  type RouteHelpers,
+} from "./route-definition.js";
+import MapRootLayout from "./server/root-layout.js";
 import type { AllUseItems } from "./route-types.js";
 import {
   EntryData,
@@ -265,14 +269,131 @@ export interface RSCRouterOptions<TEnv = any> {
     | ((env: TEnv) => { store: SegmentCacheStore; enabled?: boolean });
 }
 
+/**
+ * Type-level detection of conflicting route keys.
+ * Extracts keys that exist in both TExisting and TNew but with different URL patterns.
+ * Returns `never` if no conflicts exist.
+ *
+ * @example
+ * ```typescript
+ * ConflictingKeys<{ a: "/a" }, { a: "/b" }> // "a" (conflict - same key, different URLs)
+ * ConflictingKeys<{ a: "/a" }, { a: "/a" }> // never (no conflict - same key and URL)
+ * ConflictingKeys<{ a: "/a" }, { b: "/b" }> // never (no conflict - different keys)
+ * ```
+ */
+type ConflictingKeys<
+  TExisting extends Record<string, string>,
+  TNew extends Record<string, string>
+> = {
+  [K in keyof TExisting & keyof TNew]: TExisting[K] extends TNew[K]
+    ? TNew[K] extends TExisting[K]
+      ? never // Same value, no conflict
+      : K // Different values, conflict
+    : K; // Different values, conflict
+}[keyof TExisting & keyof TNew];
+
+/**
+ * Simplified route helpers for inline route definitions.
+ * Uses TRoutes (Record<string, string>) instead of RouteDefinition.
+ *
+ * Note: Some helpers use `any` for context types as a trade-off for simpler usage.
+ * The main type safety is in the `route` helper which enforces valid route names.
+ * For full type safety, use the standard map() API with separate handler files.
+ */
+type InlineRouteHelpers<
+  TRoutes extends Record<string, string>,
+  TEnv,
+> = {
+  /**
+   * Define a route handler for a specific route pattern
+   */
+  route: <K extends keyof TRoutes & string>(
+    name: K,
+    handler:
+      | ((ctx: HandlerContext<{}, TEnv>) => ReactNode | Promise<ReactNode>)
+      | ReactNode
+  ) => AllUseItems;
+
+  /**
+   * Define a layout that wraps child routes
+   */
+  layout: (
+    component: ReactNode | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>),
+    use?: () => AllUseItems[]
+  ) => AllUseItems;
+
+  /**
+   * Define parallel routes
+   */
+  parallel: (
+    slots: Record<`@${string}`, ReactNode | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)>,
+    use?: () => AllUseItems[]
+  ) => AllUseItems;
+
+  /**
+   * Define route middleware
+   */
+  middleware: (fn: (ctx: any, next: () => Promise<void>) => Promise<void>) => AllUseItems;
+
+  /**
+   * Define revalidation handlers
+   */
+  revalidate: (fn: (ctx: any) => boolean | Promise<boolean>) => AllUseItems;
+
+  /**
+   * Define data loaders
+   */
+  loader: (loader: any, use?: () => AllUseItems[]) => AllUseItems;
+
+  /**
+   * Define loading states
+   */
+  loading: (component: ReactNode) => AllUseItems;
+
+  /**
+   * Define error boundaries
+   */
+  errorBoundary: (
+    handler: ReactNode | ((props: { error: Error }) => ReactNode)
+  ) => AllUseItems;
+
+  /**
+   * Define not found boundaries
+   */
+  notFoundBoundary: (
+    handler: ReactNode | ((props: { pathname: string }) => ReactNode)
+  ) => AllUseItems;
+
+  /**
+   * Define intercept routes
+   */
+  intercept: (
+    name: string,
+    handler: ReactNode | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>),
+    use?: () => AllUseItems[]
+  ) => AllUseItems;
+
+  /**
+   * Define when conditions for intercepts
+   */
+  when: (condition: (ctx: any) => boolean | Promise<boolean>) => AllUseItems;
+
+  /**
+   * Define cache configuration
+   */
+  cache: (config: { ttl?: number; swr?: number } | false, use?: () => AllUseItems[]) => AllUseItems;
+};
+
 /**
  * Router builder for chaining .use() and .map()
  * TRoutes accumulates all registered route types through the chain
+ * TLocalRoutes contains the routes for the current .routes() call (for inline handler typing)
  */
 interface RouteBuilder<
   T extends RouteDefinition,
   TEnv,
   TRoutes extends Record<string, string>,
+  TLocalRoutes extends Record<string, string> = Record<string, string>,
 > {
   /**
    * Add middleware scoped to this mount
@@ -289,8 +410,34 @@ interface RouteBuilder<
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>
-  ): RouteBuilder<T, TEnv, TRoutes>;
+  ): RouteBuilder<T, TEnv, TRoutes, TLocalRoutes>;
 
+  /**
+   * Map routes to handlers
+   *
+   * Supports two patterns:
+   *
+   * 1. Lazy loading (code-split):
+   * ```typescript
+   * .routes(homeRoutes)
+   * .map(() => import("./handlers/home"))
+   * ```
+   *
+   * 2. Inline definition:
+   * ```typescript
+   * .routes({ index: "/", about: "/about" })
+   * .map(({ route }) => [
+   *   route("index", () => <HomePage />),
+   *   route("about", () => <AboutPage />),
+   * ])
+   * ```
+   */
+  // Inline definition overload - handler receives helpers (must be first for correct inference)
+  // Uses TLocalRoutes so route names don't need the prefix
+  map<H extends (helpers: InlineRouteHelpers<TLocalRoutes, TEnv>) => Array<AllUseItems>>(
+    handler: H
+  ): RSCRouter<TEnv, TRoutes>;
+  // Lazy loading overload - no parameters
   map(
     handler: () =>
       | Array<AllUseItems>
@@ -315,24 +462,40 @@ export interface RSCRouter<
 > {
   /**
    * Register routes with a prefix
-   * Route types are accumulated through the chain
+   * Route keys stay unchanged, only URL patterns get the prefix applied.
+   * This enables composable route modules that work regardless of mount point.
+   *
+   * @throws Compile-time error if route keys conflict with previously registered routes
    */
   routes<TPrefix extends string, T extends ResolvedRouteMap<any>>(
     prefix: TPrefix,
     routes: T
-  ): RouteBuilder<
-    RouteDefinition,
-    TEnv,
-    TRoutes & PrefixedRoutes<T, SanitizePrefix<TPrefix>>
-  >;
+  ): ConflictingKeys<TRoutes, T> extends never
+    ? RouteBuilder<
+        RouteDefinition,
+        TEnv,
+        TRoutes & PrefixRoutePatterns<T, TPrefix>,
+        T
+      >
+    : {
+        __error: `Route key conflict! Keys [${ConflictingKeys<TRoutes, T> & string}] already exist with different URL patterns.`;
+        hint: "Use unique key names for each route definition.";
+      };
 
   /**
    * Register routes without a prefix
    * Route types are accumulated through the chain
+   *
+   * @throws Compile-time error if route keys conflict with previously registered routes
    */
   routes<T extends ResolvedRouteMap<any>>(
     routes: T
-  ): RouteBuilder<RouteDefinition, TEnv, TRoutes & T>;
+  ): ConflictingKeys<TRoutes, T> extends never
+    ? RouteBuilder<RouteDefinition, TEnv, TRoutes & T, T>
+    : {
+        __error: `Route key conflict! Keys [${ConflictingKeys<TRoutes, T> & string}] already exist with different URL patterns.`;
+        hint: "Use unique key names for each route definition.";
+      };
 
   /**
    * Add global middleware that runs on all routes
@@ -355,11 +518,13 @@ export interface RSCRouter<
   /**
    * Type-safe URL builder for registered routes
    * Types are inferred from the accumulated route registrations
+   * Route keys stay unchanged regardless of mount prefix.
    *
    * @example
    * ```typescript
-   * router.href("shop.cart"); // "/shop/cart"
-   * router.href("shop.products.detail", { slug: "widget" }); // "/shop/product/widget"
+   * // Given: .routes("/shop", { cart: "/cart", detail: "/product/:slug" })
+   * router.href("cart"); // "/shop/cart"
+   * router.href("detail", { slug: "widget" }); // "/shop/product/widget"
    * ```
    */
   href: HrefFunction<TRoutes>;
@@ -477,14 +642,16 @@ export interface RSCRouter<
  * });
  *
  * // Route types accumulate through the chain - no module augmentation needed!
+ * // Keys stay unchanged, only URL patterns get the prefix
  * router
  *   .routes(homeRoutes)          // accumulates homeRoutes
  *   .map(() => import('./home'))
- *   .routes('/shop', shopRoutes) // accumulates PrefixedRoutes<shopRoutes, "shop">
+ *   .routes('/shop', shopRoutes) // accumulates shopRoutes with prefixed URLs
  *   .map(() => import('./shop'));
  *
  * // router.href now has type-safe autocomplete for all registered routes
- * router.href("shop.cart");
+ * // Given shopRoutes = { cart: "/cart" }, href uses original key:
+ * router.href("cart"); // "/shop/cart"
  * ```
  */
 export function createRSCRouter<TEnv = any>(
@@ -3393,15 +3560,13 @@ export function createRSCRouter<TEnv = any>(
   function createRouteBuilder<TNewRoutes extends Record<string, string>>(
     prefix: string,
     routes: TNewRoutes
-  ): RouteBuilder<RouteDefinition, TEnv, TNewRoutes> {
+  ): RouteBuilder<RouteDefinition, TEnv, any, TNewRoutes> {
     const currentMountIndex = mountIndex++;
 
-    // Merge routes into the href map with prefixes
-    // This enables type-safe router.href() calls
+    // Merge routes into the href map
+    // Keys stay unchanged for composability - only URL patterns get prefixed
     const routeEntries = routes as Record<string, string>;
     for (const [key, pattern] of Object.entries(routeEntries)) {
-      // Build prefixed key: "shop" + "cart" -> "shop.cart"
-      const prefixedKey = prefix ? `${prefix.slice(1)}.${key}` : key;
       // Build prefixed pattern: "/shop" + "/cart" -> "/shop/cart"
       const prefixedPattern =
         prefix && pattern !== "/"
@@ -3409,7 +3574,18 @@ export function createRSCRouter<TEnv = any>(
           : prefix && pattern === "/"
             ? prefix
             : pattern;
-      mergedRouteMap[prefixedKey] = prefixedPattern;
+
+      // Runtime validation: warn if key already exists with different pattern
+      const existingPattern = mergedRouteMap[key];
+      if (existingPattern !== undefined && existingPattern !== prefixedPattern) {
+        console.warn(
+          `[rsc-router] Route key conflict: "${key}" already maps to "${existingPattern}", ` +
+            `overwriting with "${prefixedPattern}". Use unique key names to avoid this.`
+        );
+      }
+
+      // Use original key - enables reusable route modules
+      mergedRouteMap[key] = prefixedPattern;
     }
 
     // Auto-register route map for runtime href() usage
@@ -3421,7 +3597,7 @@ export function createRSCRouter<TEnv = any>(
       | undefined;
 
     // Create builder object so .use() can return it
-    const builder: RouteBuilder<RouteDefinition, TEnv, TNewRoutes> = {
+    const builder: RouteBuilder<RouteDefinition, TEnv, any, TNewRoutes> = {
       use(
         patternOrMiddleware: string | MiddlewareFn<TEnv>,
         middleware?: MiddlewareFn<TEnv>
@@ -3432,16 +3608,22 @@ export function createRSCRouter<TEnv = any>(
       },
 
       map(
-        handler: () =>
-          | Array<AllUseItems>
-          | Promise<{ default: () => Array<AllUseItems> }>
-          | Promise<() => Array<AllUseItems>>
+        handler:
+          | ((helpers: InlineRouteHelpers<TNewRoutes, TEnv>) => Array<AllUseItems>)
+          | (() =>
+              | Array<AllUseItems>
+              | Promise<{ default: () => Array<AllUseItems> }>
+              | Promise<() => Array<AllUseItems>>)
       ) {
+        // Store handler as-is - detection happens at call time based on return type
+        // Both patterns use the same signature:
+        // - Inline: ({ route }) => [...] - receives helpers, returns Array
+        // - Lazy: () => import(...) - ignores helpers, returns Promise
         routesEntries.push({
           prefix,
           routes: routes as ResolvedRouteMap<any>,
           trailingSlash: trailingSlashConfig,
-          handler,
+          handler: handler as any,
           mountIndex: currentMountIndex,
         });
         // Return router with accumulated types

package/src/rsc/handler.ts

@@ -60,9 +60,10 @@ import { invokeOnError } from "../router/error-handling.js";
  * });
  * ```
  */
-export function createRSCHandler<TEnv = unknown>(
-  options: CreateRSCHandlerOptions<TEnv>
-) {
+export function createRSCHandler<
+  TEnv = unknown,
+  TRoutes extends Record<string, string> = Record<string, string>,
+>(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, version = VERSION, nonce: nonceProvider } = options;
 
   // Use provided deps or default to @vitejs/plugin-rsc/rsc exports

package/src/rsc/types.ts

@@ -140,11 +140,14 @@ export type NonceProvider<TEnv = unknown> = (
 /**
  * Options for creating an RSC handler
  */
-export interface CreateRSCHandlerOptions<TEnv = unknown> {
+export interface CreateRSCHandlerOptions<
+  TEnv = unknown,
+  TRoutes extends Record<string, string> = Record<string, string>,
+> {
   /**
    * The RSC router instance
    */
-  router: RSCRouter<TEnv>;
+  router: RSCRouter<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

package/src/server.ts

@@ -30,6 +30,7 @@ export {
   createHref,
   type HrefFunction,
   type PrefixedRoutes,
+  type PrefixRoutePatterns,
   type ParamsFor,
   type SanitizePrefix,
   type MergeRoutes,