router-kit 2.0.1 → 2.1.0

package/README.md

@@ -1,8 +1,8 @@
 # Router-Kit
 
-A professional React routing library with guards, loaders, and navigation blocking.
+A professional React routing library with guards, loaders, loading components, middlewares, and navigation blocking.
 
-**Version:** 2.0.0 | **License:** MIT
+**Version:** 2.1.0 | **License:** MIT
 
 ---
 
@@ -80,7 +80,7 @@ function App() {
 ```tsx
 const authGuard = async () => {
   const isAuth = await checkAuth();
-  return isAuth || { redirect: "/login" };
+  return isAuth || "/login";
 };
 
 const routes = createRouter([
@@ -134,6 +134,7 @@ const ctx = useOutletContext(); // Outlet context
 ## 🎭 Outlet (Nested Layouts)
 
 ```tsx
+import { useState } from "react";
 import { Outlet, useOutletContext } from "router-kit";
 
 // Parent layout with Outlet
@@ -193,7 +194,6 @@ const routes = createRouter([
 | ---------------------------------------- | ----------------- |
 | [Documentation](./docs/DOCUMENTATION.md) | Complete guide    |
 | [API Reference](./docs/API_REFERENCE.md) | Full API docs     |
-| [Examples](./docs/EXAMPLES.md)           | Code examples     |
 | [Architecture](./docs/ARCHITECTURE.md)   | Technical details |
 | [Changelog](./docs/CHANGELOG.md)         | Version history   |
 

package/dist/context/RouterProvider.js

@@ -3,6 +3,7 @@ import { Suspense, useCallback, useEffect, useMemo, useRef, useState, useTransit
 import join from "url-join";
 import Page404 from "../pages/404";
 import { createRouterError, RouterErrorCode, RouterErrors, } from "../utils/error/errors";
+import { executeMiddlewareChain } from "../utils/middleware";
 import { OutletProvider } from "./OutletContext";
 import RouterContext from "./RouterContext";
 /**
@@ -22,6 +23,8 @@ const validateUrl = (url) => {
  * Preserves '/' as a special case for root path
  */
 const normalizePath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path
             .map((p) => {
@@ -41,6 +44,8 @@ const normalizePath = (path) => {
  * Get the first path from a path (string or array)
  */
 const getFirstPath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path[0] || "";
     }
@@ -80,7 +85,7 @@ const getCurrentLocation = () => {
 /**
  * Extracts params from a path using a pattern
  */
-const extractParams = (pattern, pathname) => {
+const extractParams = (pattern, pathname, partialMatch = false) => {
     // Special case: root path matching
     const normalizedPattern = pattern === "/" ? "" : pattern;
     const normalizedPathname = pathname === "/" ? "" : pathname;
@@ -90,7 +95,14 @@ const extractParams = (pattern, pathname) => {
     if (patternParts.length === 0 && pathParts.length === 0) {
         return {};
     }
-    if (patternParts.length !== pathParts.length) {
+    // If partial match is allowed, we only need to match up to the pattern length
+    // The route matches if it consumes a prefix of the URL
+    if (partialMatch) {
+        if (patternParts.length > pathParts.length)
+            return null;
+    }
+    else if (patternParts.length !== pathParts.length) {
+        // Exact match logic (unless catch-all)
         // Check for catch-all pattern
         const hasCatchAll = patternParts.some((p) => p.startsWith("*"));
         if (!hasCatchAll)
@@ -103,6 +115,9 @@ const extractParams = (pattern, pathname) => {
         // Catch-all segment (*splat or **)
         if (patternPart.startsWith("*")) {
             const paramName = patternPart.slice(1) || "splat";
+            // For partial match, catch-all consumes everything remaining?
+            // Or just the rest of what was requested?
+            // Usually catch-all consumes everything, so it behaves like exact match + capture
             params[paramName] = pathParts.slice(i).join("/");
             return params;
         }
@@ -129,12 +144,12 @@ const extractParams = (pattern, pathname) => {
 /**
  * Match a single path pattern against current pathname (pure function)
  */
-const matchPathPattern = (routePattern, currentPath) => {
+const matchPathPattern = (routePattern, currentPath, partialMatch = false) => {
     const patterns = routePattern.split("|");
     for (const pat of patterns) {
         // Handle root path pattern
         const normalizedPat = pat === "" ? "/" : pat;
-        const extractedParams = extractParams(normalizedPat, currentPath);
+        const extractedParams = extractParams(normalizedPat, currentPath, partialMatch);
         if (extractedParams !== null) {
             return { match: true, params: extractedParams, pattern: normalizedPat };
         }
@@ -142,19 +157,21 @@ const matchPathPattern = (routePattern, currentPath) => {
     return null;
 };
 /**
- * Pure function to match routes and return result without side effects
+ * Async function to match routes with middleware and guard support
+ * Handles both sync and async guards/middleware
  */
-const matchRoutes = (routesList, currentPath, parentPath = "/", searchString = "", collectedMatches = []) => {
+const matchRoutesAsync = async (routesList, currentPath, parentPath = "/", searchString = "", collectedMatches = [], request, signal) => {
     const staticRoutes = [];
     const dynamicRoutes = [];
     const catchAllRoutes = [];
     let page404Component = null;
     for (const route of routesList) {
-        const pathArray = Array.isArray(route.path)
-            ? route.path
-            : route.path.includes("|")
-                ? route.path.split("|")
-                : [route.path];
+        const rawPath = route.path || "";
+        const pathArray = Array.isArray(rawPath)
+            ? rawPath
+            : rawPath.includes("|")
+                ? rawPath.split("|")
+                : [rawPath];
         const is404 = pathArray.some((p) => p === "404" || p === "/404");
         if (is404) {
             page404Component = route.component;
@@ -193,7 +210,9 @@ const matchRoutes = (routesList, currentPath, parentPath = "/", searchString = "
             })
                 .join("|")
             : fullPath;
-        const matchResult = matchPathPattern(fullPattern, currentPath);
+        // Enable partial matching if route has children
+        const isParent = route.children && route.children.length > 0;
+        const matchResult = matchPathPattern(fullPattern, currentPath, isParent);
         if (matchResult) {
             // Handle redirects
             if (route.redirectTo) {
@@ -207,26 +226,91 @@ const matchRoutes = (routesList, currentPath, parentPath = "/", searchString = "
                     page404Component,
                 };
             }
-            // Handle guards
-            if (route.guard) {
-                const guardResult = route.guard({
+            // Execute middleware chain (Chain of Responsibility pattern)
+            if (route.middleware && route.middleware.length > 0) {
+                const middlewareContext = {
                     pathname: currentPath,
                     params: matchResult.params,
                     search: searchString,
-                });
-                if (typeof guardResult === "string") {
+                    request,
+                    signal,
+                };
+                try {
+                    const middlewareResult = await executeMiddlewareChain(route.middleware, middlewareContext);
+                    // Handle middleware redirect
+                    if (middlewareResult.type === "redirect") {
+                        return {
+                            component: null,
+                            pattern: matchResult.pattern,
+                            params: matchResult.params,
+                            matches: collectedMatches,
+                            meta: null,
+                            redirect: middlewareResult.to || "/",
+                            page404Component,
+                            errorElement: route.errorElement,
+                            middlewareResult,
+                        };
+                    }
+                    // Handle middleware block
+                    if (middlewareResult.type === "block") {
+                        continue; // Skip this route
+                    }
+                }
+                catch (error) {
+                    // Middleware threw an error - return error result
                     return {
                         component: null,
                         pattern: matchResult.pattern,
                         params: matchResult.params,
                         matches: collectedMatches,
                         meta: null,
-                        redirect: guardResult,
+                        error: error instanceof Error ? error : new Error(String(error)),
                         page404Component,
+                        errorElement: route.errorElement,
                     };
                 }
-                if (guardResult === false) {
-                    continue; // Skip this route
+            }
+            // Handle guards (supports async)
+            if (route.guard) {
+                const guardArgs = {
+                    pathname: currentPath,
+                    params: matchResult.params,
+                    search: searchString,
+                    request,
+                    signal,
+                };
+                try {
+                    // Handle both sync and async guards
+                    const guardResult = await Promise.resolve(route.guard(guardArgs));
+                    // Guard can return string (redirect), boolean, or Promise of either
+                    if (typeof guardResult === "string") {
+                        return {
+                            component: null,
+                            pattern: matchResult.pattern,
+                            params: matchResult.params,
+                            matches: collectedMatches,
+                            meta: null,
+                            redirect: guardResult,
+                            page404Component,
+                            errorElement: route.errorElement,
+                        };
+                    }
+                    if (guardResult === false) {
+                        continue; // Skip this route
+                    }
+                }
+                catch (error) {
+                    // Guard threw an error - return error result
+                    return {
+                        component: null,
+                        pattern: matchResult.pattern,
+                        params: matchResult.params,
+                        matches: collectedMatches,
+                        meta: null,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                        page404Component,
+                        errorElement: route.errorElement,
+                    };
                 }
             }
             // Build match object
@@ -240,7 +324,7 @@ const matchRoutes = (routesList, currentPath, parentPath = "/", searchString = "
             const newMatches = [...collectedMatches, newMatch];
             // Handle nested routes with Outlet support
             if (route.children && route.children.length > 0) {
-                const childResult = matchRoutes(route.children, currentPath, fullPath, searchString, newMatches);
+                const childResult = await matchRoutesAsync(route.children, currentPath, fullPath, searchString, newMatches, request, signal);
                 if (childResult.component || childResult.redirect) {
                     // Wrap parent component with OutletProvider to render children via Outlet
                     return {
@@ -253,24 +337,37 @@ const matchRoutes = (routesList, currentPath, parentPath = "/", searchString = "
                             ? { fn: route.loader, params: matchResult.params }
                             : childResult.loader,
                         page404Component: page404Component || childResult.page404Component,
+                        errorElement: route.errorElement || childResult.errorElement,
                     };
                 }
             }
-            return {
-                component: route.component,
-                pattern: matchResult.pattern,
-                params: matchResult.params,
-                matches: newMatches,
-                meta: route.meta || null,
-                loader: route.loader
-                    ? { fn: route.loader, params: matchResult.params }
-                    : undefined,
-                page404Component,
-            };
+            // If we are here, children were checked but none matched (or didn't return a component).
+            // We must check if THIS route is an EXACT match for the current path.
+            // If it was only a partial match (prefix), and no children matched, then this route is NOT the correct match.
+            // Exceptions:
+            // 1. If it's a catch-all route (handled by exact match logic usually, or explicitly)
+            // 2. If the user intentionally wants to map a prefix to a component without children (unlikely if children prop exists)
+            const isExactMatch = matchPathPattern(fullPattern, currentPath, false);
+            if (isExactMatch) {
+                return {
+                    component: route.component,
+                    pattern: matchResult.pattern,
+                    params: matchResult.params,
+                    matches: newMatches,
+                    meta: route.meta || null,
+                    loader: route.loader
+                        ? { fn: route.loader, params: matchResult.params }
+                        : undefined,
+                    page404Component,
+                    errorElement: route.errorElement,
+                };
+            }
+            // If not exact match and no children matched, this partial match is invalid.
+            // Fall through to continue loop.
         }
         // Check children routes (for routes without matching parent)
         if (route.children) {
-            const childResult = matchRoutes(route.children, currentPath, fullPath, searchString, collectedMatches);
+            const childResult = await matchRoutesAsync(route.children, currentPath, fullPath, searchString, collectedMatches, request, signal);
             if (childResult.component || childResult.redirect) {
                 return {
                     ...childResult,
@@ -305,9 +402,21 @@ const RouterProvider = ({ routes, basename = "", fallbackElement, }) => {
     var _a;
     const [location, setLocation] = useState(getCurrentLocation);
     const [loaderData, setLoaderData] = useState(null);
+    const [error, setError] = useState(null);
+    const [matchResult, setMatchResult] = useState({
+        component: null,
+        pattern: "",
+        params: {},
+        matches: [],
+        meta: null,
+        page404Component: null,
+    });
+    // Track initial route resolution to prevent 404 flash
+    const [isResolving, setIsResolving] = useState(true);
     const [isPending, startTransition] = useTransition();
     const scrollPositions = useRef(new Map());
     const isNavigatingRef = useRef(false);
+    const abortControllerRef = useRef(null);
     /**
      * Normalize pathname by removing basename
      */
@@ -415,10 +524,58 @@ const RouterProvider = ({ routes, basename = "", fallbackElement, }) => {
         };
     }, []);
     /**
-     * Compute matched route result (pure computation)
+     * Compute matched route result with async middleware and guard support
      */
     const normalizedPath = normalizePathname(location.pathname);
-    const matchResult = useMemo(() => matchRoutes(routes, normalizedPath, "/", location.search), [routes, normalizedPath, location.search]);
+    // Async route matching with middleware and guards
+    useEffect(() => {
+        // Abort previous matching if still in progress
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        // Create new abort controller for this matching
+        const abortController = new AbortController();
+        abortControllerRef.current = abortController;
+        // Create request object for middleware/guards
+        const request = typeof window !== "undefined"
+            ? new Request(window.location.href)
+            : undefined;
+        // Execute async route matching
+        // Only set resolving for the first time to prevent layout unmounting on navigation
+        // setIsResolving(true); // Removed to prevent flicker
+        matchRoutesAsync(routes, normalizedPath, "/", location.search, [], request, abortController.signal)
+            .then((result) => {
+            // Only update if not aborted
+            if (!abortController.signal.aborted) {
+                setMatchResult(result);
+                // If the new route has a loader, we handle data clearing
+                if (result.loader) {
+                    setLoaderData(null);
+                }
+                setError(null); // Clear any previous errors on successful match
+                setIsResolving(false);
+            }
+        })
+            .catch((error) => {
+            // Ignore abort errors
+            if (error.name !== "AbortError") {
+                console.error("[router-kit] Route matching error:", error);
+                setError(error);
+                setMatchResult({
+                    component: null,
+                    pattern: "",
+                    params: {},
+                    matches: [],
+                    meta: null,
+                    page404Component: null,
+                });
+                setIsResolving(false);
+            }
+        });
+        return () => {
+            abortController.abort();
+        };
+    }, [routes, normalizedPath, location.search]);
     // Handle redirects
     useEffect(() => {
         if (matchResult.redirect) {
@@ -433,18 +590,50 @@ const RouterProvider = ({ routes, basename = "", fallbackElement, }) => {
                 params: matchResult.loader.params,
                 request: new Request(window.location.href),
                 signal: abortController.signal,
-            })).then(setLoaderData);
+            }))
+                .then((data) => {
+                setLoaderData(data);
+                setError(null); // Clear error on successful loader
+            })
+                .catch((error) => {
+                if (error.name !== "AbortError") {
+                    console.error("[router-kit] Loader error:", error);
+                    setError(error);
+                }
+            });
             return () => abortController.abort();
         }
+        else {
+            setLoaderData(null);
+        }
     }, [matchResult.loader]);
     // Handle meta/title updates
     useEffect(() => {
-        var _a;
+        var _a, _b;
         if (((_a = matchResult.meta) === null || _a === void 0 ? void 0 : _a.title) && typeof document !== "undefined") {
             document.title = matchResult.meta.title;
         }
+        if (((_b = matchResult.meta) === null || _b === void 0 ? void 0 : _b.description) && typeof document !== "undefined") {
+            let descriptionTag = document.querySelector('meta[name="description"]');
+            if (!descriptionTag) {
+                descriptionTag = document.createElement("meta");
+                descriptionTag.name = "description";
+                document.head.appendChild(descriptionTag);
+            }
+            descriptionTag.content = matchResult.meta.description;
+        }
     }, [matchResult.meta]);
-    const component = (_a = matchResult.component) !== null && _a !== void 0 ? _a : (matchResult.page404Component || _jsx(Page404, {}));
+    // Determine the loading component to show (if any)
+    const routeLoadingComponent = matchResult.matches.length > 0
+        ? matchResult.matches[matchResult.matches.length - 1].route.loading
+        : null;
+    // Only show loading if:
+    // 1. Initial resolution (isResolving)
+    // 2. We have a match with a loader but no data yet (loaderData is null)
+    // We removed isPending to prevent "flash" of loading state during standard navigation transitions
+    const showLoading = isResolving || (matchResult.loader && !loaderData);
+    // Prioritize error -> loading -> content -> 404
+    const component = (error || matchResult.error) && matchResult.errorElement ? (matchResult.errorElement) : showLoading ? (_jsx(Suspense, { fallback: fallbackElement || null, children: routeLoadingComponent || fallbackElement || null })) : ((_a = matchResult.component) !== null && _a !== void 0 ? _a : (matchResult.page404Component || _jsx(Page404, {})));
     /**
      * Build context value with memoization
      */
@@ -481,6 +670,6 @@ const RouterProvider = ({ routes, basename = "", fallbackElement, }) => {
         loaderData,
         matchResult.meta,
     ]);
-    return (_jsx(RouterContext.Provider, { value: contextValue, children: fallbackElement && isPending ? (_jsx(Suspense, { fallback: fallbackElement, children: component })) : (component) }));
+    return (_jsx(RouterContext.Provider, { value: contextValue, children: _jsx(Suspense, { fallback: fallbackElement || null, children: component }) }));
 };
 export default RouterProvider;

package/dist/core/createRouter.js

@@ -3,6 +3,8 @@
  * Preserves "/" as empty string for root path matching
  */
 const normalizePath = (path) => {
+    if (path === undefined)
+        return "";
     const pathArray = Array.isArray(path) ? path : [path];
     const normalized = pathArray.map((p) => {
         if (!p)
@@ -29,15 +31,17 @@ const validateRoute = (route, path) => {
         console.warn(`[router-kit] Route "${path}" has both component and lazy defined. Component will take precedence.`);
     }
     // Validate path patterns
-    const pathArray = Array.isArray(route.path) ? route.path : [route.path];
-    for (const p of pathArray) {
-        // Check for invalid characters
-        if (/[<>"|\\]/.test(p)) {
-            console.warn(`[router-kit] Route path "${p}" contains invalid characters.`);
-        }
-        // Warn about potential issues with catch-all routes
-        if (p.includes("*") && !p.endsWith("*") && !p.includes("*/")) {
-            console.warn(`[router-kit] Catch-all (*) should typically be at the end of a path: "${p}"`);
+    if (route.path) {
+        const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+        for (const p of pathArray) {
+            // Check for invalid characters
+            if (/[<>"|\\]/.test(p)) {
+                console.warn(`[router-kit] Route path "${p}" contains invalid characters.`);
+            }
+            // Warn about potential issues with catch-all routes
+            if (p.includes("*") && !p.endsWith("*") && !p.includes("*/")) {
+                console.warn(`[router-kit] Catch-all (*) should typically be at the end of a path: "${p}"`);
+            }
         }
     }
 };

package/dist/index.d.ts

@@ -18,7 +18,8 @@ export { useDynamicComponents } from "./hooks/useDynamicComponents";
 export { useIsNavigating, useLoaderData, useRouteMeta, } from "./hooks/useLoaderData";
 export type { OutletProps } from "./components/Outlet";
 export type { RouteProps } from "./components/route";
-export type { Blocker, BlockerFunction, DynamicComponents, GetComponent, GuardArgs, HistoryAction, LinkProps, LoaderArgs, Location, NavigateFunction, NavigateOptions, NavLinkProps, RouteGuard, RouteLoader, RouteMatch, RouteMeta, RouterContextType, RouterError, RouterKitError, RouterProviderProps, Routes, Route as RouteType, ScrollRestorationProps, } from "./types/index";
+export type { Blocker, BlockerFunction, DynamicComponents, GetComponent, GuardArgs, HistoryAction, LinkProps, LoaderArgs, Location, Middleware, MiddlewareContext, MiddlewareResult, NavigateFunction, NavigateOptions, NavLinkProps, RouteGuard, RouteLoader, RouteMatch, RouteMeta, RouterContextType, RouterError, RouterKitError, RouterProviderProps, Routes, Route as RouteType, ScrollRestorationProps, } from "./types/index";
 export { createRouterError, RouterErrorCode, RouterErrors, RouterKitError as RouterKitErrorClass, } from "./utils/error/errors";
+export { executeMiddlewareChain, createAuthMiddleware, createRoleMiddleware, createDataMiddleware, createLoggingMiddleware, } from "./utils/middleware";
 export { createRequestFromNode, getHydratedLoaderData, getLoaderDataScript, hydrateRouter, isBrowser, isServerRendered, matchServerRoutes, prefetchLoaderData, StaticRouter, } from "./ssr";
 export type { HydrateRouterOptions, ServerLoaderResult, ServerMatchResult, StaticRouterContext, StaticRouterProps, } from "./ssr";

package/dist/index.js

@@ -24,5 +24,7 @@ export { useDynamicComponents } from "./hooks/useDynamicComponents";
 export { useIsNavigating, useLoaderData, useRouteMeta, } from "./hooks/useLoaderData";
 // Error utilities
 export { createRouterError, RouterErrorCode, RouterErrors, RouterKitError as RouterKitErrorClass, } from "./utils/error/errors";
+// Middleware utilities
+export { executeMiddlewareChain, createAuthMiddleware, createRoleMiddleware, createDataMiddleware, createLoggingMiddleware, } from "./utils/middleware";
 // SSR - Server-Side Rendering
 export { createRequestFromNode, getHydratedLoaderData, getLoaderDataScript, hydrateRouter, isBrowser, isServerRendered, matchServerRoutes, prefetchLoaderData, StaticRouter, } from "./ssr";

package/dist/ssr/StaticRouter.js

@@ -25,10 +25,14 @@ const parseUrl = (url) => {
 /**
  * Extract params from a path using a pattern
  */
-const extractParams = (pattern, pathname) => {
+const extractParams = (pattern, pathname, partialMatch = false) => {
     const patternParts = pattern.split("/").filter(Boolean);
     const pathParts = pathname.split("/").filter(Boolean);
-    if (patternParts.length !== pathParts.length) {
+    if (partialMatch) {
+        if (patternParts.length > pathParts.length)
+            return null;
+    }
+    else if (patternParts.length !== pathParts.length) {
         const hasCatchAll = patternParts.some((p) => p.startsWith("*"));
         if (!hasCatchAll)
             return null;
@@ -71,6 +75,8 @@ const joinPaths = (parent, child) => {
  * Normalize path to string (handles array paths)
  */
 const normalizePath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path.map((p) => (p.startsWith("/") ? p.slice(1) : p)).join("|");
     }
@@ -80,6 +86,8 @@ const normalizePath = (path) => {
  * Get the first path from a path (string or array)
  */
 const getFirstPath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path[0] || "";
     }
@@ -137,10 +145,10 @@ const StaticRouter = ({ routes, location: locationString, basename = "", loaderD
         key: "static",
     };
     // Match path helper
-    const matchPath = (routePattern, currentPath) => {
+    const matchPath = (routePattern, currentPath, partialMatch = false) => {
         const patterns = routePattern.split("|");
         for (const pat of patterns) {
-            const extractedParams = extractParams(pat, currentPath);
+            const extractedParams = extractParams(pat, currentPath, partialMatch);
             if (extractedParams !== null) {
                 return { match: true, params: extractedParams, pattern: pat };
             }
@@ -160,7 +168,11 @@ const StaticRouter = ({ routes, location: locationString, basename = "", loaderD
                 page404Component = route.component;
                 continue;
             }
-            const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+            const pathArray = Array.isArray(route.path)
+                ? route.path
+                : route.path
+                    ? [route.path]
+                    : [];
             const hasCatchAll = pathArray.some((p) => p.includes("*"));
             const hasDynamicParams = pathArray.some((p) => p.includes(":"));
             if (hasCatchAll) {
@@ -182,12 +194,13 @@ const StaticRouter = ({ routes, location: locationString, basename = "", loaderD
             const normalizedRoutePath = normalizePath(route.path);
             const firstPath = getFirstPath(route.path);
             const fullPath = joinPaths(parentPath, firstPath);
+            const isParent = route.children && route.children.length > 0;
             const matchResult = matchPath(normalizedRoutePath.includes("|")
                 ? normalizedRoutePath
                     .split("|")
                     .map((p) => joinPaths(parentPath, p))
                     .join("|")
-                : fullPath, currentPath);
+                : fullPath, currentPath, isParent);
             if (matchResult) {
                 // Handle redirects
                 if (route.redirectTo) {
@@ -239,12 +252,23 @@ const StaticRouter = ({ routes, location: locationString, basename = "", loaderD
                 }
                 context.action = "OK";
                 context.statusCode = 200;
-                return {
-                    component: route.component,
-                    match: routeMatch,
-                    pattern: matchResult.pattern,
-                    params: matchResult.params,
-                };
+                // If no children matched, check if this is an exact match
+                const isExactMatch = matchPath(normalizedRoutePath.includes("|")
+                    ? normalizedRoutePath
+                        .split("|")
+                        .map((p) => joinPaths(parentPath, p))
+                        .join("|")
+                    : fullPath, currentPath, false // Force exact match check
+                );
+                if (isExactMatch) {
+                    return {
+                        component: route.component,
+                        match: routeMatch,
+                        pattern: matchResult.pattern,
+                        params: matchResult.params,
+                    };
+                }
+                // If not exact and no children matched, continue loop matching other routes
             }
             // Check children routes
             if (route.children) {

package/dist/ssr/serverUtils.js

@@ -1,10 +1,14 @@
 /**
  * Extract params from a path using a pattern
  */
-const extractParams = (pattern, pathname) => {
+const extractParams = (pattern, pathname, partialMatch = false) => {
     const patternParts = pattern.split("/").filter(Boolean);
     const pathParts = pathname.split("/").filter(Boolean);
-    if (patternParts.length !== pathParts.length) {
+    if (partialMatch) {
+        if (patternParts.length > pathParts.length)
+            return null;
+    }
+    else if (patternParts.length !== pathParts.length) {
         const hasCatchAll = patternParts.some((p) => p.startsWith("*"));
         if (!hasCatchAll)
             return null;
@@ -47,6 +51,8 @@ const joinPaths = (parent, child) => {
  * Normalize path to string (handles array paths)
  */
 const normalizePath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path.map((p) => (p.startsWith("/") ? p.slice(1) : p)).join("|");
     }
@@ -56,6 +62,8 @@ const normalizePath = (path) => {
  * Get the first path from a path (string or array)
  */
 const getFirstPath = (path) => {
+    if (path === undefined)
+        return "";
     if (Array.isArray(path)) {
         return path[0] || "";
     }
@@ -87,7 +95,11 @@ export function matchServerRoutes(routes, pathname, parentPath = "/") {
         const is404 = route.path === "404" || route.path === "/404";
         if (is404)
             continue;
-        const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+        const pathArray = Array.isArray(route.path)
+            ? route.path
+            : route.path
+                ? [route.path]
+                : [];
         const hasCatchAll = pathArray.some((p) => p.includes("*"));
         const hasDynamicParams = pathArray.some((p) => p.includes(":"));
         if (hasCatchAll) {
@@ -108,7 +120,8 @@ export function matchServerRoutes(routes, pathname, parentPath = "/") {
         const patterns = normalizedRoutePath.split("|");
         for (const pattern of patterns) {
             const fullPattern = joinPaths(parentPath, pattern);
-            const extractedParams = extractParams(fullPattern, pathname);
+            const isParent = route.children && route.children.length > 0;
+            const extractedParams = extractParams(fullPattern, pathname, isParent);
             if (extractedParams !== null) {
                 // Handle redirects
                 if (route.redirectTo) {
@@ -143,12 +156,20 @@ export function matchServerRoutes(routes, pathname, parentPath = "/") {
                         };
                     }
                 }
-                return {
-                    matches,
-                    params: extractedParams,
-                    statusCode: 200,
-                    meta: route.meta,
-                };
+                // If no children matched, check for exact match
+                // Rethink fullPattern logic: patterns contains split parts.
+                // We need to re-verify the specific pattern that matched partially.
+                const isExactMatch = extractParams(fullPattern, pathname, false);
+                if (isExactMatch !== null) {
+                    return {
+                        matches,
+                        params: extractedParams,
+                        statusCode: 200,
+                        meta: route.meta,
+                    };
+                }
+                // If not exact and no children matched, continue loop matching other routes (pop from matches implicitly by not returning)
+                matches.pop(); // Remove the partial match from matches array if we are continuing
             }
         }
         // Check children even if parent doesn't match

package/dist/types/index.d.ts

@@ -4,13 +4,15 @@ import { ComponentType, JSX, LazyExoticComponent, ReactNode } from "react";
  */
 export interface Route {
     /** Path pattern(s) for the route */
-    path: string | string[];
+    path?: string | string[];
     /** Component to render */
     component: JSX.Element;
     /** Nested child routes */
     children?: Route[];
     /** Index route flag - renders when parent path matches exactly */
     index?: boolean;
+    /** Component to render while loading data or performing async tasks */
+    loading?: JSX.Element;
     /** Lazy-loaded component */
     lazy?: LazyExoticComponent<ComponentType<any>>;
     /** Route loader function for data fetching */
@@ -21,6 +23,8 @@ export interface Route {
     redirectTo?: string;
     /** Route guard function */
     guard?: RouteGuard;
+    /** Middleware chain for route processing (Chain of Responsibility pattern) */
+    middleware?: Middleware[];
     /** Route metadata */
     meta?: RouteMeta;
 }
@@ -37,9 +41,36 @@ export interface LoaderArgs {
     signal: AbortSignal;
 }
 /**
- * Route guard function type
+ * Middleware context passed to middleware functions
  */
-export type RouteGuard = (args: GuardArgs) => boolean | Promise<boolean> | string;
+export interface MiddlewareContext {
+    pathname: string;
+    params: Record<string, string>;
+    search: string;
+    request?: Request;
+    signal?: AbortSignal;
+}
+/**
+ * Middleware result - can redirect, block, or continue
+ */
+export type MiddlewareResult = {
+    type: "continue";
+} | {
+    type: "redirect";
+    to: string;
+} | {
+    type: "block";
+};
+/**
+ * Middleware function type - supports both sync and async
+ * Returns MiddlewareResult or Promise<MiddlewareResult>
+ */
+export type Middleware = (context: MiddlewareContext, next: () => Promise<MiddlewareResult>) => MiddlewareResult | Promise<MiddlewareResult>;
+/**
+ * Route guard function type - supports both sync and async
+ * Can return boolean, Promise<boolean>, or redirect string
+ */
+export type RouteGuard = (args: GuardArgs) => boolean | Promise<boolean> | string | Promise<string>;
 /**
  * Guard function arguments
  */
@@ -47,6 +78,8 @@ export interface GuardArgs {
     pathname: string;
     params: Record<string, string>;
     search: string;
+    request?: Request;
+    signal?: AbortSignal;
 }
 /**
  * Route metadata

package/dist/utils/middleware.d.ts

@@ -0,0 +1,81 @@
+import type { Middleware, MiddlewareContext, MiddlewareResult } from "../types";
+/**
+ * Creates a middleware chain executor using Chain of Responsibility pattern
+ * Each middleware can either:
+ * - Continue to the next middleware (return { type: "continue" })
+ * - Redirect (return { type: "redirect", to: string })
+ * - Block the request (return { type: "block" })
+ *
+ * @param middlewares - Array of middleware functions
+ * @param context - Middleware context with route information
+ * @returns Promise resolving to middleware result
+ */
+export declare function executeMiddlewareChain(middlewares: Middleware[], context: MiddlewareContext): Promise<MiddlewareResult>;
+/**
+ * Helper to create a middleware that checks authentication
+ * @example
+ * ```ts
+ * const authMiddleware: Middleware = createAuthMiddleware({
+ *   checkAuth: async () => {
+ *     const token = localStorage.getItem('token');
+ *     return !!token;
+ *   },
+ *   redirectTo: '/login'
+ * });
+ * ```
+ */
+export declare function createAuthMiddleware(options: {
+    checkAuth: (context: MiddlewareContext) => boolean | Promise<boolean>;
+    redirectTo?: string;
+}): Middleware;
+/**
+ * Helper to create a middleware that checks permissions/roles
+ * @example
+ * ```ts
+ * const adminMiddleware: Middleware = createRoleMiddleware({
+ *   checkRole: async (context) => {
+ *     const user = await getCurrentUser();
+ *     return user?.role === 'admin';
+ *   },
+ *   redirectTo: '/unauthorized'
+ * });
+ * ```
+ */
+export declare function createRoleMiddleware(options: {
+    checkRole: (context: MiddlewareContext) => boolean | Promise<boolean>;
+    redirectTo?: string;
+}): Middleware;
+/**
+ * Helper to create a middleware that fetches data before route loads
+ * @example
+ * ```ts
+ * const dataMiddleware: Middleware = createDataMiddleware({
+ *   fetchData: async (context) => {
+ *     const response = await fetch(`/api/data/${context.params.id}`);
+ *     return response.json();
+ *   },
+ *   onData: (data) => {
+ *     // Store data in context or global state
+ *   }
+ * });
+ * ```
+ */
+export declare function createDataMiddleware<T = any>(options: {
+    fetchData: (context: MiddlewareContext) => Promise<T> | T;
+    onData?: (data: T, context: MiddlewareContext) => void | Promise<void>;
+    onError?: (error: Error, context: MiddlewareContext) => void;
+}): Middleware;
+/**
+ * Helper to create a middleware that logs route access
+ * @example
+ * ```ts
+ * const loggingMiddleware: Middleware = createLoggingMiddleware({
+ *   log: (context) => {
+ *     console.log(`Accessing: ${context.pathname}`);
+ *   }
+ * });
+ * ```
+ */
+export declare function createLoggingMiddleware(options: {
+    log: (context: MiddlewareContext) => void | Promise<void>;
+}): Middleware;

package/dist/utils/middleware.js

@@ -0,0 +1,141 @@
+/**
+ * Creates a middleware chain executor using Chain of Responsibility pattern
+ * Each middleware can either:
+ * - Continue to the next middleware (return { type: "continue" })
+ * - Redirect (return { type: "redirect", to: string })
+ * - Block the request (return { type: "block" })
+ *
+ * @param middlewares - Array of middleware functions
+ * @param context - Middleware context with route information
+ * @returns Promise resolving to middleware result
+ */
+export async function executeMiddlewareChain(middlewares, context) {
+    if (middlewares.length === 0) {
+        return { type: "continue" };
+    }
+    let index = 0;
+    /**
+     * Next function - calls the next middleware in the chain
+     */
+    const next = async () => {
+        if (index >= middlewares.length) {
+            return { type: "continue" };
+        }
+        const middleware = middlewares[index++];
+        try {
+            // Execute middleware - handle both sync and async
+            const result = await Promise.resolve(middleware(context, next));
+            // Normalize result
+            if (result && typeof result === "object" && "type" in result) {
+                return result;
+            }
+            // Fallback to continue if invalid result
+            return { type: "continue" };
+        }
+        catch (error) {
+            // On error, block the request
+            console.error("[router-kit] Middleware error:", error);
+            return { type: "block" };
+        }
+    };
+    return next();
+}
+/**
+ * Helper to create a middleware that checks authentication
+ * @example
+ * ```ts
+ * const authMiddleware: Middleware = createAuthMiddleware({
+ *   checkAuth: async () => {
+ *     const token = localStorage.getItem('token');
+ *     return !!token;
+ *   },
+ *   redirectTo: '/login'
+ * });
+ * ```
+ */
+export function createAuthMiddleware(options) {
+    return async (context, next) => {
+        const isAuthenticated = await Promise.resolve(options.checkAuth(context));
+        if (!isAuthenticated) {
+            return {
+                type: "redirect",
+                to: options.redirectTo || "/login",
+            };
+        }
+        return next();
+    };
+}
+/**
+ * Helper to create a middleware that checks permissions/roles
+ * @example
+ * ```ts
+ * const adminMiddleware: Middleware = createRoleMiddleware({
+ *   checkRole: async (context) => {
+ *     const user = await getCurrentUser();
+ *     return user?.role === 'admin';
+ *   },
+ *   redirectTo: '/unauthorized'
+ * });
+ * ```
+ */
+export function createRoleMiddleware(options) {
+    return async (context, next) => {
+        const hasRole = await Promise.resolve(options.checkRole(context));
+        if (!hasRole) {
+            return {
+                type: "redirect",
+                to: options.redirectTo || "/unauthorized",
+            };
+        }
+        return next();
+    };
+}
+/**
+ * Helper to create a middleware that fetches data before route loads
+ * @example
+ * ```ts
+ * const dataMiddleware: Middleware = createDataMiddleware({
+ *   fetchData: async (context) => {
+ *     const response = await fetch(`/api/data/${context.params.id}`);
+ *     return response.json();
+ *   },
+ *   onData: (data) => {
+ *     // Store data in context or global state
+ *   }
+ * });
+ * ```
+ */
+export function createDataMiddleware(options) {
+    return async (context, next) => {
+        try {
+            const data = await Promise.resolve(options.fetchData(context));
+            if (options.onData) {
+                await Promise.resolve(options.onData(data, context));
+            }
+            return next();
+        }
+        catch (error) {
+            if (options.onError) {
+                options.onError(error instanceof Error ? error : new Error(String(error)), context);
+            }
+            return { type: "block" };
+        }
+    };
+}
+/**
+ * Helper to create a middleware that logs route access
+ * @example
+ * ```ts
+ * const loggingMiddleware: Middleware = createLoggingMiddleware({
+ *   log: (context) => {
+ *     console.log(`Accessing: ${context.pathname}`);
+ *   }
+ * });
+ * ```
+ */
+export function createLoggingMiddleware(options) {
+    return async (context, next) => {
+        await Promise.resolve(options.log(context));
+        return next();
+    };
+}

package/package.json

@@ -5,7 +5,7 @@
     "email": "mohammed.bencheikh.dev@gmail.com",
     "url": "https://mohammedbencheikh.com/"
   },
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A professional React routing library with guards, loaders, and navigation blocking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,17 +35,13 @@
     "audit:fix": "npm audit fix",
     "validate:deps": "npm ls"
   },
-  "peerDependencies": {
-    "react": ">=16 <20",
-    "react-dom": ">=16 <20"
-  },
   "dependencies": {
     "url-join": "^5.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.2.0",
     "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2"
+    "@types/react-dom": "^19.2.2",
+    "typescript": "^5.2.0"
   },
   "overrides": {
     "minimist": "^1.2.6",