clear-react-router 1.8.8 → 1.9.0

package/README.md

@@ -48,10 +48,11 @@ It provides first-class support for:
 | `defaultLoaderFallback` | `ReactElement \| () => ReactElement` | `optional` | Default loading fallback for every route loader |
 | `defaultErrorElement` | `ReactElement \| () => ReactElement` | `optional` | Default error fallback for every route |
 | `defaultRetry` | `number \| { count: number; delay: number }` | `optional` | Default cache revalidation retry policy for all routes |
+| `defaultStaleTime` | `number` | `optional` | Default time in milliseconds before cached loader data is considered stale |
 | `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | `undefined` | Runs before every navigation. Useful for authentication, analytics, or updating shared context.            |
 | `afterLoad`  | `({ params, context, setContext }) => Promise<void>`  | `undefined` | Runs after every successful navigation. Useful for analytics, page tracking, or other global side effects. |
 | `spinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
-| `preserveScroll` | `boolean \| undefined` | `true` | Save and restore scroll position when navigating between pages |
+| `defaultPreserveScroll` | `boolean \| undefined` | `true` | Default value for save and restore scroll position when navigating between pages |
 | `showFallbackOnAnimation` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `'hover'` | Default prefetch strategy for all `<Link>` components |
 | `hoverPrefetchDelay` | `number` | `150` | Delay in milliseconds before prefetching on hover (only for `'hover'` strategy) |
