tanstack-router-cache 0.1.7 → 0.1.8

package/dist/pathname.cjs

@@ -0,0 +1,8 @@
+//#region src/pathname.ts
+const TRAILING_SLASHES_REGEX = /\/+$/u;
+function normalizeCachedRoutePathname(pathname) {
+	if (pathname === "/") return pathname;
+	return pathname.replace(TRAILING_SLASHES_REGEX, "");
+}
+//#endregion
+exports.normalizeCachedRoutePathname = normalizeCachedRoutePathname;

package/dist/pathname.js

@@ -0,0 +1,8 @@
+//#region src/pathname.ts
+const TRAILING_SLASHES_REGEX = /\/+$/u;
+function normalizeCachedRoutePathname(pathname) {
+	if (pathname === "/") return pathname;
+	return pathname.replace(TRAILING_SLASHES_REGEX, "");
+}
+//#endregion
+export { normalizeCachedRoutePathname };

package/dist/route-cache-static-data.cjs

@@ -0,0 +1,43 @@
+//#region src/route-cache-static-data.ts
+const DEFAULT_ROUTE_CACHE_MAX_AGE = Number.POSITIVE_INFINITY;
+function getRouteCacheOptions(staticData) {
+	const routeCache = staticData?.routeCache;
+	if (routeCache === true) return {};
+	if (routeCache && typeof routeCache === "object") return routeCache;
+}
+/**
+* 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`.
+*/
+function defineRouteCache(options = {}) {
+	const { gcTime, maxAge, preloadStaleTime, staleTime } = options;
+	return {
+		...gcTime === void 0 ? {} : { gcTime },
+		...preloadStaleTime === void 0 ? {} : { preloadStaleTime },
+		...staleTime === void 0 ? {} : { staleTime },
+		staticData: { routeCache: maxAge === void 0 ? true : { maxAge } }
+	};
+}
+function isRouteCacheEnabled(staticData) {
+	return Boolean(getRouteCacheOptions(staticData));
+}
+function normalizeRouteCacheMaxAge(maxAge) {
+	if (typeof maxAge !== "number" || Number.isNaN(maxAge)) return DEFAULT_ROUTE_CACHE_MAX_AGE;
+	if (!Number.isFinite(maxAge)) return DEFAULT_ROUTE_CACHE_MAX_AGE;
+	return Math.max(maxAge, 0);
+}
+function getRouteCacheMaxAge(staticData) {
+	return normalizeRouteCacheMaxAge(getRouteCacheOptions(staticData)?.maxAge);
+}
+function isCachedRouteStale(route, now = Date.now()) {
+	if (!route) return false;
+	const maxAge = getRouteCacheMaxAge(route.staticData);
+	if (maxAge === DEFAULT_ROUTE_CACHE_MAX_AGE) return false;
+	return now - (route.createdAt ?? now) > maxAge;
+}
+//#endregion
+exports.defineRouteCache = defineRouteCache;
+exports.isCachedRouteStale = isCachedRouteStale;
+exports.isRouteCacheEnabled = isRouteCacheEnabled;

package/dist/route-cache-static-data.d.ts

@@ -0,0 +1,25 @@
+import type { StaticDataRouteOption } from "@tanstack/react-router";
+import type { RouteCacheRouteOptions } from "./types";
+type CachedRouteTiming = {
+    createdAt?: number;
+    staticData: StaticDataRouteOption;
+};
+/**
+ * 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 declare function defineRouteCache(options?: RouteCacheRouteOptions): {
+    staticData: {
+        routeCache: boolean | {
+            maxAge: number;
+        };
+    };
+    staleTime?: number | undefined;
+    preloadStaleTime?: number | undefined;
+    gcTime?: number | undefined;
+};
+export declare function isRouteCacheEnabled(staticData: StaticDataRouteOption | undefined): boolean;
+export declare function isCachedRouteStale(route: CachedRouteTiming | undefined, now?: number): boolean;
+export {};

package/dist/route-cache-static-data.js

@@ -0,0 +1,41 @@
+//#region src/route-cache-static-data.ts
+const DEFAULT_ROUTE_CACHE_MAX_AGE = Number.POSITIVE_INFINITY;
+function getRouteCacheOptions(staticData) {
+	const routeCache = staticData?.routeCache;
+	if (routeCache === true) return {};
+	if (routeCache && typeof routeCache === "object") return routeCache;
+}
+/**
+* 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`.
+*/
+function defineRouteCache(options = {}) {
+	const { gcTime, maxAge, preloadStaleTime, staleTime } = options;
+	return {
+		...gcTime === void 0 ? {} : { gcTime },
+		...preloadStaleTime === void 0 ? {} : { preloadStaleTime },
+		...staleTime === void 0 ? {} : { staleTime },
+		staticData: { routeCache: maxAge === void 0 ? true : { maxAge } }
+	};
+}
+function isRouteCacheEnabled(staticData) {
+	return Boolean(getRouteCacheOptions(staticData));
+}
+function normalizeRouteCacheMaxAge(maxAge) {
+	if (typeof maxAge !== "number" || Number.isNaN(maxAge)) return DEFAULT_ROUTE_CACHE_MAX_AGE;
+	if (!Number.isFinite(maxAge)) return DEFAULT_ROUTE_CACHE_MAX_AGE;
+	return Math.max(maxAge, 0);
+}
+function getRouteCacheMaxAge(staticData) {
+	return normalizeRouteCacheMaxAge(getRouteCacheOptions(staticData)?.maxAge);
+}
+function isCachedRouteStale(route, now = Date.now()) {
+	if (!route) return false;
+	const maxAge = getRouteCacheMaxAge(route.staticData);
+	if (maxAge === DEFAULT_ROUTE_CACHE_MAX_AGE) return false;
+	return now - (route.createdAt ?? now) > maxAge;
+}
+//#endregion
+export { defineRouteCache, isCachedRouteStale, isRouteCacheEnabled };

