clear-react-router 1.9.1 → 1.9.3

package/README.md

@@ -31,7 +31,7 @@ It provides first-class support for:
 - **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)
-- **Typed Query Param** — Type-safe reading and writing of URL query parameters with built-in parsers for strings, numbers, booleans, arrays, and Zod schemas
+- **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
@@ -82,12 +82,13 @@ Normalizes route configuration. Extracts dynamic params, builds nested paths.
 | `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 }` | `undefined` | Overrides the global cache revalidation retry policy for this route |
+| `retry` | `number \| { count: number; delay: number }` | Overrides the global cache revalidation retry policy for this route |
+| `optimistic` |  `boolean \| undefined` | Instant navigation using stale data while fresh data is loaded in the background |
 | `errorElement` | `ReactElement \| () => ReactElement` | Error fallback for the route. Overrides the global `defaultErrorElement` set in `Router` |
 | `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 |
+| `pollingInterval` | `number \| undefined` | Polling interval (in milliseconds) for automatically revalidating data while the route is active |
+| `preserveScroll` | `boolean \| undefined` | Save and restore route scroll position when navigating between pages |
 
 Loader arguments:
 ```ts
@@ -113,7 +114,7 @@ Component for client-side navigation with prefetch support, active state detecti
 | `style` | `CSSProperties \| ({ isActive, isPending }) => CSSProperties` | `undefined` | Inline styles. Can be a function for dynamic styling |
 | `activeClassName` | `string` optional | `'active-link'` | Class name applied when the link matches the current URL |
 | `pendingClassName` | `string` optional | `'pending-link'` | Class name applied when the link's target is loading |
-| `onClick` | `() => void` | `undefined` | Callback fired before navigation |
+| `beforeNavigate` | `() => Promise<void> \| undefined` | `undefined` | Callback fired before navigation |
 
 **State values:**
 
@@ -163,6 +164,11 @@ import { Router, Link } from 'clear-react-router';
 <Link to="/profile" style={({ isActive }) => ({ fontWeight: isActive ? 'bold' : 'normal' })}>
   Profile
 </Link>
