@ovineko/react-router 0.0.2 → 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
 });
@@ -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.

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,
@@ -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,14 +215,9 @@ 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 };
@@ -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 {
@@ -298,6 +309,8 @@ export {
   URLParseError,
   createRouteWithParams,
   createRouteWithoutParams,
+  optionalSearchParams,
   replaceState,
-  setGlobalErrorRedirect
+  setGlobalErrorRedirect,
+  useRedirect
 };

package/dist/utils.d.ts

@@ -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.2",
+  "version": "0.0.3",
   "description": "Type-safe wrapper for React Router v7 with typed params, query params, and Link components",
   "keywords": [
     "react",