@rangojs/router 0.0.0-experimental.0f44aca1

package/src/index.ts

@@ -0,0 +1,277 @@
+/**
+ * @rangojs/router
+ *
+ * Single user-facing entrypoint for all router APIs.
+ *
+ * The "react-server" export condition selects index.rsc.ts (real implementations)
+ * vs this file (client stubs for server-only functions).
+ *
+ * For client-only exports (Outlet, useOutlet, hooks, components):
+ *   import from "@rangojs/router/client"
+ */
+
+// Error classes (can be used on both server and client)
+export {
+  RouteNotFoundError,
+  DataNotFoundError,
+  notFound,
+  MiddlewareError,
+  HandlerError,
+  BuildError,
+  InvalidHandlerError,
+  RouterError,
+  Skip,
+  isSkip,
+} from "./errors.js";
+
+// Types (safe to import anywhere - no runtime code)
+export type {
+  // Configuration types
+  DocumentProps,
+  DefaultEnv,
+  RouteDefinition,
+  RouteConfig,
+  RouteDefinitionOptions,
+  TrailingSlashMode,
+  // Handler types
+  Handler, // Supports params object, path pattern, or route name
+  HandlerContext,
+  ExtractParams,
+  GenericParams,
+  // Middleware types
+  Middleware,
+  // Revalidation types
+  RevalidateParams,
+  Revalidate,
+  RouteKeys,
+  // Loader types
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  FetchableLoaderOptions,
+  LoadOptions,
+  // Error boundary types
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
+} from "./types.js";
+
+// Search params schema types
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
+
+// Client-safe createLoader - only stores the $$id, function is not included
+// Use this when defining loaders that will be imported by client components
+export { createLoader } from "./loader.js";
+
+// Route definition types (safe to import anywhere)
+export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
+export type { TransitionConfig, ViewTransitionClass } from "./types.js";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+} from "./route-types.js";
+
+// Response route types (usable in both server and client contexts)
+export type {
+  ResponseHandler,
+  ResponseHandlerContext,
+  JsonResponseHandler,
+  TextResponseHandler,
+  JsonValue,
+  ResponsePathFn,
+  JsonResponsePathFn,
+  TextResponsePathFn,
+  RouteResponse,
+  ResponseError,
+  ResponseEnvelope,
+} from "./urls.js";
+
+// Middleware context types
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
+/**
+ * Error-throwing stub for server-only `urls` function.
+ */
+export function urls(): never {
+  throw serverOnlyStubError("urls");
+}
+
+/**
+ * Error-throwing stub for server-only `createRouter` function.
+ */
+export function createRouter(): never {
+  throw serverOnlyStubError("createRouter");
+}
+
+/**
+ * Error-throwing stub for server-only `redirect` function.
+ */
+export function redirect(): never {
+  throw serverOnlyStubError("redirect");
+}
+
+// Handle API (universal - works on both server and client)
+export { createHandle, isHandle, type Handle } from "./handle.js";
+
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
+
+/**
+ * Error-throwing stub for server-only `Prerender` function.
+ */
+export function Prerender(): never {
+  throw serverOnlyStubError("Prerender");
+}
+
+/**
+ * Error-throwing stub for server-only `Static` function.
+ */
+export function Static(): never {
+  throw serverOnlyStubError("Static");
+}
+
+/**
+ * Error-throwing stub for server-only `getRequestContext` function.
+ */
+export function getRequestContext(): never {
+  throw serverOnlyStubError("getRequestContext");
+}
+
+/**
+ * Error-throwing stub for server-only `cookies` function.
+ */
+export function cookies(): never {
+  throw serverOnlyStubError("cookies");
+}
+
+/**
+ * Error-throwing stub for server-only `headers` function.
+ */
+export function headers(): never {
+  throw serverOnlyStubError("headers");
+}
+
+/**
+ * Error-throwing stub for server-only `createReverse` function.
+ */
+export function createReverse(): never {
+  throw serverOnlyStubError("createReverse");
+}
+
+// Error-throwing stubs for server-only route helpers
+export function layout(): never {
+  throw serverOnlyStubError("layout");
+}
+export function cache(): never {
+  throw serverOnlyStubError("cache");
+}
+export function middleware(): never {
+  throw serverOnlyStubError("middleware");
+}
+export function revalidate(): never {
+  throw serverOnlyStubError("revalidate");
+}
+export function loader(): never {
+  throw serverOnlyStubError("loader");
+}
+export function loading(): never {
+  throw serverOnlyStubError("loading");
+}
+export function parallel(): never {
+  throw serverOnlyStubError("parallel");
+}
+export function intercept(): never {
+  throw serverOnlyStubError("intercept");
+}
+export function when(): never {
+  throw serverOnlyStubError("when");
+}
+export function errorBoundary(): never {
+  throw serverOnlyStubError("errorBoundary");
+}
+export function notFoundBoundary(): never {
+  throw serverOnlyStubError("notFoundBoundary");
+}
+export function transition(): never {
+  throw serverOnlyStubError("transition");
+}
+
+// Request context type (safe for client)
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+
+// Cookie store types (safe for client)
+export type {
+  CookieStore,
+  Cookie,
+  ReadonlyHeaders,
+} from "./server/cookie-store.js";
+
+// Meta types
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+
+// Breadcrumb types
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+
+// Reverse type utilities for type-safe URL generation (Django-style URL reversal)
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
+// scopedReverse() helper for handlers to get locally-typed reverse
+export { scopedReverse } from "./reverse.js";
+
+// Location state (universal - works on both server and client)
+export {
+  createLocationState,
+  type LocationStateDefinition,
+  type LocationStateEntry,
+  type LocationStateOptions,
+} from "./browser/react/location-state-shared.js";
+
+// Path-based response type lookup from RegisteredRoutes
+export type { PathResponse } from "./href-client.js";
+
+// Telemetry sink
+export { createConsoleSink } from "./router/telemetry.js";
+export { createOTelSink } from "./router/telemetry-otel.js";
+export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";

