@rangojs/router 0.0.0-experimental.10

package/src/route-map-builder.ts

@@ -0,0 +1,242 @@
+/**
+ * Client-safe route map builder
+ *
+ * Provides a fluent API for building route maps with prefixes.
+ * Can be imported in client code without pulling in server dependencies.
+ *
+ * @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 {}
+ *   }
+ * }
+ * ```
+ */
+
+import type { PrefixRoutePatterns } from "./reverse.js";
+
+/**
+ * Route map builder interface
+ *
+ * Accumulates route types through the builder chain for type-safe reverse.
+ */
+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;
+}
+
+/**
+ * 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 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 prefixedPattern =
+      normalizedPrefix && pattern !== "/"
+        ? `/${normalizedPrefix}${pattern}`
+        : normalizedPrefix && pattern === "/"
+          ? `/${normalizedPrefix}`
+          : pattern;
+    // Use original key - enables reusable route modules
+    routeMap[key] = prefixedPattern;
+  }
+}
+
+/**
+ * Create a new route map builder
+ *
+ * @returns A builder for accumulating routes with type-safe prefixes
+ *
+ * @example
+ * ```typescript
+ * const routeMap = createRouteMap()
+ *   .add(homeRoutes)
+ *   .add(blogRoutes, "blog");
+ *
+ * // Types are accumulated through the chain
+ * type AppRoutes = typeof routeMap.routes;
+ * ```
+ */
+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;
+    },
+  };
+
+  return builder;
+}
+
+// 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;
+
+/**
+ * Register the route map globally for reverse to use at runtime
+ *
+ * Call this after building your route map to make it available to reverse.
+ * Routes are merged with any existing registered routes.
+ *
+ * @param map - The route map to register
+ *
+ * @example
+ * ```typescript
+ * const routeMap = createRouteMap()
+ *   .add(homeRoutes)
+ *   .add(blogRoutes, "blog");
+ *
+ * registerRouteMap(routeMap.routes);
+ * ```
+ */
+export function registerRouteMap(map: Record<string, string>): void {
+  // Always merge with existing map (don't replace)
+  globalRouteMap = { ...globalRouteMap, ...map };
+}
+
+/**
+ * Get the globally registered route map
+ *
+ * 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
+ */
+export function getGlobalRouteMap(): Record<string, string> {
+  // Cached manifest is complete (includes lazy routes), so prefer it
+  if (cachedManifest) {
+    return cachedManifest;
+  }
+  return globalRouteMap;
+}
+
+/**
+ * Set the cached manifest (for runtime cache integration)
+ *
+ * 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.
+ *
+ * @param manifest - The complete route manifest to cache
+ */
+export function setCachedManifest(manifest: Record<string, string>): void {
+  cachedManifest = manifest;
+}
+
+/**
+ * Check if a cached manifest is loaded
+ *
+ * @returns true if a complete manifest is available
+ */
+export function hasCachedManifest(): boolean {
+  return cachedManifest !== null;
+}
+
+/**
+ * Clear the cached manifest (for testing)
+ */
+export function clearCachedManifest(): void {
+  cachedManifest = null;
+}
+
+/**
+ * Set pre-computed route entries from build-time data.
+ *
+ * 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.
+ *
+ * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
+ */
+export function setPrecomputedEntries(
+  entries: Array<{ staticPrefix: string; routes: Record<string, string> }> | null,
+): void {
+  cachedPrecomputedEntries = entries;
+}
+
+/**
+ * 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;
+}
+
+// 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;
+}

package/src/route-types.ts

@@ -0,0 +1,220 @@
+/**
+ * Type definitions for route system items
+ * These are extracted separately to avoid circular dependencies
+ * and to prevent bundling server-only code in client bundles
+ */
+
+/**
+ * Branded return types for route helpers
+ */
+export declare const LayoutBrand: unique symbol;
+export declare const RouteBrand: unique symbol;
+export declare const ParallelBrand: unique symbol;
+export declare const InterceptBrand: unique symbol;
+export declare const MiddlewareBrand: unique symbol;
+export declare const RevalidateBrand: unique symbol;
+export declare const LoaderBrand: unique symbol;
+export declare const LoadingBrand: unique symbol;
+export declare const ErrorBoundaryBrand: unique symbol;
+export declare const NotFoundBoundaryBrand: unique symbol;
+export declare const WhenBrand: unique symbol;
+export declare const CacheBrand: unique symbol;
+export declare const IncludeBrand: unique symbol;
+export declare const UrlPatternsBrand: unique symbol;
+
+export type LayoutItem = {
+  name: string;
+  type: "layout";
+  uses?: AllUseItems[];
+  [LayoutBrand]: void;
+};
+
+/**
+ * Typed layout item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedLayoutItem<
+  TChildRoutes extends Record<string, string> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = LayoutItem & {
+  readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
+};
+export type RouteItem = {
+  name: string;
+  type: "route";
+  uses?: AllUseItems[];
+  [RouteBrand]: void;
+};
+
+/**
+ * Typed route item that carries route name and pattern as phantom types
+ * Used for type inference in urls() API
+ */
+export type TypedRouteItem<
+  TName extends string = string,
+  TPattern extends string = string,
+  TData = unknown,
+> = RouteItem & {
+  readonly __name?: TName;
+  readonly __pattern?: TPattern;
+  readonly __data?: TData;
+};
+export type ParallelItem = {
+  name: string;
+  type: "parallel";
+  uses?: ParallelUseItem[];
+  [ParallelBrand]: void;
+};
+export type InterceptItem = {
+  name: string;
+  type: "intercept";
+  uses?: InterceptUseItem[];
+  [InterceptBrand]: void;
+};
+export type LoaderItem = {
+  name: string;
+  type: "loader";
+  uses?: LoaderUseItem[];
+  [LoaderBrand]: void;
+};
+export type MiddlewareItem = {
+  name: string;
+  type: "middleware";
+  uses?: AllUseItems[];
+  [MiddlewareBrand]: void;
+};
+export type RevalidateItem = {
+  name: string;
+  type: "revalidate";
+  uses?: AllUseItems[];
+  [RevalidateBrand]: void;
+};
+export type LoadingItem = {
+  name: string;
+  type: "loading";
+  [LoadingBrand]: void;
+};
+export type ErrorBoundaryItem = {
+  name: string;
+  type: "errorBoundary";
+  uses?: AllUseItems[];
+  [ErrorBoundaryBrand]: void;
+};
+export type NotFoundBoundaryItem = {
+  name: string;
+  type: "notFoundBoundary";
+  uses?: AllUseItems[];
+  [NotFoundBoundaryBrand]: void;
+};
+export type WhenItem = {
+  name: string;
+  type: "when";
+  [WhenBrand]: void;
+};
+export type CacheItem = {
+  name: string;
+  type: "cache";
+  uses?: AllUseItems[];
+  [CacheBrand]: void;
+};
+
+/**
+ * Typed cache item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedCacheItem<
+  TChildRoutes extends Record<string, string> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = CacheItem & {
+  readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
+};
+
+/**
+ * Include item for URL pattern composition (used by urls() API)
+ */
+export type IncludeItem = {
+  type: "include";
+  name: string;
+  prefix: string;
+  patterns: unknown; // UrlPatterns - avoid circular ref
+  options?: { name?: string; lazy?: boolean };
+  /** Whether this include should be lazily evaluated on first request */
+  lazy?: boolean;
+  /** Captured context for deferred lazy evaluation */
+  _lazyContext?: {
+    urlPrefix: string;
+    namePrefix: string | undefined;
+    parent: unknown; // EntryData - avoid circular import
+  };
+  [IncludeBrand]: void;
+};
+
+/**
+ * Typed include item that carries nested routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedIncludeItem<
+  TRoutes extends Record<string, string> = Record<string, string>,
+  TNamePrefix extends string = string,
+  TUrlPrefix extends string = string,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
+> = IncludeItem & {
+  readonly __routes?: TRoutes;
+  readonly __namePrefix?: TNamePrefix;
+  readonly __urlPrefix?: TUrlPrefix;
+  readonly __responses?: TResponses;
+};
+
+/**
+ * Union types for use() callbacks
+ */
+export type AllUseItems =
+  | LayoutItem
+  | RouteItem
+  | MiddlewareItem
+  | RevalidateItem
+  | ParallelItem
+  | InterceptItem
+  | LoaderItem
+  | LoadingItem
+  | ErrorBoundaryItem
+  | NotFoundBoundaryItem
+  | CacheItem
+  | IncludeItem;
+
+/** Items that can be used inside a layout callback */
+export type LayoutUseItem = AllUseItems;
+export type RouteUseItem =
+  | LayoutItem
+  | ParallelItem
+  | InterceptItem
+  | MiddlewareItem
+  | RevalidateItem
+  | LoaderItem
+  | LoadingItem
+  | ErrorBoundaryItem
+  | NotFoundBoundaryItem
+  | CacheItem;
+/** Items that can be used inside a response route (path.json(), etc.) */
+export type ResponseRouteUseItem =
+  | MiddlewareItem
+  | CacheItem;
+export type ParallelUseItem =
+  | RevalidateItem
+  | LoaderItem
+  | LoadingItem
+  | ErrorBoundaryItem
+  | NotFoundBoundaryItem;
+export type InterceptUseItem =
+  | MiddlewareItem
+  | RevalidateItem
+  | LoaderItem
+  | LoadingItem
+  | ErrorBoundaryItem
+  | NotFoundBoundaryItem
+  | LayoutItem
+  | RouteItem
+  | WhenItem;
+export type LoaderUseItem = RevalidateItem | CacheItem;