@rangojs/router 0.0.0-experimental.0f44aca1

package/src/types/index.ts

@@ -0,0 +1,88 @@
+// Global namespace (must be imported for side effects: `declare global`)
+export type {
+  GetRegisteredRoutes,
+  DefaultHandlerRouteMap,
+  DefaultReverseRouteMap,
+  DefaultEnv,
+} from "./global-namespace.js";
+// Ensure the global namespace declaration is evaluated
+import "./global-namespace.js";
+
+// Route configuration
+export type {
+  DocumentProps,
+  ExtractParams,
+  TrailingSlashMode,
+  RouteConfig,
+  RouteDefinitionOptions,
+  RouteDefinition,
+  ResolvedRouteMap,
+} from "./route-config.js";
+
+// Boundaries (error/notFound)
+export type {
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  LoaderDataResult,
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./boundaries.js";
+export { isLoaderDataResult } from "./boundaries.js";
+
+// Handler context and related types
+export type {
+  MiddlewareFn,
+  ScopedRouteMap,
+  Handler,
+  HandlerContext,
+  InternalHandlerContext,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  RouteKeys,
+  ExtractRouteParams,
+  HandlersForRouteMap,
+  Revalidate,
+  Middleware,
+} from "./handler-context.js";
+
+// Segments
+export type {
+  ViewTransitionClass,
+  TransitionConfig,
+  ResolvedSegment,
+  SegmentMetadata,
+  SlotState,
+  RootLayoutProps,
+  MatchResult,
+} from "./segments.js";
+
+// Route entries
+export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
+
+// Loader types
+export type {
+  LoaderContext,
+  LoaderFn,
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderDefinition,
+} from "./loader-types.js";
+
+// Cache types
+export type {
+  CacheContext,
+  CacheOptions,
+  PartialCacheOptions,
+  EntryCacheConfig,
+} from "./cache-types.js";
+
+// Error handling types
+export type {
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
+} from "./error-types.js";

package/src/types/loader-types.ts

@@ -0,0 +1,183 @@
+import type { ContextVar } from "../context-var.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
+import type {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultVars,
+} from "./global-namespace.js";
+
+/**
+ * Context passed to loader functions during execution
+ *
+ * Loaders run after middleware but before handlers, so they have access
+ * to middleware-set variables via get().
+ *
+ * @template TParams - Route params type (e.g., { slug: string })
+ * @template TEnv - Environment type for bindings/variables
+ *
+ * @example
+ * ```typescript
+ * const CartLoader = createLoader(async (ctx) => {
+ *   "use server";
+ *   const user = ctx.get("user");  // From auth middleware
+ *   return await db.cart.get(user.id);
+ * });
+ *
+ * // With typed params:
+ * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // slug is typed as string
+ *   return await db.products.findBySlug(slug);
+ * });
+ * ```
+ */
+export type LoaderContext<
+  TParams = Record<string, string | undefined>,
+  TEnv = DefaultEnv,
+  TBody = unknown,
+  TSearch extends SearchSchema = {},
+> = {
+  params: TParams;
+  /**
+   * Route params extracted from the URL pattern match (server-side only).
+   * Unlike `params`, these cannot be overridden by client-provided loader params.
+   * Use this when you need trusted, server-matched route params for auth or
+   * resource scoping.
+   */
+  routeParams: Record<string, string>;
+  request: Request;
+  searchParams: URLSearchParams;
+  search: {} extends TSearch ? {} : ResolveSearchSchema<TSearch>;
+  pathname: string;
+  url: URL;
+  env: TEnv;
+  var: DefaultVars;
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+  } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
+  /**
+   * Access another loader's data (returns promise since loaders run in parallel)
+   */
+  use: <T, TLoaderParams = any>(
+    loader: LoaderDefinition<T, TLoaderParams>,
+  ) => Promise<T>;
+  /**
+   * HTTP method (GET, POST, PUT, PATCH, DELETE)
+   * Available when loader is called via load({ method: "POST", ... })
+   */
+  method: string;
+  /**
+   * Request body for POST/PUT/PATCH/DELETE requests
+   * Available when loader is called via load({ method: "POST", body: {...} })
+   */
+  body: TBody | undefined;
+  /**
+   * Form data when loader is invoked via action (fetchable loaders)
+   * Available when loader is called via form submission
+   */
+  formData?: FormData;
+  /**
+   * Generate URLs from route names.
+   * Same scoped reverse as route handlers — `.name` resolves within the
+   * current include() scope, `name` resolves globally.
+   */
+  reverse: ScopedReverseFunction<
+    Record<string, string>,
+    DefaultReverseRouteMap
+  >;
+};
+
+/**
+ * Loader function signature
+ *
+ * @template T - The return type of the loader
+ * @template TParams - Route params type (defaults to generic Record)
+ * @template TEnv - Environment type for bindings/variables
+ *
+ * @example
+ * ```typescript
+ * const myLoader: LoaderFn<{ items: Item[] }> = async (ctx) => {
+ *   "use server";
+ *   return { items: await db.items.list() };
+ * };
+ *
+ * // With typed params:
+ * const productLoader: LoaderFn<Product, { slug: string }> = async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // typed as string
+ *   return await db.products.findBySlug(slug);
+ * };
+ * ```
+ */
+export type LoaderFn<
+  T,
+  TParams = Record<string, string | undefined>,
+  TEnv = DefaultEnv,
+> = (ctx: LoaderContext<TParams, TEnv>) => Promise<T> | T;
+
+/**
+ * Options for fetchable loaders
+ *
+ * Middleware uses the same MiddlewareFn signature as route/app middleware,
+ * enabling reuse of the same middleware functions everywhere.
+ */
+export type FetchableLoaderOptions = {
+  fetchable?: true;
+  middleware?: MiddlewareFn[];
+};
+
+/**
+ * Options for load() calls - type-safe union based on method
+ */
+export type LoadOptions =
+  | {
+      method?: "GET";
+      params?: Record<string, string>;
+    }
+  | {
+      method: "POST" | "PUT" | "PATCH" | "DELETE";
+      params?: Record<string, string>;
+      body?: FormData | Record<string, any>;
+    };
+
+/**
+ * Loader definition object
+ *
+ * Created via createLoader(). Contains the loader name and function.
+ * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ *
+ * @template T - The return type of the loader
+ * @template TParams - Route params type (for type-safe params access)
+ *
+ * @example
+ * ```typescript
+ * // Definition (same file works on server and client)
+ * export const CartLoader = createLoader(async (ctx) => {
+ *   "use server";
+ *   return await db.cart.get(ctx.get("user").id);
+ * });
+ *
+ * // With typed params:
+ * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
+ *   "use server";
+ *   const { slug } = ctx.params;  // slug is typed as string
+ *   return await db.products.findBySlug(slug);
+ * });
+ *
+ * // Server usage
+ * const cart = ctx.use(CartLoader);
+ *
+ * // Client usage (fn is stripped, only name remains)
+ * const cart = useLoader(CartLoader);
+ * ```
+ */
+export type LoaderDefinition<
+  T = any,
+  TParams = Record<string, string | undefined>,
+> = {
+  __brand: "loader";
+  $$id: string; // Injected by Vite plugin (exposeInternalIds) - unique identifier
+  fn?: LoaderFn<T, TParams, any>; // Optional - server-side only, stored in registry for RSC
+};

