@rangojs/router 0.0.0-experimental.8ff1c5d → 0.0.0-experimental.90

package/src/href.ts

@@ -1,255 +0,0 @@
-import type { ExtractParams } from "./types.js";
-
-/**
- * Sanitize prefix string by removing leading slash
- * "/shop" -> "shop", "blog" -> "blog", "" -> ""
- */
-export type SanitizePrefix<T extends string> = T extends `/${infer P}` ? P : T;
-
-/**
- * Helper type to merge multiple route definitions into a single accumulated type.
- * Note: When using createRouter, types accumulate automatically through the
- * builder chain, so this type is typically not needed.
- *
- * @example
- * ```typescript
- * // Manual type merging (rarely needed):
- * type AppRoutes = MergeRoutes<[
- *   typeof homeRoutes,
- *   PrefixRoutePatterns<typeof blogRoutes, "/blog">,
- * ]>;
- *
- * // Preferred: Let router accumulate types automatically
- * const router = createRouter<AppEnv>()
- *   .routes(homeRoutes).map(...)
- *   .routes("/blog", blogRoutes).map(...);
- * type AppRoutes = typeof router.routeMap;
- * ```
- */
-export type MergeRoutes<T extends unknown[]> = T extends [
-  infer First,
-  ...infer Rest
-]
-  ? First & MergeRoutes<Rest>
-  : {};
-
-/**
- * Add key prefix to all entries in a route map
- * { "cart": "/cart" } with prefix "shop" -> { "shop.cart": "/shop/cart" }
- */
-export type PrefixRouteKeys<
-  T,
-  Prefix extends string
-> = Prefix extends ""
-  ? T
-  : { [K in keyof T as `${Prefix}.${K & string}`]: T[K] };
-
-/**
- * Add path prefix to all patterns in a route map
- * { "cart": "/cart" } with prefix "/shop" -> { "cart": "/shop/cart" }
- */
-export type PrefixRoutePatterns<
-  T,
-  PathPrefix extends string
-> = {
-  [K in keyof T]: PathPrefix extends "" | "/"
-    ? T[K]
-    : T[K] extends "/"
-      ? PathPrefix
-      : T[K] extends string
-        ? `${PathPrefix}${T[K]}`
-        : T[K];
-};
-
-/**
- * Combined: prefix both keys and patterns
- * Used for module augmentation registration
- *
- * @example
- * ```typescript
- * // Given shopRoutes = { "index": "/", "cart": "/cart", "products.detail": "/product/:slug" }
- * // PrefixedRoutes<typeof shopRoutes, "shop"> produces:
- * // { "shop.index": "/shop", "shop.cart": "/shop/cart", "shop.products.detail": "/shop/product/:slug" }
- * ```
- */
-export type PrefixedRoutes<
-  T,
-  KeyPrefix extends string,
-  PathPrefix extends string = KeyPrefix extends "" ? "" : `/${KeyPrefix}`
-> = PrefixRouteKeys<PrefixRoutePatterns<T, PathPrefix>, KeyPrefix>;
-
-/**
- * Helper to safely extract route patterns from a routes object
- * Handles both Record<string, string> and interface types (like RegisteredRoutes)
- */
-type RoutePatternFor<TRoutes, TName extends keyof TRoutes> =
-  TRoutes[TName] extends string ? TRoutes[TName] : string;
-
-/**
- * Extract params type for a route
- */
-export type ParamsFor<
-  TRoutes,
-  TName extends keyof TRoutes
-> = ExtractParams<RoutePatternFor<TRoutes, TName>>;
-
-/**
- * Check if an object type has any keys
- */
-type IsEmptyObject<T> = keyof T extends never ? true : false;
-
-/**
- * Type-safe href function signature
- *
- * Validates route names and params at compile time.
- * Use route names instead of raw paths for full type safety.
- *
- * @example
- * ```typescript
- * href("cart")                           // ✓ Validates route exists
- * href("product.detail", { id: "123" })  // ✓ Validates route + params
- * ```
- */
-export type HrefFunction<TRoutes> = {
-  /**
-   * Route without params - validates route name exists
-   */
-  <TName extends keyof TRoutes & string>(
-    name: IsEmptyObject<ExtractParams<RoutePatternFor<TRoutes, TName>>> extends true ? TName : never
-  ): string;
-
-  /**
-   * Route with params - validates both route name and params
-   */
-  <TName extends keyof TRoutes & string>(
-    name: TName,
-    params: ExtractParams<RoutePatternFor<TRoutes, TName>>
-  ): string;
-};
-
-/**
- * Type-safe scoped href function signature for use with scopedHref<typeof patterns>()
- *
- * **Recommended: Use route names for type safety.**
- * Route names validate both the route exists and params are correct.
- * Path-based URLs (`/...`) are an escape hatch with no validation.
- *
- * @example
- * ```typescript
- * // RECOMMENDED: Use route names for type safety
- * href("blog.post", { slug: "hello" })  // ✓ Validates route + params
- * href("shop.cart")                      // ✓ Validates route exists
- *
- * // ESCAPE HATCH: Path-based URLs (no validation)
- * href("/about")                         // ⚠ No type checking
- * href("/typo/in/path")                  // ⚠ Won't catch errors
- * ```
- */
-export type ScopedHrefFunction<TLocalRoutes> = {
-  /**
-   * Route without params - validates route name exists
-   * @recommended Use this for type-safe URL generation
-   */
-  <TName extends keyof TLocalRoutes & string>(
-    name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? TName : never
-  ): string;
-
-  /**
-   * Route with params - validates both route name and params
-   * @recommended Use this for type-safe URL generation with parameters
-   */
-  <TName extends keyof TLocalRoutes & string>(
-    name: TName,
-    params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
-  ): string;
-
-  /**
-   * Absolute route name (contains dot) - global lookup
-   * Use for cross-module navigation: "shop.cart", "blog.post"
-   */
-  (name: `${string}.${string}`, params?: Record<string, string>): string;
-
-  /**
-   * Path-based URL - ESCAPE HATCH, no type validation
-   * Prefer route names for type safety. Only use paths when necessary.
-   */
-  (name: `/${string}`, params?: Record<string, string>): string;
-};
-
-/**
- * Extract local routes type from UrlPatterns
- * Used with scopedHref() to get the routes type from patterns
- */
-export type ExtractLocalRoutes<TPatterns> =
-  TPatterns extends { readonly _routes?: infer TRoutes } ? TRoutes : Record<string, string>;
-
-/**
- * Get a locally-typed href function from ctx.href for composable modules.
- *
- * This is a type-only cast - ctx.href already resolves local names at runtime
- * based on the current route prefix. This helper just provides type safety
- * for local route names within a url module.
- *
- * @param href - The ctx.href function from HandlerContext
- * @returns The same href function, but typed for local routes
- *
- * @example
- * ```typescript
- * // urls/blog.tsx
- * export const blogPatterns = urls(({ path }) => [
- *   path("/", (ctx) => {
- *     // Get locally-typed href for this module's routes
- *     const href = scopedHref<typeof blogPatterns>(ctx.href);
- *
- *     href("index");              // ✓ Type-safe local route
- *     href("post", { slug: "x" }); // ✓ Type-safe with params
- *     href("shop.cart");          // ✓ Cross-module (absolute name)
- *
- *     return <BlogIndex />;
- *   }, { name: "index" }),
- *
- *   path("/:slug", BlogPost, { name: "post" }),
- * ]);
- * ```
- */
-export function scopedHref<TPatterns>(
-  href: (name: string, params?: Record<string, string>) => string
-): ScopedHrefFunction<ExtractLocalRoutes<TPatterns>> {
-  return href as ScopedHrefFunction<ExtractLocalRoutes<TPatterns>>;
-}
-
-/**
- * Create a type-safe href function for URL generation
- *
- * @param routeMap - Flattened route map with all registered routes
- * @returns Type-safe href function
- *
- * @example
- * ```typescript
- * // 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>>(
-  routeMap: TRoutes
-): HrefFunction<TRoutes & Record<string, string>> {
-  return ((name: string, params?: Record<string, string>) => {
-    const pattern = routeMap[name];
-    if (!pattern) {
-      throw new Error(`Unknown route: ${name}`);
-    }
-
-    if (!params) return pattern;
-
-    // Replace :param placeholders with actual values
-    return pattern.replace(/:([^/]+)/g, (_, key) => {
-      const value = params[key];
-      if (value === undefined) {
-        throw new Error(`Missing param "${key}" for route "${name}"`);
-      }
-      return encodeURIComponent(value);
-    });
-  }) as HrefFunction<TRoutes>;
-}

package/src/server/route-manifest-cache.ts

@@ -1,173 +0,0 @@
-/**
- * Route Manifest Cache
- *
- * Three-tier caching strategy for route manifest data:
- * 1. In-memory (same isolate) - instant
- * 2. SegmentCacheStore (caches.default on Cloudflare) - ~1-2ms
- * 3. Generate on-demand (cache miss) - ~98ms
- *
- * Benefits:
- * - Removes 725KB bundled manifest from worker code
- * - Typical cold start: 0-2ms (cache hit)
- * - Worst case: ~98ms (first request per colo)
- */
-
-import type { SegmentCacheStore, CachedEntryData } from "../cache/types.js";
-import type { GeneratedManifest } from "../build/generate-manifest.js";
-import { setCachedManifest, hasCachedManifest } from "../route-map-builder.js";
-
-/**
- * Cached route data structure
- */
-interface CachedRouteData {
-  /** Route name → pattern mapping for href() */
-  routeManifest: Record<string, string>;
-  /** Version string for cache invalidation */
-  version: string;
-}
-
-// ============================================================================
-// Tier 1: In-memory singleton (same isolate - instant)
-// ============================================================================
-
-let memoryManifest: CachedRouteData | null = null;
-
-/**
- * Options for getRouteManifestData
- */
-export interface GetRouteManifestOptions {
-  /** Cache store implementation (e.g., CFCacheStore). If omitted, memory-only caching is used. */
-  store?: SegmentCacheStore;
-  /** Optional function to schedule non-blocking cache write (e.g., ctx.waitUntil) */
-  waitUntil?: (promise: Promise<void>) => void;
-}
-
-/**
- * Get route manifest data with caching:
- * 1. In-memory (same isolate) - instant
- * 2. SegmentCacheStore (if provided, e.g., CFCacheStore on Cloudflare) - ~1-2ms
- * 3. Generate on-demand (cache miss) - ~98ms
- *
- * When no store is provided, only in-memory caching is used (memory-only mode).
- * This is suitable for development or when external cache is not available.
- *
- * @param generateFn - Function to generate manifest on cache miss
- * @param version - Version string for cache invalidation
- * @param options - Optional cache store and waitUntil function
- * @returns Cached or freshly generated route data
- */
-export async function getRouteManifestData(
-  generateFn: () => GeneratedManifest,
-  version: string,
-  options?: GetRouteManifestOptions
-): Promise<CachedRouteData> {
-  const { store, waitUntil } = options ?? {};
-  const cacheKey = `route-manifest:${version}`;
-
-  const startTime = performance.now();
-
-  // 1. In-memory check (same isolate) - instant
-  if (memoryManifest?.version === version) {
-    console.log("[route-manifest] HIT memory cache (same isolate)");
-    return memoryManifest;
-  }
-
-  // 2. Cache store check (if store provided) - ~1-2ms
-  if (store) {
-    try {
-      const cached = await store.get(cacheKey);
-      if (cached?.data) {
-        // Extract manifest from the CachedEntryData wrapper
-        const manifest = (cached.data as unknown as { manifest: CachedRouteData }).manifest;
-        if (manifest?.version === version) {
-          memoryManifest = manifest;
-          setCachedManifest(memoryManifest.routeManifest);
-          const duration = (performance.now() - startTime).toFixed(2);
-          console.log(`[route-manifest] HIT edge cache (${duration}ms, ${Object.keys(manifest.routeManifest).length} routes)`);
-          return memoryManifest;
-        }
-      }
-    } catch (error) {
-      // Cache miss or error - fall through to generation
-      console.warn("[route-manifest] Edge cache read failed:", error);
-    }
-  }
-
-  // 3. Generate on cache miss - ~98ms
-  const generated = generateFn();
-  memoryManifest = {
-    routeManifest: generated.routeManifest,
-    version,
-  };
-  // Make available to getGlobalRouteMap() for href()
-  setCachedManifest(memoryManifest.routeManifest);
-  const duration = (performance.now() - startTime).toFixed(2);
-  console.log(`[route-manifest] MISS - generated fresh (${duration}ms, ${Object.keys(generated.routeManifest).length} routes)`);
-
-  // Store in cache for other isolates (only if store provided)
-  // OFF RENDERING PATH via waitUntil
-  if (store) {
-    console.log("[route-manifest] Writing to edge cache (via waitUntil)...");
-    const cachePromise = (async () => {
-      try {
-        // Wrap in CachedEntryData format expected by SegmentCacheStore
-        const data: CachedEntryData = {
-          segments: [],
-          handles: {},
-          expiresAt: Date.now() + 31536000 * 1000, // 1 year
-        };
-        // Store manifest in a custom field
-        (data as unknown as { manifest: CachedRouteData }).manifest = memoryManifest!;
-        await store.set(cacheKey, data, 31536000); // 1 year TTL
-        console.log("[route-manifest] Edge cache write complete");
-      } catch (error) {
-        console.warn("[route-manifest] Edge cache write failed:", error);
-      }
-    })();
-
-    if (waitUntil) {
-      // Non-blocking: cache write happens after response is sent
-      waitUntil(cachePromise);
-    } else {
-      // Fallback: blocking write (dev mode or no waitUntil available)
-      await cachePromise;
-    }
-  }
-
-  return memoryManifest;
-}
-
-/**
- * Sync access to in-memory manifest (for href())
- * Returns null if not yet loaded
- *
- * @returns The route manifest or null if not loaded
- */
-export function getRouteManifestSync(): Record<string, string> | null {
-  return memoryManifest?.routeManifest ?? null;
-}
-
-/**
- * Clear in-memory cache (for testing)
- */
-export function clearRouteManifestCache(): void {
-  memoryManifest = null;
-}
-
-/**
- * Check if manifest is loaded in memory
- *
- * @returns true if manifest is available synchronously
- */
-export function isManifestLoaded(): boolean {
-  return memoryManifest !== null;
-}
-
-/**
- * Get the current cached version (for debugging)
- *
- * @returns The version string or null if not loaded
- */
-export function getManifestVersion(): string | null {
-  return memoryManifest?.version ?? null;
-}