+
+// Use `beforeNavigate`
+<Link to="/details" beforeNavigate={saveDashboardData}>
+  Admin Panel
+</Link>
 ```
 **Important**: prefetch="render" should be used sparingly, as it preloads data immediately when the link is rendered, which may cause unnecessary network requests.
 

package/dist/components/Link.d.ts

@@ -13,7 +13,7 @@ type LinkProps = Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'className' | 'sty
     className?: string | ((arg: States) => string);
     activeClassName?: string;
     pendingClassName?: string;
-    onClick?(): void;
+    beforeNavigate?(): Promise<void>;
 };
-export declare const Link: ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName, pendingClassName, }: LinkProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Link: ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, activeClassName, pendingClassName, }: LinkProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/index.js

@@ -113,13 +113,13 @@ var createCommitNavigation = (navigationExecutor, routeItemDataState) => (nextLo
 };
 //#endregion
 //#region utils/isCacheItemFresh.ts
-var createIsCacheItemFresh = (timestampMap) => ({ routeItem, pathname }) => {
+var createIsCacheItemFresh = (loaderMap) => ({ routeItem, pathname }) => {
 	if (!routeItem) return true;
-	const timestamp = timestampMap.get(pathname);
-	if (timestamp === void 0) return false;
+	const item = loaderMap.get(pathname);
+	if (item === void 0) return false;
 	const staleTime = routeItem.staleTime ?? routerConfig.defaultStaleTime;
 	if (staleTime === void 0) return true;
-	return Date.now() - timestamp <= staleTime;
+	return Date.now() - item.timestamp <= staleTime;
 };
 //#endregion
 //#region ../../node_modules/react/cjs/react-jsx-runtime.production.js
@@ -216,9 +216,9 @@ var findRoute = (pathname, includeAll) => {
 var navigationSeq = 0;
 var interval = 0;
 var createNavigate = (routerState, revalidateCache) => {
-	const { loaderStateRef, scrollMapState, pendingState, contextState, timestampMap, routeItemDataState } = routerState;
+	const { loaderStateRef, scrollMapState, pendingState, contextState, loaderMap, routeItemDataState } = routerState;
 	const commitNavigation = createCommitNavigation(createCommitState(routerState), routeItemDataState);
-	const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
+	const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
 	const getContext = () => ({
 		context: contextState.getState(),
 		setContext: contextState.setState
@@ -265,14 +265,23 @@ var createNavigate = (routerState, revalidateCache) => {
 				[prevPathname]: scrollPosition
 			};
 		});
-		const pendingShouldExist = routeItem?.loader && !isCacheItemFresh({
-			routeItem,
-			pathname: location.pathname
-		});
-		pendingState.setState(pendingShouldExist ? {
-			routeItem,
-			location
-		} : void 0);
+		if (routeItem?.optimistic && loaderMap.has(location.pathname)) {
+			routeItemDataState.setState({
+				routeItem,
+				location
+			});
+			const currentLoaderState = loaderMap.get(location.pathname)?.state;
+			if (currentLoaderState) loaderStateRef.set(currentLoaderState);
+		} else {
+			const pendingShouldExist = routeItem?.loader && !isCacheItemFresh({
+				routeItem,
+				pathname: location.pathname
+			});
+			pendingState.setState(pendingShouldExist ? {
+				routeItem,
+				location
+			} : void 0);
+		}
 	};
 	const afterEachLoad = (routeItem) => {
 		if (!routeItem?.pollingInterval) return;
@@ -319,10 +328,10 @@ var createNavigate = (routerState, revalidateCache) => {
 //#endregion
 //#region runtime/invalidate.ts
 var redirect = () => Promise.resolve();
-var createInvalidate = ({ routeItemDataState, loaderStateRef, timestampMap, currentLoaderState, contextState }, revalidateCache) => {
+var createInvalidate = ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }, revalidateCache) => {
 	const invalidatePath = async (routeItem, pathname, options) => {
 		const routePathname = routeItemDataState.getState().location.pathname;
-		timestampMap.delete(pathname);
+		loaderMap.delete(pathname);
 		const params = getParamsObject();
 		try {
 			if (routeItem?.beforeLoad && options?.withBeforeLoad) {
@@ -359,7 +368,7 @@ var createInvalidate = ({ routeItemDataState, loaderStateRef, timestampMap, curr
 		const routeItem = findRoute(pathname);
 		if (!routeItem) return [];
 		const pathnameArray = [];
-		for (const [key] of timestampMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
+		for (const [key] of loaderMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
 		const currentResults = await Promise.all(pathnameArray.map((pathname) => invalidatePath(routeItem, pathname, options)));
 		if (!options?.withChildren || !routeItem.children?.length) return currentResults;
 		const childResults = await Promise.all(routeItem.children.map((child) => invalidateItem(`${pathname}${child.path}`, options)));
@@ -385,7 +394,6 @@ var createPrefetch = (revalidateCache) => async (pathname) => {
 };
 //#endregion
 //#region utils/revalidateCache.ts
-var loaderMapRef = {};
 var loadingPromises = /* @__PURE__ */ new Map();
 var isObjectRetry = (arg) => typeof arg === "object";
 var createRetry = (arg) => {
@@ -406,16 +414,17 @@ var getRetry = (routeItem) => {
 };
 var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var createRevalidateCache = (routerState) => {
-	const { loaderStateRef, timestampMap, contextState } = routerState;
+	const { loaderStateRef, contextState, loaderMap } = routerState;
 	const revalidateCache = async ({ routeItem, pathname, search = "" }, retried = 0) => {
 		if (!routeItem?.loader) return;
-		const isCacheItemFresh = createIsCacheItemFresh(timestampMap);
+		const isCacheItemFresh = createIsCacheItemFresh(loaderMap);
 		if (loadingPromises.has(pathname)) return loadingPromises.get(pathname);
 		if (isCacheItemFresh({
 			routeItem,
 			pathname
 		})) {
-			loaderStateRef.set(loaderMapRef[pathname]);
+			const item = loaderMap.get(pathname);
+			if (item?.state) loaderStateRef.set(item.state);
 			return;
 		}
 		const promise = (async () => {
@@ -431,13 +440,15 @@ var createRevalidateCache = (routerState) => {
 					setContext,
 					searchParams
 				});
-				timestampMap.set(`${pathname}${search}`, Date.now());
 				loaderStateRef.set((prev) => ({
 					...prev,
 					data: result,
 					loaderError: null
 				}));
-				loaderMapRef[`${pathname}${search}`] = loaderStateRef.value;
+				loaderMap.set(`${pathname}${search}`, {
+					state: loaderStateRef.value,
+					timestamp: Date.now()
+				});
 				return {
 					data: result,
 					error: null
@@ -506,7 +517,7 @@ var createRouterInstance = () => {
 			to: ""
 		}),
 		loaderStateRef: new Cell(emptyLoaderState),
-		timestampMap: /* @__PURE__ */ new Map()
+		loaderMap: /* @__PURE__ */ new Map()
 	};
 	const revalidateCache = createRevalidateCache(routerState);
 	const invalidate = createInvalidate(routerState, revalidateCache);
@@ -745,7 +756,7 @@ var useLocation = () => {
 };
 //#endregion
 //#region components/Link.tsx
-var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, onClick, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
+var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
 	const isPending = useIsRoutePending(to);
 	const { pathname } = useLocation();
 	const navigate = useNavigate();
@@ -804,7 +815,7 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay, classNam
 	].filter(Boolean).join(" ");
 	const clickHandler = async (event) => {
 		event.preventDefault();
-		onClick?.();
+		await beforeNavigate?.();
 		await navigate(to);
 	};
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", {

package/dist/runtime/invalidate.d.ts

@@ -1,2 +1,2 @@
 import { type InvalidateOptions, InvalidateResult, RevalidateCache, RouterState } from '../types';
-export declare const createInvalidate: ({ routeItemDataState, loaderStateRef, timestampMap, currentLoaderState, contextState }: RouterState, revalidateCache: RevalidateCache) => (pathList?: string | string[], options?: InvalidateOptions) => Promise<InvalidateResult[]>;
+export declare const createInvalidate: ({ routeItemDataState, loaderStateRef, loaderMap, currentLoaderState, contextState }: RouterState, revalidateCache: RevalidateCache) => (pathList?: string | string[], options?: InvalidateOptions) => Promise<InvalidateResult[]>;

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export type ClientRouteItem = {
     fallback?: RenderElement;
     children?: ClientRouteItem[];
     staleTime?: number;
+    optimistic?: boolean;
     pollingInterval?: number;
     retry?: Retry;
     preserveScroll?: boolean;
@@ -94,6 +95,10 @@ export type RouterProps = {
     afterLoad?: ClientRouteItem['afterLoad'];
     context?: Record<string, unknown>;
 };
+export type LoaderStateItem = {
+    state: LoaderState;
+    timestamp: number;
+};
 export type RouterState = {
     routeItemDataState: Store<RouteItemData>;
     pendingState: Store<RouteItemData | undefined>;
@@ -105,7 +110,7 @@ export type RouterState = {
         to: string;
     }>;
     loaderStateRef: Cell<LoaderState>;
-    timestampMap: Map<string, number>;
+    loaderMap: Map<string, LoaderStateItem>;
 };
 export type RouterType = {
     state: Omit<RouterState, 'timestampMap'>;

package/dist/utils/isCacheItemFresh.d.ts

@@ -1,5 +1,5 @@
-import type { RouteItem } from '../types';
-export declare const createIsCacheItemFresh: (timestampMap: Map<string, number>) => ({ routeItem, pathname }: {
+import { LoaderStateItem, RouteItem } from '../types';
+export declare const createIsCacheItemFresh: (loaderMap: Map<string, LoaderStateItem>) => ({ routeItem, pathname }: {
     routeItem?: RouteItem;
     pathname: string;
 }) => boolean;

package/package.json

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