docs: add route cache JSDoc

Author: santiago-ramos-02

src/contexts/router-cache.tsx

@@ -11,26 +11,66 @@ import {
 } from "../route-cache-static-data";
 
 type RouterCacheProviderProps = {
+  /**
+   * Clears all cached routes when the key changes.
+   *
+   * Use this for user, tenant, workspace, locale, or environment boundaries.
+   *
+   * @defaultValue `"__default__"`
+   */
   cacheScopeKey?: string | number | null;
+  /** Outlet and surrounding UI that can access the route cache. */
   children: ReactNode;
+  /**
+   * Initial cached route entries.
+   *
+   * Most apps do not need this. Entries without enabled `staticData.routeCache`
+   * or entries older than their `maxAge` are ignored.
+   *
+   * @defaultValue `{}`
+   */
   defaultCachedRoutes?: CachedRoutes;
+  /**
+   * Maximum cached route entries across this provider.
+   *
+   * Set to `0` to disable caching.
+   *
+   * @defaultValue `Infinity`
+   */
   maxEntries?: number;
+  /**
+   * Maximum cached entries for the same TanStack route id.
+   *
+   * Useful for dynamic routes where each pathname can create a separate cached
+   * view.
+   *
+   * @defaultValue `Infinity`
+   */
   maxEntriesPerRouteId?: number;
 };
 
 type RouterSnapshot = ComponentProps<typeof RouterContextProvider>["router"];
 
 export type CachedRouteData = {
+  /** First time this cache entry was stored, as `Date.now()`. */
   createdAt?: number;
+  /** Full cached href, including search and hash when available. */
   href?: string;
+  /** Last time this cached route became visible, as `Date.now()`. */
   lastVisibleAt?: number;
+  /** TanStack Router route id used for per-route entry limits. */
   routeId?: string;
+  /** Static data from the deepest cache-enabled route match. */
   staticData: StaticDataRouteOption;
+  /** TanStack Router match id rendered by the cached outlet. */
   matchId?: string;
+  /** Router snapshot used to keep the cached route tree isolated while hidden. */
   routerSnapshot?: RouterSnapshot;
+  /** Whether the cached route has a complete snapshot and can be restored. */
   ready?: boolean;
 };
 
+/** Cached route entries keyed by normalized pathname. */
 export type CachedRoutes = {
   [key: string]: CachedRouteData;
 };

src/index.ts

@@ -16,6 +16,12 @@ export type * from "./types";
 declare module "@tanstack/react-router" {
   // biome-ignore lint/style/useConsistentTypeDefinitions: TanStack Router static data is extended through interface merging.
   interface StaticDataRouteOption {
+    /**
+     * Enables retained route-view caching for this route.
+     *
+     * Use `true` for default behavior, or pass an options object for
+     * route-cache-specific settings such as `maxAge`.
+     */
     routeCache?: RouteCacheStaticOption;
   }
 }

src/route-cache-static-data.ts

@@ -22,6 +22,12 @@ function getRouteCacheOptions(
   }
 }
 
+/**
+ * Builds route options for a cacheable TanStack Router route.
+ *
+ * TanStack Router loader-cache options are returned at the route-option level,
+ * while route-cache-specific options are stored under `staticData.routeCache`.
+ */
 export function defineRouteCache(options: RouteCacheRouteOptions = {}) {
   const { gcTime, maxAge, preloadStaleTime, staleTime } = options;
 

src/types.ts

@@ -1,24 +1,65 @@
+/** Visibility mode for a cached route container. */
 export type ActivityMode = "visible" | "hidden";
 
+/** Route-cache options stored in TanStack Router `staticData.routeCache`. */
 export type RouteCacheOptions = {
+  /**
+   * Maximum age, in milliseconds, for a retained route view.
+   *
+   * Expired cached views are not restored. This only controls the retained
+   * mounted view; use TanStack Router's `staleTime`, `preloadStaleTime`, and
+   * `gcTime` route options for loader-data caching.
+   *
+   * @defaultValue `Infinity`
+   */
   maxAge?: number;
 };
 
+/**
+ * Static route-cache opt-in value.
+ *
+ * Use `true` to keep the route view cached with default behavior, or an object
+ * when the retained view needs route-cache-specific options.
+ */
 export type RouteCacheStaticOption = boolean | RouteCacheOptions;
 
+/** Options accepted by `defineRouteCache`. */
 export type RouteCacheRouteOptions = RouteCacheOptions & {
+  /**
+   * TanStack Router loader garbage-collection time, in milliseconds.
+   *
+   * This is returned as a top-level route option.
+   */
   gcTime?: number;
+  /**
+   * TanStack Router preload freshness time, in milliseconds.
+   *
+   * This is returned as a top-level route option.
+   */
   preloadStaleTime?: number;
+  /**
+   * TanStack Router loader freshness time, in milliseconds.
+   *
+   * This is returned as a top-level route option and does not control the
+   * retained route view lifetime. Use `maxAge` for that.
+   */
   staleTime?: number;
 };
 
+/** Emitted when navigation to a ready cached route begins. */
 export type RouteCacheNavigationStart = {
+  /** Normalized pathname for the cached route being restored. */
   pathname: string;
+  /** `performance.now()` timestamp for the navigation start. */
   startedAt: number;
 };
 
+/** Emitted after a cached route has become visible and painted. */
 export type RouteCacheNavigationComplete = RouteCacheNavigationStart & {
+  /** Total elapsed time from start to painted, in milliseconds. */
   duration: number;
+  /** `performance.now()` timestamp after the visible route painted. */
   paintedAt: number;
+  /** `performance.now()` timestamp when the cached route became visible. */
   visibleAt: number;
 };