clear-react-router 1.6.2 → 1.6.3

package/README.md

@@ -2,21 +2,33 @@
 
 A lightweight, type-safe routing library for React applications with nested routes, data loading, navigation blocking, and prefetching.
 
+## Why Clear Router?
+
+Most React routers focus on flexibility and ecosystem integrations.
+Clear Router focuses on predictable navigation with a small, explicit API.
+
+It provides first-class support for:
+
+- Predictable routing
+- Built-in data loading
+- Small API
+
 ## Features
 
-- 🧩 **Nested Routes** - Organize your UI with nested layouts and routes
-- ⚡ **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
-- 🔒 **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
-- 🎯 **Type-safe Redirects** - Redirect from beforeLoad hook
-- 📦 **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
-- 🎨 **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
+- **Nested Routes** - Organize your UI with nested layouts and routes
+- **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
+- **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
+- **Type-safe Redirects** - Redirect from beforeLoad hook
+- **Cache invalidation** - Manual route invalidation
+- **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
+- **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
 
 ## API
 
@@ -28,8 +40,8 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 |----------|------|-------------|
 | `path` | `string` | Route path, e.g., `/user/:userId` |
 | `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
-| `loader` | `({ params, context, setContext }) => Promise<unknown>` | Fetch data using route params and context. Can update context via `setContext` |
 | `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` |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
@@ -245,21 +257,21 @@ Returns current location `{ pathname, search, state }`.
 const { pathname, search, state } = useLocation();
 ```
 
-### `useLoaderState()`
+### `useLoaderState<T>()`
 
 Returns the cached data loaded by the current route's `loader`, along with any errors from `loader` or `beforeLoad`. Data is automatically cached and reused when navigating back to the same route.
 
 **Returns:**
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `data` | `unknown` | The data returned from the route's `loader` |
+|----------|:----:|-------------|
+| `data` | `T` | The data returned from the route's `loader` |
 | `loaderError` | `Error \| null` | Error from the `loader` (if any) |
 | `beforeLoadError` | `Error \| null` | Error from the `beforeLoad` hook (if any) |
 
 ```
-function UserProfile() {
-  const { data, loaderError, beforeLoadError } = useLoaderState();
+const UserProfile = () => {
+  const { data, loaderError, beforeLoadError } = useLoaderState<User>();
 ```
 
 ### Caching behavior:
