@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/route-map-builder.ts

@@ -1,146 +1,281 @@
 /**
- * Client-safe route map builder
+ * Route manifest storage and retrieval.
  *
- * Provides a fluent API for building route maps with prefixes.
- * Can be imported in client code without pulling in server dependencies.
+ * The route manifest maps route names to URL patterns. It is populated
+ * by the virtual module (which imports from .named-routes.gen.ts files)
+ * and consumed by reverse() and href() at runtime.
  *
- * @example
- * ```typescript
- * import { createRouteMap, registerRouteMap } from "rsc-router/browser";
- *
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog")
- *   .add(shopRoutes, "shop");
- *
- * registerRouteMap(routeMap.routes);
- *
- * declare global {
- *   namespace RSCRouter {
- *     interface RegisteredRoutes extends typeof routeMap.routes {}
- *   }
- * }
- * ```
+ * See docs/manifests.md for the full data flow.
  */
 
-import type { PrefixRoutePatterns } from "./href.js";
+// Singleton route map instance - populated incrementally as routes are encountered
+let globalRouteMap: Record<string, string> = {};
+
+// Cached complete manifest - includes all routes (including lazy includes)
+// Set from runtime cache or build-time import
+let cachedManifest: Record<string, string> | null = null;
+
+// Pre-computed route entries from build-time prefix tree leaf nodes.
+// Used by evaluateLazyEntry() to skip running the handler for route matching.
+let cachedPrecomputedEntries: Array<{
+  staticPrefix: string;
+  routes: Record<string, string>;
+}> | null = null;
 
 /**
- * Route map builder interface
- *
- * Accumulates route types through the builder chain for type-safe href.
+ * Register routes into the global route map.
+ * Routes are merged with any existing registered routes.
+ * Called by createRouter() during module evaluation.
  */
-export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
-  /**
-   * Add routes without prefix
-   */
-  add<T extends Record<string, string>>(routes: T): RouteMapBuilder<TRoutes & T>;
-
-  /**
-   * 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 & PrefixRoutePatterns<T, `/${P}`>>;
-
-  /**
-   * The accumulated route map (for typeof extraction in module augmentation)
-   */
-  readonly routes: TRoutes;
+export function registerRouteMap(map: Record<string, string>): void {
+  // Always merge with existing map (don't replace)
+  globalRouteMap = { ...globalRouteMap, ...map };
 }
 
 /**
- * Add routes to a map with optional prefix
- * Keys stay unchanged for composability - only URL patterns get prefixed.
+ * Get the globally registered route map
  *
- * @param routeMap - The map to add routes to
- * @param routes - Routes to add
- * @param prefix - Optional prefix for URL paths WITHOUT leading slash (keys stay unchanged)
+ * Used internally by reverse to resolve route names to URLs at runtime.
+ * Returns the cached manifest if available (complete with lazy includes),
+ * otherwise returns the runtime-accumulated route map.
+ *
+ * @returns The registered route map
+ * @internal
  */
-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 prefixedPattern =
-      normalizedPrefix && pattern !== "/"
-        ? `/${normalizedPrefix}${pattern}`
-        : normalizedPrefix && pattern === "/"
-          ? `/${normalizedPrefix}`
-          : pattern;
-    // Use original key - enables reusable route modules
-    routeMap[key] = prefixedPattern;
+export function getGlobalRouteMap(): Record<string, string> {
+  // Cached manifest is complete (includes lazy routes), so prefer it
+  if (cachedManifest) {
+    return cachedManifest;
   }
+  return globalRouteMap;
 }
 
 /**
- * Create a new route map builder
- *
- * @returns A builder for accumulating routes with type-safe prefixes
+ * Set the cached manifest (for runtime cache integration)
  *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
+ * This sets the complete route manifest from a runtime cache.
+ * The cached manifest includes all routes (including lazy includes)
+ * and takes precedence over the incrementally-built globalRouteMap.
  *
- * // Types are accumulated through the chain
- * type AppRoutes = typeof routeMap.routes;
- * ```
+ * @param manifest - The complete route manifest to cache
  */
