clear-react-router 1.3.5 → 1.3.7

package/README.md

@@ -13,6 +13,7 @@ A lightweight, type-safe routing library for React applications with nested rout
 - 📦 **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
@@ -87,9 +88,21 @@ Component for client-side navigation with prefetch support.
 | Prop | Type | Default |
 |------|------|---------|
 | `to` | `string` | required |
-| `prefetch` | `boolean` | `true` |
+| `prefetch` | `boolean` optional | `true` |
+| `prefetchDelay` | `number` optional | `150` | Delay in ms before prefetch starts (prevents unnecessary requests on quick mouse passes) |
 | `children` | `ReactElement` | required |
 
+```
+// Default — prefetch after 150ms hover
+<Link to="/dashboard">Dashboard</Link>
+
+// Custom prefetch delay (300ms)
+<Link to="/heavy-page" prefetchDelay={300}>Heavy Page</Link>
+
+// Disable prefetch
+<Link to="/about" prefetch={false}>About</Link>
+```
+
 ### `redirect`
 
 Function provided to `beforeLoad` for programmatic redirection.
@@ -279,6 +292,114 @@ useBeforeUnload(text ? onSave : undefined);
 ```
 > **Note:** Pass `undefined` to disable the handler (e.g., if there is no changes).
 
+### `useQueryParam()`
+
+A flexible hook for working with typed query parameters. You provide a parser function, and it returns the parsed value and a setter.
+
+```
+import { useQueryParam, parser } from 'clear-react-router';
+
+const ProductPage = () => {
+  // String parameter
+  const [brand, setBrand] = useQueryParam('brand', parser.string, 'nike');
+
+  // Number parameter
+  const [page, setPage] = useQueryParam('page', parser.integer, 1);
+
+  // Boolean parameter
+  const [isActive, setIsActive] = useQueryParam('active', parser.boolean, false);
+
+  // Array of strings
+  const [colors, setColors] = useQueryParam('colors', parser.stringArray);
+
+  // Array of numbers
+  const [prices, setPrices] = useQueryParam('prices', parser.floatArray);
+
+  return (
+    <div>
+      <p>Brand: {brand}</p>
+      <p>Page: {page}</p>
+      <button onClick={() => setPage(page + 1)}>Next</button>
+    </div>
+  );
+}
+```
+**Signature:** `useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void]`
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `field` | `string` | The query parameter key (e.g., `'page'`, `'brand'`) |
+| `parser` | `(arg: string[]) => T` | Function that transforms the raw string array into the desired type |
+| `defaultValue` | `T` (optional) | Default value returned when the parameter is missing or empty |
+
+**Returns:**
+
+| Element | Type | Description |
+|---------|------|-------------|
+| `value` | `T` | The parsed value from the query parameter |
+| `setValue` | `(arg: T) => void` | Function to update the query parameter |
+
+### Built-in Parsers
+
+| Parser | Input | Output | Description |
+|--------|-------|--------|-------------|
+| `parser.string` | `string[]` | `string` | First value or empty string |
+| `parser.stringArray` | `string[]` | `string[]` | All values as array |
+| `parser.integer` | `string[]` | `number` | First value parsed as integer (default: `0`) |
+| `parser.integerArray` | `string[]` | `number[]` | All values parsed as integers |
+| `parser.float` | `string[]` | `number` | First value parsed as float (default: `0`) |
+| `parser.floatArray` | `string[]` | `number[]` | All values parsed as floats |
+| `parser.boolean` | `string[]` | `boolean` | First value parsed as boolean (`'true'` → `true`) |
+| `parser.booleanArray` | `string[]` | `boolean[]` | All values parsed as booleans |
+
+### Using Zod Schemas
+`useQueryParam` works seamlessly with Zod for complex validation:
+
+```
+import { z } from 'zod';
+import { useQueryParam, parser } from 'clear-react-router';
+
+const filterSchema = z.object({
+  name: z.string(),
+  age: z.number().min(0),
+  active: z.boolean().optional(),
+});
+
+function ProductFilter() {
+  const [filter, setFilter] = useQueryParam(
+    'filter',
+    parser.zodSchema(filterSchema),
+    { name: '', age: 0 }
+  );
+
+  return (
+    <div>
+      <p>Name: {filter.name}</p>
+      <p>Age: {filter.age}</p>
+      <button onClick={() => setFilter({ ...filter, age: filter.age + 1 })}>
+        Increment Age
+      </button>
+    </div>
+  );
+}
+```
+
+### Custom Parsers
+You can write your own parser for any format:
+
+```
+// Custom parser for comma-separated values
+const csvParser = (params: string[]): string[] => {
+  const value = params[0] || '';
+  return value ? value.split(',').map(v => v.trim()) : [];
+};
+
+const TagsFilter() {
+  const [tags, setTags] = useQueryParam('tags', csvParser, []);
+  // tags: string[]
+}
+```
+
 ### `useRouterContext()`
 
 Returns the router context object and a function to update it. Useful for accessing or modifying global state (like user authentication, theme, etc.) from anywhere in your app.

package/dist/components/Link.d.ts

@@ -6,6 +6,7 @@ type LinkProps = {
         style: CSSProperties;
     }>;
     prefetch?: boolean;
+    prefetchDelay?: number;
 };
-export declare const Link: ({ children, to, prefetch }: LinkProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Link: ({ children, to, prefetch, prefetchDelay }: LinkProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/context/RouterProviderContext.d.ts

@@ -1,3 +1,4 @@
+import { Dispatch, SetStateAction } from 'react';
 import { BlockerState, Location, RouteItem, UpdateBlockedRouteProps } from '../types/global';
 export type PropsContextValue = {
     routeList: RouteItem[];
@@ -10,6 +11,7 @@ export type NavigationContextValue = {
     shouldErrorElementShown: boolean;
 };
 export type ActionsContextValue = {
+    setLocation: Dispatch<SetStateAction<Location>>;
     updateLocation(route: Location): Promise<void>;
     updateBlockedRoute(arg: UpdateBlockedRouteProps): void;
     prefetchLoader(arg: string): Promise<void>;

package/dist/hooks/useQueryParam.d.ts

@@ -0,0 +1 @@
+export declare function useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void];

package/dist/index.d.ts

@@ -8,7 +8,9 @@ export { useLoaderState } from './hooks/useLoaderState';
 export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
+export { useQueryParam } from './hooks/useQueryParam';
 export { useSearchParams } from './hooks/useSearchParams';
 export { useHistoricalTrail } from './hooks/useHistoricalTrail';
+export { parser } from './utils/parser';
 export { createRouter } from './utils/utils';
 export type { RouteItem, BlockerState, Location } from './types/global';

package/dist/index.js

@@ -45,7 +45,7 @@ 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, location, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated }) => {
+var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, location, setLocation, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated }) => {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PropsContext.Provider, {
 		value: {
 			routeList,
@@ -53,6 +53,7 @@ var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocat
 		},
 		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 			value: {
+				setLocation,
 				updateLocation,
 				updateBlockedRoute,
 				prefetchLoader,
@@ -431,6 +432,7 @@ var RouterProvider = ({ children, routeList, context: initialContext = {}, isAni
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({
 			location,
+			setLocation,
 			updateLocation,
 			loaderCache,
 			prefetchLoader,
@@ -543,13 +545,31 @@ var useNavigate = () => {
 };
 //#endregion
 //#region components/Link.tsx
-var Link = ({ children, to, prefetch = true }) => {
+var STANDARD_DELAY = 150;
+var Link = ({ children, to, prefetch = true, prefetchDelay = STANDARD_DELAY }) => {
 	const { prefetchLoader } = useRouterActions();
 	const navigate = useNavigate();
+	const timeout = useRef(0);
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", {
 		style: { cursor: "pointer" },
 		onClick: () => navigate(to),
-		onMouseOver: () => prefetch && prefetchLoader(to),
+		onMouseEnter: useCallback(() => {
+			if (!prefetch || !prefetchDelay) return;
+			if (timeout.current) clearTimeout(timeout.current);
+			timeout.current = window.setTimeout(() => prefetchLoader(to), prefetchDelay);
+		}, [
+			prefetch,
+			prefetchDelay,
+			prefetchLoader,
+			to
+		]),
+		onMouseLeave: useCallback(() => {
+			if (!prefetch || !prefetchDelay) return;
+			if (timeout.current) {
+				clearTimeout(timeout.current);
+				timeout.current = 0;
+			}
+		}, [prefetch, prefetchDelay]),
 		children
 	});
 };
@@ -611,7 +631,7 @@ var useRouterContext = () => {
 //#region hooks/useSearchParams.ts
 var useSearchParams = () => {
 	const location = useLocation();
-	const navigate = useNavigate();
+	const { setLocation } = useRouterActions();
 	const locationRef = useLatest(location);
 	const searchString = useMemo(() => location.search ? location.search.replace("?", "") : location.pathname.split("?")?.[1] ?? "", [location.pathname, location.search]);
 	const searchParams = useMemo(() => new URLSearchParams(searchString), [searchString]);
@@ -621,11 +641,14 @@ var useSearchParams = () => {
 	}, [searchParams]);
 	const navigateWithSearchParams = useCallback((params) => {
 		const newSearch = params.toString();
-		navigate({
-			pathname: locationRef.current.pathname,
-			search: newSearch ? `?${newSearch}` : ""
-		});
-	}, [locationRef, navigate]);
+		const { pathname } = locationRef.current;
+		const search = newSearch ? `?${newSearch}` : "";
+		setLocation((prevState) => ({
+			...prevState,
+			search
+		}));
+		history.replaceState(null, "", pathname + search);
+	}, [locationRef, setLocation]);
 	return {
 		searchParams,
 		getSearchParams,
@@ -642,6 +665,24 @@ var useSearchParams = () => {
 	};
 };
 //#endregion
+//#region hooks/useQueryParam.ts
+function useQueryParam(field, parser, defaultValue) {
+	const { searchParams, setSearchParams } = useSearchParams();
+	return [useMemo(() => {
+		const result = parser(searchParams.getAll(field));
+		if (result !== void 0 && result !== null && result !== "") return result;
+		if (defaultValue !== void 0) return defaultValue;
+		return result;
+	}, [
+		field,
+		parser,
+		searchParams,
+		defaultValue
+	]), useCallback((value) => {
+		setSearchParams(field, (typeof value === "object" ? JSON.stringify : String)(value));
+	}, [setSearchParams, field])];
+}
+//#endregion
 //#region hooks/useHistoricalTrail.ts
 var useHistoricalTrail = () => {
 	const { pathname } = useLocation();
@@ -656,4 +697,39 @@ var useHistoricalTrail = () => {
 	return trail;
 };
 //#endregion
-export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };
+//#region utils/parser.ts
+var parser = {
+	string: (params) => params[0] || "",
+	stringArray: (params) => params,
+	integer: (params) => {
+		const result = parseInt(params[0] || "", 10);
+		return isNaN(result) ? 0 : result;
+	},
+	integerArray: (params) => params.map((el) => {
+		const result = parseInt(el, 10);
+		return isNaN(result) ? 0 : result;
+	}),
+	float: (params) => {
+		const result = parseFloat(params[0] || "");
+		return isNaN(result) ? 0 : result;
+	},
+	floatArray: (params) => params.map((el) => {
+		const result = parseFloat(el);
+		return isNaN(result) ? 0 : result;
+	}),
+	boolean: (params) => params[0]?.toLowerCase() === "true",
+	booleanArray: (params) => params.map((el) => el.toLowerCase() === "true"),
+	zodSchema: (schema) => (params) => {
+		let parsed;
+		try {
+			parsed = JSON.parse(params[0] ?? "{}");
+		} catch {
+			throw new Error("Invalid JSON");
+		}
+		const result = schema.safeParse(parsed);
+		if (!result.success) throw new Error("Invalid schema");
+		return result.data;
+	}
+};
+//#endregion
+export { Link, Router, RouterProvider, createRouter, parser, useBeforeUnload, useBlocker, useHistoricalTrail, 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 = PropsContextValue & NavigationContextValue & ActionsContextValue & DataContextValue & {
     children: ReactNode;
 };
-export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, location, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, location, setLocation, prefetchLoader, loaderCache, blockerState, routeList, shouldErrorElementShown, isLoading, isAnimated, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/utils/parser.d.ts

@@ -0,0 +1,21 @@
+type ZodInterface<T> = {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+};
+export declare const parser: {
+    string: (params: string[]) => string;
+    stringArray: (params: string[]) => string[];
+    integer: (params: string[]) => number;
+    integerArray: (params: string[]) => number[];
+    float: (params: string[]) => number;
+    floatArray: (params: string[]) => number[];
+    boolean: (params: string[]) => boolean;
+    booleanArray: (params: string[]) => boolean[];
+    zodSchema: <T>(schema: ZodInterface<T>) => (params: string[]) => T;
+};
+export {};

package/package.json

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