@ovineko/react-router 0.0.1 → 0.0.3

package/README.md

@@ -16,20 +16,22 @@ Peer dependencies: `react@^19`, `react-router@^7`, `valibot@^1`.
 - ✅ **Two hook variants** - Normal hooks (auto-redirect on error) and Raw hooks (manual error handling)
 - ✅ **Smart validation** - Ignores extra query params and invalid optional params
 - ✅ **Global error handling** - Configure fallback redirect URLs globally or per-route
+- ✅ **Conditional redirects** - `useRedirect` hook for declarative navigation with infinite loop prevention
+- ✅ **Optional search params helper** - `optionalSearchParams` utility to avoid repetitive `v.optional()` calls
 - ✅ **Type-safe** - Full TypeScript support with inferred types
 - ✅ **Hash support** - Generate paths with hash fragments
 
 ## Quick Start
 
 ```tsx
-import { createRouteWithParams } from "@ovineko/react-router";
+import { createRouteWithParams, optionalSearchParams } from "@ovineko/react-router";
 import * as v from "valibot";
 
 const userRoute = createRouteWithParams("/users/:id", {
   params: v.object({ id: v.pipe(v.string(), v.uuid()) }),
-  searchParams: v.object({
-    tab: v.optional(v.string()),
-    page: v.optional(v.pipe(v.string(), v.transform(Number), v.number())),
+  searchParams: optionalSearchParams({
+    tab: v.string(),
+    page: v.pipe(v.string(), v.transform(Number), v.number()),
   }),
   errorRedirect: "/404", // Optional: redirect on validation error
 });
@@ -174,7 +176,7 @@ userRoute.path({ id: "42" }, { tab: "settings" }, "profile");
 #### Type-safe Links
 
 ```tsx
-<userRoute.Link params={{ id: "42" }} queryParams={{ tab: "profile" }}>
+<userRoute.Link params={{ id: "42" }} searchParams={{ tab: "profile" }}>
   View Profile
 </userRoute.Link>
 
@@ -207,6 +209,95 @@ setSearchParams({ q: "vue" }, { replace: true });
 
 ### Utilities
 
+#### `useRedirect(path, condition, replace?)`
+
+Declarative hook for conditional redirects with built-in infinite loop prevention.
+
+**Parameters:**
+
+- `path: string` - Target redirect URL
+- `condition: boolean` - Whether to trigger the redirect
+- `replace?: boolean` - Use replace instead of push (default: `true`)
+
+**Features:**
+
+- Prevents infinite redirect loops using `useRef` tracking
+- Only redirects once when condition becomes `true`
+- Resets automatically when condition becomes `false`
+- Uses `replace: true` by default to prevent back-button issues
+
+```tsx
+import { useRedirect } from "@ovineko/react-router";
+
+function ProtectedPage() {
+  const { isAuthenticated, isLoading } = useAuth();
+
+  // Redirect to login if not authenticated
+  useRedirect("/login", !isAuthenticated && !isLoading);
+
+  if (isLoading) return <Spinner />;
+  return <div>Protected Content</div>;
+}
+
+// Advanced usage with custom options
+function UserProfile() {
+  const { user, error } = useUser();
+
+  // Redirect without replacing history
+  useRedirect("/users", !user && !error, false);
+
+  return <div>{user?.name}</div>;
+}
+```
+
+#### `optionalSearchParams(entries)`
+
+Utility to make all search param fields optional automatically, avoiding repetitive `v.optional()` calls.
+
+**Parameters:**
+
+- `entries: ObjectEntries` - Valibot schema entries for search params
+
+**Returns:** Valibot object schema with all fields wrapped in `v.optional()`
+
+```tsx
+import { optionalSearchParams } from "@ovineko/react-router";
+import * as v from "valibot";
+
+// ❌ Before: Manual v.optional() for each field
+const route = createRouteWithParams("/search", {
+  params: v.object({ id: v.string() }),
+  searchParams: v.object({
+    q: v.optional(v.string()),
+    page: v.optional(v.pipe(v.string(), v.transform(Number), v.number())),
+    sort: v.optional(v.string()),
+    filter: v.optional(v.string()),
+  }),
+});
+
+// ✅ After: Clean and concise
+const route = createRouteWithParams("/search", {
+  params: v.object({ id: v.string() }),
+  searchParams: optionalSearchParams({
+    q: v.string(),
+    page: v.pipe(v.string(), v.transform(Number), v.number()),
+    sort: v.string(),
+    filter: v.string(),
+  }),
+});
+
+// All fields are automatically optional!
+const [searchParams] = route.useSearchParams();
+// Type: Readonly<{ q?: string; page?: number; sort?: string; filter?: string }>
+```
+
+**Benefits:**
+
+- Cleaner, more readable code
+- Less boilerplate for search params (which are typically optional)
+- Full TypeScript support with proper type inference
+- Works with any Valibot schema (transformations, pipes, etc.)
+
 #### `setGlobalErrorRedirect(url)`
 
 Set global fallback redirect URL for validation errors.