-export function createRouteMap(): RouteMapBuilder<{}> {
-  const routeMap: Record<string, string> = {};
-
-  const builder: RouteMapBuilder<any> = {
-    add(routes: Record<string, string>, prefix?: string) {
-      addRoutes(routeMap, routes, prefix);
-      return builder;
-    },
-    get routes() {
-      return routeMap;
-    },
-  };
+export function setCachedManifest(manifest: Record<string, string>): void {
+  cachedManifest = manifest;
+}
 
-  return builder;
+/**
+ * Check if a cached manifest is loaded
+ *
+ * @returns true if a complete manifest is available
+ */
+export function hasCachedManifest(): boolean {
+  return cachedManifest !== null;
 }
 
-// Singleton route map instance - populated when routes.ts is imported
-let globalRouteMap: Record<string, string> = {};
+/**
+ * Clear the cached manifest (for testing)
+ */
+export function clearCachedManifest(): void {
+  cachedManifest = null;
+}
 
 /**
- * Register the route map globally for href to use at runtime
- *
- * Call this after building your route map to make it available to href.
- *
- * @param map - The route map to register
+ * Set pre-computed route entries from build-time data.
  *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
+ * Each entry corresponds to a leaf node in the prefix tree (no nested includes).
+ * evaluateLazyEntry() checks these before running the handler, avoiding the
+ * 5-50ms cost of handler evaluation for route matching on the first request.
  *
- * registerRouteMap(routeMap.routes);
- * ```
+ * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
  */
-export function registerRouteMap(map: Record<string, string>): void {
-  globalRouteMap = map;
+export function setPrecomputedEntries(
+  entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> | null,
+): void {
+  cachedPrecomputedEntries = entries;
 }
 
 /**
- * Get the globally registered route map
- *
- * Used internally by href to resolve route names to URLs at runtime.
+ * Get pre-computed route entries (if available)
+ */
+export function getPrecomputedEntries(): typeof cachedPrecomputedEntries {
+  return cachedPrecomputedEntries;
+}
+
+// Route trie for O(path_length) matching at runtime.
+// Built at build time from the route manifest and serialized into the virtual module.
+let cachedRouteTrie: import("./build/route-trie.js").TrieNode | null = null;
+
+export function setRouteTrie(trie: typeof cachedRouteTrie): void {
+  cachedRouteTrie = trie;
+}
+
+export function getRouteTrie(): typeof cachedRouteTrie {
+  return cachedRouteTrie;
+}
+
+// Per-router isolated data: each router gets its own manifest, trie, and
+// precomputed entries so multi-router setups (e.g. site + admin via
+// createHostRouter()) don't see each other's routes.
+const perRouterManifestMap: Map<string, Record<string, string>> = new Map();
+const perRouterTrieMap: Map<string, import("./build/route-trie.js").TrieNode> =
+  new Map();
+const perRouterPrecomputedEntriesMap: Map<
+  string,
+  Array<{ staticPrefix: string; routes: Record<string, string> }>
+> = new Map();
+
+/**
+ * Clear all cached route data (global and per-router).
+ * Called during HMR when route definitions change so the handler rebuilds
+ * the trie from the updated router.urlpatterns on the next request.
  *
- * @returns The registered route map
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
  */
-export function getGlobalRouteMap(): Record<string, string> {
-  return globalRouteMap;
+export function clearAllRouterData(): void {
+  globalRouteMap = {};
+  cachedManifest = null;
+  cachedPrecomputedEntries = null;
+  cachedRouteTrie = null;
+  rootScopeRoutes.clear();
+  globalSearchSchemas.clear();
+  perRouterManifestMap.clear();
+  perRouterTrieMap.clear();
+  perRouterPrecomputedEntriesMap.clear();
+}
+
+export function setRouterManifest(
+  routerId: string,
+  manifest: Record<string, string>,
+): void {
+  perRouterManifestMap.set(routerId, manifest);
+}
+
+/** @internal */
+export function getRouterManifest(
+  routerId: string,
+): Record<string, string> | undefined {
+  return perRouterManifestMap.get(routerId);
+}
+
+export function setRouterTrie(
+  routerId: string,
+  trie: import("./build/route-trie.js").TrieNode,
+): void {
+  perRouterTrieMap.set(routerId, trie);
+}
+
+export function getRouterTrie(
+  routerId: string,
+): import("./build/route-trie.js").TrieNode | undefined {
+  return perRouterTrieMap.get(routerId);
+}
+
+export function setRouterPrecomputedEntries(
+  routerId: string,
+  entries: Array<{ staticPrefix: string; routes: Record<string, string> }>,
+): void {
+  perRouterPrecomputedEntriesMap.set(routerId, entries);
+}
+
+export function getRouterPrecomputedEntries(
+  routerId: string,
+): Array<{ staticPrefix: string; routes: Record<string, string> }> | undefined {
+  return perRouterPrecomputedEntriesMap.get(routerId);
+}
+
+// Lazy loader registry: per-router manifest modules are loaded on first request
+// via import() to keep startup fast and allow Rollup to code-split per router.
+const routerManifestLoaders: Map<string, () => Promise<any>> = new Map();
+
+export function registerRouterManifestLoader(
+  routerId: string,
+  loader: () => Promise<any>,
+): void {
+  routerManifestLoaders.set(routerId, loader);
+}
+
+export async function ensureRouterManifest(routerId: string): Promise<void> {
+  // Check both manifest AND trie. The virtual module's setRouterManifest()
+  // pre-sets the manifest at startup, but the per-router trie is only
+  // available from the lazy loader. Without this, the lazy loader never
+  // runs and findMatch falls back to the global merged trie — which
+  // contains routes from ALL routers and breaks multi-router setups.
+  if (perRouterManifestMap.has(routerId) && perRouterTrieMap.has(routerId))
+    return;
+  const loader = routerManifestLoaders.get(routerId);
+  if (loader) {
+    const mod = await loader();
+    if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
+    if (mod.trie) perRouterTrieMap.set(routerId, mod.trie);
+    if (mod.precomputedEntries)
+      perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
+    routerManifestLoaders.delete(routerId);
+  }
+}
+
+// Dev-mode manifest readiness gate.
+// The Vite discovery plugin calls setManifestReadyPromise() before starting
+// discovery, and resolves it when discovery completes. The handler awaits
+// waitForManifestReady() on first request if the manifest isn't yet available.
+let manifestReadyPromise: Promise<void> | null = null;
+
+export function setManifestReadyPromise(promise: Promise<void>): void {
+  manifestReadyPromise = promise;
+}
+
+export function waitForManifestReady(): Promise<void> | null {
+  return manifestReadyPromise;
+}
+
+// ============================================================================
+// Route Scope Registry
+// ============================================================================
+
+// Tracks whether each route is at root scope (no named include boundary above).
+// Used by dot-local reverse resolution to decide whether bare-name fallback
+// is allowed after scoped lookups are exhausted.
+const rootScopeRoutes: Map<string, boolean> = new Map();
+
+/**
+ * Register whether a route is at root scope.
+ * Called by path() during route evaluation.
+ */
+export function registerRouteRootScope(
+  routeName: string,
+  rootScoped: boolean,
+): void {
+  rootScopeRoutes.set(routeName, rootScoped);
+}
+
+/**
+ * Check if a route is at root scope.
+ * Returns undefined if the route has not been registered (e.g. in unit tests).
+ */
+export function isRouteRootScoped(routeName: string): boolean | undefined {
+  return rootScopeRoutes.get(routeName);
+}
+
+// ============================================================================
+// Search Schema Registry
+// ============================================================================
+
+import type { SearchSchema } from "./search-params.js";
+
+// Global search schema map: route name -> search schema descriptor.
+// Populated by path() when a search option is provided.
+const globalSearchSchemas: Map<string, SearchSchema> = new Map();
+
+export function registerSearchSchema(
+  routeName: string,
+  schema: SearchSchema,
+): void {
+  globalSearchSchemas.set(routeName, schema);
+}
+
+export function getSearchSchema(routeName: string): SearchSchema | undefined {
+  return globalSearchSchemas.get(routeName);
 }

package/src/route-name.ts

@@ -0,0 +1,53 @@
+/**
+ * Route name utilities for filtering internal route names.
+ *
+ * Internal names stay active in the runtime manifest for matching and local
+ * reverse() resolution, but they must not leak into public APIs or generated
+ * route maps.
+ */
+
+export const AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+export const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+
+const RESERVED_PREFIXES = [
+  AUTO_GENERATED_ROUTE_PREFIX,
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+] as const;
+
+/**
+ * Check if a route name is internal.
+ * Internal names include:
+ * - unnamed path() routes like "$path__health" or "docs.$path__health"
+ * - hidden include scopes like "$prefix_0.index" or "blog.$prefix_1.post"
+ *
+ * User-defined names containing "$" (e.g. "docs.$admin") are valid and must
+ * be preserved.
+ */
+export function isAutoGeneratedRouteName(name: string): boolean {
+  return name.split(".").some((segment) => {
+    return (
+      segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) ||
+      segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX)
+    );
+  });
+}
+
+/**
+ * Validate that a user-provided route name does not collide with
+ * reserved internal prefixes. Checks every dot-separated segment,
+ * mirroring the same rule used by isAutoGeneratedRouteName().
+ *
+ * Throws with a clear message when a reserved prefix is detected.
+ */
+export function validateUserRouteName(name: string): void {
+  for (const segment of name.split(".")) {
+    for (const prefix of RESERVED_PREFIXES) {
+      if (segment.startsWith(prefix)) {
+        throw new Error(
+          `Route name "${name}" contains segment "${segment}" which uses reserved internal prefix "${prefix}". ` +
+            `Choose a different name to avoid collision with auto-generated route names.`,
+        );
+      }
+    }
+  }
+}