@@ -273,6 +285,71 @@ function UserProfile() {
 }
 ```
 
+### `useInvalidate`
+
+Returns a function that marks route data as stale and re-runs the route lifecycle.
+
+Calling `invalidate()` clears the cached loader result for a route and executes both `beforeLoad` and `loader` again. This is useful after mutations or any operation that changes data used by the route.
+
+#### Current route
+
+Invalidate the currently active route:
+
+```tsx
+const invalidate = useInvalidate();
+
+await invalidate();
+```
+
+#### Specific route
+
+You can also invalidate any registered route by passing its pathname:
+
+```tsx
+const invalidate = useInvalidate();
+
+await invalidate('/posts');
+```
+
+The route does not need to be currently active. Its cache will be marked as stale, and the next time it is visited, `beforeLoad` and `loader` will run again.
+
+#### Why use it?
+
+A common use case is refreshing route data after a mutation.
+
+For example, after deleting a post while viewing `/posts/42`, you may want the posts list to be reloaded the next time the user navigates to `/posts`:
+
+```tsx
+const invalidate = useInvalidate();
+
+await deletePost(id);
+await invalidate('/posts');
+```
+
+Likewise, after updating the current page, you can immediately refresh its data:
+
+```tsx
+const invalidate = useInvalidate();
+
+await updateProfile(data);
+await invalidate();
+```
+
+#### Notes
+
+* `invalidate()` re-executes both `beforeLoad` and `loader` for the invalidated route.
+* Cached data is discarded before the new loader starts.
+* When used as an event handler, wrap the call in an arrow function:
+
+```tsx
+<button onClick={() => invalidate()}>
+	Refresh
+</button>
+```
+
+Passing `invalidate` directly (`onClick={invalidate}`) is not supported because React passes a `MouseEvent` object to event handlers.
+
+
 ### `useBlocker(callback)`
 
 Blocks navigation when callback returns `true`.
@@ -370,7 +447,7 @@ type Adapter<T> = {
 | Element | Type | Description |
 |---------|------|-------------|
 | `value` | `T` | The parsed value from the query parameter |
-| `setValue` | `(arg: T | null) => void` | Function to update the query parameter. Null is passed to remove the parameter. |
+| `setValue` | `(arg: T \| null) => void` | Function to update the query parameter. Null is passed to remove the parameter. |
 
 ### Built-in Adapters
 

package/dist/context/RouterProviderContext.d.ts

@@ -12,6 +12,7 @@ export type ActionsContextValue = {
     prefetchLoader(arg: string): Promise<void>;
     setContext(arg: object): void;
     restoreScroll(): void;
+    invalidate(path?: string): void;
 };
 export type DataContextValue = {
     context: Record<string, unknown>;

package/dist/hooks/useHandleNavigation.d.ts

@@ -10,8 +10,9 @@ type UseHandleNavigation = {
         pathname: string;
     }): boolean;
     loaderStateRef: RefObject<LoaderState>;
+    clearTimestamp(path: string): void;
 };
-export declare const useHandleNavigation: ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, }: UseHandleNavigation) => {
+export declare const useHandleNavigation: ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp, }: UseHandleNavigation) => {
     blockerState: BlockerState;
     updateLocation: (nextLocation: Location) => Promise<void>;
     updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;
@@ -20,5 +21,6 @@ export declare const useHandleNavigation: ({ routeList, context, revalidateCache
     currentLoaderFallback: import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement) | undefined;
     isLoading: boolean;
     loaderState: LoaderState;
+    invalidate: (pathname?: string) => Promise<void>;
 };
 export {};

package/dist/hooks/useInvalidate.d.ts

@@ -0,0 +1 @@
+export declare const useInvalidate: () => (path?: string) => void;

package/dist/hooks/useLoader.d.ts

@@ -13,5 +13,6 @@ export declare const useLoader: ({ routeList, context, setContext }: UseLoaderPa
         pathname: string;
     }) => boolean;
     loaderStateRef: import("react").RefObject<LoaderState>;
+    clearTimestamp: (pathname: string) => void;
 };
 export {};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { useNavigate } from './hooks/useNavigate';
 export { useParams } from './hooks/useParams';
 export { useLocation } from './hooks/useLocation';
 export { useLoaderState } from './hooks/useLoaderState';
+export { useInvalidate } from './hooks/useInvalidate';
 export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';

package/dist/index.js

@@ -45,14 +45,15 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 var import_jsx_runtime = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = require_react_jsx_runtime_production();
 })))();
-var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState }) => {
+var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate }) => {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 		value: {
 			updateLocation,
 			updateBlockedRoute,
 			prefetchLoader,
 			setContext,
-			restoreScroll
+			restoreScroll,
+			invalidate
 		},
 		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataContext.Provider, {
 			value: { context },
@@ -187,7 +188,7 @@ var comparePaths = (el, pathname) => {
 //#endregion
 //#region hooks/useHandleNavigation.ts
 var ALL_LOCATIONS = "*";
-var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef }) => {
+var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp }) => {
 	const { isAnimated, showFallbackIfAnimated: showFallback } = routerConfig;
 	const [isLoading, setIsLoading] = useState(false);
 	const [blockedRoute, setBlockedRoute] = useState({
@@ -203,16 +204,16 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 	const [loaderState, setLoaderState] = useState(emptyLoaderState);
 	const prevPathname = useRef("");
 	const navigationSeq = useRef(0);
-	const scrollMapRef = useLatest(scrollMap);
+	const scrollMapLatest = useLatest(scrollMap);
 	const restoreScroll = useCallback(() => {
-		if (!prevPathname.current || !scrollMapRef.current[prevPathname.current]) return;
+		if (!prevPathname.current || !scrollMapLatest.current[prevPathname.current]) return;
 		requestAnimationFrame(() => {
 			window.scrollTo({
-				top: scrollMapRef.current[prevPathname.current],
+				top: scrollMapLatest.current[prevPathname.current],
 				behavior: "smooth"
 			});
 		});
-	}, [scrollMapRef]);
+	}, [scrollMapLatest]);
 	const navigation = useCallback((nextLocation, routeItem) => {
 		setRouteItemData({
 			routeItem,
@@ -237,21 +238,19 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 			navigation(nextLocation, routeItem);
 		}
 	}, [navigation, isAnimated]);
-	const navigationHandler = useCallback(async (nextLocation) => {
-		navigationSeq.current = navigationSeq.current + 1;
-		const seq = navigationSeq.current;
-		loaderStateRef.current = emptyLoaderState;
-		const nextItem = routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, nextLocation.pathname));
-		const params = getParamsObject({
-			params: nextItem?.params,
-			pathname: nextLocation.pathname
+	const invalidate = useCallback(async (pathname = routeItemData.location.pathname) => {
+		if (typeof pathname !== "string") return;
+		const routeItem = routeList.find((el) => comparePaths(el, pathname));
+		const resultParams = getParamsObject({
+			params: routeItem?.params,
+			pathname
 		});
-		if (nextItem?.beforeLoad) try {
-			const redirect = async (location) => await navigationHandler(typeof location === "string" ? { pathname: location } : location);
-			await nextItem.beforeLoad({
+		clearTimestamp(pathname);
+		try {
+			if (routeItem?.beforeLoad) await routeItem.beforeLoad({
 				context,
-				redirect,
-				params,
+				redirect: () => Promise.resolve(),
+				params: resultParams,
 				setContext
 			});
 			loaderStateRef.current = {
@@ -263,7 +262,50 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 				...loaderStateRef.current,
 				beforeLoadError: error
 			};
-			return transitionedNavigation(nextLocation, nextItem);
+		}
+		await revalidateCache({
+			routeItem,
+			pathname
+		});
+		if (pathname === routeItemData.location.pathname) setLoaderState(loaderStateRef.current);
+	}, [
+		clearTimestamp,
+		context,
+		loaderStateRef,
+		revalidateCache,
+		routeItemData.location.pathname,
+		routeList,
+		setContext
+	]);
+	const navigationHandler = useCallback(async (nextLocation) => {
+		navigationSeq.current = navigationSeq.current + 1;
+		const seq = navigationSeq.current;
+		loaderStateRef.current = emptyLoaderState;
+		const nextItem = routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, nextLocation.pathname));
+		const params = getParamsObject({
+			params: nextItem?.params,
+			pathname: nextLocation.pathname
+		});
+		if (nextItem?.beforeLoad) {
+			const redirect = async (location) => await navigationHandler(typeof location === "string" ? { pathname: location } : location);
+			try {
+				await nextItem.beforeLoad({
+					context,
+					redirect,
+					params,
+					setContext
+				});
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: null
+				};
+			} catch (error) {
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: error
+				};
+				return transitionedNavigation(nextLocation, nextItem);
+			}
 		}
 		if (seq !== navigationSeq.current) return;
 		setScrollMap((prevState) => {
@@ -359,19 +401,20 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 		restoreScroll,
 		currentLoaderFallback,
 		isLoading,
-		loaderState
+		loaderState,
+		invalidate
 	};
 };
 //#endregion
 //#region hooks/useLoader.ts
 var useLoader = ({ routeList, context, setContext }) => {
-	const timestampMapRef = useRef({});
+	const timestampMapRef = useRef(/* @__PURE__ */ new Map());
 	const loaderMapRef = useRef({});
 	const loaderStateRef = useRef(emptyLoaderState);
 	const loadingPromises = useRef(/* @__PURE__ */ new Map());
 	const isCacheItemFresh = useCallback(({ routeItem, pathname }) => {
 		if (!routeItem) return true;
-		const currentCacheTimestamp = timestampMapRef.current[pathname];
+		const currentCacheTimestamp = timestampMapRef.current.get(pathname);
 		if (!currentCacheTimestamp) return false;
 		if (!routeItem.staleTime) return true;
 		return Date.now() - currentCacheTimestamp < routeItem.staleTime;
@@ -398,20 +441,13 @@ var useLoader = ({ routeList, context, setContext }) => {
 					context,
 					setContext
 				});
-				timestampMapRef.current = {
-					...timestampMapRef.current,
-					[pathname]: Date.now()
-				};
-				loaderMapRef.current[pathname] = {
-					data: result,
-					loaderError: null,
-					beforeLoadError: null
-				};
+				timestampMapRef.current.set(pathname, Date.now());
 				loaderStateRef.current = {
 					...loaderStateRef?.current,
 					data: result,
 					loaderError: null
 				};
+				loaderMapRef.current[pathname] = loaderStateRef.current;
 			} catch (error) {
 				loaderStateRef.current = {
 					...loaderStateRef?.current,
@@ -439,25 +475,29 @@ var useLoader = ({ routeList, context, setContext }) => {
 		}, [revalidateCache, routeList]),
 		revalidateCache,
 		isCacheItemFresh,
-		loaderStateRef
+		loaderStateRef,
+		clearTimestamp: useCallback((pathname) => {
+			timestampMapRef.current.delete(pathname);
+		}, [])
 	};
 };
 //#endregion
 //#region components/RouterProvider.tsx
 var RouterProvider = ({ children, routeList, context: initialContext = {} }) => {
 	const [context, setContext] = useState(initialContext);
-	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef } = useLoader({
+	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef, clearTimestamp } = useLoader({
 		routeList,
 		context,
 		setContext
 	});
-	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState } = useHandleNavigation({
+	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate } = useHandleNavigation({
 		routeList,
 		context,
 		setContext,
 		revalidateCache,
 		isCacheItemFresh,
-		loaderStateRef
+		loaderStateRef,
+		clearTimestamp
 	});
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({
@@ -471,7 +511,8 @@ var RouterProvider = ({ children, routeList, context: initialContext = {} }) =>
 			restoreScroll,
 			currentLoaderFallback,
 			isLoading,
-			loaderState
+			loaderState,
+			invalidate
 		}), [
 			blockerState,
 			context,
@@ -482,7 +523,8 @@ var RouterProvider = ({ children, routeList, context: initialContext = {} }) =>
 			currentLoaderFallback,
 			restoreScroll,
 			isLoading,
-			loaderState
+			loaderState,
+			invalidate
 		]),
 		children
 	});
@@ -682,6 +724,12 @@ var useLoaderState = () => {
 	return loaderState;
 };
 //#endregion
+//#region hooks/useInvalidate.ts
+var useInvalidate = () => {
+	const { invalidate } = useRouterActions();
+	return invalidate;
+};
+//#endregion
 //#region hooks/useBlocker.ts
 var useBlocker = (blockerFn) => {
 	const { blockerState } = useNavigationState();
@@ -887,4 +935,4 @@ var adapter = {
 	})
 };
 //#endregion
-export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };
+export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useInvalidate, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };

package/dist/provider/Provider.d.ts

@@ -3,5 +3,5 @@ import { type ActionsContextValue, type DataContextValue, type NavigationContext
 type ProviderProps = NavigationContextValue & ActionsContextValue & DataContextValue & {
     children: ReactNode;
 };
-export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/package.json

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