clear-react-router 1.3.9 → 1.4.1

package/README.md

@@ -224,13 +224,21 @@ const { pathname, search, state } = useLocation();
 
 ### `useLoaderState()`
 
-Returns the cached data loaded by the current route's `loader`. Data is automatically cached and reused when navigating back to the same route.
+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` |
+| `loaderError` | `Error \| null` | Error from the `loader` (if any) |
+| `beforeLoadError` | `Error \| null` | Error from the `beforeLoad` hook (if any) |
+
 ```
-const UserProfile = () => {
-  const user = useLoaderState();
-  return <div>{user.name}</div>;
-}
+function UserProfile() {
+  const { data, loaderError, beforeLoadError } = useLoaderState();
 ```
+
 ### Caching behavior:
 - The loader result is cached and reused when navigating back to the same route (e.g., from /user/123 back to /user/456 it will be a new request because different params, but from /user/456 to /user/456 — cache hit).
 - Use staleTime in route config to control how long cache is considered fresh:
@@ -294,26 +302,23 @@ useBeforeUnload(text ? onSave : undefined);
 
 ### `useQueryParam()`
 
-A flexible hook for working with typed query parameters. You provide a parser function, and it returns the parsed value and a setter.
+A flexible hook for working with typed query parameters. You provide an adapter object with `parse` and `serialize` functions, and it returns the parsed value and a setter.
 
 ```
-import { useQueryParam, parser } from 'clear-react-router';
+import { useQueryParam, adapter } from 'clear-react-router';
 
 const ProductPage = () => {
   // String parameter
-  const [brand, setBrand] = useQueryParam('brand', parser.string, 'nike');
+  const [brand, setBrand] = useQueryParam('brand', adapter.string, 'nike');
 
   // Number parameter
-  const [page, setPage] = useQueryParam('page', parser.integer, 1);
+  const [page, setPage] = useQueryParam('page', adapter.integer, 1);
 
-  // Boolean parameter
-  const [isActive, setIsActive] = useQueryParam('active', parser.boolean, false);
-
-  // Array of strings
-  const [colors, setColors] = useQueryParam('colors', parser.stringArray);
+  // Date parameter
+  const [date, setDate] = useQueryParam('date', adapter.date, new Date());
 
   // Array of numbers
-  const [prices, setPrices] = useQueryParam('prices', parser.floatArray);
+  const [prices, setPrices] = useQueryParam('prices', adapter.floatArray);
 
   return (
     <div>
@@ -324,12 +329,17 @@ const ProductPage = () => {
   );
 }
 ```
-**Signature:** `useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void]`
+type Adapter<T> = {
+	parse: (params: string[]) => T;
+	serialize?: (params: T) => string | string[];
+}
+
+**Signature:** `useQueryParam<T>(field: string, adapter: Adapter<T>, defaultValue?: T): [T, (arg: T | null) => 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 |
+| `adapter` | `Adapter<T>` | Parser and optional serializer for params (serializer String is used in case of serializer not passed) |
 | `defaultValue` | `T` (optional) | Default value returned when the parameter is missing or empty |
 
 **Returns:**
@@ -337,27 +347,30 @@ const ProductPage = () => {
 | 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 |
+| `setValue` | `(arg: T | null) => void` | Function to update the query parameter. Null is passed to remove the parameter. |
+
+### Built-in Adapters
+
+| Adapter | Input | Output | Description |
+|---------|-------|--------|-------------|
+| `adapter.string` | `string[]` | `string` | First value or empty string |
+| `adapter.stringArray` | `string[]` | `string[]` | All values as array |
+| `adapter.integer` | `string[]` | `number` | First value parsed as integer (default: `0`) |
+| `adapter.integerArray` | `string[]` | `number[]` | All values parsed as integers |
+| `adapter.float` | `string[]` | `number` | First value parsed as float (default: `0`) |
+| `adapter.floatArray` | `string[]` | `number[]` | All values parsed as floats |
+| `adapter.boolean` | `string[]` | `boolean` | First value parsed as boolean (`'true'` → `true`) |
+| `adapter.booleanArray` | `string[]` | `boolean[]` | All values parsed as booleans |
+| `adapter.date` | `string[]` | `Date` | First value parsed as Date from timestamp |
+| `adapter.dateArray` | `string[]` | `Date[]` | All values parsed as Dates from timestamps |
+| `adapter.zodSchema` | `string[]` | `T` | Validates JSON string against Zod schema |
 
 ### Using Zod Schemas
 `useQueryParam` works seamlessly with Zod for complex validation:
 
 ```
 import { z } from 'zod';
-import { useQueryParam, parser } from 'clear-react-router';
+import { useQueryParam, adapter } from 'clear-react-router';
 
 const filterSchema = z.object({
   name: z.string(),
@@ -368,7 +381,7 @@ const filterSchema = z.object({
 function ProductFilter() {
   const [filter, setFilter] = useQueryParam(
     'filter',
-    parser.zodSchema(filterSchema),
+    adapter.zodSchema(filterSchema),
     { name: '', age: 0 }
   );
 
@@ -384,18 +397,21 @@ function ProductFilter() {
 }
 ```
 
-### Custom Parsers
-You can write your own parser for any format:
+### Custom Adapters
+You can write your own adapter 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()) : [];
-};
+// Custom adapter for comma-separated values
+const csvAdapter = {
+  parse: (params: string[]): string[] => {
+    const value = params[0] || '';
+    return value ? value.split(',').map(v => v.trim()) : [];
+  },
+  serialize: (value: string[]): string[] => value
+}
 
 const TagsFilter() {
-  const [tags, setTags] = useQueryParam('tags', csvParser, []);
+  const [tags, setTags] = useQueryParam('tags', csvAdapter, []);
   // tags: string[]
 }
 ```

package/dist/hooks/useQueryParam.d.ts

@@ -1 +1,2 @@
-export declare function useQueryParam<T>(field: string, parser: (arg: string[]) => T, defaultValue?: T): [T, (arg: T) => void];
+import { Adapter } from '../types/global';
+export declare function useQueryParam<T>(field: string, adapter: Adapter<T>, defaultValue?: T): [T, (arg: T | null) => void];

package/dist/index.d.ts

@@ -11,6 +11,6 @@ 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 { adapter } from './utils/adapter';
 export { createRouter } from './utils/utils';
-export type { RouteItem, BlockerState, Location } from './types/global';
+export type { RouteItem, BlockerState, Location, Adapter } from './types/global';

package/dist/index.js

@@ -675,21 +675,28 @@ var useSearchParams = () => {
 };
 //#endregion
 //#region hooks/useQueryParam.ts
-function useQueryParam(field, parser, defaultValue) {
+function useQueryParam(field, adapter, defaultValue) {
 	const { searchParams, setSearchParams } = useSearchParams();
 	return [useMemo(() => {
-		const result = parser(searchParams.getAll(field));
-		if (result !== void 0 && result !== null && result !== "") return result;
+		const params = searchParams.getAll(field);
+		const result = adapter.parse(params);
+		const isValid = !(result instanceof Date) || result instanceof Date && !isNaN(result.getTime());
+		if (result !== void 0 && result !== null && result !== "" && isValid) return result;
 		if (defaultValue !== void 0) return defaultValue;
 		return result;
 	}, [
 		field,
-		parser,
+		adapter,
 		searchParams,
 		defaultValue
 	]), useCallback((value) => {
-		setSearchParams(field, (typeof value === "object" ? JSON.stringify : String)(value));
-	}, [setSearchParams, field])];
+		if (!value) return setSearchParams(field, []);
+		setSearchParams(field, (adapter.serialize || String)(value));
+	}, [
+		field,
+		adapter.serialize,
+		setSearchParams
+	])];
 }
 //#endregion
 //#region hooks/useHistoricalTrail.ts
@@ -706,39 +713,65 @@ var useHistoricalTrail = () => {
 	return trail;
 };
 //#endregion
-//#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;
+//#region utils/adapter.ts
+var adapter = {
+	string: { parse: (params) => params[0] || "" },
+	stringArray: {
+		parse: (params) => params,
+		serialize: (value) => value
 	},
-	integerArray: (params) => params.map((el) => {
-		const result = parseInt(el, 10);
+	integer: { parse: (params) => {
+		const result = parseInt(params[0] || "");
 		return isNaN(result) ? 0 : result;
-	}),
-	float: (params) => {
+	} },
+	integerArray: {
+		parse: (params) => params.map((el) => {
+			const result = parseInt(el);
+			return isNaN(result) ? 0 : result;
+		}),
+		serialize: (value) => value.map(String)
+	},
+	float: { parse: (params) => {
 		const result = parseFloat(params[0] || "");
 		return isNaN(result) ? 0 : result;
+	} },
+	floatArray: {
+		parse: (params) => params.map((el) => {
+			const result = parseFloat(el);
+			return isNaN(result) ? 0 : result;
+		}),
+		serialize: (value) => value.map(String)
 	},
-	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;
+	boolean: {
+		parse: (params) => params[0]?.toLowerCase() === "true",
+		serialize: String
+	},
+	booleanArray: {
+		parse: (params) => params.map((el) => el.toLowerCase() === "true"),
+		serialize: (value) => value.map(String)
+	},
+	date: {
+		parse: (params) => new Date(Number(params[0])),
+		serialize: (arg) => String(arg.getTime())
+	},
+	dateArray: {
+		parse: (params) => params.map((param) => new Date(Number(param))),
+		serialize: (args) => args.map((arg) => String(arg.getTime()))
+	},
+	zodSchema: {
+		parse: (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;
+		},
+		serialize: JSON.stringify
 	}
 };
 //#endregion
-export { Link, Router, RouterProvider, createRouter, parser, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };
+export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };

package/dist/types/global.d.ts

@@ -55,3 +55,7 @@ export type LoaderState = Record<string, {
     loaderError: Error | null;
     beforeLoadError: Error | null;
 }>;
+export type Adapter<T> = {
+    parse: (params: string[]) => T;
+    serialize?: (params: T) => string | string[];
+};

package/dist/utils/adapter.d.ts

@@ -0,0 +1,56 @@
+type ZodInterface<T> = {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: unknown;
+    };
+};
+export declare const adapter: {
+    string: {
+        parse: (params: string[]) => string;
+    };
+    stringArray: {
+        parse: (params: string[]) => string[];
+        serialize: (value: string[]) => string[];
+    };
+    integer: {
+        parse: (params: string[]) => number;
+    };
+    integerArray: {
+        parse: (params: string[]) => number[];
+        serialize: (value: number[]) => string[];
+    };
+    float: {
+        parse: (params: string[]) => number;
+    };
+    floatArray: {
+        parse: (params: string[]) => number[];
+        serialize: (value: number[]) => string[];
+    };
+    boolean: {
+        parse: (params: string[]) => boolean;
+        serialize: StringConstructor;
+    };
+    booleanArray: {
+        parse: (params: string[]) => boolean[];
+        serialize: (value: boolean[]) => string[];
+    };
+    date: {
+        parse: (params: string[]) => Date;
+        serialize: (arg: Date) => string;
+    };
+    dateArray: {
+        parse: (params: string[]) => Date[];
+        serialize: (args: Date[]) => string[];
+    };
+    zodSchema: {
+        parse: <T>(schema: ZodInterface<T>) => (params: string[]) => T;
+        serialize: {
+            (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
+            (value: any, replacer?: (number | string)[] | null, space?: string | number): string;
+        };
+    };
+};
+export {};

package/package.json

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

package/dist/utils/parser.d.ts

@@ -1,21 +0,0 @@
-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 {};