@rangojs/router 0.0.0-experimental.0f44aca1

package/src/route-definition/redirect.ts

@@ -0,0 +1,93 @@
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import {
+  requireRequestContext,
+  getRequestContext,
+} from "../server/request-context.js";
+
+/**
+ * Create a soft redirect Response for middleware short-circuit
+ *
+ * Returns a Response that signals a client-side navigation to the target URL.
+ * Unlike Response.redirect() which causes a full page reload, this redirect
+ * is handled by the router for SPA-style navigation.
+ *
+ * Supports an optional state parameter to carry location state through the
+ * redirect. On the target page, state can be read via useLocationState()
+ * (use { flash: true } in createLocationState for read-once flash messages).
+ *
+ * @param url - The URL to redirect to
+ * @param statusOrOptions - HTTP status code (default: 302) or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple redirect
+ * middleware((ctx, next) => {
+ *   if (!ctx.get('user')) {
+ *     return redirect('/login');
+ *   }
+ *   next();
+ * })
+ *
+ * // Redirect with state
+ * return redirect('/dashboard', {
+ *   state: [Flash({ text: "Item saved!" })],
+ * });
+ *
+ * // Redirect with custom status and state
+ * return redirect('/login', {
+ *   status: 303,
+ *   state: [Flash({ text: "Session expired" })],
+ * });
+ * ```
+ */
+export function redirect(url: string, status?: number): Response;
+export function redirect(
+  url: string,
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+  },
+): Response;
+export function redirect(
+  url: string,
+  statusOrOptions?:
+    | number
+    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
+): Response {
+  const status =
+    typeof statusOrOptions === "number"
+      ? statusOrOptions
+      : (statusOrOptions?.status ?? 302);
+  const state =
+    typeof statusOrOptions === "object" ? statusOrOptions?.state : undefined;
+
+  if (state) {
+    const ctx = requireRequestContext();
+    ctx.setLocationState(state);
+
+    if (process.env.NODE_ENV !== "production") {
+      const reqCtx = getRequestContext();
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.url.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.url.searchParams.has("_rsc_action")
+      ) {
+        console.warn(
+          `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
+            "Location state is only delivered during SPA navigations and will be lost on this request.",
+        );
+      }
+    }
+  }
+
+  return new Response(null, {
+    status,
+    headers: {
+      Location: url,
+      "X-RSC-Redirect": "soft",
+    },
+  });
+}

package/src/route-definition.ts

@@ -0,0 +1 @@
+export * from "./route-definition/index.js";

package/src/route-map-builder.ts

@@ -0,0 +1,275 @@
+/**
+ * Route manifest storage and retrieval.
+ *
+ * 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.
+ *
+ * See docs/manifests.md for the full data flow.
+ */
+
+// 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 routes into the global route map.
+ * Routes are merged with any existing registered routes.
+ * Called by createRouter() during module evaluation.
+ */
+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
+ * @internal
+ */
+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;
+}
+
+// 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.
+ *
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
+ */
+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> {
+  if (perRouterManifestMap.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.`,
+        );
+      }
+    }
+  }
+}

package/src/route-types.ts

@@ -0,0 +1,259 @@
+/**
+ * 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 TransitionBrand: 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, any> = 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,
+  TSearch = {},
+> = RouteItem & {
+  readonly __name?: TName;
+  readonly __pattern?: TPattern;
+  readonly __data?: TData;
+  readonly __search?: TSearch;
+};
+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;
+};
+export type TransitionItem = {
+  name: string;
+  type: "transition";
+  [TransitionBrand]: void;
+};
+
+/**
+ * Typed transition item that carries child routes as phantom type
+ * Used for type inference when transition() wraps child routes
+ */
+export type TypedTransitionItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = TransitionItem & {
+  readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
+};
+
+/**
+ * Typed cache item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedCacheItem<
+  TChildRoutes extends Record<string, any> = 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
+    /** Counter snapshot from pattern extraction for consistent shortCode indices */
+    counters?: Record<string, number>;
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<
+      string,
+      import("./cache/profile-registry.js").CacheProfile
+    >;
+    /** Root scope flag for dot-local reverse resolution */
+    rootScoped?: boolean;
+  };
+  [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, any> = 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
+  | TransitionItem
+  | 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
+  | TransitionItem;
+/** 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
+  | TransitionItem;
+export type InterceptUseItem =
+  | MiddlewareItem
+  | RevalidateItem
+  | LoaderItem
+  | LoadingItem
+  | ErrorBoundaryItem
+  | NotFoundBoundaryItem
+  | LayoutItem
+  | RouteItem
+  | WhenItem
+  | TransitionItem;
+export type LoaderUseItem = RevalidateItem | CacheItem;
+
+/**
+ * Allow composition factories in use() callbacks.
+ * Factories return T[], which placed inside a use() callback array
+ * creates nested arrays like (T | T[])[]. These are flattened at
+ * runtime via .flat(3).
+ */
+export type UseItems<T> = (T | readonly T[])[];