package/src/vite/expose-handle-id.ts

@@ -1,209 +0,0 @@
-import type { Plugin, ResolvedConfig } from "vite";
-import MagicString from "magic-string";
-import path from "node:path";
-import crypto from "node:crypto";
-
-/**
- * Normalize path to forward slashes
- */
-function normalizePath(p: string): string {
-  return p.split(path.sep).join("/");
-}
-
-/**
- * Generate a short hash for a handle ID
- * Uses first 8 chars of SHA-256 hash for uniqueness while keeping IDs short
- * Appends export name for easier debugging: "abc123#Breadcrumbs"
- */
-function hashHandleId(filePath: string, exportName: string): string {
-  const input = `${filePath}#${exportName}`;
-  const hash = crypto.createHash("sha256").update(input).digest("hex");
-  return `${hash.slice(0, 8)}#${exportName}`;
-}
-
-/**
- * Check if file imports createHandle from rsc-router
- */
-function hasCreateHandleImport(code: string): boolean {
-  // Match: import { createHandle } from "@rangojs/router" or "@rangojs/router/..."
-  const pattern =
-    /import\s*\{[^}]*\bcreateHandle\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/[^"']+)?["']/;
-  return pattern.test(code);
-}
-
-/**
- * Analyze createHandle arguments to determine injection strategy
- * Returns: { hasArgs: boolean, firstArgIsString: boolean, firstArgIsFunction: boolean }
- */
-function analyzeCreateHandleArgs(
-  code: string,
-  startPos: number,
-  endPos: number
-): { hasArgs: boolean; firstArgIsString: boolean; firstArgIsFunction: boolean } {
-  // Extract the content between parentheses
-  const content = code.slice(startPos, endPos).trim();
-
-  if (!content) {
-    return { hasArgs: false, firstArgIsString: false, firstArgIsFunction: false };
-  }
-
-  // Check if first arg starts with a quote (string literal)
-  const firstArgIsString = /^["']/.test(content);
-
-  // Check if first arg starts with ( for arrow function or function keyword
-  const firstArgIsFunction =
-    content.startsWith("(") ||
-    content.startsWith("function") ||
-    // Check for identifier that could be a collect function reference
-    /^[a-zA-Z_$][a-zA-Z0-9_$]*\s*(?:,|$)/.test(content);
-
-  return { hasArgs: true, firstArgIsString, firstArgIsFunction };
-}
-
-/**
- * Transform export const X = createHandle(...) patterns to inject $$id
- *
- * Handles these cases:
- * 1. createHandle() - no args -> inject (undefined, "id")
- * 2. createHandle("name") - string name -> inject (, "id") after existing arg
- * 3. createHandle(collectFn) - collect function -> inject (collectFn, "id")
- * 4. createHandle("name", collectFn) - both -> inject (, "id") after existing args
- */
-function transformHandleExports(
-  code: string,
-  filePath: string,
-  sourceId?: string,
-  isBuild: boolean = false
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  // Quick bail-out
-  if (!code.includes("createHandle")) {
-    return null;
-  }
-
-  // Must have direct import from rsc-router
-  if (!hasCreateHandleImport(code)) {
-    return null;
-  }
-
-  // Match: export const X = createHandle<...>(
-  // Captures the export name (X)
-  const pattern = /export\s+const\s+(\w+)\s*=\s*createHandle\s*(?:<[^>]*>)?\s*\(/g;
-
-  const s = new MagicString(code);
-  let hasChanges = false;
-  let match: RegExpExecArray | null;
-
-  while ((match = pattern.exec(code)) !== null) {
-    const exportName = match[1];
-    const matchEnd = match.index + match[0].length;
-
-    // Find the end of the createHandle(...) call
-    let parenDepth = 1;
-    let i = matchEnd;
-    while (i < code.length && parenDepth > 0) {
-      if (code[i] === "(") parenDepth++;
-      if (code[i] === ")") parenDepth--;
-      i++;
-    }
-
-    // i now points just after the closing )
-    const closeParenPos = i - 1;
-
-    // Analyze what arguments exist
-    const args = analyzeCreateHandleArgs(code, matchEnd, closeParenPos);
-
-    // Find the semicolon or end of statement
-    let statementEnd = i;
-    while (statementEnd < code.length && /\s/.test(code[statementEnd])) {
-      statementEnd++;
-    }
-    if (code[statementEnd] === ";") {
-      statementEnd++;
-    }
-
-    // Generate ID: hashed in production, readable in dev
-    const handleId = isBuild
-      ? hashHandleId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    // Inject $$id as the last parameter
-    let paramInjection: string;
-    if (!args.hasArgs) {
-      // No args: createHandle() -> createHandle(undefined, "id")
-      paramInjection = `undefined, "${handleId}"`;
-    } else {
-      // Has args: createHandle(x) -> createHandle(x, "id")
-      paramInjection = `, "${handleId}"`;
-    }
-    s.appendLeft(closeParenPos, paramInjection);
-
-    // Also set $$id property for external access
-    const propInjection = `\n${exportName}.$$id = "${handleId}";`;
-    s.appendRight(statementEnd, propInjection);
-    hasChanges = true;
-  }
-
-  if (!hasChanges) {
-    return null;
-  }
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({ source: sourceId, includeContent: true }),
-  };
-}
-
-/**
- * Vite plugin that exposes $$id on createHandle calls.
- *
- * When users create handles with createHandle(), this plugin:
- * 1. Injects a $$id as the last parameter (used as the handle name)
- * 2. Sets $$id property on the exported constant for external access
- *
- * This allows handles to be created without explicit names:
- * - Before: export const Breadcrumbs = createHandle<Item>("breadcrumbs")
- * - After:  export const Breadcrumbs = createHandle<Item>()
- *
- * The name is auto-generated from file path + export name.
- *
- * Requirements:
- * - Must use direct import: import { createHandle } from "@rangojs/router"
- * - Must use named export: export const MyHandle = createHandle(...)
- */
-export function exposeHandleId(): Plugin {
-  let config: ResolvedConfig;
-  let isBuild = false;
-
-  return {
-    name: "@rangojs/router:expose-handle-id",
-    enforce: "post",
-
-    configResolved(resolvedConfig) {
-      config = resolvedConfig;
-      isBuild = config.command === "build";
-    },
-
-    transform(code, id) {
-      // Skip node_modules
-      if (id.includes("/node_modules/")) {
-        return;
-      }
-
-      // Quick bail-out
-      if (!code.includes("createHandle")) {
-        return;
-      }
-
-      // Must have direct import from rsc-router
-      if (!hasCreateHandleImport(code)) {
-        return;
-      }
-
-      // Get relative path for the ID
-      const relativePath = normalizePath(path.relative(config.root, id));
-
-      // Transform: inject $$id
-      return transformHandleExports(code, relativePath, id, isBuild);
-    },
-  };
-}