tanstack-router-cache 0.1.1 → 0.1.2

package/README.md

@@ -2,21 +2,21 @@
 
 Route view caching for [`@tanstack/react-router`](https://tanstack.com/router).
 
-`tanstack-router-cache` keeps selected route trees mounted while they are hidden, then restores them when the user navigates back. Use it for tab-like workflows, long forms, filtered lists, scroll positions, and page state that should survive route changes without moving everything into global state.
+Keep selected route trees mounted while they are hidden, then restore them when the user navigates back.
 
 ## Install
 
 ```sh
-bun add tanstack-router-cache
+npm install tanstack-router-cache
 ```
 
 ```sh
-npm install tanstack-router-cache
+bun add tanstack-router-cache
 ```
 
-## Consumer requirements
+## Requirements
 
-Your app should already use React and TanStack Router. This package keeps them as peer dependencies so it does not install a second router or React runtime.
+Your app should already install these packages:
 
 | Package | Supported versions |
 | --- | --- |
@@ -24,27 +24,23 @@ Your app should already use React and TanStack Router. This package keeps them a
 | `react-dom` | Match your React version. |
 | `@tanstack/react-router` | `>=1.168.14 <2.0.0` |
 
-## Maintenance
-
-This package is intended to stay compatible with current TanStack Router 1.x releases. The peer dependency floor is tested against the oldest version supported by the current implementation, while development tracks the latest compatible TanStack Router version.
-
 ## Usage
 
-Wrap the route tree that should support retention:
+Wrap your route outlet once:
 
 ```tsx
 import { RouterCacheOutlet, RouterCacheProvider } from "tanstack-router-cache";
 
 export function RootRoute() {
   return (
-    <RouterCacheProvider maxEntries={8} maxEntriesPerRouteId={2}>
+    <RouterCacheProvider>
       <RouterCacheOutlet />
     </RouterCacheProvider>
   );
 }
 ```
 
-Enable caching on a route:
+Enable caching on any route that should stay mounted:
 
 ```tsx
 export const Route = createFileRoute("/customers")({
@@ -55,29 +51,16 @@ export const Route = createFileRoute("/customers")({
 });
 ```
 
-Run work only while a retained route is visible:
+For the full API, see [docs](./docs).
 
-```tsx
-import { useRouteCacheEffect } from "tanstack-router-cache";
-
-function CustomersPage() {
-  useRouteCacheEffect(() => {
-    const controller = new AbortController();
-
-    return () => {
-      controller.abort();
-    };
-  }, []);
-
-  return <CustomersTable />;
-}
-```
+## Examples
 
-More usage details are in [docs/usage.md](./docs/usage.md).
+- [Basic](https://github.com/santiago-ramos-02/tanstack-router-cache/tree/main/examples/basic): the smallest useful setup. Start here; most apps only need this pattern.
+- [Power-user demo](https://github.com/santiago-ramos-02/tanstack-router-cache/tree/main/examples/power-user-demo): a larger demo with retained forms, filtered lists, cache controls, route lifecycle state, and window scroll restoration. Use it when you need to inspect edge cases.
 
 ## Acknowledgements
 
-This project originated from [`hemengke1997/tanstack-router-keepalive`](https://github.com/hemengke1997/tanstack-router-keepalive). The implementation has since diverged substantially, including current TanStack Router compatibility, cache limits, error handling, navigation lifecycle instrumentation, dependency updates, and memory-focused eviction.
+This project originated from [`hemengke1997/tanstack-router-keepalive`](https://github.com/hemengke1997/tanstack-router-keepalive), then diverged with current TanStack Router compatibility, a different API, cache limits, error handling, navigation lifecycle tools, dependency updates, and memory-focused eviction.
 
 ## License
 

package/dist/index.cjs

@@ -131,8 +131,9 @@ function RouterCacheProviderScope({ children, defaultCachedRoutes = EMPTY_CACHED
 		maxEntries: normalizeLimit(maxEntries),
 		maxEntriesPerRouteId: normalizeLimit(maxEntriesPerRouteId)
 	});
-	const initialCachedRoutes = (0, react.useRef)(applyCachedRouteLimits(filterRouterCacheRoutes(defaultCachedRoutes), cacheConfigRef.current, /* @__PURE__ */ new Set()));
-	const [cachedRoutes, setCachedRoutes] = (0, react.useState)(() => initialCachedRoutes.current);
+	const initialCachedRoutesRef = (0, react.useRef)(null);
+	if (initialCachedRoutesRef.current === null) initialCachedRoutesRef.current = applyCachedRouteLimits(filterRouterCacheRoutes(defaultCachedRoutes), cacheConfigRef.current, /* @__PURE__ */ new Set());
+	const [cachedRoutes, setCachedRoutes] = (0, react.useState)(() => initialCachedRoutesRef.current ?? EMPTY_CACHED_ROUTES);
 	const [erroredRouteCounts, setErroredRouteCounts] = (0, react.useState)({});
 	const updateCachedRoutes = (key, value) => {
 		setCachedRoutes((state) => getNextCachedRoutesState({
@@ -340,7 +341,8 @@ function isProduction() {
 function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 	const warningThresholdRef = (0, react.useRef)(null);
 	const lastWarnedCountRef = (0, react.useRef)(null);
-	const lastSnapshotRef = (0, react.useRef)(buildSnapshot(cachedRoutes, visiblePathname));
+	const lastSnapshotRef = (0, react.useRef)(null);
+	if (lastSnapshotRef.current === null) lastSnapshotRef.current = buildSnapshot(cachedRoutes, visiblePathname);
 	const snapshot = (0, react.useMemo)(() => buildSnapshot(cachedRoutes, visiblePathname), [cachedRoutes, visiblePathname]);
 	(0, react.useEffect)(() => {
 		if (isProduction()) return;
@@ -351,7 +353,7 @@ function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 			return lastSnapshotRef.current;
 		};
 		const api = {
-			getSnapshot: () => lastSnapshotRef.current,
+			getSnapshot: () => lastSnapshotRef.current ?? snapshot,
 			lastSnapshot: snapshot,
 			refresh,
 			setWarningThreshold: (nextThreshold) => {
@@ -623,6 +625,30 @@ function dismissTransientUi(container, pathname) {
 //#endregion
 //#region src/components/off-screen-in.tsx
 const windowScrollPositions = /* @__PURE__ */ new Map();
+const IMMEDIATE_SCROLL_RESTORE_DELAY = 0;
+const EARLY_SCROLL_RESTORE_DELAY = 80;
+const MIDDLE_SCROLL_RESTORE_DELAY = 240;
+const LATE_SCROLL_RESTORE_DELAY = 600;
+const FINAL_SCROLL_RESTORE_DELAY = 1e3;
+const SCROLL_TRACKING_INTERVAL_MS = 200;
+const SCROLL_KEYS = new Set([
+	" ",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"ArrowUp",
+	"End",
+	"Home",
+	"PageDown",
+	"PageUp"
+]);
+const SCROLL_RESTORE_DELAYS = [
+	IMMEDIATE_SCROLL_RESTORE_DELAY,
+	EARLY_SCROLL_RESTORE_DELAY,
+	MIDDLE_SCROLL_RESTORE_DELAY,
+	LATE_SCROLL_RESTORE_DELAY,
+	FINAL_SCROLL_RESTORE_DELAY
+];
 function OffScreenIn(props) {
 	const { mode, children, containerRef, pathname } = props;
 	const localContainerRef = (0, react.useRef)(null);
@@ -653,26 +679,61 @@ function OffScreenIn(props) {
 				y: globalThis.scrollY
 			});
 		};
-		if (mode === "hidden") {
-			saveScrollPosition();
-			return;
-		}
+		if (mode === "hidden") return;
 		const savedPosition = windowScrollPositions.get(pathname);
-		const handleScroll = () => saveScrollPosition();
+		let userRequestedScroll = false;
+		let scrollTrackingIntervalId;
+		const startScrollTracking = () => {
+			scrollTrackingIntervalId ??= globalThis.setInterval(saveScrollPosition, SCROLL_TRACKING_INTERVAL_MS);
+		};
+		const handleScroll = () => {
+			if (!savedPosition || userRequestedScroll) saveScrollPosition();
+		};
+		const markUserRequestedScroll = () => {
+			userRequestedScroll = true;
+		};
+		const handleKeyDown = (event) => {
+			if (SCROLL_KEYS.has(event.key)) markUserRequestedScroll();
+		};
 		globalThis.addEventListener("scroll", handleScroll, { passive: true });
+		globalThis.addEventListener("wheel", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("touchstart", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("pointerdown", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("keydown", handleKeyDown);
 		if (!savedPosition) {
+			startScrollTracking();
 			saveScrollPosition();
-			return () => globalThis.removeEventListener("scroll", handleScroll);
+			return () => {
+				if (scrollTrackingIntervalId !== void 0) globalThis.clearInterval(scrollTrackingIntervalId);
+				globalThis.removeEventListener("scroll", handleScroll);
+				globalThis.removeEventListener("wheel", markUserRequestedScroll);
+				globalThis.removeEventListener("touchstart", markUserRequestedScroll);
+				globalThis.removeEventListener("pointerdown", markUserRequestedScroll);
+				globalThis.removeEventListener("keydown", handleKeyDown);
+			};
 		}
+		const restoreScrollPosition = () => {
+			if (userRequestedScroll) return;
+			globalThis.scrollTo(savedPosition.x, savedPosition.y);
+			saveScrollPosition();
+			startScrollTracking();
+		};
+		const timeoutIds = [];
 		let rafId = globalThis.requestAnimationFrame(() => {
 			rafId = globalThis.requestAnimationFrame(() => {
-				globalThis.scrollTo(savedPosition.x, savedPosition.y);
-				saveScrollPosition();
+				restoreScrollPosition();
+				for (const delay of SCROLL_RESTORE_DELAYS) timeoutIds.push(globalThis.setTimeout(restoreScrollPosition, delay));
 			});
 		});
 		return () => {
 			globalThis.cancelAnimationFrame(rafId);
+			for (const timeoutId of timeoutIds) globalThis.clearTimeout(timeoutId);
+			if (scrollTrackingIntervalId !== void 0) globalThis.clearInterval(scrollTrackingIntervalId);
 			globalThis.removeEventListener("scroll", handleScroll);
+			globalThis.removeEventListener("wheel", markUserRequestedScroll);
+			globalThis.removeEventListener("touchstart", markUserRequestedScroll);
+			globalThis.removeEventListener("pointerdown", markUserRequestedScroll);
+			globalThis.removeEventListener("keydown", handleKeyDown);
 		};
 	}, [mode, pathname]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Activity, {
@@ -742,15 +803,8 @@ function getLiveRouterMethodDescriptors(router) {
 		return [[methodName, { value: method.bind(router) }]];
 	}));
 }
-function isRouterSearch(value) {
-	return typeof value === "object" && value !== null;
-}
 function toRouterLocation(location) {
-	return {
-		href: location.href,
-		pathname: location.pathname,
-		search: isRouterSearch(location.search) ? location.search : void 0
-	};
+	return { ...location };
 }
 function isReadyCachedRoute(route) {
 	return Boolean(route && isRouteCacheEnabled(route.staticData) && route.ready && route.matchId && route.routerSnapshot);
@@ -962,7 +1016,8 @@ function RouteCacheManager() {
 	const pendingCachedNavigationRef = (0, react.useRef)(null);
 	const previousPathnameRef = (0, react.useRef)(void 0);
 	const previousHrefRef = (0, react.useRef)(void 0);
-	const previousRouteCacheModesRef = (0, react.useRef)(/* @__PURE__ */ new Map());
+	const previousRouteCacheModesRef = (0, react.useRef)(null);
+	if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
 	const previousVisiblePathnameRef = (0, react.useRef)(void 0);
 	const routerLocation = (0, _tanstack_react_router.useRouterState)({ select: (state) => toRouterLocation(state.location) });
 	const routerHref = routerLocation.href;
@@ -1058,6 +1113,7 @@ function RouteCacheManager() {
 		visiblePathname
 	]);
 	(0, react.useLayoutEffect)(() => {
+		if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
 		previousRouteCacheModesRef.current = syncCachedRouteActivityEvents({
 			cachedRoutes,
 			eventListener,

package/dist/index.js

@@ -130,8 +130,9 @@ function RouterCacheProviderScope({ children, defaultCachedRoutes = EMPTY_CACHED
 		maxEntries: normalizeLimit(maxEntries),
 		maxEntriesPerRouteId: normalizeLimit(maxEntriesPerRouteId)
 	});
-	const initialCachedRoutes = useRef(applyCachedRouteLimits(filterRouterCacheRoutes(defaultCachedRoutes), cacheConfigRef.current, /* @__PURE__ */ new Set()));
-	const [cachedRoutes, setCachedRoutes] = useState(() => initialCachedRoutes.current);
+	const initialCachedRoutesRef = useRef(null);
+	if (initialCachedRoutesRef.current === null) initialCachedRoutesRef.current = applyCachedRouteLimits(filterRouterCacheRoutes(defaultCachedRoutes), cacheConfigRef.current, /* @__PURE__ */ new Set());
+	const [cachedRoutes, setCachedRoutes] = useState(() => initialCachedRoutesRef.current ?? EMPTY_CACHED_ROUTES);
 	const [erroredRouteCounts, setErroredRouteCounts] = useState({});
 	const updateCachedRoutes = (key, value) => {
 		setCachedRoutes((state) => getNextCachedRoutesState({
@@ -339,7 +340,8 @@ function isProduction() {
 function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 	const warningThresholdRef = useRef(null);
 	const lastWarnedCountRef = useRef(null);
-	const lastSnapshotRef = useRef(buildSnapshot(cachedRoutes, visiblePathname));
+	const lastSnapshotRef = useRef(null);
+	if (lastSnapshotRef.current === null) lastSnapshotRef.current = buildSnapshot(cachedRoutes, visiblePathname);
 	const snapshot = useMemo(() => buildSnapshot(cachedRoutes, visiblePathname), [cachedRoutes, visiblePathname]);
 	useEffect(() => {
 		if (isProduction()) return;
@@ -350,7 +352,7 @@ function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 			return lastSnapshotRef.current;
 		};
 		const api = {
-			getSnapshot: () => lastSnapshotRef.current,
+			getSnapshot: () => lastSnapshotRef.current ?? snapshot,
 			lastSnapshot: snapshot,
 			refresh,
 			setWarningThreshold: (nextThreshold) => {
@@ -622,6 +624,30 @@ function dismissTransientUi(container, pathname) {
 //#endregion
 //#region src/components/off-screen-in.tsx
 const windowScrollPositions = /* @__PURE__ */ new Map();
+const IMMEDIATE_SCROLL_RESTORE_DELAY = 0;
+const EARLY_SCROLL_RESTORE_DELAY = 80;
+const MIDDLE_SCROLL_RESTORE_DELAY = 240;
+const LATE_SCROLL_RESTORE_DELAY = 600;
+const FINAL_SCROLL_RESTORE_DELAY = 1e3;
+const SCROLL_TRACKING_INTERVAL_MS = 200;
+const SCROLL_KEYS = new Set([
+	" ",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+	"ArrowUp",
+	"End",
+	"Home",
+	"PageDown",
+	"PageUp"
+]);
+const SCROLL_RESTORE_DELAYS = [
+	IMMEDIATE_SCROLL_RESTORE_DELAY,
+	EARLY_SCROLL_RESTORE_DELAY,
+	MIDDLE_SCROLL_RESTORE_DELAY,
+	LATE_SCROLL_RESTORE_DELAY,
+	FINAL_SCROLL_RESTORE_DELAY
+];
 function OffScreenIn(props) {
 	const { mode, children, containerRef, pathname } = props;
 	const localContainerRef = useRef(null);
@@ -652,26 +678,61 @@ function OffScreenIn(props) {
 				y: globalThis.scrollY
 			});
 		};
-		if (mode === "hidden") {
-			saveScrollPosition();
-			return;
-		}
+		if (mode === "hidden") return;
 		const savedPosition = windowScrollPositions.get(pathname);
-		const handleScroll = () => saveScrollPosition();
+		let userRequestedScroll = false;
+		let scrollTrackingIntervalId;
+		const startScrollTracking = () => {
+			scrollTrackingIntervalId ??= globalThis.setInterval(saveScrollPosition, SCROLL_TRACKING_INTERVAL_MS);
+		};
+		const handleScroll = () => {
+			if (!savedPosition || userRequestedScroll) saveScrollPosition();
+		};
+		const markUserRequestedScroll = () => {
+			userRequestedScroll = true;
+		};
+		const handleKeyDown = (event) => {
+			if (SCROLL_KEYS.has(event.key)) markUserRequestedScroll();
+		};
 		globalThis.addEventListener("scroll", handleScroll, { passive: true });
+		globalThis.addEventListener("wheel", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("touchstart", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("pointerdown", markUserRequestedScroll, { passive: true });
+		globalThis.addEventListener("keydown", handleKeyDown);
 		if (!savedPosition) {
+			startScrollTracking();
 			saveScrollPosition();
-			return () => globalThis.removeEventListener("scroll", handleScroll);
+			return () => {
+				if (scrollTrackingIntervalId !== void 0) globalThis.clearInterval(scrollTrackingIntervalId);
+				globalThis.removeEventListener("scroll", handleScroll);
+				globalThis.removeEventListener("wheel", markUserRequestedScroll);
+				globalThis.removeEventListener("touchstart", markUserRequestedScroll);
+				globalThis.removeEventListener("pointerdown", markUserRequestedScroll);
+				globalThis.removeEventListener("keydown", handleKeyDown);
+			};
 		}
+		const restoreScrollPosition = () => {
+			if (userRequestedScroll) return;
+			globalThis.scrollTo(savedPosition.x, savedPosition.y);
+			saveScrollPosition();
+			startScrollTracking();
+		};
+		const timeoutIds = [];
 		let rafId = globalThis.requestAnimationFrame(() => {
 			rafId = globalThis.requestAnimationFrame(() => {
-				globalThis.scrollTo(savedPosition.x, savedPosition.y);
-				saveScrollPosition();
+				restoreScrollPosition();
+				for (const delay of SCROLL_RESTORE_DELAYS) timeoutIds.push(globalThis.setTimeout(restoreScrollPosition, delay));
 			});
 		});
 		return () => {
 			globalThis.cancelAnimationFrame(rafId);
+			for (const timeoutId of timeoutIds) globalThis.clearTimeout(timeoutId);
+			if (scrollTrackingIntervalId !== void 0) globalThis.clearInterval(scrollTrackingIntervalId);
 			globalThis.removeEventListener("scroll", handleScroll);
+			globalThis.removeEventListener("wheel", markUserRequestedScroll);
+			globalThis.removeEventListener("touchstart", markUserRequestedScroll);
+			globalThis.removeEventListener("pointerdown", markUserRequestedScroll);
+			globalThis.removeEventListener("keydown", handleKeyDown);
 		};
 	}, [mode, pathname]);
 	return /* @__PURE__ */ jsx(Activity, {
@@ -741,15 +802,8 @@ function getLiveRouterMethodDescriptors(router) {
 		return [[methodName, { value: method.bind(router) }]];
 	}));
 }
-function isRouterSearch(value) {
-	return typeof value === "object" && value !== null;
-}
 function toRouterLocation(location) {
-	return {
-		href: location.href,
-		pathname: location.pathname,
-		search: isRouterSearch(location.search) ? location.search : void 0
-	};
+	return { ...location };
 }
 function isReadyCachedRoute(route) {
 	return Boolean(route && isRouteCacheEnabled(route.staticData) && route.ready && route.matchId && route.routerSnapshot);
@@ -961,7 +1015,8 @@ function RouteCacheManager() {
 	const pendingCachedNavigationRef = useRef(null);
 	const previousPathnameRef = useRef(void 0);
 	const previousHrefRef = useRef(void 0);
-	const previousRouteCacheModesRef = useRef(/* @__PURE__ */ new Map());
+	const previousRouteCacheModesRef = useRef(null);
+	if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
 	const previousVisiblePathnameRef = useRef(void 0);
 	const routerLocation = useRouterState({ select: (state) => toRouterLocation(state.location) });
 	const routerHref = routerLocation.href;
@@ -1057,6 +1112,7 @@ function RouteCacheManager() {
 		visiblePathname
 	]);
 	useLayoutEffect(() => {
+		if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
 		previousRouteCacheModesRef.current = syncCachedRouteActivityEvents({
 			cachedRoutes,
 			eventListener,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-router-cache",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Route view caching for TanStack Router.",
   "type": "module",
   "license": "MIT",
@@ -46,8 +46,8 @@
     "build": "bun run clean && rolldown -c && tsc",
     "typecheck": "tsc --noEmit",
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
-    "lint": "biome check .",
-    "lint:fix": "biome check . --write",
+    "lint": "biome lint src rolldown.config.ts --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
+    "lint:fix": "biome lint src rolldown.config.ts --write --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
     "pack:dry-run": "bun pm pack --dry-run",
     "prepack": "bun run build",
     "prepublishOnly": "bun run lint && bun run typecheck"