clear-react-router 2.0.0 → 2.0.3

package/README.md

@@ -22,17 +22,17 @@ It provides first-class support for:
 ## Features
 
 - **Nested Routes** - Organize your UI with nested layouts and routes
-- **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
+- **Data Loading** - Built-in loaders with TTL-based caching (`staleTime`)
 - **Navigation Blocking** - Prevent accidental navigation with `useBlocker`
 - **Smooth Animations** - Page transitions with fade effect (customizable duration)
 - **Static Layout** — Keep navbar, footer, and other elements outside the router to avoid unnecessary re-renders
 - **Programmatic Redirects** - Redirect from beforeLoad hook
 - **Cache invalidation** - Manual route invalidation
+- **Bounded Cache** - Automatically evicts least recently used entries once `maxCacheSize` is reached, keeping memory usage predictable in long sessions
 - **Prefetching** - Preload data on hover for instant navigation
 - **Lazy Loading** - Code-split your routes with dynamic imports for optimal performance
 - **Scroll Restoration** — Automatically saves and restores scroll position when navigating back to a page (preserves user's scroll position)
 - **Optimistic navigation** — Instantly renders stale cached data while fresh data is loaded in the background.
-- **Flexible API** - Use components or hooks as you prefer
 - **Browser History** - Full support for browser back/forward buttons
 - **Context-aware** - Pass and update context through routes
 
@@ -43,6 +43,7 @@ It provides first-class support for:
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `routes` | `RouteItem[]` | required | Array of route configurations |
+| `maxCacheSize` | `number \| undefined` | 60 for mobile, 150 for desktop | Maximum number of cached loader entries. Once the limit is reached, the least recently used entries are evicted |
 | `isAnimated` | `boolean \| undefined` | `false` | Enable smooth page fade transitions |
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
 | `spinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
@@ -79,7 +80,7 @@ Normalizes route configuration. Extracts dynamic params, builds nested paths.
 | `path` | `string` | Route path, e.g., `/user/:userId` |
 | `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
 | `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | Runs before every route navigation. Auth checks and redirects. Can update context via `setContext`. `redirect` is provided by the router |
-| `loader` | `({ params, context, setContext, searchParams }) => Promise<unknown>` | Fetch data using route params, search params, and context. Can update context via `setContext` |
+| `loader` | `({ params, context, setContext, searchParams, signal }) => Promise<unknown>` | Fetch data using route params, search params, abort controller signal and context. Can update context via `setContext` |
 | `afterLoad` | `({ params, context, setContext }) => Promise<void>` | Runs after a successful navigation once the route has finished loading. Analytics, side effects after data is loaded. Can update context via `setContext` |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback for the route's `loader`. Overrides the global `defaultLoaderFallback` set in `Router` |
@@ -98,6 +99,7 @@ Loader arguments:
   context: Record<string, unknown>;                                 // Router context
   setContext: Dispatch<SetStateAction<Record<string, unknown>>>;    // Updates the router context
   searchParams: Record<string, string>;                             // URL search parameters
+  signal: AbortSignal;                                              // AbortController signal
 }
 ```
 
@@ -563,16 +565,24 @@ const UserProfile = () => {
 ```
 
 ### Caching behavior:
+
 - The loader result is cached and reused when navigating back to the same route (e.g., from /user/123 back to /user/456 it will be a new request because different params, but from /user/456 to /user/456 — cache hit).
-- Use staleTime in route config to control how long cache is considered fresh:
-```
+- Use `staleTime` in route config to control how long cache is considered fresh:
+
+```tsx
 {
   path: '/user/:userId',
   loader: async ({ params }) => fetchUser(params.userId),
   staleTime: 60000, // 1 minute — cache is fresh for 60 seconds
 }
 ```
- - Stale cache entries are cleaned up incrementally on every navigation, keeping the loader cache from growing unbounded over long sessions.
+
+- Stale entries are cleaned up on every navigation, so cache growth stays tied to how often you actually revisit stale data — not to how long the session lasts.
+- On top of that, the cache is bounded by `maxCacheSize` — once the limit is reached, the least recently used entry is evicted to make room for a new one, regardless of whether it's still fresh. This caps memory usage for apps with many high-cardinality dynamic routes (e.g. `/product/:id` across a large catalog). It defaults to a device-aware value (lower on mobile) and can be overridden on the `Router`:
+
+```tsx
+<Router routes={routes} maxCacheSize={200} />
+```
 
 
 ### `useInvalidate()`

package/dist/components/Router.d.ts

@@ -1,2 +1,2 @@
 import { RouterProps } from '../types';
-export declare const Router: ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated, spinner, defaultPreserveScroll, showFallbackOnAnimation, defaultPrefetch, defaultHoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Router: ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated, spinner, defaultPreserveScroll, showFallbackOnAnimation, maxCacheSize, defaultPrefetch, defaultHoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/config/routerConfig.d.ts

@@ -1,6 +1,7 @@
 import { ClientRouteItem, RouterProps } from '../types';
 declare class RouterConfig {
     routes: RouterProps['routes'];
+    maxCacheSize: number;
     defaultPrefetch: RouterProps['defaultPrefetch'];
     isAnimated: RouterProps['isAnimated'];
     defaultHoverPrefetchDelay: number;

package/dist/index.js

@@ -86,6 +86,7 @@ function _defineProperty(e, r, t) {
 var RouterConfig = class {
 	constructor() {
 		_defineProperty(this, "routes", []);
+		_defineProperty(this, "maxCacheSize", 0);
 		_defineProperty(this, "defaultPrefetch", "hover");
 		_defineProperty(this, "isAnimated", false);
 		_defineProperty(this, "defaultHoverPrefetchDelay", 150);
@@ -113,8 +114,8 @@ var createCommitNavigation = (navigationExecutor, routeItemDataState) => (nextLo
 };
 //#endregion
 //#region utils/isCacheItemFresh.ts
-var createIsCacheItemFresh = (loaderMap) => (pathname, search) => {
-	const item = loaderMap.get(`${pathname}${search}`);
+var createIsCacheItemFresh = (loaderMap) => (path) => {
+	const item = loaderMap.get(path);
 	if (item === void 0) return false;
 	const resolvedStaleTime = item.staleTime ?? routerConfig.defaultStaleTime;
 	if (resolvedStaleTime === void 0) return true;
@@ -220,12 +221,18 @@ var findRoute = (pathname, includeAll) => {
 };
 //#endregion
 //#region runtime/navigate.ts
-var navigationSeq = 0;
-var interval = 0;
 var createNavigate = (routerState, revalidateCache) => {
+	let navigationSeq = 0;
+	let interval = 0;
+	let abortController = null;
 	const { loaderStateRef, scrollMapState, pendingState, contextState, loaderMap, routeItemDataState } = routerState;
 	const commitNavigation = createCommitNavigation(createCommitState(routerState), routeItemDataState);
 	const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
+	const createSignal = () => {
+		abortController?.abort();
+		abortController = new AbortController();
+		return abortController.signal;
+	};
 	const getContext = () => ({
 		context: contextState.getState(),
 		setContext: contextState.setState
@@ -272,37 +279,44 @@ var createNavigate = (routerState, revalidateCache) => {
 				[prevPathname]: scrollPosition
 			};
 		});
-		if (routeItem?.optimistic && loaderMap.has(location.pathname)) {
+		const path = `${location.pathname}${location.search}`;
+		if (routeItem?.optimistic && loaderMap.has(path)) {
 			routeItemDataState.setState({
 				routeItem,
 				location
 			});
-			const currentLoaderState = loaderMap.get(location.pathname)?.state;
+			const currentLoaderState = loaderMap.get(path)?.state;
 			if (currentLoaderState) loaderStateRef.set(currentLoaderState);
 		} else {
-			const pendingShouldExist = routeItem?.loader && !isCacheItemFresh(location.pathname, location.search);
+			const pendingShouldExist = routeItem?.loader && !isCacheItemFresh(path);
 			pendingState.setState(pendingShouldExist ? {
 				routeItem,
 				location
 			} : void 0);
 		}
 	};
-	const afterEachLoad = (routeItem, location) => {
+	const polling = (routeItem, location) => {
 		if (!routeItem?.pollingInterval) return;
+		const signal = createSignal();
 		interval = window.setInterval(() => revalidateCache({
 			routeItem,
-			pathname: location.pathname
+			pathname: location.pathname,
+			search: location.search,
+			signal
 		}), routeItem.pollingInterval);
 	};
-	const loader = async (routeItem, location) => {
+	const loader = async (routeItem, location, seq) => {
 		if (!routeItem?.loader) return;
 		window.clearInterval(interval);
+		const signal = createSignal();
 		await revalidateCache({
 			routeItem,
 			pathname: location.pathname,
-			search: location.search
+			search: location.search,
+			signal
 		});
-		afterEachLoad(routeItem, location);
+		if (seq !== navigationSeq) return;
+		polling(routeItem, location);
 	};
 	const afterLoad = async (routeItem, params) => {
 		const { defaultAfterLoad } = routerConfig;
@@ -322,7 +336,7 @@ var createNavigate = (routerState, revalidateCache) => {
 		await beforeLoad(nextItem, params);
 		if (seq !== navigationSeq) return;
 		prepareNavigation(nextItem, nextLocation);
-		await loader(nextItem, nextLocation);
+		await loader(nextItem, nextLocation, seq);
 		if (seq !== navigationSeq) return;
 		commitNavigation(nextLocation, nextItem);
 		await afterLoad(nextItem, params);
@@ -331,7 +345,7 @@ var createNavigate = (routerState, revalidateCache) => {
 };
 //#endregion
 //#region runtime/invalidate.ts
-var redirect = () => Promise.resolve();
+var redirect = Promise.resolve;
 var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }, revalidateCache) => {
 	const invalidatePath = async (routeItem, pathname, options) => {
 		const routePathname = routeItemDataState.getState().location.pathname;
@@ -398,7 +412,6 @@ var createPrefetch = (revalidateCache) => async (pathname) => {
 };
 //#endregion
 //#region utils/revalidateCache.ts
-var loadingPromises = /* @__PURE__ */ new Map();
 var isObjectRetry = (arg) => typeof arg === "object";
 var createRetry = (arg) => {
 	if (arg === void 0) return null;
@@ -418,26 +431,44 @@ var getRetry = (routeItem) => {
 };
 var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
-	const { loaderStateRef, contextState, loaderMap } = routerState;
-	const removeFirstStaleItem = () => {
-		const deletedItem = [...loaderMap.entries()].find(([, item]) => {
+	const { loaderStateRef, contextState, loaderMap, loadingPromises } = routerState;
+	const removeStaleItems = () => {
+		const deletedItems = [...loaderMap.entries()].filter(([, item]) => {
 			const staleTime = item.staleTime ?? routerConfig.defaultStaleTime;
 			return staleTime && staleTime + item.timestamp < Date.now();
 		});
-		if (deletedItem) loaderMap.delete(deletedItem[0]);
+		if (deletedItems.length) deletedItems.forEach((item) => loaderMap.delete(item[0]));
 	};
-	const revalidateCache = async ({ routeItem, pathname, search = "" }, retried = 0) => {
+	const evict = () => {
+		if (loaderMap.size <= routerConfig.maxCacheSize) return;
+		const oldestKey = loaderMap.keys().next().value;
+		if (oldestKey) loaderMap.delete(oldestKey);
+	};
+	const moveItemToLastPosition = (path) => {
+		const item = loaderMap.get(path);
+		if (item) {
+			loaderMap.delete(path);
+			loaderMap.set(path, item);
+		}
+		return item;
+	};
+	const revalidateCache = async ({ routeItem, pathname, search = "", signal }, retried = 0) => {
 		if (!routeItem?.loader) return;
 		const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
-		removeFirstStaleItem();
-		if (loadingPromises.has(pathname)) return loadingPromises.get(`${pathname}${search}`);
-		if (isCacheItemFresh(pathname, search)) {
-			const item = loaderMap.get(`${pathname}${search}`);
+		removeStaleItems();
+		const path = `${pathname}${search}`;
+		if (loadingPromises.has(path)) {
+			moveItemToLastPosition(path);
+			return loadingPromises.get(path);
+		}
+		if (isCacheItemFresh(path)) {
+			const item = moveItemToLastPosition(path);
 			if (item?.state) loaderStateRef.set(item.state);
 			return;
 		}
 		const promise = (async () => {
 			if (!routeItem?.loader) return;
+			const effectiveSignal = signal ?? new AbortController().signal;
 			try {
 				const context = contextState.getState();
 				const setContext = contextState.setState;
@@ -447,31 +478,38 @@ var createRevalidateCache = (routerState) => {
 					params,
 					context,
 					setContext,
-					searchParams
+					searchParams,
+					signal: effectiveSignal
 				});
 				loaderStateRef.set((prev) => ({
 					...prev,
 					data: result,
 					loaderError: null
 				}));
-				loaderMap.set(`${pathname}${search}`, {
+				loaderMap.set(path, {
 					state: loaderStateRef.value,
 					timestamp: Date.now(),
 					staleTime: routeItem.staleTime
 				});
+				evict();
 				return {
 					data: result,
 					error: null
 				};
 			} catch (error) {
+				if (effectiveSignal.aborted) return {
+					data: null,
+					error: null
+				};
 				const retry = getRetry(routeItem);
 				if (retry && retry.count > retried) {
-					loadingPromises.delete(`${pathname}${search}`);
+					loadingPromises.delete(path);
 					if (retry.delay) await sleep(retry.delay);
 					await revalidateCache({
 						routeItem,
 						pathname,
-						search
+						search,
+						signal
 					}, retried + 1);
 					return {
 						data: null,
@@ -489,10 +527,10 @@ var createRevalidateCache = (routerState) => {
 					};
 				}
 			} finally {
-				loadingPromises.delete(`${pathname}${search}`);
+				loadingPromises.delete(path);
 			}
 		})();
-		loadingPromises.set(`${pathname}${search}`, promise);
+		loadingPromises.set(path, promise);
 		return promise;
 	};
 	return revalidateCache;
@@ -528,7 +566,8 @@ var createRouterInstance = () => {
 			to: ""
 		}),
 		loaderStateRef: new Cell(emptyLoaderState),
-		loaderMap: /* @__PURE__ */ new Map()
+		loaderMap: /* @__PURE__ */ new Map(),
+		loadingPromises: /* @__PURE__ */ new Map()
 	};
 	const revalidateCache = createRevalidateCache(routerState);
 	const invalidate = createInvalidate(routerState, revalidateCache);
@@ -716,7 +755,9 @@ var renderElement = (Component) => {
 //#region components/Router.tsx
 var EmptyBoundary = ({ children }) => children;
 var IS_MOBILE = isMobile();
-var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated = false, spinner = true, defaultPreserveScroll = true, showFallbackOnAnimation = false, defaultPrefetch = IS_MOBILE ? "viewport" : "hover", defaultHoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
+var MOBILE_CACHE_SIZE = 60;
+var DESKTOP_CACHE_SIZE = 150;
+var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime, context: initialContext, isAnimated = false, spinner = true, defaultPreserveScroll = true, showFallbackOnAnimation = false, maxCacheSize = IS_MOBILE ? MOBILE_CACHE_SIZE : DESKTOP_CACHE_SIZE, defaultPrefetch = IS_MOBILE ? "viewport" : "hover", defaultHoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
 	const { useRouteItemData, usePendingState } = router.hooks;
 	const [routeItemData] = useRouteItemData();
 	const [pendingState] = usePendingState();
@@ -732,7 +773,8 @@ var Router = ({ routes, defaultBeforeLoad, defaultAfterLoad, animationDuration,
 		defaultAfterLoad,
 		defaultRetry,
 		defaultStaleTime,
-		defaultPreserveScroll
+		defaultPreserveScroll,
+		maxCacheSize
 	});
 	useApplyCustomAnimation(animationDuration);
 	useSetInitialContext(initialContext);

package/dist/types.d.ts

@@ -23,6 +23,7 @@ export type ClientRouteItem = {
         context: Record<string, unknown>;
         setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
         searchParams: Record<string, string>;
+        signal: AbortSignal;
     }): Promise<unknown>;
     loaderFallback?: RenderElement;
     errorElement?: RenderElement;
@@ -64,6 +65,7 @@ export type RevalidateCacheArgs = {
     pathname: string;
     routeItem?: RouteItem;
     search?: string;
+    signal?: AbortSignal;
 };
 export type LoaderState<T = unknown> = {
     data: T;
@@ -92,6 +94,7 @@ export type RouterProps = {
     showFallbackOnAnimation?: boolean;
     defaultPrefetch?: 'hover' | 'render' | 'viewport' | 'none';
     defaultHoverPrefetchDelay?: number;
+    maxCacheSize?: number;
     errorBoundary?: ComponentType<{
         children: ReactNode;
     }>;
@@ -104,6 +107,13 @@ export type LoaderStateItem = {
     timestamp: number;
     staleTime: number | undefined;
 };
+export type LoadingPromise = Promise<{
+    data: unknown;
+    error: null;
+} | {
+    data: null;
+    error: unknown;
+} | undefined>;
 export type RouterState = {
     routeItemDataState: Store<RouteItemData>;
     pendingState: Store<RouteItemData | undefined>;
@@ -116,6 +126,7 @@ export type RouterState = {
     }>;
     loaderStateRef: Cell<LoaderState>;
     loaderMap: Map<string, LoaderStateItem>;
+    loadingPromises: Map<string, LoadingPromise>;
 };
 export type RouterType = {
     state: Omit<RouterState, 'timestampMap'>;
@@ -147,10 +158,7 @@ export type InvalidateOptions = {
     withChildren?: boolean;
     withBeforeLoad?: boolean;
 };
-export type RevalidateCache = ({ routeItem, pathname, }: RevalidateCacheArgs) => Promise<{
-    data: unknown;
-    error: unknown;
-}>;
+export type RevalidateCache = (args: RevalidateCacheArgs) => LoadingPromise;
 export type Options = Partial<{
     onSuccess: (args: unknown) => void;
     onError: (args: unknown) => void;

package/dist/utils/isCacheItemFresh.d.ts

@@ -1,2 +1,2 @@
 import { LoaderStateItem } from '../types';
-export declare const createIsCacheItemFresh: (loaderMap: Map<string, LoaderStateItem>) => (pathname: string, search?: string) => boolean;
+export declare const createIsCacheItemFresh: (loaderMap: Map<string, LoaderStateItem>) => (path: string) => boolean;

package/dist/utils/revalidateCache.d.ts

@@ -1,2 +1,8 @@
 import { RevalidateCacheArgs, RouterState } from '../types';
-export declare const createRevalidateCache: (routerState: RouterState) => ({ routeItem, pathname, search }: RevalidateCacheArgs, retried?: number) => Promise<any>;
+export declare const createRevalidateCache: (routerState: RouterState) => ({ routeItem, pathname, search, signal }: RevalidateCacheArgs, retried?: number) => Promise<{
+    data: unknown;
+    error: null;
+} | {
+    data: null;
+    error: unknown;
+} | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "2.0.0",
+  "version": "2.0.3",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {