@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/browser/prefetch-fetch.ts

@@ -1,109 +0,0 @@
-/**
- * Prefetch Fetch
- *
- * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
- * and useRouter().prefetch(). Sends low-priority fetch requests with
- * X-Rango-State and X-Rango-Prefetch headers so the browser HTTP cache
- * can serve the response on subsequent navigation.
- */
-
-import {
-  hasPrefetch,
-  markPrefetchInflight,
-  markPrefetched,
-  clearPrefetchInflight,
-} from "./prefetch-cache.js";
-import { getRangoState } from "./rango-state.js";
-import { enqueuePrefetch } from "./prefetch-queue.js";
-
-/**
- * Build an RSC partial URL for prefetching.
- * Includes _rsc_v for version mismatch detection when available.
- */
-function buildPrefetchUrl(
-  url: string,
-  segmentIds: string[],
-  version?: string,
-): URL {
-  const targetUrl = new URL(url, window.location.origin);
-  targetUrl.searchParams.set("_rsc_partial", "true");
-  if (segmentIds.length > 0) {
-    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-  }
-  if (version) {
-    targetUrl.searchParams.set("_rsc_v", version);
-  }
-  return targetUrl;
-}
-
-/**
- * Core prefetch fetch logic. Returns a Promise and accepts an optional
- * AbortSignal for cancellation by the prefetch queue.
- */
-function executePrefetchFetch(
-  key: string,
-  fetchUrl: string,
-  signal?: AbortSignal,
-): Promise<void> {
-  markPrefetchInflight(key);
-
-  return fetch(fetchUrl, {
-    priority: "low" as RequestPriority,
-    signal,
-    headers: {
-      "X-Rango-State": getRangoState(),
-      "X-RSC-Router-Client-Path": window.location.href,
-      "X-Rango-Prefetch": "1",
-    },
-  })
-    .then((response) => {
-      // Drain body to ensure full download for browser HTTP cache.
-      // pipeTo avoids decoding the stream into a JS string (unlike .text()).
-      if (response.ok && response.body) {
-        return response.body
-          .pipeTo(new WritableStream())
-          .then(() => markPrefetched(key));
-      }
-    })
-    .catch(() => {
-      // Silently ignore prefetch failures (including abort)
-    })
-    .finally(() => {
-      clearPrefetchInflight(key);
-    });
-}
-
-/**
- * Prefetch (direct): fetch with low priority and store in browser HTTP cache.
- * Used by hover strategy -- fires immediately without queueing.
- */
-export function prefetchDirect(
-  url: string,
-  segmentIds: string[],
-  version?: string,
-): void {
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
-  const key = targetUrl.pathname + targetUrl.search;
-  if (hasPrefetch(key)) return;
-  executePrefetchFetch(key, targetUrl.toString());
-}
-
-/**
- * Prefetch (queued): goes through the concurrency-limited queue.
- * Used by viewport/render strategies to avoid flooding the server.
- * Returns the cache key for use in cleanup.
- */
-export function prefetchQueued(
-  url: string,
-  segmentIds: string[],
-  version?: string,
-): string {
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
-  const key = targetUrl.pathname + targetUrl.search;
-  if (hasPrefetch(key)) return key;
-  const fetchUrlStr = targetUrl.toString();
-  enqueuePrefetch(key, (signal) =>
-    executePrefetchFetch(key, fetchUrlStr, signal),
-  );
-  return key;
-}

package/src/browser/prefetch-queue.ts

