@rangojs/router 0.0.0-experimental.7 → 0.0.0-experimental.71

package/src/browser/request-controller.ts

@@ -1,164 +0,0 @@
-import type { RequestController, DisposableAbortController } from "./types.js";
-
-// Polyfill Symbol.dispose for Safari and older browsers
-if (typeof Symbol.dispose === "undefined") {
-  (Symbol as any).dispose = Symbol("Symbol.dispose");
-}
-
-/**
- * Create a request controller for managing concurrent abort controllers
- *
- * This utility helps manage concurrent navigation requests by providing
- * a way to abort all pending requests when a new navigation starts.
- *
- * @returns RequestController instance
- *
- * @example
- * ```typescript
- * const controller = createRequestController();
- *
- * // Start a new request
- * const abortController = controller.create();
- * fetch(url, { signal: abortController.signal });
- *
- * // Abort all pending requests (e.g., when starting new navigation)
- * controller.abortAll();
- *
- * // Clean up completed request
- * controller.remove(abortController);
- * ```
- */
-export function createRequestController(): RequestController {
-  // Navigation controllers - aborted on new navigation
-  // Using WeakRef to allow GC if controller is no longer referenced elsewhere
-  const controllers: WeakRef<AbortController>[] = [];
-  // Action controllers - NOT aborted by navigation, only by errors
-  const actionControllers: WeakRef<AbortController>[] = [];
-
-  /**
-   * Remove stale (garbage collected) refs from an array
-   */
-  function pruneStaleRefs(refs: WeakRef<AbortController>[]): void {
-    for (let i = refs.length - 1; i >= 0; i--) {
-      if (!refs[i].deref()) {
-        refs.splice(i, 1);
-      }
-    }
-  }
-
-  return {
-    /**
-     * Create a new abort controller and track it for navigation
-     *
-     * @returns A new AbortController
-     */
-    create(): AbortController {
-      const controller = new AbortController();
-      controllers.push(new WeakRef(controller));
-      console.log(
-        `[Browser] Created abort controller, total: ${controllers.length}`,
-      );
-      return controller;
-    },
-
-    /**
-     * Create a disposable abort controller for navigation use with `using` keyword
-     *
-     * The controller will be automatically removed from tracking when
-     * it goes out of scope, regardless of how the scope is exited.
-     *
-     * @returns A DisposableAbortController
-     *
-     * @example
-     * ```typescript
-     * async function handleNavigation() {
-     *   requestController.abortAll();
-     *   using { controller } = requestController.createDisposable();
-     *   // ... use controller.signal ...
-     *   // controller is automatically removed on scope exit
-     * }
-     * ```
-     */
-    createDisposable(): DisposableAbortController {
-      const controller = this.create();
-      return {
-        controller,
-        [Symbol.dispose]: () => {
-          this.remove(controller);
-        },
-      };
-    },
-
-    /**
-     * Create a disposable abort controller for actions
-     *
-     * Action controllers are NOT aborted by navigation - they complete
-     * independently. Only aborted by abortAllActions() on error.
-     *
-     * @returns A DisposableAbortController
-     */
-    createActionDisposable(): DisposableAbortController {
-      const controller = new AbortController();
-      const ref = new WeakRef(controller);
-      actionControllers.push(ref);
-      console.log(
-        `[Browser] Created action controller, total: ${actionControllers.length}`,
-      );
-      return {
-        controller,
-        [Symbol.dispose]: () => {
-          const index = actionControllers.indexOf(ref);
-          if (index !== -1) {
-            actionControllers.splice(index, 1);
-            console.log(
-              `[Browser] Removed action controller, remaining: ${actionControllers.length}`,
-            );
-          }
-        },
-      };
-    },
-
-    /**
-     * Abort all navigation controllers (NOT actions)
-     *
-     * Called when starting new navigation. Actions continue
-     * to complete in the background.
-     */
-    abortAll(): void {
-      controllers.forEach((ref) => ref.deref()?.abort());
-      controllers.length = 0;
-      console.log(`[Browser] Aborted all navigation controllers`);
-    },
-
-    /**
-     * Abort all action controllers
-     *
-     * Called when an action error occurs - prevents other actions
-     * from completing and overwriting the error UI.
-     */
-    abortAllActions(): void {
-      actionControllers.forEach((ref) => ref.deref()?.abort());
-      actionControllers.length = 0;
-      console.log(`[Browser] Aborted all action controllers`);
-    },
-
-    /**
-     * Remove a specific controller from tracking
-     *
-     * Call this when a request completes successfully.
-     *
-     * @param controller - The controller to remove
-     */
-    remove(controller: AbortController): void {
-      // Prune any stale refs while searching
-      pruneStaleRefs(controllers);
-      const index = controllers.findIndex((ref) => ref.deref() === controller);
-      if (index !== -1) {
-        controllers.splice(index, 1);
-        console.log(
-          `[Browser] Removed abort controller, remaining: ${controllers.length}`,
-        );
-      }
-    },
-  };
-}