package/src/internal-debug.ts

@@ -0,0 +1,11 @@
+// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
+// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
+// in all runtimes including Cloudflare Workers where process.env is unavailable.
+// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+export const INTERNAL_RANGO_DEBUG: boolean =
+  typeof __RANGO_DEBUG__ !== "undefined"
+    ? __RANGO_DEBUG__
+    : typeof process !== "undefined" &&
+      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
+
+declare const __RANGO_DEBUG__: boolean;

package/src/loader.rsc.ts

@@ -0,0 +1,89 @@
+/**
+ * rsc-router/loader (RSC/server version)
+ *
+ * Server-side createLoader implementation with full loader functionality.
+ * Only used in react-server context via export conditions.
+ *
+ * For non-fetchable loaders: returns a loader definition with fn included
+ * For fetchable loaders: stores fn in registry and returns a serializable loader
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin as a hidden parameter.
+ * Users don't need to pass any name - IDs are auto-generated from file path.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+import type { MiddlewareFn } from "./router/middleware.js";
+import {
+  registerFetchableLoader,
+  getFetchableLoader,
+} from "./server/fetchable-loader-store.js";
+
+export { getFetchableLoader };
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - the $$id parameter is injected by Vite plugin, not user-provided
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable?: true | FetchableLoaderOptions,
+  // Hidden parameter injected by Vite exposeInternalIds plugin
+  __injectedId?: string,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  // The $$id will be set on the returned object by Vite plugin
+  // For fetchable loaders, __injectedId is also passed as a parameter
+  const loaderId = __injectedId || "";
+
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
+  // If not fetchable, store fn in registry (for SSR ctx.use() resolution)
+  // but mark fetchable=false so the _rsc_loader endpoint rejects it.
+  if (fetchable === undefined) {
+    if (fn && loaderId) {
+      registerFetchableLoader(loaderId, fn, [], false);
+    }
+    return {
+      __brand: "loader",
+      $$id: loaderId,
+    };
+  }
+
+  // Fetchable loader - store fn in registry and return a serializable object
+  const middleware: MiddlewareFn[] =
+    fetchable === true ? [] : fetchable?.middleware || [];
+
+  // Register the function in the internal registry by $$id (server-side only)
+  // The loader fetch handler looks it up by $$id when load() is called from the client.
+  if (fn && loaderId) {
+    registerFetchableLoader(loaderId, fn, middleware, true);
+  }
+
+  return {
+    __brand: "loader",
+    $$id: loaderId,
+  };
+}

package/src/loader.ts

@@ -0,0 +1,64 @@
+/**
+ * rsc-router/loader (client version)
+ *
+ * Client-only stub for createLoader. Returns a minimal loader definition
+ * ({ __brand, $$id }) that can be passed to hooks like useLoader.
+ * The actual loader function is not included -- it only exists on the server.
+ *
+ * For export-only loader files, the Vite plugin replaces the entire file with
+ * object literals (bypassing this function). Those stubs only contain
+ * { __brand, $$id }.
+ * This function only runs when loaders are in mixed files (not export-only).
+ *
+ * The $$id is injected by the Vite exposeInternalIds plugin.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - client stub that just returns the loader definition
+// The $$id parameter is injected by Vite plugin, not user-provided
+//
+// NOTE: For export-only loader files, the Vite plugin replaces the entire
+// file with object literals (bypassing this function). This function only
+// runs when loaders are in mixed files (not export-only).
+export function createLoader<T>(
+  _fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  _fetchable?: true | FetchableLoaderOptions,
+  __injectedId?: string,
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  const loaderId = __injectedId || "";
+
+  if (!loaderId && process.env.NODE_ENV === "development") {
+    throw new Error(
+      "[rsc-router] Loader is missing $$id. " +
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the loader is exported with: export const MyLoader = createLoader(...)",
+    );
+  }
+
+  return {
+    __brand: "loader",
+    $$id: loaderId,
+  };
+}

package/src/network-error-thrower.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { NetworkError } from "./errors.js";
+
+interface NetworkErrorThrowerProps {
+  error: NetworkError;
+}
+
+/**
+ * Client component that throws a NetworkError during render.
+ * Used to trigger the root error boundary when a network error occurs
+ * during navigation or server actions.
+ *
+ * This must be a separate component because:
+ * 1. Errors must be thrown during React's render phase to be caught by error boundaries
+ * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
+ */
+export function NetworkErrorThrower({
+  error,
+}: NetworkErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/outlet-context.ts

@@ -0,0 +1,15 @@
+import { Context, createContext, type ReactNode } from "react";
+import type { ResolvedSegment } from "./types";
+
+export interface OutletContextValue {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  parent?: OutletContextValue | null;
+  /** Loading component for Suspense fallback (from segment's loading() definition) */
+  loading?: ReactNode;
+}
+
+export const OutletContext: Context<OutletContextValue | null> =
+  createContext<OutletContextValue | null>(null);

package/src/outlet-provider.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useContext, useMemo, type ReactNode } from "react";
+import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Provider for outlet content - used internally by renderSegments
+ *
+ * Stores a reference to parent context so useLoader can walk up the chain
+ * to find loader data from parent layouts. If this segment defines a loading
+ * component, Outlet will wrap content with Suspense using that as fallback.
+ */
+export function OutletProvider({
+  content,
+  parallel,
+  segment,
+  loaderData,
+  children,
+}: {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  children: ReactNode;
+}): ReactNode {
+  // Get parent context to enable walking up the chain for loader lookups
+  const parentContext = useContext(OutletContext);
+
+  const value = useMemo(
+    () => ({
+      content,
+      parallel,
+      segment,
+      loaderData,
+      parent: parentContext,
+      loading: segment?.loading,
+    }),
+    [content, parallel, segment, loaderData, parentContext],
+  );
+
+  return (
+    <OutletContext.Provider value={value}>{children}</OutletContext.Provider>
+  );
+}

package/src/prerender/param-hash.ts

@@ -0,0 +1,37 @@
+/**
+ * Deterministic param hashing for prerender storage keys.
+ *
+ * Used at build time (child process) to generate filenames and at
+ * runtime (worker) to look up pre-rendered data. Both environments
+ * must produce identical hashes for the same params.
+ *
+ * Uses a simple DJB2-based hash that works in all JS environments
+ * (Node.js, Cloudflare Workers, browsers) without crypto imports.
+ */
+
+/**
+ * Compute a deterministic hash string from route params.
+ * For static routes (no params), returns "_".
+ */
+export function hashParams(params: Record<string, string>): string {
+  const entries = Object.entries(params);
+  if (entries.length === 0) return "_";
+
+  const sorted = entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const str = sorted
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+  return djb2Hex(str);
+}
+
+/**
+ * DJB2 hash returning an 8-char hex string.
+ * Deterministic across all JS runtimes.
+ */
+function djb2Hex(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}