@@ -1,81 +0,0 @@
-/**
- * Prefetch Queue
- *
- * Concurrency-limited FIFO queue for speculative prefetches (viewport/render).
- * Hover prefetches bypass this queue — they fire directly for immediate response
- * to user intent.
- *
- * All queued/executing prefetches share a single AbortController so they can
- * be cancelled in bulk when a navigation starts.
- */
-
-const MAX_CONCURRENT = 2;
-
-let active = 0;
-const queue: Array<{
-  key: string;
-  execute: (signal: AbortSignal) => Promise<void>;
-}> = [];
-const queued = new Set<string>();
-const executing = new Set<string>();
-let abortController: AbortController | null = null;
-
-function startExecution(
-  key: string,
-  execute: (signal: AbortSignal) => Promise<void>,
-): void {
-  active++;
-  executing.add(key);
-  abortController ??= new AbortController();
-  execute(abortController.signal).finally(() => {
-    active--;
-    executing.delete(key);
-    drain();
-  });
-}
-
-function drain(): void {
-  while (active < MAX_CONCURRENT && queue.length > 0) {
-    const item = queue.shift()!;
-    queued.delete(item.key);
-    startExecution(item.key, item.execute);
-  }
-}
-
-/**
- * Enqueue a prefetch for concurrency-limited execution.
- * If below the concurrency limit, executes immediately.
- * Otherwise queues for later execution.
- * Deduplicates by key — items already queued or executing are skipped.
- *
- * The executor receives an AbortSignal that is aborted when
- * cancelAllPrefetches() is called (e.g. on navigation start).
- */
-export function enqueuePrefetch(
-  key: string,
-  execute: (signal: AbortSignal) => Promise<void>,
-): void {
-  if (queued.has(key) || executing.has(key)) return;
-
-  if (active < MAX_CONCURRENT) {
-    startExecution(key, execute);
-  } else {
-    queued.add(key);
-    queue.push({ key, execute });
-  }
-}
-
-/**
- * Cancel all in-flight and queued prefetches.
- * Called when a navigation starts — speculative prefetches should not
- * compete with navigation fetches for connection slots.
- */
-export function cancelAllPrefetches(): void {
-  abortController?.abort();
-  abortController = null;
-
-  queue.length = 0;
-  queued.clear();
-  executing.clear();
-  // active count resets naturally as aborted fetches settle in .finally()
-}

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/route-definition/route-function.ts

@@ -1,119 +0,0 @@
-import type {
-  ResolvedRouteMap,
-  RouteConfig,
-  RouteDefinition,
-  RouteDefinitionOptions,
-  TrailingSlashMode,
-} from "../types.js";
-
-/**
- * Result of route() function with paths and trailing slash config
- */
-export interface RouteDefinitionResult<T extends RouteDefinition> {
-  routes: ResolvedRouteMap<T>;
-  trailingSlash: Record<string, TrailingSlashMode>;
-}
-
-/**
- * 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"
-  );
-}
-
-/**
- * Define routes with optional trailing slash configuration
- *
- * @example
- * ```typescript
- * // Simple string paths
- * const routes = route({
- *   blog: "/blog",
- *   post: "/blog/:id",
- * });
- *
- * // With trailing slash config
- * const routes = route({
- *   blog: "/blog",
- *   api: { path: "/api", trailingSlash: "ignore" },
- * }, { trailingSlash: "never" }); // global default
- * ```
- */
-export function route<const T extends RouteDefinition>(
-  input: T,
-  options?: RouteDefinitionOptions,
-): ResolvedRouteMap<T> & {
-  __trailingSlash?: Record<string, TrailingSlashMode>;
-} {
-  const trailingSlash: Record<string, TrailingSlashMode> = {};
-  const routes = flattenRoutes(
-    input as RouteDefinition,
-    "",
-    trailingSlash,
-    options?.trailingSlash,
-  );
-
-  // Attach trailing slash config as a non-enumerable property
-  // This keeps backwards compatibility while passing the config through
-  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;
-}
-
-/**
- * Flatten nested route definitions
- */
-function flattenRoutes(
-  routes: RouteDefinition,
-  prefix: string,
-  trailingSlashConfig: Record<string, TrailingSlashMode>,
-  defaultTrailingSlash?: 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;
-      // Apply default trailing slash if set
-      if (defaultTrailingSlash) {
-        trailingSlashConfig[fullKey] = defaultTrailingSlash;
-      }
-    } else if (isRouteConfig(value)) {
-      // Route config object with path and optional trailingSlash
-      flattened[fullKey] = value.path;
-      // Use route-specific config or fall back to default
-      const mode = value.trailingSlash ?? defaultTrailingSlash;
-      if (mode) {
-        trailingSlashConfig[fullKey] = mode;
-      }
-    } else {
-      // Nested routes - flatten recursively
-      const nested = flattenRoutes(
-        value,
-        `${fullKey}.`,
-        trailingSlashConfig,
-        defaultTrailingSlash,
-      );
-      Object.assign(flattened, nested);
-    }
-  }
-
-  return flattened;
-}

package/src/router.gen.ts

@@ -1,6 +0,0 @@
-// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-  about: "/about",
-  home: "/",
-} as const;
-export type routes = typeof routes;

package/src/static-handler.gen.ts

@@ -1,5 +0,0 @@
-// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-  "doc.gs": "/getting-started",
-} as const;
-export type routes = typeof routes;

package/src/urls.gen.ts

@@ -1,8 +0,0 @@
-// Auto-generated by @rangojs/router - do not edit
-export const routes = {
-  health: "/health",
-  home: "/",
-  index: "/",
-  post: "/:slug",
-} as const;
-export type routes = typeof routes;