@@ -256,25 +347,6 @@ const params = route.useParams(); // Readonly<{ id: string }>
 const [searchParams] = route.useSearchParams(); // Readonly<{ page?: number }>
 ```
 
-## Migration from v0.x
-
-The library now uses valibot for validation instead of TypeScript generics:
-
-**Before:**
-
-```tsx
-const route = createRouteWithParams<{ id: string }, { q: string }>("/users/:id");
-```
-
-**After:**
-
-```tsx
-const route = createRouteWithParams("/users/:id", {
-  params: v.object({ id: v.string() }),
-  searchParams: v.object({ q: v.string() }),
-});
-```
-
 **Benefits:**
 
 - Runtime validation

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import * as v from "valibot";
 import type { InferSearchParams, RouteWithoutParams, RouteWithParams, State } from "./types";
 export type { RouteBase, RouteWithoutParams, RouteWithParams, State, UseParamsRawResult, UseSearchParamsRawResult, } from "./types";
+export { optionalSearchParams } from "./utils";
 export { URLParseError } from "./validation";
 export declare const setGlobalErrorRedirect: (url: string) => void;
+export declare const useRedirect: (path: string, is: boolean, replace?: boolean) => void;
 export declare const createRouteWithParams: <TParams extends v.GenericSchema, TSearchParams extends undefined | v.GenericSchema = undefined>(pattern: string, config: {
     errorRedirect?: string;
     params: TParams;

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.tsx
-import { memo, useCallback, useEffect, useMemo } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef } from "react";
 import {
   generatePath,
   Link,
@@ -32,7 +32,7 @@ function safeDecodeURIComponent(value) {
 }
 
 // src/utils.ts
-var queryParamsToString = (params) => {
+var searchParamsToString = (params) => {
   if (!params || typeof params !== "object" || Array.isArray(params)) {
     return "";
   }
@@ -141,6 +141,15 @@ var cleanOptionalParams = (obj, schema) => {
   }
   return cleaned;
 };
+var optionalSearchParams = (entries) => {
+  const optionalEntries = {};
+  for (const key in entries) {
+    if (Object.hasOwn(entries, key)) {
+      optionalEntries[key] = v.optional(entries[key]);
+    }
+  }
+  return v.object(optionalEntries);
+};
 
 // src/index.tsx
 import { jsx } from "react/jsx-runtime";
@@ -151,6 +160,18 @@ var setGlobalErrorRedirect = (url) => {
 var getErrorRedirectUrl = (routeLevel) => {
   return routeLevel ?? globalErrorRedirect;
 };
+var useRedirect = (path, is, replace = true) => {
+  const navigate = useNavigate();
+  const hasRedirectedRef = useRef(false);
+  useEffect(() => {
+    if (is && !hasRedirectedRef.current) {
+      hasRedirectedRef.current = true;
+      navigate(path, { replace });
+    } else if (!is) {
+      hasRedirectedRef.current = false;
+    }
+  }, [is, navigate, path, replace]);
+};
 var createSearchParamsHook = (schema) => {
   const useSearchParamsRaw = () => {
     const [rawSearchParams, setRawSearchParams] = useSearchParams();
@@ -194,26 +215,21 @@ var createSearchParamsHook = (schema) => {
     return { data, error, setter };
   };
   const useSearchParamsHook = (errorRedirectUrl) => {
-    const navigate = useNavigate();
     const { data, error, setter } = useSearchParamsRaw();
-    useEffect(() => {
-      if (error) {
-        const redirectUrl = getErrorRedirectUrl(errorRedirectUrl);
-        navigate(redirectUrl, { replace: true });
-      }
-    }, [error, navigate, errorRedirectUrl]);
+    const redirectUrl = getErrorRedirectUrl(errorRedirectUrl);
+    useRedirect(redirectUrl, Boolean(error));
     return [data ?? {}, setter];
   };
   return { useSearchParamsHook, useSearchParamsRaw };
 };
 var createRouteWithParams = (pattern, config) => {
-  const getPath = (params, searchParams, hash) => `${generatePath(pattern, params)}${queryParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
+  const getPath = (params, searchParams, hash) => `${generatePath(pattern, params)}${searchParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
   const searchParamsHooks = config.searchParams ? createSearchParamsHook(config.searchParams) : null;
   const LinkComponent = memo(
     ({
       children,
       params,
-      queryParams,
+      searchParams,
       state,
       ...props
     }) => {
@@ -222,7 +238,7 @@ var createRouteWithParams = (pattern, config) => {
         () => ({ prevPath: pathname, ...state }),
         [pathname, state]
       );
-      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(params, queryParams), children });
+      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(params, searchParams), children });
     }
   );
   const useParamsRaw = () => {
@@ -234,14 +250,9 @@ var createRouteWithParams = (pattern, config) => {
     return [void 0, result.issues];
   };
   const useParamsHook = () => {
-    const navigate = useNavigate();
     const [params, error] = useParamsRaw();
-    useEffect(() => {
-      if (error) {
-        const redirectUrl = getErrorRedirectUrl(config.errorRedirect);
-        navigate(redirectUrl, { replace: true });
-      }
-    }, [error, navigate]);
+    const redirectUrl = getErrorRedirectUrl(config.errorRedirect);
+    useRedirect(redirectUrl, Boolean(error));
     return params ?? {};
   };
   return {
@@ -259,16 +270,16 @@ var createRouteWithParams = (pattern, config) => {
   };
 };
 var createRouteWithoutParams = (pattern, config) => {
-  const getPath = (searchParams, hash) => `${pattern}${queryParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
+  const getPath = (searchParams, hash) => `${pattern}${searchParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
   const searchParamsHooks = config?.searchParams ? createSearchParamsHook(config.searchParams) : null;
   const LinkComponent = memo(
-    ({ children, queryParams, state, ...props }) => {
+    ({ children, searchParams, state, ...props }) => {
       const { pathname } = useLocation();
       const mergedState = useMemo(
         () => ({ prevPath: pathname, ...state }),
         [pathname, state]
       );
-      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(queryParams), children });
+      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(searchParams), children });
     }
   );
   return {
@@ -298,6 +309,8 @@ export {
   URLParseError,
   createRouteWithParams,
   createRouteWithoutParams,
+  optionalSearchParams,
   replaceState,
-  setGlobalErrorRedirect
+  setGlobalErrorRedirect,
+  useRedirect
 };

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type InferSearchParams<T> = T extends v.GenericSchema ? v.InferOutput<T>
 export interface LinkPropsWithoutParams<SearchParams> extends Omit<LinkPropsLib, "to"> {
     children: React.ReactNode | string;
     className?: string;
-    queryParams?: SearchParams;
+    searchParams?: SearchParams;
     state?: State;
     style?: React.CSSProperties;
 }

package/dist/utils.d.ts

@@ -1,12 +1,12 @@
 import * as v from "valibot";
 import type { SearchParamsInput } from "./types";
-export declare const queryParamsToString: (params?: SearchParamsInput) => string;
+export declare const searchParamsToString: (params?: SearchParamsInput) => string;
 export declare const searchParamsToObject: (params: URLSearchParams) => Record<string, string | string[]>;
 export declare const objectToSearchParams: (obj: Record<string, unknown>) => URLSearchParams;
 export declare const parseURLParamsRaw: (pattern: string, url: string) => Record<string, string>;
 /**
  * Filters an object to only include keys that exist in the valibot object schema.
- * Ignores extra query parameters not defined in the schema.
+ * Ignores extra search parameters not defined in the schema.
  */
 export declare const filterBySchemaKeys: <T extends v.ObjectSchema<any, any>>(obj: Record<string, unknown>, schema: T) => Record<string, unknown>;
 /**
@@ -15,3 +15,25 @@ export declare const filterBySchemaKeys: <T extends v.ObjectSchema<any, any>>(ob
  * Required parameters are kept as-is for subsequent validation.
  */
 export declare const cleanOptionalParams: <T extends v.ObjectSchema<any, any>>(obj: Record<string, unknown>, schema: T) => Record<string, unknown>;
+/**
+ * Wraps all fields in a Valibot object schema with v.optional().
+ * Useful for search params where all fields should be optional by default.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * searchParams: v.object({
+ *   filter: v.optional(v.string()),
+ *   sort: v.optional(v.string()),
+ *   page: v.optional(v.number())
+ * })
+ *
+ * // You can write:
+ * searchParams: optionalSearchParams({
+ *   filter: v.string(),
+ *   sort: v.string(),
+ *   page: v.number()
+ * })
+ * ```
+ */
+export declare const optionalSearchParams: <TEntries extends v.ObjectEntries>(entries: TEntries) => v.ObjectSchema<any, undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovineko/react-router",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Type-safe wrapper for React Router v7 with typed params, query params, and Link components",
   "keywords": [
     "react",