@ovineko/react-router 0.0.4 → 0.1.0

package/README.md

@@ -250,6 +250,94 @@ function UserProfile() {
 }
 ```
 
+#### `GuardedRoute`
+
+Declarative route guard wrapper for React Router v7 route configs. Makes route protection visible at the routing config level instead of hidden inside page components.
+
+**Props:**
+
+- `useGuard: () => GuardResult` - A React hook that returns guard state
+- `loadingFallback?: React.ReactNode` - Optional loading UI (blocks child rendering)
+
+**GuardResult interface:**
+
+```tsx
+interface GuardResult {
+  allowed: boolean; // Whether the user is allowed to access this route
+  isLoading: boolean; // Whether the guard data is still loading
+  redirectTo: string; // Where to redirect when !allowed && !isLoading
+}
+```
+
+**Behavior:**
+
+- **Default (no `loadingFallback`):** Renders `<Outlet />` immediately while `isLoading` is true. This allows the child page's lazy import to start in parallel with the guard's data fetching.
+- **With `loadingFallback`:** Renders the fallback instead of `<Outlet />` while `isLoading` is true. Use this when you need to block child rendering until the guard resolves.
+- **Redirect:** When `isLoading` is false and `allowed` is false, redirects to `redirectTo` using `replace` (guards are access checks, not navigation).
+
+**Example - Extracting Guard from Data Hook:**
+
+A page has a `useOrderData` hook that fetches data. Without a guard, a user can navigate directly to `/orders/123/checkout` even when the order doesn't exist — the redirect logic is buried inside the data hook and invisible from the route config.
+
+```tsx
+import { GuardedRoute } from "@ovineko/react-router";
+import type { GuardResult } from "@ovineko/react-router";
+
+// ✅ Guard hook — extracted, visible in route config
+function useOrderGuard(): GuardResult {
+  const { orderId } = useParams<{ orderId: string }>();
+  const { data, isLoading } = useSWR(`/api/orders/${orderId}`);
+
+  return {
+    allowed: Boolean(data?.order),
+    isLoading,
+    redirectTo: "/orders",
+  };
+}
+
+// ✅ Data hook — pure, no redirects
+function useOrderData() {
+  const { orderId } = useParams<{ orderId: string }>();
+  const { data, isLoading } = useSWR(`/api/orders/${orderId}`);
+  return { order: data?.order, isLoading };
+}
+
+function Checkout() {
+  const { order, isLoading } = useOrderData();
+  // No guard logic here — GuardedRoute already handled it
+  if (isLoading) return <Spinner />;
+  return <div>Checkout for order {order.id}</div>;
+}
+
+// ✅ Route config — protection is visible and declarative
+const routes: RouteObject[] = [
+  {
+    element: <GuardedRoute useGuard={useOrderGuard} />,
+    children: [{ path: "orders/:orderId/checkout", element: <Checkout /> }],
+  },
+];
+```
+
+**Example - With `loadingFallback`:**
+
+When you need to block child rendering until the guard resolves:
+
+```tsx
+const protectedRoutes: RouteObject[] = [
+  {
+    element: <GuardedRoute useGuard={useAuthGuard} loadingFallback={<Spinner />} />,
+    children: [{ path: "dashboard", element: <Dashboard /> }],
+  },
+];
+```
+
+**Comparison with `useRedirect`:**
+
+- `useRedirect` - Hook-level conditional redirect (used inside components)
+- `GuardedRoute` - Config-level declarative guard (used in route definitions)
+
+Both complement each other: `GuardedRoute` makes route protection explicit in the config, while `useRedirect` handles component-level conditional navigation.
+
 #### `optionalSearchParams(entries)`
 
 Utility to make all search param fields optional automatically, avoiding repetitive `v.optional()` calls.

package/dist/GuardedRoute.d.ts

@@ -0,0 +1,9 @@
+import type { GuardResult } from "./types";
+export interface GuardedRouteProps {
+    /** Optional loading fallback shown while isLoading is true.
+     *  When omitted, renders <Outlet /> immediately (allows parallel lazy loading). */
+    loadingFallback?: React.ReactNode;
+    /** A React hook that returns GuardResult. Called inside the component. */
+    useGuard: () => GuardResult;
+}
+export declare function GuardedRoute({ loadingFallback, useGuard }: GuardedRouteProps): string | number | bigint | true | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element;

package/dist/GuardedRoute.js

@@ -0,0 +1,6 @@
+import {
+  GuardedRoute
+} from "./chunk-TFMOCB4F.js";
+export {
+  GuardedRoute
+};

package/dist/chunk-TFMOCB4F.js

@@ -0,0 +1,17 @@
+// src/GuardedRoute.tsx
+import { Navigate, Outlet } from "react-router";
+import { jsx } from "react/jsx-runtime";
+function GuardedRoute({ loadingFallback, useGuard }) {
+  const { allowed, isLoading, redirectTo } = useGuard();
+  if (!isLoading && !allowed) {
+    return /* @__PURE__ */ jsx(Navigate, { replace: true, to: redirectTo });
+  }
+  if (isLoading && loadingFallback) {
+    return loadingFallback;
+  }
+  return /* @__PURE__ */ jsx(Outlet, {});
+}
+
+export {
+  GuardedRoute
+};

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as v from "valibot";
 import type { InferSearchParams, RouteWithoutParams, RouteWithParams, State } from "./types";
-export type { RouteBase, RouteWithoutParams, RouteWithParams, State, UseParamsRawResult, UseSearchParamsRawResult, } from "./types";
+export { GuardedRoute } from "./GuardedRoute";
+export type { GuardedRouteProps } from "./GuardedRoute";
+export type { GuardResult, RouteBase, RouteWithoutParams, RouteWithParams, State, UseParamsRawResult, UseSearchParamsRawResult, } from "./types";
 export { optionalSearchParams } from "./utils";
 export { URLParseError } from "./validation";
 export declare const setGlobalErrorRedirect: (url: string) => void;

package/dist/index.js

@@ -1,3 +1,7 @@
+import {
+  GuardedRoute
+} from "./chunk-TFMOCB4F.js";
+
 // src/index.tsx
 import { memo, useCallback, useEffect, useMemo, useRef } from "react";
 import {
@@ -306,6 +310,7 @@ var replaceState = (state) => {
   );
 };
 export {
+  GuardedRoute,
   URLParseError,
   createRouteWithParams,
   createRouteWithoutParams,

package/dist/types.d.ts

@@ -1,5 +1,13 @@
 import type { LinkProps as LinkPropsLib, NavigateOptions } from "react-router";
 import type * as v from "valibot";
+export interface GuardResult {
+    /** Whether the user is allowed to access this route */
+    allowed: boolean;
+    /** Whether the guard data is still loading */
+    isLoading: boolean;
+    /** Where to redirect when !allowed && !isLoading */
+    redirectTo: string;
+}
 export type InferSearchParams<T> = T extends v.GenericSchema ? v.InferOutput<T> : undefined;
 export interface LinkPropsWithoutParams<SearchParams> extends Omit<LinkPropsLib, "to"> {
     children: React.ReactNode | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovineko/react-router",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "Type-safe wrapper for React Router v7 with typed params, query params, and Link components",
   "keywords": [
     "react",
@@ -26,6 +26,7 @@
   },
   "license": "MIT",
   "author": "Alexander Svinarev <shibanet0@gmail.com> (shibanet0.com)",
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -43,9 +44,9 @@
     "valibot": "^1"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}