package/src/cache/memory-store.ts

@@ -1,253 +0,0 @@
-/**
- * In-Memory Cache Store
- *
- * Simple implementation for development and testing.
- * Not suitable for production (no persistence, single-instance only).
- *
- * @internal This is reserved for future extensibility.
- * For segment caching, use MemorySegmentCacheStore instead.
- */
-
-import type {
-  CacheStore,
-  CacheEntry,
-  CacheValue,
-  CachePutOptions,
-  CacheMetadata,
-  CacheValueType,
-} from "./types.js";
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Default TTL when no explicit value is provided */
-const DEFAULT_TTL_SECONDS = 60;
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface StoredEntry {
-  /** Stored value (streams/responses converted to ArrayBuffer) */
-  value: ArrayBuffer | string | object;
-  metadata: CacheMetadata;
-}
-
-/**
- * In-memory cache store implementation
- */
-export class MemoryCacheStore implements CacheStore {
-  private cache = new Map<string, StoredEntry>();
-
-  async match<T = CacheValue>(key: string): Promise<CacheEntry<T> | undefined> {
-    const entry = this.cache.get(key);
-
-    if (!entry) {
-      return undefined;
-    }
-
-    // Check expiration
-    if (entry.metadata.expiresAt && Date.now() > entry.metadata.expiresAt) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    // Reconstruct value based on original type
-    const value = this.reconstructValue(entry);
-
-    return {
-      value: value as T,
-      metadata: entry.metadata,
-    };
-  }
-
-  async put<T extends CacheValue>(
-    key: string,
-    value: T,
-    options?: CachePutOptions
-  ): Promise<void> {
-    const ttl = options?.ttl ?? DEFAULT_TTL_SECONDS;
-    const expiresAt = Date.now() + ttl * 1000;
-
-    // Detect value type and convert for storage
-    const { storedValue, valueType, responseHeaders, responseStatus } =
-      await this.prepareForStorage(value);
-
-    const metadata: CacheMetadata = {
-      ...options?.metadata,
-      expiresAt,
-      valueType,
-      responseHeaders,
-      responseStatus,
-    };
-
-    this.cache.set(key, {
-      value: storedValue,
-      metadata,
-    });
-  }
-
-  async delete(key: string): Promise<boolean> {
-    return this.cache.delete(key);
-  }
-
-  /**
-   * Clear all entries (useful for testing)
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Get current cache size (useful for testing/debugging)
-   */
-  get size(): number {
-    return this.cache.size;
-  }
-
-  /**
-   * Manually purge expired entries
-   */
-  purgeExpired(): number {
-    const now = Date.now();
-    let purged = 0;
-
-    for (const [key, entry] of this.cache) {
-      if (entry.metadata.expiresAt && now > entry.metadata.expiresAt) {
-        this.cache.delete(key);
-        purged++;
-      }
-    }
-
-    return purged;
-  }
-
-  /**
-   * Prepare a value for storage
-   * Converts streams and responses to ArrayBuffer, detects type
-   */
-  private async prepareForStorage(value: CacheValue): Promise<{
-    storedValue: ArrayBuffer | string | object;
-    valueType: CacheValueType;
-    responseHeaders?: Record<string, string>;
-    responseStatus?: number;
-  }> {
-    // ReadableStream -> ArrayBuffer
-    if (value instanceof ReadableStream) {
-      return {
-        storedValue: await streamToArrayBuffer(value),
-        valueType: "stream",
-      };
-    }
-
-    // Response -> ArrayBuffer + headers/status
-    if (value instanceof Response) {
-      const headers: Record<string, string> = {};
-      value.headers.forEach((v, k) => {
-        headers[k] = v;
-      });
-
-      return {
-        storedValue: await value.clone().arrayBuffer(),
-        valueType: "response",
-        responseHeaders: headers,
-        responseStatus: value.status,
-      };
-    }
-
-    // ArrayBuffer -> store as-is
-    if (value instanceof ArrayBuffer) {
-      return {
-        storedValue: value,
-        valueType: "arraybuffer",
-      };
-    }
-
-    // String -> store as-is
-    if (typeof value === "string") {
-      return {
-        storedValue: value,
-        valueType: "string",
-      };
-    }
-
-    // Object -> store as-is (JSON-serializable)
-    return {
-      storedValue: value,
-      valueType: "object",
-    };
-  }
-
-  /**
-   * Reconstruct original value type from stored entry
-   */
-  private reconstructValue(entry: StoredEntry): CacheValue {
-    const { value, metadata } = entry;
-
-    switch (metadata.valueType) {
-      case "stream":
-        return arrayBufferToStream(value as ArrayBuffer);
-
-      case "response": {
-        const status = metadata.responseStatus ?? 200;
-        // Status codes 204 (No Content) and 304 (Not Modified) cannot have a body
-        const isNullBodyStatus = status === 204 || status === 304;
-        return new Response(isNullBodyStatus ? null : (value as ArrayBuffer), {
-          status,
-          headers: metadata.responseHeaders,
-        });
-      }
-
-      case "arraybuffer":
-      case "string":
-      case "object":
-      default:
-        return value as CacheValue;
-    }
-  }
-}
-
-/**
- * Convert a ReadableStream to ArrayBuffer.
- * @internal
- */
-async function streamToArrayBuffer(
-  stream: ReadableStream<Uint8Array>
-): Promise<ArrayBuffer> {
-  const chunks: Uint8Array[] = [];
-  const reader = stream.getReader();
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
-  }
-
-  // Concatenate chunks
-  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-
-  for (const chunk of chunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
-  }
-
-  return result.buffer;
-}
-
-/**
- * Convert an ArrayBuffer to a ReadableStream.
- * @internal
- */
-function arrayBufferToStream(buffer: ArrayBuffer): ReadableStream<Uint8Array> {
-  const uint8 = new Uint8Array(buffer);
-
-  return new ReadableStream({
-    start(controller) {
-      controller.enqueue(uint8);
-      controller.close();
-    },
-  });
-}

package/src/href-context.ts

@@ -1,33 +0,0 @@
-"use client";
-
-/**
- * Href Context for route name resolution
- *
- * This module is marked "use client" so it can be imported by both:
- * - Server (segment-system): Gets a client reference for createElement
- * - Client (useHref): Uses the actual context for useContext
- *
- * The context stores:
- * - routeMap: Map of route names to URL patterns
- * - routeName: Current matched route name (for local name resolution)
- */
-import { createContext, type Context } from "react";
-
-/**
- * Context value for href resolution
- */
-export interface HrefContextValue {
-  /** Route map: route name -> URL pattern */
-  routeMap: Record<string, string>;
-  /** Current matched route name (includes name prefix from include()) */
-  routeName?: string;
-}
-
-/**
- * Context for href resolution (route map and current route name)
- *
- * On the server: Populated by renderSegments() via HrefContext.Provider
- * On the client: Populated by NavigationProvider from RSC metadata
- */
-export const HrefContext: Context<HrefContextValue | null> =
-  createContext<HrefContextValue | null>(null);

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>;
-}