router-kit 2.0.0 → 2.1.0

package/dist/core/createRouter.js

@@ -1,17 +1,22 @@
 /**
  * Normalizes a path by removing leading slashes and handling arrays
+ * Preserves "/" as empty string for root path matching
  */
 const normalizePath = (path) => {
+    if (path === undefined)
+        return "";
     const pathArray = Array.isArray(path) ? path : [path];
-    return pathArray
-        .map((p) => {
+    const normalized = pathArray.map((p) => {
         if (!p)
             return "";
+        // Root path "/" becomes empty string
+        if (p === "/")
+            return "";
         // Remove leading slashes but preserve the path structure
         return p.startsWith("/") ? p.replace(/^\/+/, "") : p;
-    })
-        .filter(Boolean)
-        .join("|");
+    });
+    // Join with | but don't filter out empty strings (they represent root "/")
+    return normalized.join("|");
 };
 /**
  * Validates a route configuration
@@ -26,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/hooks/useLocation.js

@@ -6,10 +6,15 @@ const createKey = () => {
     return Math.random().toString(36).substring(2, 10);
 };
 /**
- * Get current location snapshot
+ * Cached location to avoid infinite loops with useSyncExternalStore
+ */
+let cachedLocation = null;
+let cachedLocationString = "";
+/**
+ * Get current location snapshot (cached)
  */
 const getLocationSnapshot = () => {
-    var _a, _b;
+    var _a;
     if (typeof window === "undefined") {
         return {
             pathname: "",
@@ -19,13 +24,24 @@ const getLocationSnapshot = () => {
             key: "default",
         };
     }
-    return {
+    // Create a string representation to compare
+    const currentLocationString = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    const currentStateKey = (_a = window.history.state) === null || _a === void 0 ? void 0 : _a.key;
+    const fullLocationString = `${currentLocationString}|${currentStateKey || ""}`;
+    // Return cached location if nothing changed
+    if (cachedLocation && cachedLocationString === fullLocationString) {
+        return cachedLocation;
+    }
+    // Create new location and cache it
+    cachedLocation = {
         pathname: window.location.pathname,
         search: window.location.search,
         hash: window.location.hash,
         state: window.history.state,
-        key: (_b = (_a = window.history.state) === null || _a === void 0 ? void 0 : _a.key) !== null && _b !== void 0 ? _b : createKey(),
+        key: currentStateKey !== null && currentStateKey !== void 0 ? currentStateKey : createKey(),
     };
+    cachedLocationString = fullLocationString;
+    return cachedLocation;
 };
 /**
  * Subscribe to location changes
@@ -34,23 +50,30 @@ const subscribeToLocation = (callback) => {
     if (typeof window === "undefined") {
         return () => { };
     }
-    window.addEventListener("popstate", callback);
-    window.addEventListener("locationchange", callback);
+    const handleLocationChange = () => {
+        // Invalidate cache on location change
+        cachedLocation = null;
+        cachedLocationString = "";
+        callback();
+    };
+    window.addEventListener("popstate", handleLocationChange);
+    window.addEventListener("locationchange", handleLocationChange);
     return () => {
-        window.removeEventListener("popstate", callback);
-        window.removeEventListener("locationchange", callback);
+        window.removeEventListener("popstate", handleLocationChange);
+        window.removeEventListener("locationchange", handleLocationChange);
     };
 };
 /**
- * Server-side location snapshot
+ * Server-side location snapshot (cached)
  */
-const getServerSnapshot = () => ({
+const serverSnapshot = {
     pathname: "",
     search: "",
     hash: "",
     state: null,
     key: "default",
-});
+};
+const getServerSnapshot = () => serverSnapshot;
 /**
  * Hook to access the current location
  *

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;
@@ -67,6 +71,32 @@ const joinPaths = (parent, child) => {
     const normalizedChild = child.startsWith("/") ? child : `/${child}`;
     return `${normalizedParent}${normalizedChild}`;
 };
+/**
+ * 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("|");
+    }
+    return 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] || "";
+    }
+    // Handle pipe-separated paths (already normalized)
+    if (path.includes("|")) {
+        return path.split("|")[0];
+    }
+    return path;
+};
 /**
  * StaticRouter - Server-side rendering router
  *
@@ -115,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 };
             }
@@ -138,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) {
@@ -157,8 +191,16 @@ const StaticRouter = ({ routes, location: locationString, basename = "", loaderD
             ...catchAllRoutes,
         ];
         for (const route of orderedRoutes) {
-            const fullPath = joinPaths(parentPath, route.path);
-            const matchResult = matchPath(fullPath, currentPath);
+            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, isParent);
             if (matchResult) {
                 // Handle redirects
                 if (route.redirectTo) {
@@ -210,17 +252,29 @@ 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) {
-                const fullPath = joinPaths(parentPath, route.path);
-                const childMatch = findMatch(route.children, currentPath, fullPath);
+                const firstPath = getFirstPath(route.path);
+                const childFullPath = joinPaths(parentPath, firstPath);
+                const childMatch = findMatch(route.children, currentPath, childFullPath);
                 if (childMatch)
                     return childMatch;
             }

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;
@@ -43,6 +47,32 @@ const joinPaths = (parent, child) => {
     const normalizedChild = child.startsWith("/") ? child : `/${child}`;
     return `${normalizedParent}${normalizedChild}`;
 };
+/**
+ * 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("|");
+    }
+    return 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] || "";
+    }
+    // Handle pipe-separated paths (already normalized)
+    if (path.includes("|")) {
+        return path.split("|")[0];
+    }
+    return path;
+};
 /**
  * Match routes for a given URL on the server
  *
@@ -65,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) {
@@ -80,11 +114,14 @@ export function matchServerRoutes(routes, pathname, parentPath = "/") {
     }
     const orderedRoutes = [...staticRoutes, ...dynamicRoutes, ...catchAllRoutes];
     for (const route of orderedRoutes) {
-        const fullPath = joinPaths(parentPath, route.path);
-        const patterns = route.path.split("|");
+        const normalizedRoutePath = normalizePath(route.path);
+        const firstPath = getFirstPath(route.path);
+        const fullPath = joinPaths(parentPath, firstPath);
+        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) {
@@ -119,18 +156,27 @@ 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
         if (route.children) {
-            const fullPath = joinPaths(parentPath, route.path);
-            const childResult = matchServerRoutes(route.children, pathname, fullPath);
+            const firstPath = getFirstPath(route.path);
+            const childFullPath = joinPaths(parentPath, firstPath);
+            const childResult = matchServerRoutes(route.children, pathname, childFullPath);
             if (childResult.matches.length > 0 || childResult.redirect) {
                 return childResult;
             }

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;