package/dist/types.d.ts

@@ -1,10 +1,60 @@
+/** 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;
 };

package/docs/architecture.md

@@ -45,12 +45,12 @@ flowchart TD
 
 ## Route lifecycle
 
-A route becomes cacheable only after the current match is resolved, successful, and marked with `staticData.routeCache: true`.
+A route becomes cacheable only after the current match is resolved, successful, and marked with enabled `staticData.routeCache`.
 
 ```mermaid
 stateDiagram-v2
   [*] --> LiveRoute: normal TanStack render
-  LiveRoute --> WaitingForReady: routeCache true
+  LiveRoute --> WaitingForReady: routeCache enabled
   WaitingForReady --> CachedReady: match success and snapshot stored
   CachedReady --> VisibleCached: pathname is visible
   VisibleCached --> HiddenCached: navigate away
@@ -60,7 +60,7 @@ stateDiagram-v2
   Evicted --> [*]
 ```
 
-In normal usage, a cached route alternates between `visible` and `hidden`. It leaves the cache when a limit evicts it, the app invalidates it, the route stops being cacheable, or an error boundary marks it as failed.
+In normal usage, a cached route alternates between `visible` and `hidden`. It leaves the cache when a limit evicts it, its route `maxAge` expires, the app invalidates it, the route stops being cacheable, or an error boundary marks it as failed.
 
 ## Provider state
 
@@ -147,7 +147,7 @@ classDiagram
 | `href` | Full route href, including search and hash when available. Used for restoration. |
 | `lastVisibleAt` | Last time the entry became visible. Primary eviction timestamp. |
 | `routeId` | TanStack route id. Used by `maxEntriesPerRouteId`. |
-| `staticData` | Route static data. The route is cacheable when `routeCache` is `true`. |
+| `staticData` | Route static data. The route is cacheable when `routeCache` is `true` or an options object. |
 | `matchId` | Match id used to render the cached route with TanStack Router's `Match`. |
 | `routerSnapshot` | Router-like object with isolated snapshot stores used by the cached route tree. |
 | `ready` | Marks that the route has a complete snapshot and can be rendered from cache. |
@@ -204,7 +204,7 @@ flowchart TD
   staticData["Find deepest routeCache static data"]
   errored{"Current route errored?"}
   resolved{"Match resolved?"}
-  cacheable{"routeCache true?"}
+  cacheable{"routeCache enabled?"}
   ready{"Match successful?"}
   write["Create or refresh cache entry"]
   deleteEntry["Delete cache entry"]
@@ -225,6 +225,8 @@ flowchart TD
 
 The current entry being written is protected during limit enforcement so the route that just became ready is not immediately evicted.
 
+Cached entries with a route `maxAge` are treated as expired when their age exceeds that value. Expired entries are not rendered from the snapshot and are removed on the next cache update.
+
 ## Visible pathname
 
 The manager tracks three pathnames:
@@ -496,6 +498,7 @@ The memory controls are:
 - route opt-in through `staticData.routeCache`,
 - `maxEntries` for global cache size,
 - `maxEntriesPerRouteId` for dynamic routes,
+- route-level `maxAge` for expiring retained views,
 - `cacheScopeKey` for tenant, user, workspace, or environment resets,
 - `destroy`, `destroyAll`, and `invalidateWhere` for manual invalidation,
 - automatic deletion when a route stops being cacheable or enters an error state.

package/docs/cache-behavior.md

@@ -5,6 +5,7 @@
 - Hidden cached routes are rendered in off-screen containers and receive active-change events.
 - Cached dynamic routes can grow memory use if every id is retained; use `maxEntriesPerRouteId` for those routes.
 - If a cached destination is restored with an outdated href, the package navigates back to the cached href with `replace: true` and `resetScroll: false`.
+- A route can use `staticData.routeCache.maxAge` to stop restoring an old retained view after a fixed age.
 
 ## Eviction
 
@@ -26,3 +27,19 @@ Use `cacheScopeKey` when cached views must not survive a user, tenant, workspace
 
 Changing the scope key clears existing cached route entries for that provider.
 
+## Route max age
+
+`maxAge` controls the lifetime of this package's retained route view. It does not replace TanStack Router's top-level `staleTime`, `preloadStaleTime`, or `gcTime` options.
+
+```tsx
+export const Route = createFileRoute("/customers")({
+  staticData: {
+    routeCache: {
+      maxAge: 10 * 60_000,
+    },
+  },
+  component: CustomersPage,
+});
+```
+
+When a cached entry is older than `maxAge`, the cache manager does not restore it. The live route renders and the expired cache entry is removed on the next cache update.

package/docs/components.md

@@ -19,7 +19,7 @@ Owns the route cache and exposes cache state to the rest of the package.
 | --- | --- | --- | --- |
 | `children` | `ReactNode` | Required | The outlet and surrounding UI that can use the cache. |
 | `cacheScopeKey` | `string | number | null` | `"__default__"` | Resets the entire cache when the key changes. Use this for tenant, user, workspace, or environment changes. |
-| `defaultCachedRoutes` | `CachedRoutes` | `{}` | Initial cache data. Most apps do not need this. Entries without `staticData.routeCache: true` are ignored. |
+| `defaultCachedRoutes` | `CachedRoutes` | `{}` | Initial cache data. Most apps do not need this. Entries without enabled `staticData.routeCache` or entries older than their `maxAge` are ignored. |
 | `maxEntries` | `number` | `Infinity` | Maximum cached route entries across the provider. `0` disables caching. Non-finite or invalid values are treated as `Infinity`. |
 | `maxEntriesPerRouteId` | `number` | `Infinity` | Maximum cached entries for the same TanStack route id. Useful for dynamic routes such as `/customers/$id`. |
 
@@ -38,4 +38,3 @@ Renders the live TanStack Router outlet and any hidden cached route views.
 | `children` | `ReactNode` | `undefined` | Optional content rendered after the outlet manager. |
 
 Use one `RouterCacheOutlet` inside a `RouterCacheProvider` for the route branch you want to cache.
-

package/docs/getting-started.md

@@ -70,7 +70,25 @@ export const Route = createFileRoute("/customers")({
 });
 ```
 
-Routes without `routeCache: true` are rendered and unmounted by TanStack Router normally.
+Routes without enabled `routeCache` are rendered and unmounted by TanStack Router normally.
+
+When you also need TanStack Router loader cache options, use `defineRouteCache`. It keeps Router options at the top level of the route config while adding the `staticData.routeCache` opt-in for this package.
+
+```tsx
+import { defineRouteCache } from "tanstack-router-cache";
+
+export const Route = createFileRoute("/customers")({
+  ...defineRouteCache({
+    gcTime: Number.POSITIVE_INFINITY,
+    maxAge: 10 * 60_000,
+    preloadStaleTime: 30_000,
+    staleTime: Number.POSITIVE_INFINITY,
+  }),
+  component: CustomersPage,
+});
+```
+
+In that example, `staleTime`, `preloadStaleTime`, and `gcTime` are TanStack Router route options. `maxAge` is the route-cache view lifetime; after that age the cached view is not restored and the live route renders again.
 
 ### 3. Pause route work while hidden
 
@@ -123,7 +141,7 @@ export const Route = createFileRoute("/customers")({
 });
 ```
 
-Routes without `routeCache: true` are rendered normally and are removed when TanStack Router unmounts them.
+Routes without enabled `routeCache` are rendered normally and are removed when TanStack Router unmounts them.
 
 ## Route static data
 
@@ -132,7 +150,11 @@ The package augments TanStack Router's `StaticDataRouteOption` type:
 ```ts
 declare module "@tanstack/react-router" {
   interface StaticDataRouteOption {
-    routeCache?: boolean;
+    routeCache?:
+      | boolean
+      | {
+          maxAge?: number;
+        };
   }
 }
 ```
@@ -148,4 +170,17 @@ export const Route = createFileRoute("/reports")({
 });
 ```
 
+Use an object when the retained route view should expire independently from TanStack Router's loader cache:
+
+```tsx
+export const Route = createFileRoute("/reports")({
+  staticData: {
+    routeCache: {
+      maxAge: 5 * 60_000,
+    },
+  },
+  component: ReportsPage,
+});
+```
+
 If multiple child matches are present, the cache manager checks child route static data from deepest to shallowest and uses the deepest retained route data.

package/docs/types.md

@@ -5,6 +5,18 @@
 ```ts
 export type ActivityMode = "visible" | "hidden";
 
+export type RouteCacheOptions = {
+  maxAge?: number;
+};
+
+export type RouteCacheStaticOption = boolean | RouteCacheOptions;
+
+export type RouteCacheRouteOptions = RouteCacheOptions & {
+  gcTime?: number;
+  preloadStaleTime?: number;
+  staleTime?: number;
+};
+
 export type RouteCacheNavigationStart = {
   pathname: string;
   startedAt: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-router-cache",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Route view caching for TanStack Router.",
   "type": "module",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@types/react-dom": "19.2.3",
     "react": "19.2.7",
     "react-dom": "19.2.7",
-    "rolldown": "1.1.1",
+    "rolldown": "1.1.2",
     "typescript": "6.0.3"
   }
 }