clear-react-router 1.7.6 → 1.7.8

package/README.md

@@ -64,6 +64,8 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
 | `defaultLoaderFallback` | `ReactElement \| () => ReactElement` | `optional` | Default loading fallback for every route loader |
 | `defaultErrorElement` | `ReactElement \| () => ReactElement` | `optional` | Default error fallback for every route |
+| `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 |
 | `showFallbackOnAnimation` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
@@ -72,6 +74,8 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `errorBoundary` | `ComponentType<{ children: ReactNode }>` | `undefined` | Custom error boundary component for catching render errors in route components |
 
+> **Note:** Global lifecycle hooks wrap every route navigation. The global beforeLoad runs **before** the route-specific beforeLoad, while the global afterLoad runs **after** the route-specific afterLoad.
+
 ```tsx
 <div>
   <Navbar />
@@ -396,13 +400,13 @@ const UserProfile = () => {
 
 ### `useInvalidate()`
 
-Returns a function that marks route data as stale and re-runs the route lifecycle.
+Returns a function that revalidates cached route data by executing the route lifecycle again.
 
-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.
+Calling `invalidate()` clears the cached loader result and immediately runs both `beforeLoad` and `loader` for the specified route. This is useful after mutations or any operation that changes data used by the route.
 
 #### Current route
 
-Invalidate the currently active route:
+Revalidate the currently active route:
 
 ```tsx
 const invalidate = useInvalidate();
@@ -412,41 +416,80 @@ await invalidate();
 
 #### Specific route
 
-You can also invalidate any registered route by passing its pathname:
+Revalidate 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.
+#### Multiple routes
+
+You can revalidate several routes at once by passing an array of pathnames:
+
+```tsx
+await invalidate([ '/posts', '/profile', '/settings' ]);
+```
 
-#### Why use it?
+#### Dynamic routes
 
-A common use case is refreshing route data after a mutation.
+When a dynamic route pattern is provided, every cached route matching that pattern will be revalidated.
 
-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`:
+For example:
 
 ```tsx
-const invalidate = useInvalidate();
+await invalidate('/post/[id]');
+```
 
-await deletePost(id);
-await invalidate('/posts');
+will revalidate all cached routes such as:
+
+```text
+/post/1
+/post/17
+/post/42
 ```
 
-Likewise, after updating the current page, you can immediately refresh its data:
+This also works for nested dynamic routes:
 
 ```tsx
-const invalidate = useInvalidate();
+await invalidate('/post/[id]/comment/[id]');
+```
 
-await updateProfile(data);
-await invalidate();
+#### Including child routes
+
+To revalidate a single route together with its cached child routes, pass the `withChildren` option:
+
+```tsx
+await invalidate('/posts', { withChildren: true }); // a route, not a route list
+```
+
+This will recursively revalidate cached routes inside the route tree.
+
+For example, if the following routes have been visited:
+
+```text
+/posts
+/post/17
+/post/23
+/post/42/comments
 ```
 
+then:
+
+```tsx
+await invalidate('/posts', { withChildren: true });
+```
+
+will revalidate the cached child routes:
+
+```text
+/post/17
+/post/23
+/post/42/comments
+```
 #### Notes
 
 * `invalidate()` re-executes both `beforeLoad` and `loader` for the invalidated route.
+* Only routes that already have cached data are revalidated.
 * Cached data is discarded before the new loader starts.
 * When used as an event handler, wrap the call in an arrow function:
 

package/dist/components/Router.d.ts

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

package/dist/config/routerConfig.d.ts

@@ -1,10 +1,12 @@
-import { RouterProps } from '../types/global';
+import { ClientRouteItem, RouterProps } from '../types/global';
 declare class RouterConfig {
     routes: RouterProps['routes'];
     prefetch: RouterProps['prefetch'];
     isAnimated: RouterProps['isAnimated'];
     showFallbackOnAnimation: RouterProps['showFallbackOnAnimation'];
     hoverPrefetchDelay: number;
+    beforeLoad?: ClientRouteItem['beforeLoad'];
+    afterLoad?: ClientRouteItem['afterLoad'];
     configure(config: Partial<RouterConfig>): void;
 }
 export declare const routerConfig: RouterConfig;

package/dist/hooks/useGetAction.d.ts

@@ -1,4 +1,4 @@
 export declare const useGetAction: (actionKey: string) => {
     currentAction: (arg: FormData) => Promise<unknown> | Promise<void> | void | unknown;
-    invalidate: (path?: string) => Promise<void>;
+    invalidate: typeof import("../runtime/invalidate").invalidate;
 };

package/dist/hooks/useInvalidate.d.ts

@@ -1 +1,2 @@
-export declare const useInvalidate: () => (path?: string) => Promise<void>;
+import { invalidate } from '../runtime/invalidate';
+export declare const useInvalidate: () => typeof invalidate;

package/dist/index.js

@@ -170,21 +170,28 @@ var createLazyComponent = (importFn, fallback) => {
 //#region utils/utils.ts
 var isLazy = (el) => typeof el.element === "function" && el.element.toString().includes("import(");
 var parseClientRouteItem = (el, parentParams = [], parentPath = "") => {
-	const currentParamsList = el.path.match(/:[^/]+/g);
-	const normalizedSplitPath = el.path.replaceAll(/:[^/]+(\/|$)/g, "").split("/").filter(Boolean);
-	const splitPath = el.path.split("/");
-	const currentParams = currentParamsList ? [...parentParams, ...currentParamsList.map((param, index) => ({
-		key: normalizedSplitPath[index],
-		value: param.slice(1)
-	}))] : parentParams;
-	const path = currentParams.length ? `${parentPath}${splitPath.slice(0, splitPath.length - 1).join("/")}` : el.path;
+	const segments = el.path.split("/").filter(Boolean);
+	const staticSegments = [];
+	const currentParams = [...parentParams];
+	let lastStaticSegment = "";
+	for (const segment of segments) if (segment.startsWith(":")) {
+		if (!lastStaticSegment) throw new Error(`Route "${el.path}" cannot start with a parameter.`);
+		currentParams.push({
+			key: lastStaticSegment,
+			value: segment.slice(1)
+		});
+	} else {
+		lastStaticSegment = segment;
+		staticSegments.push(segment);
+	}
+	const path = `${parentPath}/${staticSegments.join("/")}`.replace(/\/+/g, "/");
 	const resolvedElement = isLazy(el) ? createLazyComponent(el.element, el.fallback) : el.element;
 	return [{
 		...el,
 		path,
 		params: currentParams,
 		element: resolvedElement
-	}, ...el.children?.flatMap((child) => parseClientRouteItem(child, currentParams, path)) || []];
+	}, ...el.children?.flatMap((child) => parseClientRouteItem(child, currentParams, path)) ?? []];
 };
 var createRouter = (clientList) => clientList.flatMap((el) => parseClientRouteItem(el, []));
 var getParamsObject = ({ params, pathname }) => {
@@ -264,8 +271,8 @@ var revalidateCache = ({ routeItem, pathname }) => {
 	return promise;
 };
 //#endregion
-//#region utils/navigationExecutor.ts
-var navigationExecutor = (nextLocation, routeItem) => {
+//#region utils/commitState.ts
+var commitState = (nextLocation, routeItem) => {
 	routeItemDataState.setState({
 		routeItem,
 		location: nextLocation
@@ -287,6 +294,8 @@ var RouterConfig = class {
 		_defineProperty(this, "isAnimated", false);
 		_defineProperty(this, "showFallbackOnAnimation", false);
 		_defineProperty(this, "hoverPrefetchDelay", 150);
+		_defineProperty(this, "beforeLoad", void 0);
+		_defineProperty(this, "afterLoad", void 0);
 	}
 	configure(config) {
 		Object.assign(this, config);
@@ -294,17 +303,17 @@ var RouterConfig = class {
 };
 var routerConfig = new RouterConfig();
 //#endregion
-//#region utils/transitionedNavigation.ts
-var transitionedNavigation = (nextLocation, routeItem) => {
+//#region utils/commitNavigation.ts
+var commitNavigation = (nextLocation, routeItem) => {
 	const { isAnimated } = routerConfig;
 	if (!isAnimated || !prevPathnameRef.value) {
-		navigationExecutor(nextLocation, routeItem);
+		commitState(nextLocation, routeItem);
 		return;
 	}
 	try {
-		document.startViewTransition(() => navigationExecutor(nextLocation, routeItem));
+		document.startViewTransition(() => commitState(nextLocation, routeItem));
 	} catch {
-		navigationExecutor(nextLocation, routeItem);
+		commitState(nextLocation, routeItem);
 	}
 };
 var findRoute = (pathname, includeAll) => {
@@ -314,21 +323,24 @@ var findRoute = (pathname, includeAll) => {
 //#endregion
 //#region runtime/navigate.ts
 var navigationSeq = 0;
-var navigate = async (nextLocation) => {
-	navigationSeq = navigationSeq + 1;
-	const seq = navigationSeq;
+var routeResolve = (location) => {
 	loaderStateRef.set(emptyLoaderState);
-	const { isAnimated, showFallbackOnAnimation: showFallback } = routerConfig;
-	const nextItem = findRoute(nextLocation.pathname, true);
-	const params = getParamsObject({
-		params: nextItem?.params,
-		pathname: nextLocation.pathname
-	});
-	const { context, setContext } = getContext();
-	if (nextItem?.beforeLoad) {
-		const redirect = async (location) => await navigate(typeof location === "string" ? { pathname: location } : location);
+	const nextItem = findRoute(location.pathname, true);
+	return {
+		nextItem,
+		params: getParamsObject({
+			params: nextItem?.params,
+			pathname: location.pathname
+		})
+	};
+};
+var beforeLoad = async (routeItem, params) => {
+	const { beforeLoad } = routerConfig;
+	const runBeforeLoad = async (loaderFn) => {
+		const redirect = async (redirected) => await navigate(typeof redirected === "string" ? { pathname: redirected } : redirected);
+		const { context, setContext } = getContext();
 		try {
-			await nextItem.beforeLoad({
+			await loaderFn({
 				context,
 				redirect,
 				params,
@@ -343,10 +355,13 @@ var navigate = async (nextLocation) => {
 				...prev,
 				beforeLoadError: error
 			}));
-			return transitionedNavigation(nextLocation, nextItem);
 		}
-	}
-	if (seq !== navigationSeq) return;
+	};
+	if (beforeLoad) await runBeforeLoad(beforeLoad);
+	if (routeItem?.beforeLoad) await runBeforeLoad(routeItem?.beforeLoad);
+};
+var prepareNavigation = (routeItem, location) => {
+	const { isAnimated, showFallbackOnAnimation: showFallback } = routerConfig;
 	scrollMapState.setState((prevState) => {
 		const scrollPosition = document.scrollingElement?.scrollTop ?? 0;
 		if (!scrollPosition || prevState[prevPathnameRef.value] === scrollPosition) return prevState;
@@ -356,24 +371,44 @@ var navigate = async (nextLocation) => {
 		};
 	});
 	loaderFallbackState.setState(isCacheItemFresh({
-		routeItem: nextItem,
-		pathname: nextLocation.pathname
-	}) || isAnimated && !showFallback ? void 0 : nextItem?.loaderFallback);
-	if (nextItem?.loader) {
-		isLoadingState.setState(true);
-		await revalidateCache({
-			routeItem: nextItem,
-			pathname: nextLocation.pathname
-		});
-	}
-	if (seq !== navigationSeq) return;
-	transitionedNavigation(nextLocation, nextItem);
-	if (nextItem?.afterLoad) await nextItem.afterLoad({
+		routeItem,
+		pathname: location.pathname
+	}) || isAnimated && !showFallback ? void 0 : routeItem?.loaderFallback);
+};
+var loader = async (routeItem, location) => {
+	if (!routeItem?.loader) return;
+	isLoadingState.setState(true);
+	await revalidateCache({
+		routeItem,
+		pathname: location.pathname
+	});
+};
+var afterLoad = async (routeItem, params) => {
+	const { afterLoad } = routerConfig;
+	const { context, setContext } = getContext();
+	if (routeItem?.afterLoad) await routeItem.afterLoad({
+		context,
+		params,
+		setContext
+	});
+	if (afterLoad) await afterLoad({
 		context,
 		params,
 		setContext
 	});
 };
+var navigate = async (nextLocation) => {
+	navigationSeq = navigationSeq + 1;
+	const seq = navigationSeq;
+	const { nextItem, params } = routeResolve(nextLocation);
+	await beforeLoad(nextItem, params);
+	if (seq !== navigationSeq) return;
+	prepareNavigation(nextItem, nextLocation);
+	await loader(nextItem, nextLocation);
+	if (seq !== navigationSeq) return;
+	commitNavigation(nextLocation, nextItem);
+	await afterLoad(nextItem, params);
+};
 //#endregion
 //#region hooks/useNavigation.ts
 var useNavigation = () => {
@@ -483,7 +518,7 @@ var renderElement = (Component) => {
 //#endregion
 //#region components/Router.tsx
 var EmptyBoundary = ({ children }) => children;
-var Router = ({ routes, animationDuration, isAnimated = false, spinner = true, preserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary, context: initialContext, defaultLoaderFallback, defaultErrorElement }) => {
+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 }) => {
 	const [isLoading] = useIsLoading();
 	const [currentLoaderFallback] = useLoaderFallback();
 	const [routeItemData] = useRouteItemData();
@@ -494,7 +529,9 @@ var Router = ({ routes, animationDuration, isAnimated = false, spinner = true, p
 		isAnimated,
 		prefetch,
 		hoverPrefetchDelay,
-		showFallbackOnAnimation
+		showFallbackOnAnimation,
+		beforeLoad,
+		afterLoad
 	});
 	useApplyCustomAnimation(animationDuration);
 	useSetInitialContext(initialContext);
@@ -625,22 +662,21 @@ var FormProvider = ({ children, isSubmitting }) => /* @__PURE__ */ (0, import_js
 });
 //#endregion
 //#region runtime/invalidate.ts
-var invalidate = async (path) => {
+var redirect = () => Promise.resolve();
+var invalidatePath = async (routeItem, pathname) => {
 	const routePathname = routeItemDataState.getState().location.pathname;
-	const pathname = path || routePathname;
-	const routeItem = findRoute(pathname);
-	const resultParams = getParamsObject({
+	timestampMap.delete(pathname);
+	const params = getParamsObject({
 		params: routeItem?.params,
 		pathname
 	});
-	timestampMap.delete(pathname);
 	try {
 		if (routeItem?.beforeLoad) {
 			const { context, setContext } = getContext();
 			await routeItem.beforeLoad({
 				context,
-				redirect: () => Promise.resolve(),
-				params: resultParams,
+				redirect,
+				params,
 				setContext
 			});
 		}
@@ -660,6 +696,22 @@ var invalidate = async (path) => {
 	});
 	if (pathname === routePathname) currentLoaderState.setState(loaderStateRef.value);
 };
+var invalidateItem = async (pathname, withChildren) => {
+	const routeItem = findRoute(pathname);
+	if (!routeItem) return;
+	const pathnameArray = [];
+	for (const [key] of timestampMap) if (comparePaths(routeItem, key)) pathnameArray.push(key);
+	await Promise.all(pathnameArray.map((pathname) => invalidatePath(routeItem, pathname)));
+	if (withChildren && routeItem.children?.length) {
+		const childPathList = routeItem.children.map((el) => el.path);
+		await Promise.all(childPathList.map((el) => invalidateItem(`${pathname}${el}`, withChildren)));
+	}
+};
+async function invalidate(pathList, options) {
+	const routePathname = routeItemDataState.getState().location.pathname;
+	const pathnameList = Array.isArray(pathList) ? pathList : pathList ? [pathList] : [routePathname];
+	await Promise.all(pathnameList.map((pathname) => invalidateItem(pathname, options?.withChildren)));
+}
 //#endregion
 //#region hooks/useInvalidate.ts
 var useInvalidate = () => invalidate;

package/dist/runtime/invalidate.d.ts

@@ -1 +1,6 @@
-export declare const invalidate: (path?: string) => Promise<void>;
+type Options = {
+    withChildren?: boolean;
+};
+export declare function invalidate(path?: string[]): Promise<void>;
+export declare function invalidate(path?: string, options?: Options): Promise<void>;
+export {};

package/dist/types/global.d.ts

@@ -3,6 +3,17 @@ export type LazyComponent = () => Promise<{
     default: ComponentType<unknown>;
 }>;
 export type RenderElement = (() => ReactElement) | ReactElement;
+export type BeforeLoad = (arg: {
+    context: Record<string, unknown>;
+    redirect: (arg: Location | string) => Promise<void>;
+    params: Record<string, string>;
+    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+}) => Promise<unknown> | undefined | void;
+export type AfterLoad = (arg: {
+    context: Record<string, unknown>;
+    params: Record<string, string>;
+    setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
+}) => Promise<void>;
 export type ClientRouteItem = {
     path: string;
     element: RenderElement | LazyComponent;
@@ -16,12 +27,7 @@ export type ClientRouteItem = {
     fallback?: RenderElement;
     children?: ClientRouteItem[];
     staleTime?: number;
-    beforeLoad?: (arg: {
-        context: Record<string, unknown>;
-        redirect: (arg: Location | string) => Promise<void>;
-        params: Record<string, string>;
-        setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
-    }) => Promise<unknown> | undefined | void;
+    beforeLoad?: BeforeLoad;
     afterLoad?: (arg: {
         context: Record<string, unknown>;
         params: Record<string, string>;
@@ -79,5 +85,7 @@ export type RouterProps = {
     errorBoundary?: ComponentType<{
         children: ReactNode;
     }>;
+    beforeLoad?: ClientRouteItem['beforeLoad'];
+    afterLoad?: ClientRouteItem['afterLoad'];
     context?: Record<string, unknown>;
 };

package/dist/utils/commitNavigation.d.ts

@@ -0,0 +1,2 @@
+import { Location, RouteItem } from '../types/global';
+export declare const commitNavigation: (nextLocation: Location, routeItem: RouteItem | undefined) => void;

package/dist/utils/commitState.d.ts

@@ -0,0 +1,2 @@
+import { Location, RouteItem } from '../types/global';
+export declare const commitState: (nextLocation: Location, routeItem: RouteItem | undefined) => void;

package/package.json

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

package/dist/utils/navigationExecutor.d.ts

@@ -1,2 +0,0 @@
-import { Location, RouteItem } from '../types/global';
-export declare const navigationExecutor: (nextLocation: Location, routeItem: RouteItem | undefined) => void;

package/dist/utils/transitionedNavigation.d.ts

@@ -1,2 +0,0 @@
-import { Location, RouteItem } from '../types/global';
-export declare const transitionedNavigation: (nextLocation: Location, routeItem: RouteItem | undefined) => void;