@rangojs/router 0.0.0-experimental.2

package/src/route-map-builder.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 "./href.js";
+
+/**
+ * Route map builder interface
+ *
+ * Accumulates route types through the builder chain for type-safe href.
+ */
+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 when routes.ts is imported
+let globalRouteMap: Record<string, string> = {};
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const routeMap = createRouteMap()
+ *   .add(homeRoutes)
+ *   .add(blogRoutes, "blog");
+ *
+ * registerRouteMap(routeMap.routes);
+ * ```
+ */
+export function registerRouteMap(map: Record<string, string>): void {
+  globalRouteMap = map;
+}
+
+/**
+ * Get the globally registered route map
+ *
+ * Used internally by href to resolve route names to URLs at runtime.
+ *
+ * @returns The registered route map
+ */
+export function getGlobalRouteMap(): Record<string, string> {
+  return globalRouteMap;
+}

package/src/route-types.ts

@@ -0,0 +1,198 @@
+/**
+ * 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>
+> = LayoutItem & {
+  readonly __childRoutes?: TChildRoutes;
+};
+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
+> = RouteItem & {
+  readonly __name?: TName;
+  readonly __pattern?: TPattern;
+};
+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>
+> = CacheItem & {
+  readonly __childRoutes?: TChildRoutes;
+};
+
+/**
+ * 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 };
+  [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
+> = IncludeItem & {
+  readonly __routes?: TRoutes;
+  readonly __namePrefix?: TNamePrefix;
+};
+
+/**
+ * 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;
+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;

package/src/route-utils.ts

@@ -0,0 +1,89 @@
+/**
+ * Client-safe route utilities
+ *
+ * These utilities can be imported in client code without pulling in server dependencies.
+ */
+
+import type { RouteDefinition, RouteConfig, ResolvedRouteMap, TrailingSlashMode } from "./types.js";
+
+/**
+ * Check if a value is a RouteConfig object
+ */
+function isRouteConfig(value: unknown): value is RouteConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "path" in value &&
+    typeof (value as RouteConfig).path === "string"
+  );
+}
+
+/**
+ * Flatten nested route definitions
+ */
+function flattenRoutes(
+  routes: RouteDefinition,
+  prefix: string,
+  trailingSlashConfig: Record<string, TrailingSlashMode>
+): Record<string, string> {
+  const flattened: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(routes)) {
+    const fullKey = prefix + key;
+    if (typeof value === "string") {
+      // Direct route pattern - include prefix
+      flattened[fullKey] = value;
+    } else if (isRouteConfig(value)) {
+      // Route config object - extract path and trailing slash config
+      flattened[fullKey] = value.path;
+      if (value.trailingSlash) {
+        trailingSlashConfig[fullKey] = value.trailingSlash;
+      }
+    } else {
+      // Nested routes - flatten recursively
+      const nested = flattenRoutes(value, `${fullKey}.`, trailingSlashConfig);
+      Object.assign(flattened, nested);
+    }
+  }
+
+  return flattened;
+}
+
+/**
+ * Define routes with type safety (client-safe version)
+ *
+ * This is a client-safe version of the route function that can be imported
+ * in client code without pulling in server dependencies.
+ *
+ * @param input - Route definition object
+ * @returns Flattened route map with full type information
+ *
+ * @example
+ * ```typescript
+ * const shopRoutes = route({
+ *   index: "/",
+ *   cart: "/cart",
+ *   products: {
+ *     detail: "/product/:slug",
+ *     category: "/products/:category",
+ *   },
+ * });
+ * // Result: { index: "/", cart: "/cart", "products.detail": "/product/:slug", "products.category": "/products/:category" }
+ * ```
+ */
+export function route<const T extends RouteDefinition>(
+  input: T
+): ResolvedRouteMap<T> {
+  const trailingSlash: Record<string, TrailingSlashMode> = {};
+  const routes = flattenRoutes(input as RouteDefinition, "", trailingSlash);
+
+  const result = routes as ResolvedRouteMap<T> & { __trailingSlash?: Record<string, TrailingSlashMode> };
+  if (Object.keys(trailingSlash).length > 0) {
+    Object.defineProperty(result, "__trailingSlash", {
+      value: trailingSlash,
+      enumerable: false,
+      writable: false,
+    });
+  }
+  return result;
+}

package/src/router/__tests__/match-context.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import { createPipelineState } from "../match-context";
+
+describe("match-context", () => {
+  describe("createPipelineState()", () => {
+    it("should create initial state with default values", () => {
+      const state = createPipelineState();
+
+      expect(state.cacheHit).toBe(false);
+      expect(state.segments).toEqual([]);
+      expect(state.matchedIds).toEqual([]);
+      expect(state.interceptSegments).toEqual([]);
+      expect(state.slots).toEqual({});
+    });
+
+    it("should create state without cached data by default", () => {
+      const state = createPipelineState();
+
+      expect(state.cachedSegments).toBeUndefined();
+      expect(state.cachedMatchedIds).toBeUndefined();
+      expect(state.shouldRevalidate).toBeUndefined();
+    });
+
+    it("should allow mutation of state properties", () => {
+      const state = createPipelineState();
+
+      state.cacheHit = true;
+      state.segments.push({
+        id: "seg1",
+        type: "route",
+        component: null,
+        params: {},
+      });
+      state.matchedIds.push("seg1");
+      state.slots["@modal"] = { active: true, segments: [] };
+
+      expect(state.cacheHit).toBe(true);
+      expect(state.segments).toHaveLength(1);
+      expect(state.matchedIds).toContain("seg1");
+      expect(state.slots["@modal"]).toBeDefined();
+    });
+
+    it("should create independent state instances", () => {
+      const state1 = createPipelineState();
+      const state2 = createPipelineState();
+
+      state1.cacheHit = true;
+      state1.segments.push({
+        id: "seg1",
+        type: "route",
+        component: null,
+        params: {},
+      });
+
+      expect(state2.cacheHit).toBe(false);
+      expect(state2.segments).toHaveLength(0);
+    });
+
+    it("should support setting cache-related properties", () => {
+      const state = createPipelineState();
+
+      state.cacheHit = true;
+      state.shouldRevalidate = true;
+      state.cachedSegments = [
+        { id: "cached1", type: "route", component: "CachedComponent", params: {} },
+      ];
+      state.cachedMatchedIds = ["cached1"];
+
+      expect(state.cacheHit).toBe(true);
+      expect(state.shouldRevalidate).toBe(true);
+      expect(state.cachedSegments).toHaveLength(1);
+      expect(state.cachedMatchedIds).toContain("cached1");
+    });
+
+    it("should support intercept segments", () => {
+      const state = createPipelineState();
+
+      state.interceptSegments.push({
+        id: "modal-seg",
+        type: "route",
+        component: "ModalComponent",
+        params: {},
+      });
+
+      expect(state.interceptSegments).toHaveLength(1);
+      expect(state.interceptSegments[0].id).toBe("modal-seg");
+    });
+
+    it("should support slots with nested segments", () => {
+      const state = createPipelineState();
+
+      state.slots["@modal"] = {
+        active: true,
+        segments: [
+          { id: "modal1", type: "route", component: "Modal1", params: {} },
+          { id: "modal2", type: "route", component: "Modal2", params: {} },
+        ],
+      };
+
+      expect(state.slots["@modal"].active).toBe(true);
+      expect(state.slots["@modal"].segments).toHaveLength(2);
+    });
+  });
+});