package/src/types/route-config.ts

@@ -0,0 +1,170 @@
+import type { ReactNode } from "react";
+
+/**
+ * Props for the Document component that wraps the entire application.
+ */
+export type DocumentProps = {
+  children: ReactNode;
+};
+
+/**
+ * Parse constraint values into a union type
+ * "a|b|c" -> "a" | "b" | "c"
+ */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+/**
+ * Extract param info from a param segment
+ *
+ * Handles:
+ * - :param -> { name: "param", optional: false, type: string }
+ * - :param? -> { name: "param", optional: true, type: string }
+ * - :param(a|b) -> { name: "param", optional: false, type: "a" | "b" }
+ * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
+ */
+type ExtractParamInfo<T extends string> =
+  // Optional + constrained (with optional suffix): :param(a|b)?suffix
+  T extends `${infer Name}(${infer Constraint})?${string}`
+    ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
+    : // Constrained (with optional suffix): :param(a|b)suffix
+      T extends `${infer Name}(${infer Constraint})${string}`
+      ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
+      : // Optional (with optional suffix): :param?suffix
+        T extends `${infer Name}?${string}`
+        ? { name: Name; optional: true; type: string }
+        : // Param with dot-suffix: :param.html
+          T extends `${infer Name}.${string}`
+          ? { name: Name; optional: false; type: string }
+          : // Param with dash-suffix: :param-slug
+            T extends `${infer Name}-${string}`
+            ? { name: Name; optional: false; type: string }
+            : // Param with tilde-suffix: :param~v2
+              T extends `${infer Name}~${string}`
+              ? { name: Name; optional: false; type: string }
+              : // Required: :param (no suffix)
+                { name: T; optional: false; type: string };
+
+/**
+ * Build param object from info
+ */
+type ParamFromInfo<Info> = Info extends {
+  name: infer N extends string;
+  optional: true;
+  type: infer V;
+}
+  ? { [K in N]?: V }
+  : Info extends {
+        name: infer N extends string;
+        optional: false;
+        type: infer V;
+      }
+    ? { [K in N]: V }
+    : never;
+
+/**
+ * Merge two param objects preserving optionality
+ * Uses Pick to preserve the modifiers from source types
+ */
+type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
+  ? { [K in keyof O]: O[K] }
+  : never;
+
+/**
+ * Extract route params from a pattern with depth limit to prevent infinite recursion
+ *
+ * Supports:
+ * - Required params: /:slug -> { slug: string }
+ * - Optional params: /:locale? -> { locale?: string }
+ * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
+ * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ *
+ * @example
+ * ExtractParams<"/products/:id"> // { id: string }
+ * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
+ * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
+ * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ */
+export type ExtractParams<
+  T extends string,
+  Depth extends readonly unknown[] = [],
+> = Depth["length"] extends 10
+  ? { [key: string]: string | undefined } // Fallback to generic params if too deep
+  : // Match param with remaining path: :param.../rest
+    T extends `${infer _Start}:${infer Param}/${infer Rest}`
+    ? MergeParams<
+        ParamFromInfo<ExtractParamInfo<Param>>,
+        ExtractParams<`/${Rest}`, readonly [...Depth, unknown]>
+      >
+    : // Match param at end: :param...
+      T extends `${infer _Start}:${infer Param}`
+      ? ParamFromInfo<ExtractParamInfo<Param>>
+      : {};
+
+/**
+ * Trailing slash handling mode
+ * - "never": Redirect URLs with trailing slash to without
+ * - "always": Redirect URLs without trailing slash to with
+ * - "ignore": Match both with and without trailing slash
+ */
+export type TrailingSlashMode = "never" | "always" | "ignore";
+
+/**
+ * Route configuration object (alternative to string path)
+ */
+export type RouteConfig = {
+  path: string;
+  trailingSlash?: TrailingSlashMode;
+};
+
+/**
+ * Route definition options (global defaults)
+ */
+export type RouteDefinitionOptions = {
+  trailingSlash?: TrailingSlashMode;
+};
+
+export type RouteDefinition = {
+  [key: string]: string | RouteConfig | RouteDefinition;
+};
+
+/**
+ * Recursively flatten nested routes with depth limit to prevent infinite recursion
+ * Transforms: { products: { detail: "/product/:slug" } } => { "products.detail": "/product/:slug" }
+ * Also handles RouteConfig objects: { api: { path: "/api" } } => { "api": "/api" }
+ */
+type FlattenRoutes<
+  T extends RouteDefinition,
+  Prefix extends string = "",
+  Depth extends readonly unknown[] = [],
+> = Depth["length"] extends 5
+  ? never
+  : {
+      [K in keyof T]: T[K] extends string
+        ? Record<`${Prefix}${K & string}`, T[K]>
+        : T[K] extends RouteConfig
+          ? Record<`${Prefix}${K & string}`, T[K]["path"]>
+          : T[K] extends RouteDefinition
+            ? FlattenRoutes<
+                T[K],
+                `${Prefix}${K & string}.`,
+                readonly [...Depth, unknown]
+              >
+            : never;
+    }[keyof T];
+
+/**
+ * Union to intersection helper
+ */
+type UnionToIntersection<U> = (
+  U extends unknown ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Resolved route map - flattened route definitions with full paths
+ */
+export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
+  FlattenRoutes<T>
+>;

package/src/types/route-entry.ts

@@ -0,0 +1,102 @@
+import type { AllUseItems } from "../route-types.js";
+import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
+
+/**
+ * Context captured for lazy include evaluation
+ */
+export interface LazyIncludeContext {
+  urlPrefix: string;
+  namePrefix: string | undefined;
+  parent: unknown; // EntryData - avoid circular import
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+}
+
+/**
+ * Internal route entry stored in router
+ */
+export interface RouteEntry<TEnv = any> {
+  prefix: string;
+  /**
+   * Pre-computed static prefix for fast short-circuit matching.
+   * Extracted from prefix at registration time (everything before first param).
+   *
+   * Examples:
+   * - "/api" -> staticPrefix = "/api"
+   * - "/site/:locale" -> staticPrefix = "/site"
+   * - "/:locale" -> staticPrefix = "" (empty, can't optimize)
+   *
+   * At runtime: if staticPrefix && !pathname.startsWith(staticPrefix), skip entry.
+   */
+  staticPrefix: string;
+  /**
+   * Route patterns map. For lazy entries, this starts as empty and is
+   * populated on first request.
+   */
+  routes: ResolvedRouteMap<any>;
+  /**
+   * Trailing slash config per route key
+   * If not specified for a route, defaults to pattern-based detection
+   */
+  trailingSlash?: Record<string, TrailingSlashMode>;
+  /**
+   * Supported handler shapes:
+   *   - sync: () => Array<AllUseItems>
+   *   - lazy import: () => Promise<{ default: () => Array<AllUseItems> }>
+   *   - lazy function: () => Promise<() => Array<AllUseItems>>
+   *
+   * Direct Promise<Array> is NOT supported and rejected at runtime.
+   */
+  handler: () =>
+    | Array<AllUseItems>
+    | Promise<{ default: () => Array<AllUseItems> }>
+    | Promise<() => Array<AllUseItems>>;
+  mountIndex: number;
+
+  /**
+   * Route keys in this entry that have pre-render handlers.
+   * Used by the non-trie match path to set the `pr` flag.
+   */
+  prerenderRouteKeys?: Set<string>;
+
+  /**
+   * Route keys in this entry that use `{ passthrough: true }`.
+   * Used by the non-trie match path to set the `pt` flag.
+   */
+  passthroughRouteKeys?: Set<string>;
+
+  // === Lazy evaluation fields ===
+
+  /**
+   * Whether this entry is lazily evaluated.
+   * When true, routes are populated on first matching request.
+   */
+  lazy?: boolean;
+
+  /**
+   * For lazy entries: the UrlPatterns to evaluate
+   */
+  lazyPatterns?: unknown;
+
+  /**
+   * For lazy entries: captured context at definition time
+   */
+  lazyContext?: LazyIncludeContext;
+
+  /**
+   * For lazy entries: whether patterns have been evaluated
+   */
+  lazyEvaluated?: boolean;
+
+  /**
+   * Cache profiles for DSL-time cache("profileName") resolution.
+   * Set on all entries (lazy and non-lazy) so loadManifest() can
+   * propagate them into the HelperContext Store.
+   */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+}

package/src/types/segments.ts

@@ -0,0 +1,148 @@
+import type { ReactNode } from "react";
+import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+
+/**
+ * CSS class(es) for a ViewTransition phase.
+ * Can be a simple string or an object mapping transition types to class names
+ * for direction-aware transitions (e.g., { "navigation": "slide-right", "navigation-back": "slide-left" }).
+ */
+export type ViewTransitionClass = Record<string, string> | string;
+
+/**
+ * Configuration for React's <ViewTransition> component.
+ * Maps directly to ViewTransitionProps (minus children/ref/callbacks).
+ */
+export interface TransitionConfig {
+  enter?: ViewTransitionClass;
+  exit?: ViewTransitionClass;
+  update?: ViewTransitionClass;
+  share?: ViewTransitionClass;
+  default?: ViewTransitionClass;
+  name?: string;
+}
+
+/**
+ * Resolved segment with component
+ *
+ * Segment types:
+ * - layout: Wraps child content via <Outlet />
+ * - route: The leaf content for a URL
+ * - parallel: Named slots rendered via <ParallelOutlet name="@slot" />
+ * - loader: Data segment (no visual rendering, carries loaderData)
+ * - error: Error fallback segment (replaces failed segment with error UI)
+ * - notFound: Not found fallback segment (replaces segment when data not found)
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface ResolvedSegment {
+  id: string;
+  namespace: string; // Optional namespace for segment (used for parallel groups)
+  type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
+  index: number;
+  component: ReactNode; // Component, handler promise, or resolved element
+  loading?: ReactNode; // Loading component for this segment (shown during navigation)
+  transition?: TransitionConfig; // ViewTransition config for this segment
+  layout?: ReactNode; // Layout element to wrap content (used by intercept segments)
+  params?: Record<string, string>;
+  slot?: string; // For parallel segments: '@sidebar', '@modal', etc.
+  belongsToRoute?: boolean; // True if segment belongs to the matched route (route itself + its children)
+  layoutName?: string; // For layouts: the layout name identifier
+  parallelName?: string; // For parallels: the parallel group name (used to match with revalidations)
+  // Loader-specific fields
+  loaderId?: string; // For loaders: the loader $$id identifier
+  loaderData?: any; // For loaders: the resolved data from loader execution
+  // Intercept loader fields (for streaming loader data in parallel segments)
+  loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
+  loaderIds?: string[]; // IDs ($$id) of loaders for this segment
+  // Error-specific fields
+  error?: ErrorInfo; // For error segments: the error information
+  // NotFound-specific fields
+  notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
+  // Mount path from include() scope, used for MountContext.Provider wrapping
+  mountPath?: string;
+}
+
+/**
+ * Segment metadata (without component)
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SegmentMetadata {
+  id: string;
+  type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
+  index: number;
+  params?: Record<string, string>;
+  slot?: string;
+  loaderId?: string;
+  error?: ErrorInfo;
+  notFoundInfo?: NotFoundInfo;
+}
+
+// Note: route symbols are now defined in route-definition.ts
+// as properties on the route() function
+
+/**
+ * State of a named slot (e.g., @modal, @sidebar)
+ * Used for intercepting routes where slots render alternative content
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface SlotState {
+  /**
+   * Whether the slot is currently active (has content to render)
+   */
+  active: boolean;
+  /**
+   * Segments for this slot when active
+   */
+  segments?: ResolvedSegment[];
+}
+
+/**
+ * Props passed to the root layout component
+ */
+export interface RootLayoutProps {
+  children: ReactNode;
+}
+
+/**
+ * Router match result
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface MatchResult {
+  segments: ResolvedSegment[];
+  matched: string[];
+  diff: string[];
+  /**
+   * Merged route params from all matched segments
+   * Available for use by the handler after route matching
+   */
+  params: Record<string, string>;
+  /**
+   * The matched route name (includes name prefix from include()).
+   * Used by ctx.reverse() for local name resolution.
+   */
+  routeName?: string;
+  /**
+   * State of named slots for this route match
+   * Key is slot name (e.g., "@modal"), value is slot state
+   * Slots are used for intercepting routes during soft navigation
+   */
+  slots?: Record<string, SlotState>;
+  /**
+   * Redirect URL for trailing slash normalization.
+   * When set, the RSC handler should return a 308 redirect to this URL
+   * instead of rendering the page.
+   */
+  redirect?: string;
+  /**
+   * Route-level middleware collected from the matched entry tree.
+   * These run with the same onion-style execution as app-level middleware,
+   * wrapping the entire RSC response creation.
+   */
+  routeMiddleware?: Array<{
+    handler: import("../router/middleware.js").MiddlewareFn;
+    params: Record<string, string>;
+  }>;
+}

package/src/types.ts

@@ -0,0 +1 @@
+export * from "./types/index.js";