@@ -76,15 +77,27 @@ 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` | Auth checks and redirects. Can update context via `setContext`. `redirect` is provided by the router |
-| `loader` | `({ params, context, setContext }) => Promise<unknown>` | Fetch data using route params and context. Can update context via `setContext` |
-| `afterLoad` | `({ params, context, setContext }) => Promise<void>` | Analytics, side effects after data is loaded. Can update context via `setContext` |
+| `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` |
+| `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` |
-| `retry` | `number \| { count: number; delay: number }` | `optional` | Overrides the global cache revalidation retry policy for this route |
+| `retry` | `number \| { count: number; delay: number }` | `undefined` | Overrides the global cache revalidation retry policy for this route |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback for the route. Overrides the global `defaultErrorElement` set in `Router` |
-| `staleTime` | `number` | Time in ms before cached data is considered stale and re-fetched in the background. If not provided, data never expires (cached forever) |
-| `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can refresh loader data using the router-provided `invalidate`. |
+| `staleTime` | `number` | Time in milliseconds before cached loader data is considered stale. Overrides Router.defaultStaleTime. If neither value is provided, cached data never expires |
+| `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can invalidate cached loader data using the router-provided `invalidate` |
+| `pollingInterval` | `number \| undefined` | `undefined` | Polling interval (in milliseconds) for automatically revalidating data while the route is active |
+| `preserveScroll` | `boolean \| undefined` | `undefined` | Save and restore route scroll position when navigating between pages |
+
+Loader arguments:
+```ts
+{
+  params: Record<string, string>;                                   // Route parameters
+  context: Record<string, unknown>;                                 // Router context
+  setContext: Dispatch<SetStateAction<Record<string, unknown>>>;    // Updates the router context
+  searchParams: Record<string, string>;                             // URL search parameters
+}
+```
 
 ### `Link`
 

package/dist/components/Router.d.ts

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

package/dist/config/routerConfig.d.ts

@@ -8,6 +8,8 @@ declare class RouterConfig {
     beforeLoad?: ClientRouteItem['beforeLoad'];
     afterLoad?: ClientRouteItem['afterLoad'];
     defaultRetry?: RouterProps['defaultRetry'];
+    defaultStaleTime?: RouterProps['defaultStaleTime'];
+    defaultPreserveScroll?: RouterProps['defaultPreserveScroll'];
     configure(config: Partial<RouterConfig>): void;
 }
 export declare const routerConfig: RouterConfig;

package/dist/hooks/usePreserveScroll.d.ts

@@ -1 +1,2 @@
-export declare const usePreserveScroll: (preserveScroll: boolean) => void;
+import { RouteItemData } from '../types';
+export declare const usePreserveScroll: ({ routeItem, location: { pathname } }: RouteItemData) => void;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Suspense, createContext, lazy, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Suspense, createContext, lazy, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
@@ -96,6 +96,8 @@ var RouterConfig = class {
 		_defineProperty(this, "beforeLoad", void 0);
 		_defineProperty(this, "afterLoad", void 0);
 		_defineProperty(this, "defaultRetry", void 0);
+		_defineProperty(this, "defaultStaleTime", void 0);
+		_defineProperty(this, "defaultPreserveScroll", void 0);
 	}
 	configure(config) {
 		Object.assign(this, config);
@@ -120,10 +122,11 @@ var createCommitNavigation = (navigationExecutor, prevPathnameRef) => (nextLocat
 //#region utils/isCacheItemFresh.ts
 var createIsCacheItemFresh = (timestampMap) => ({ routeItem, pathname }) => {
 	if (!routeItem) return true;
-	const currentCacheTimestamp = timestampMap.get(pathname);
-	if (!currentCacheTimestamp) return false;
-	if (!routeItem.staleTime) return true;
-	return Date.now() - currentCacheTimestamp < routeItem.staleTime;
+	const timestamp = timestampMap.get(pathname);
+	if (timestamp === void 0) return false;
+	const staleTime = routeItem.staleTime ?? routerConfig.defaultStaleTime;
+	if (staleTime === void 0) return true;
+	return Date.now() - timestamp <= staleTime;
 };
 //#endregion
 //#region ../../node_modules/react/cjs/react-jsx-runtime.production.js
@@ -218,8 +221,9 @@ var findRoute = (pathname, includeAll) => {
 //#endregion
 //#region runtime/navigate.ts
 var navigationSeq = 0;
+var interval = 0;
 var createNavigate = (routerState, revalidateCache) => {
-	const { loaderStateRef, scrollMapState, prevPathnameRef, loaderFallbackState, isLoadingState, contextState, timestampMap, pendingPathRef } = routerState;
+	const { loaderStateRef, scrollMapState, prevPathnameRef, loaderFallbackState, isLoadingState, contextState, timestampMap, pendingPathRef, routeItemDataState } = routerState;
 	const commitNavigation = createCommitNavigation(createCommitState(routerState), prevPathnameRef);
 	const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
 	const getContext = () => ({
@@ -273,15 +277,28 @@ var createNavigate = (routerState, revalidateCache) => {
 			pathname: location.pathname
 		}) || isAnimated && !showFallback ? void 0 : routeItem?.loaderFallback);
 	};
+	const beforeEachLoad = (location) => {
+		window.clearInterval(interval);
+		if (routeItemDataState.getState().location.pathname !== location.pathname) isLoadingState.setState(true);
+		pendingPathRef.set(location.pathname);
+	};
+	const afterEachLoad = (routeItem) => {
+		pendingPathRef.set("");
+		if (!routeItem?.pollingInterval) return;
+		interval = window.setInterval(() => revalidateCache({
+			routeItem,
+			pathname: location.pathname
+		}), routeItem.pollingInterval);
+	};
 	const loader = async (routeItem, location) => {
 		if (!routeItem?.loader) return;
-		isLoadingState.setState(true);
-		pendingPathRef.set(location.pathname);
+		beforeEachLoad(location);
 		await revalidateCache({
 			routeItem,
-			pathname: location.pathname
+			pathname: location.pathname,
+			search: location.search
 		});
-		pendingPathRef.set("");
+		afterEachLoad(routeItem);
 	};
 	const afterLoad = async (routeItem, params) => {
 		const { afterLoad } = routerConfig;
@@ -399,7 +416,7 @@ var getRetry = (routeItem) => {
 var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
 	const { loaderStateRef, timestampMap, contextState } = routerState;
-	const revalidateCache = async ({ routeItem, pathname }, retried = 0) => {
+	const revalidateCache = async ({ routeItem, pathname, search = "" }, retried = 0) => {
 		if (!routeItem?.loader) return;
 		const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
 		if (loadingPromises.has(pathname)) return loadingPromises.get(pathname);
@@ -416,18 +433,20 @@ var createRevalidateCache = (routerState) => {
 				const context = contextState.getState();
 				const setContext = contextState.setState;
 				const params = getParamsObject(routeItem, pathname);
+				const searchParams = Object.fromEntries(new URLSearchParams(search).entries());
 				const result = await routeItem?.loader({
 					params,
 					context,
-					setContext
+					setContext,
+					searchParams
 				});
-				timestampMap.set(pathname, Date.now());
+				timestampMap.set(`${pathname}${search}`, Date.now());
 				loaderStateRef.set((prev) => ({
 					...prev,
 					data: result,
 					loaderError: null
 				}));
-				loaderMapRef[pathname] = loaderStateRef.value;
+				loaderMapRef[`${pathname}${search}`] = loaderStateRef.value;
 				return {
 					data: result,
 					error: null
@@ -435,7 +454,7 @@ var createRevalidateCache = (routerState) => {
 			} catch (error) {
 				const retry = getRetry(routeItem);
 				if (retry && retry.count > retried) {
-					loadingPromises.delete(pathname);
+					loadingPromises.delete(`${pathname}${search}`);
 					if (retry.delay) await sleep(retry.delay);
 					await revalidateCache({
 						routeItem,
@@ -457,10 +476,10 @@ var createRevalidateCache = (routerState) => {
 					};
 				}
 			} finally {
-				loadingPromises.delete(pathname);
+				loadingPromises.delete(`${pathname}${search}`);
 			}
 		})();
-		loadingPromises.set(pathname, promise);
+		loadingPromises.set(`${pathname}${search}`, promise);
 		return promise;
 	};
 	return revalidateCache;
@@ -504,8 +523,8 @@ var createRouterInstance = () => {
 		timestampMap: /* @__PURE__ */ new Map()
 	};
 	const revalidateCache = createRevalidateCache(routerState);
-	const navigate = createNavigate(routerState, revalidateCache);
 	const invalidate = createInvalidate(routerState, revalidateCache);
+	const navigate = createNavigate(routerState, revalidateCache);
 	const prefetch = createPrefetch(revalidateCache);
 	const useGetAction = (actionKey) => {
 		const { routeItem } = routerState.routeItemDataState.getState();
@@ -665,16 +684,10 @@ var useApplyCustomAnimation = (animationDuration) => {
 	}, [animationDuration]);
 };
 //#endregion
-//#region hooks/useLocation.ts
-var useLocation = () => {
-	const [routeItemData] = router.hooks.useRouteItemData();
-	return routeItemData.location;
-};
-//#endregion
 //#region hooks/usePreserveScroll.ts
-var usePreserveScroll = (preserveScroll) => {
+var usePreserveScroll = ({ routeItem, location: { pathname } }) => {
+	const preserveScroll = routeItem?.preserveScroll === void 0 ? routerConfig.defaultPreserveScroll : routeItem.preserveScroll;
 	const restoreScroll = router.hooks.useRestoreScroll();
-	const { pathname } = useLocation();
 	useEffect(() => {
 		if (preserveScroll) restoreScroll();
 	}, [
@@ -686,7 +699,7 @@ var usePreserveScroll = (preserveScroll) => {
 //#endregion
 //#region hooks/useSetRouterConfig.ts
 var useSetRouterConfig = (routerProps) => {
-	useEffect(() => routerConfig.configure(routerProps), [routerProps]);
+	useLayoutEffect(() => routerConfig.configure(routerProps), [routerProps]);
 };
 //#endregion
 //#region hooks/useSetInitialContext.ts
@@ -708,7 +721,7 @@ var renderElement = (Component) => {
 //#endregion
 //#region components/Router.tsx
 var EmptyBoundary = ({ children }) => children;
-var Router = ({ routes, beforeLoad, afterLoad, animationDuration, isAnimated = false, spinner = true, preserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary, context: initialContext, defaultLoaderFallback, defaultErrorElement, defaultRetry }) => {
+var Router = ({ routes, beforeLoad, afterLoad, animationDuration, isAnimated = false, spinner = true, defaultPreserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary, context: initialContext, defaultLoaderFallback, defaultErrorElement, defaultRetry, defaultStaleTime }) => {
 	const { useIsLoading, useLoaderFallback, useRouteItemData, useCurrentLoaderState } = router.hooks;
 	const [isLoading] = useIsLoading();
 	const [currentLoaderFallback] = useLoaderFallback();
@@ -723,15 +736,17 @@ var Router = ({ routes, beforeLoad, afterLoad, animationDuration, isAnimated = f
 		showFallbackOnAnimation,
 		beforeLoad,
 		afterLoad,
-		defaultRetry
+		defaultRetry,
+		defaultStaleTime,
+		defaultPreserveScroll
 	});
 	useApplyCustomAnimation(animationDuration);
 	useSetInitialContext(initialContext);
-	usePreserveScroll(preserveScroll);
+	usePreserveScroll(routeItemData);
+	const { routeItem, location } = routeItemData;
 	const showErrorElement = !isLoading && Boolean(loaderState.loaderError || loaderState.beforeLoadError);
 	const showSpinner = spinner && isAnimated && isLoading;
 	const loadingContent = !showErrorElement && isLoading;
-	const { routeItem, location } = routeItemData;
 	if ((showFallbackOnAnimation || !isAnimated) && loadingContent) return renderElement(currentLoaderFallback || defaultLoaderFallback);
 	if (!showFallbackOnAnimation && isAnimated && loadingContent) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
 	if (!routeItem) return null;
@@ -752,6 +767,12 @@ var useIsRoutePending = (routePath) => {
 //#region hooks/useNavigate.ts
 var useNavigate = router.hooks.useNavigate;
 //#endregion
+//#region hooks/useLocation.ts
+var useLocation = () => {
+	const [routeItemData] = router.hooks.useRouteItemData();
+	return routeItemData.location;
+};
+//#endregion
 //#region components/Link.tsx
 var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
 	const isPending = useIsRoutePending(to);

package/dist/types.d.ts

@@ -18,13 +18,16 @@ export type ClientRouteItem = {
         params: Record<string, string>;
         context: Record<string, unknown>;
         setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+        searchParams: Record<string, string>;
     }): Promise<unknown>;
     loaderFallback?: RenderElement;
     errorElement?: RenderElement;
     fallback?: RenderElement;
     children?: ClientRouteItem[];
     staleTime?: number;
+    pollingInterval?: number;
     retry?: Retry;
+    preserveScroll?: boolean;
     beforeLoad?: BeforeLoad;
     afterLoad?: (arg: {
         context: Record<string, unknown>;
@@ -55,6 +58,7 @@ export type BlockerState = 'blocked' | 'unblocked' | 'charged';
 export type RevalidateCacheArgs = {
     pathname: string;
     routeItem?: RouteItem;
+    search?: string;
 };
 export type LoaderState<T = unknown> = {
     data: T;
@@ -79,8 +83,9 @@ export type RouterProps = {
     isAnimated?: boolean;
     animationDuration?: number;
     spinner?: boolean;
-    preserveScroll?: boolean;
+    defaultPreserveScroll?: boolean;
     defaultRetry?: Retry;
+    defaultStaleTime?: number;
     defaultLoaderFallback?: RenderElement;
     defaultErrorElement?: RenderElement;
     showFallbackOnAnimation?: boolean;

package/dist/utils/revalidateCache.d.ts

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

package/package.json

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