@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/theme/use-theme.ts

@@ -27,9 +27,6 @@ import type { UseThemeReturn } from "./types.js";
  *
  * Must be used within a ThemeProvider (which is automatically included
  * in NavigationProvider when theme is enabled in router config).
- *
- * @returns Theme state and methods
- * @throws Error if used outside ThemeProvider
  */
 export function useTheme(): UseThemeReturn {
   const ctx = requireThemeContext();

package/src/types/boundaries.ts

@@ -1,22 +1,12 @@
 import type { ReactNode } from "react";
 
-/**
- * Error information passed to error boundary fallback components
- */
 export interface ErrorInfo {
-  /** Error message (always available) */
   message: string;
-  /** Error name/type (e.g., "RouteNotFoundError", "MiddlewareError") */
   name: string;
-  /** Optional error code for programmatic handling */
   code?: string;
-  /** Stack trace (only in development) */
   stack?: string;
-  /** Original error cause if available */
   cause?: unknown;
-  /** Segment ID where the error occurred */
   segmentId: string;
-  /** Segment type where the error occurred */
   segmentType:
     | "layout"
     | "route"
@@ -46,13 +36,9 @@ export interface ErrorInfo {
  * ```
  */
 export interface ErrorBoundaryFallbackProps {
-  /** Error information */
   error: ErrorInfo;
 }
 
-/**
- * Error boundary handler - receives error info and returns fallback UI
- */
 export type ErrorBoundaryHandler = (
   props: ErrorBoundaryFallbackProps,
 ) => ReactNode;
@@ -77,17 +63,10 @@ export type ErrorBoundaryHandler = (
  * ```
  */
 export interface ClientErrorBoundaryFallbackProps {
-  /** Error information */
   error: ErrorInfo;
-  /** Function to reset error state and retry rendering */
   reset: () => void;
 }
 
-/**
- * Wrapped loader data result for deferred resolution with error handling.
- * When loaders are deferred to client-side resolution, errors need to be
- * wrapped so the client can handle them appropriately.
- */
 export type LoaderDataResult<T = unknown> =
   | { __loaderResult: true; ok: true; data: T }
   | {
@@ -97,9 +76,6 @@ export type LoaderDataResult<T = unknown> =
       fallback: ReactNode | null;
     };
 
-/**
- * Type guard to check if a value is a wrapped loader result
- */
 export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
   return (
     typeof value === "object" &&
@@ -109,15 +85,9 @@ export function isLoaderDataResult(value: unknown): value is LoaderDataResult {
   );
 }
 
-/**
- * Not found information passed to notFound boundary fallback components
- */
 export interface NotFoundInfo {
-  /** Not found message */
   message: string;
-  /** Segment ID where notFound was thrown */
   segmentId: string;
-  /** Segment type where notFound was thrown */
   segmentType:
     | "layout"
     | "route"
@@ -125,7 +95,6 @@ export interface NotFoundInfo {
     | "loader"
     | "middleware"
     | "cache";
-  /** The pathname that triggered the not found */
   pathname?: string;
 }
 
@@ -146,13 +115,9 @@ export interface NotFoundInfo {
  * ```
  */
 export interface NotFoundBoundaryFallbackProps {
-  /** Not found information */
   notFound: NotFoundInfo;
 }
 
-/**
- * NotFound boundary handler - receives not found info and returns fallback UI
- */
 export type NotFoundBoundaryHandler = (
   props: NotFoundBoundaryFallbackProps,
 ) => ReactNode;

package/src/types/error-types.ts

@@ -14,19 +14,19 @@
  * - "unknown": Fallback for unclassified errors (not currently invoked)
  */
 export type ErrorPhase =
-  | "routing" // During route matching
-  | "manifest" // During manifest loading (reserved, not currently invoked)
-  | "middleware" // During middleware execution (errors propagate to handler phase)
-  | "loader" // During loader execution
-  | "handler" // During route/layout handler execution
-  | "rendering" // During RSC/SSR rendering (SSR handler uses separate callback)
-  | "action" // During server action execution
-  | "revalidation" // During revalidation evaluation
-  | "cache" // During "use cache" background operations (stale revalidation, async cache writes)
-  | "prerender" // During build-time pre-rendering (Vite closeBundle)
-  | "static" // During build-time static handler rendering (Vite closeBundle)
-  | "origin" // During cross-origin request validation (CSRF protection)
-  | "unknown"; // Fallback for unclassified errors
+  | "routing"
+  | "manifest"
+  | "middleware"
+  | "loader"
+  | "handler"
+  | "rendering"
+  | "action"
+  | "revalidation"
+  | "cache"
+  | "prerender"
+  | "static"
+  | "origin"
+  | "unknown";
 
 /**
  * Comprehensive context passed to onError callback
@@ -59,99 +59,35 @@ export type ErrorPhase =
  * ```
  */
 export interface OnErrorContext<TEnv = any> {
-  /**
-   * The error that occurred
-   */
   error: Error;
-
-  /**
-   * Phase where the error occurred
-   */
   phase: ErrorPhase;
-
-  /**
-   * The original request
-   */
   request: Request;
-
-  /**
-   * Parsed URL from the request
-   */
   url: URL;
-
-  /**
-   * Request pathname
-   */
   pathname: string;
-
-  /**
-   * HTTP method
-   */
   method: string;
-
-  /**
-   * Matched route key (if available)
-   * e.g., "shop.products.detail"
-   */
+  /** Matched route key (if available) e.g., "shop.products.detail" */
   routeKey?: string;
-
-  /**
-   * Route params (if available)
-   * e.g., { slug: "headphones" }
-   */
+  /** Route params (if available) e.g., { slug: "headphones" } */
   params?: Record<string, string>;
-
-  /**
-   * Segment ID where error occurred (if available)
-   * e.g., "M1L0" for a layout, "M1R0" for a route
-   */
+  /** Segment ID where error occurred (if available) e.g., "M1L0" for a layout, "M1R0" for a route */
   segmentId?: string;
-
-  /**
-   * Segment type where error occurred (if available)
-   */
+  /** Segment type where error occurred (if available) */
   segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
-
-  /**
-   * Loader name (if error occurred in a loader)
-   */
+  /** Loader name (if error occurred in a loader) */
   loaderName?: string;
-
-  /**
-   * Middleware name/id (if error occurred in middleware)
-   */
+  /** Middleware name/id (if error occurred in middleware) */
   middlewareId?: string;
-
-  /**
-   * Action ID (if error occurred during server action)
-   * e.g., "src/actions.ts#addToCart"
-   */
+  /** Action ID (if error occurred during server action) e.g., "src/actions.ts#addToCart" */
   actionId?: string;
-
-  /**
-   * Environment/bindings (platform context)
-   */
+  /** Environment/bindings (platform context) */
   env?: TEnv;
-
-  /**
-   * Duration from request start to error (milliseconds)
-   */
+  /** Duration from request start to error (milliseconds) */
   duration?: number;
-
-  /**
-   * Whether this is a partial/navigation request
-   */
+  /** Whether this is a partial/navigation request */
   isPartial?: boolean;
-
-  /**
-   * Whether an error boundary caught the error
-   * If true, the error was handled and a fallback UI was rendered
-   */
+  /** Whether an error boundary caught the error */
   handledByBoundary?: boolean;
-
-  /**
-   * Stack trace (if available)
-   */
+  /** Stack trace (if available) */
   stack?: string;
 
   /**

package/src/types/global-namespace.ts

@@ -20,26 +20,16 @@
 declare global {
   namespace Rango {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Env {
-      // Empty by default - users augment with their bindings (e.g., { DB: D1Database })
-    }
+    interface Env {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface Vars {
-      // Empty by default - users augment with their variables (e.g., { user?: User })
-    }
+    interface Vars {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface RegisteredRoutes {
-      // Empty by default - users augment with their merged route maps for type-safe href()
-      // Values are string (pattern) for RSC routes, or { path: string; response: T } for response routes
-    }
+    interface RegisteredRoutes {}
 
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
-    interface GeneratedRouteMap {
-      // Empty by default - populated by generated named-routes.gen.ts
-      // Maps route names to URL pattern strings for Handler<"routeName"> support
-    }
+    interface GeneratedRouteMap {}
   }
 }
 
@@ -97,7 +87,17 @@ export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never
 export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
 
 /**
- * Default variables type - uses global augmentation if available, Record<string, any> otherwise
+ * Variables type backing the string-key `ctx.get` / `ctx.set` overloads.
+ *
+ * Uses `Rango.Vars` augmentation when present; otherwise falls back to
+ * `Record<string, any>` so an un-augmented app can use string-key vars with
+ * zero config -- at the cost of a typo'd key being silently `any`.
+ *
+ * This `any` fallback is deliberate (see #561) and is an intentional asymmetry
+ * with `DefaultEnv` above, which falls back to `unknown`: env bindings are
+ * platform-critical and should be registered, so a forgotten binding is made a
+ * compile error; vars are ad-hoc and middleware-set, so the zero-config path
+ * wins. Augment `Rango.Vars` for type-safe keys.
  */
 export type DefaultVars = keyof Rango.Vars extends never
   ? Record<string, any>

package/src/types/handler-context.ts

@@ -107,14 +107,6 @@ type StrictLocalParamsWithExtras<TEntry> =
     ? Record<string, string>
     : ExtractParamsFromEntry<TEntry, {}> & Record<string, string>;
 
-// HandlerContext.reverse is the only reverse surface with runtime param autofill
-// from the current matched request. Middleware/loaders/request context do not
-// have the same local-route guarantees, so they keep plain ScopedReverseFunction.
-//
-// When a handler has an explicit local route map, enforce that local route
-// params declared by that map are present while still allowing extra mount
-// params to be passed through. Global names remain autofill-friendly because
-// parent include() params are often unknown at the module definition site.
 type StrictLocalAutofillGlobalReverseFunction<TLocalRoutes, TGlobalRoutes> =
   ScopedReverseFunction<TLocalRoutes, TGlobalRoutes> & {
     <TName extends keyof TGlobalRoutes & string>(
@@ -535,13 +527,24 @@ export type ActionRef =
  * downstream revalidators, or nothing (`void` / `null` / `undefined`) to defer
  * to the current suggestion without changing it.
  *
+ * Two idioms cover almost every case; they differ only in what an _unrelated_
+ * action does. Match actions by reference with `ctx.isAction()` (rename-safe)
+ * rather than `actionId?.includes("...")` (a renamed or moved action silently
+ * stops matching). Because `isAction` returns a raw boolean, combine it with
+ * `|| undefined` to defer or leave it bare to suppress.
+ *
  * @example
  * ```ts
- * // Re-render when a cart action happened or the browser signals staleness;
- * // defer otherwise (|| undefined) so the segment default still applies
- * revalidate(({ actionId, stale }) =>
- *   actionId?.includes("cart") || stale || undefined
- * )
+ * import * as CartActions from "./actions/cart";
+ *
+ * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
+ * // undefined so the segment's default decision still applies (and downstream
+ * // revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ *
+ * // Idiom B — "mine only": re-render on my actions and suppress everything
+ * // else (isAction returns a raw boolean, so an unrelated action yields false).
+ * revalidate((ctx) => ctx.isAction(CartActions))
  *
  * // Always re-render when params change (default behavior made explicit)
  * revalidate(({ defaultShouldRevalidate }) => defaultShouldRevalidate)

package/src/types/index.ts

@@ -1,14 +1,11 @@
-// 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,
@@ -19,7 +16,6 @@ export type {
   ResolvedRouteMap,
 } from "./route-config.js";
 
-// Boundaries (error/notFound)
 export type {
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -32,7 +28,6 @@ export type {
 } from "./boundaries.js";
 export { isLoaderDataResult } from "./boundaries.js";
 
-// Handler context and related types
 export type {
   MiddlewareFn,
   ScopedRouteMap,
@@ -50,7 +45,6 @@ export type {
   Middleware,
 } from "./handler-context.js";
 
-// Segments
 export type {
   ViewTransitionClass,
   TransitionConfig,
@@ -61,10 +55,8 @@ export type {
   MatchResult,
 } from "./segments.js";
 
-// Route entries
 export type { LazyIncludeContext, RouteEntry } from "./route-entry.js";
 
-// Loader types
 export type {
   LoaderContext,
   LoaderFn,
@@ -73,7 +65,6 @@ export type {
   LoaderDefinition,
 } from "./loader-types.js";
 
-// Cache types
 export type {
   CacheContext,
   CacheOptions,
@@ -81,7 +72,6 @@ export type {
   EntryCacheConfig,
 } from "./cache-types.js";
 
-// Error handling types
 export type {
   ErrorPhase,
   OnErrorContext,

package/src/types/request-scope.ts

@@ -1,22 +1,3 @@
-/**
- * RequestScope: the fields every user-facing context shares.
- *
- * A handler, middleware, loader, response handler, and the ALS-bound
- * RequestContext are all different phases of the same request, and they
- * all carry the same set of request-scoped capabilities: the raw Request,
- * the parsed URL pair (`url` is cleaned of internal `_rsc*` params,
- * `originalUrl` retains them), pathname/searchParams, platform bindings
- * (`env`), and two escape hatches for work that outlives the response
- * (`waitUntil`) or needs the raw Cloudflare runtime object
- * (`executionContext`).
- *
- * Each public context type intersects `RequestScope<TEnv>` with its own
- * phase-specific fields (e.g. `params`/`reverse` on HandlerContext,
- * `headers`/`header()` on MiddlewareContext). That keeps platform surface
- * in one place and lets the next runtime escape hatch we need land in
- * one file instead of four.
- */
-
 import type { DefaultEnv } from "./global-namespace.js";
 
 /**

package/src/types/route-config.ts

@@ -7,47 +7,24 @@ 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}`
+    : 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}`
+      : T extends `${infer Name}?${string}`
         ? { name: Name; optional: true; type: string }
-        : // Param with dot-suffix: :param.html
-          T extends `${infer Name}.${string}`
+        : T extends `${infer Name}.${string}`
           ? { name: Name; optional: false; type: string }
-          : // Param with dash-suffix: :param-slug
-            T extends `${infer Name}-${string}`
+          : T extends `${infer Name}-${string}`
             ? { name: Name; optional: false; type: string }
-            : // Param with tilde-suffix: :param~v2
-              T extends `${infer Name}~${string}`
+            : T extends `${infer Name}~${string}`
               ? { name: Name; optional: false; type: string }
-              : // Required: :param (no suffix)
-                { name: T; optional: false; type: string };
+              : { name: T; optional: false; type: string };
 
-/**
- * Build param object from info
- */
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
   optional: true;
@@ -62,10 +39,6 @@ type ParamFromInfo<Info> = Info extends {
     ? { [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;
@@ -109,17 +82,11 @@ export type ExtractParams<
  */
 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;
 };
@@ -128,11 +95,6 @@ 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 = "",
@@ -153,18 +115,12 @@ type FlattenRoutes<
             : 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

@@ -1,9 +1,6 @@
 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;
@@ -25,9 +22,6 @@ export interface LazyIncludeContext {
   includeScope?: string;
 }
 
-/**
- * Internal route entry stored in router
- */
 export interface RouteEntry<TEnv = any> {
   prefix: string;
   /**

package/src/types/segments.ts

@@ -41,14 +41,6 @@ export interface TransitionConfig {
 /**
  * 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 {
@@ -89,11 +81,6 @@ export interface ResolvedSegment {
   _handlerRan?: boolean;
 }
 
-/**
- * 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";

package/src/urls/include-helper.ts

@@ -37,10 +37,8 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
     if (!item) continue;
 
     if (item.type === "include") {
-      // All includes are lazy; the router expands them on first matching request.
       result.push(item);
     } else if (item.type === "layout" && (item as any).uses) {
-      // Process nested items in layout
       const layoutItem = item as any;
       layoutItem.uses = processItems(layoutItem.uses);
       result.push(layoutItem);
@@ -141,8 +139,6 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
           ? (parentRootScoped ?? false)
           : parentRootScoped;
 
-    // All includes are lazy - patterns are evaluated on first matching request
-    // This improves cold start time significantly for large route sets
     return {
       type: "include",
       name,

package/src/urls/index.ts

@@ -1,4 +1,3 @@
-// Response types and symbols
 export {
   RESPONSE_TYPE,
   type ResponseHandler,
@@ -8,7 +7,6 @@ export {
   type ResponseHandlerContext,
 } from "./response-types.js";
 
-// Pattern types
 export type {
   UnnamedRoute,
   LocalOnlyInclude,
@@ -17,7 +15,6 @@ export type {
   IncludeOptions,
 } from "./pattern-types.js";
 
-// Type extraction utilities
 export type {
   ExtractRoutes,
   ExtractResponses,
@@ -25,7 +22,6 @@ export type {
   RouteResponse,
 } from "./type-extraction.js";
 
-// Path helper types
 export type {
   PathFn,
   ResponsePathFn,
@@ -35,10 +31,8 @@ export type {
   PathHelpers,
 } from "./path-helper-types.js";
 
-// Main entry point
 export { urls } from "./urls-function.js";
 
-// Re-exports from route-types
 export type {
   AllUseItems,
   IncludeItem,

package/src/urls/path-helper-types.ts

@@ -348,9 +348,9 @@ export type PathHelpers<TEnv> = {
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
-    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
   };