router-kit 1.3.4 → 2.0.1

package/dist/ssr/serverUtils.d.ts

@@ -0,0 +1,107 @@
+import type { Route, RouteMatch, RouteMeta } from "../types";
+/**
+ * Result from matching routes on the server
+ */
+export interface ServerMatchResult {
+    /** Matched route path */
+    matches: RouteMatch[];
+    /** Extracted route params */
+    params: Record<string, string>;
+    /** Redirect URL if route redirects */
+    redirect?: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Route metadata */
+    meta?: RouteMeta;
+}
+/**
+ * Result from data loading on the server
+ */
+export interface ServerLoaderResult<T = any> {
+    /** Loaded data keyed by route path */
+    data: Record<string, T>;
+    /** Errors encountered during loading */
+    errors: Record<string, Error>;
+    /** Time taken to load data (ms) */
+    loadTime: number;
+}
+/**
+ * Match routes for a given URL on the server
+ *
+ * @example
+ * ```ts
+ * const result = matchServerRoutes(routes, '/users/123');
+ * if (result.redirect) {
+ *   return res.redirect(result.redirect);
+ * }
+ * console.log(result.params); // { id: '123' }
+ * ```
+ */
+export declare function matchServerRoutes(routes: Route[], pathname: string, parentPath?: string): ServerMatchResult;
+/**
+ * Prefetch loader data for matched routes
+ *
+ * This function runs all route loaders in parallel and returns
+ * the combined data. Use this on the server before rendering.
+ *
+ * @example
+ * ```ts
+ * // server.ts
+ * app.get('*', async (req, res) => {
+ *   const matchResult = matchServerRoutes(routes, req.url);
+ *
+ *   if (matchResult.redirect) {
+ *     return res.redirect(matchResult.redirect);
+ *   }
+ *
+ *   const loaderResult = await prefetchLoaderData(
+ *     matchResult.matches,
+ *     req.url,
+ *     { headers: req.headers }
+ *   );
+ *
+ *   const html = renderToString(
+ *     <StaticRouter
+ *       routes={routes}
+ *       location={req.url}
+ *       loaderData={loaderResult.data}
+ *     />
+ *   );
+ *
+ *   // Inject loader data for hydration
+ *   const finalHtml = html.replace(
+ *     '</head>',
+ *     `<script>window.__LOADER_DATA__ = ${JSON.stringify(loaderResult.data)}</script></head>`
+ *   );
+ *
+ *   res.send(finalHtml);
+ * });
+ * ```
+ */
+export declare function prefetchLoaderData(matches: RouteMatch[], url: string, requestInit?: RequestInit): Promise<ServerLoaderResult>;
+/**
+ * Create a Request object from Node.js IncomingMessage
+ *
+ * @example
+ * ```ts
+ * import { createRequestFromNode } from 'router-kit/ssr';
+ *
+ * app.get('*', (req, res) => {
+ *   const request = createRequestFromNode(req);
+ *   // Use request with loaders
+ * });
+ * ```
+ */
+export declare function createRequestFromNode(nodeRequest: {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}, baseUrl?: string): Request;
+/**
+ * Generate script tag for hydrating loader data on the client
+ */
+export declare function getLoaderDataScript(data: Record<string, any>): string;
+/**
+ * Get loader data from window on the client side
+ */
+export declare function getHydratedLoaderData(): Record<string, any> | null;

package/dist/ssr/serverUtils.js

@@ -0,0 +1,288 @@
+/**
+ * Extract params from a path using a pattern
+ */
+const extractParams = (pattern, pathname) => {
+    const patternParts = pattern.split("/").filter(Boolean);
+    const pathParts = pathname.split("/").filter(Boolean);
+    if (patternParts.length !== pathParts.length) {
+        const hasCatchAll = patternParts.some((p) => p.startsWith("*"));
+        if (!hasCatchAll)
+            return null;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const patternPart = patternParts[i];
+        const pathPart = pathParts[i];
+        if (patternPart.startsWith("*")) {
+            const paramName = patternPart.slice(1) || "splat";
+            params[paramName] = pathParts.slice(i).join("/");
+            return params;
+        }
+        if (patternPart.startsWith(":")) {
+            const paramName = patternPart.slice(1);
+            if (paramName.endsWith("?")) {
+                params[paramName.slice(0, -1)] = pathPart !== null && pathPart !== void 0 ? pathPart : "";
+            }
+            else {
+                if (pathPart === undefined)
+                    return null;
+                params[paramName] = pathPart;
+            }
+            continue;
+        }
+        if (patternPart !== pathPart)
+            return null;
+    }
+    return params;
+};
+/**
+ * Join paths safely
+ */
+const joinPaths = (parent, child) => {
+    const normalizedParent = parent.endsWith("/") ? parent.slice(0, -1) : parent;
+    const normalizedChild = child.startsWith("/") ? child : `/${child}`;
+    return `${normalizedParent}${normalizedChild}`;
+};
+/**
+ * Normalize path to string (handles array paths)
+ */
+const normalizePath = (path) => {
+    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 (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
+ *
+ * @example
+ * ```ts
+ * const result = matchServerRoutes(routes, '/users/123');
+ * if (result.redirect) {
+ *   return res.redirect(result.redirect);
+ * }
+ * console.log(result.params); // { id: '123' }
+ * ```
+ */
+export function matchServerRoutes(routes, pathname, parentPath = "/") {
+    const matches = [];
+    // Sort routes by priority
+    const staticRoutes = [];
+    const dynamicRoutes = [];
+    const catchAllRoutes = [];
+    for (const route of routes) {
+        const is404 = route.path === "404" || route.path === "/404";
+        if (is404)
+            continue;
+        const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+        const hasCatchAll = pathArray.some((p) => p.includes("*"));
+        const hasDynamicParams = pathArray.some((p) => p.includes(":"));
+        if (hasCatchAll) {
+            catchAllRoutes.push(route);
+        }
+        else if (hasDynamicParams) {
+            dynamicRoutes.push(route);
+        }
+        else {
+            staticRoutes.push(route);
+        }
+    }
+    const orderedRoutes = [...staticRoutes, ...dynamicRoutes, ...catchAllRoutes];
+    for (const route of orderedRoutes) {
+        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);
+            if (extractedParams !== null) {
+                // Handle redirects
+                if (route.redirectTo) {
+                    return {
+                        matches: [],
+                        params: extractedParams,
+                        redirect: route.redirectTo,
+                        statusCode: 302,
+                        meta: route.meta,
+                    };
+                }
+                const match = {
+                    route,
+                    params: extractedParams,
+                    pathname,
+                    pathnameBase: parentPath,
+                    pattern: fullPattern,
+                };
+                matches.push(match);
+                // Check nested routes
+                if (route.children && route.children.length > 0) {
+                    const childResult = matchServerRoutes(route.children, pathname, fullPath);
+                    if (childResult.redirect) {
+                        return childResult;
+                    }
+                    if (childResult.matches.length > 0) {
+                        return {
+                            matches: [...matches, ...childResult.matches],
+                            params: { ...extractedParams, ...childResult.params },
+                            statusCode: childResult.statusCode,
+                            meta: childResult.meta || route.meta,
+                        };
+                    }
+                }
+                return {
+                    matches,
+                    params: extractedParams,
+                    statusCode: 200,
+                    meta: route.meta,
+                };
+            }
+        }
+        // Check children even if parent doesn't match
+        if (route.children) {
+            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;
+            }
+        }
+    }
+    // No match found
+    return {
+        matches: [],
+        params: {},
+        statusCode: 404,
+    };
+}
+/**
+ * Prefetch loader data for matched routes
+ *
+ * This function runs all route loaders in parallel and returns
+ * the combined data. Use this on the server before rendering.
+ *
+ * @example
+ * ```ts
+ * // server.ts
+ * app.get('*', async (req, res) => {
+ *   const matchResult = matchServerRoutes(routes, req.url);
+ *
+ *   if (matchResult.redirect) {
+ *     return res.redirect(matchResult.redirect);
+ *   }
+ *
+ *   const loaderResult = await prefetchLoaderData(
+ *     matchResult.matches,
+ *     req.url,
+ *     { headers: req.headers }
+ *   );
+ *
+ *   const html = renderToString(
+ *     <StaticRouter
+ *       routes={routes}
+ *       location={req.url}
+ *       loaderData={loaderResult.data}
+ *     />
+ *   );
+ *
+ *   // Inject loader data for hydration
+ *   const finalHtml = html.replace(
+ *     '</head>',
+ *     `<script>window.__LOADER_DATA__ = ${JSON.stringify(loaderResult.data)}</script></head>`
+ *   );
+ *
+ *   res.send(finalHtml);
+ * });
+ * ```
+ */
+export async function prefetchLoaderData(matches, url, requestInit) {
+    const startTime = Date.now();
+    const data = {};
+    const errors = {};
+    const loaderPromises = matches
+        .filter((match) => match.route.loader)
+        .map(async (match) => {
+        const routePath = match.pattern;
+        const abortController = new AbortController();
+        try {
+            // Create a Request object for the loader
+            const request = new Request(url, {
+                ...requestInit,
+                signal: abortController.signal,
+            });
+            const loaderArgs = {
+                params: match.params,
+                request,
+                signal: abortController.signal,
+            };
+            const result = await match.route.loader(loaderArgs);
+            data[routePath] = result;
+        }
+        catch (error) {
+            errors[routePath] =
+                error instanceof Error ? error : new Error(String(error));
+        }
+    });
+    await Promise.all(loaderPromises);
+    return {
+        data,
+        errors,
+        loadTime: Date.now() - startTime,
+    };
+}
+/**
+ * Create a Request object from Node.js IncomingMessage
+ *
+ * @example
+ * ```ts
+ * import { createRequestFromNode } from 'router-kit/ssr';
+ *
+ * app.get('*', (req, res) => {
+ *   const request = createRequestFromNode(req);
+ *   // Use request with loaders
+ * });
+ * ```
+ */
+export function createRequestFromNode(nodeRequest, baseUrl = "http://localhost") {
+    const url = new URL(nodeRequest.url || "/", baseUrl);
+    const headers = new Headers();
+    if (nodeRequest.headers) {
+        for (const [key, value] of Object.entries(nodeRequest.headers)) {
+            if (value) {
+                headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+            }
+        }
+    }
+    return new Request(url.toString(), {
+        method: nodeRequest.method || "GET",
+        headers,
+    });
+}
+/**
+ * Generate script tag for hydrating loader data on the client
+ */
+export function getLoaderDataScript(data) {
+    const serialized = JSON.stringify(data).replace(/</g, "\\u003c");
+    return `<script>window.__ROUTER_KIT_DATA__ = ${serialized}</script>`;
+}
+/**
+ * Get loader data from window on the client side
+ */
+export function getHydratedLoaderData() {
+    if (typeof window === "undefined")
+        return null;
+    return window.__ROUTER_KIT_DATA__ || null;
+}

package/dist/types/index.d.ts

@@ -1,8 +1,70 @@
-import { JSX } from "react";
+import { ComponentType, JSX, LazyExoticComponent, ReactNode } from "react";
+/**
+ * Route configuration interface
+ */
 export interface Route {
+    /** Path pattern(s) for the route */
     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;
+    /** Lazy-loaded component */
+    lazy?: LazyExoticComponent<ComponentType<any>>;
+    /** Route loader function for data fetching */
+    loader?: RouteLoader;
+    /** Error boundary element for this route */
+    errorElement?: JSX.Element;
+    /** Redirect to another path */
+    redirectTo?: string;
+    /** Route guard function */
+    guard?: RouteGuard;
+    /** Route metadata */
+    meta?: RouteMeta;
+}
+/**
+ * Route loader function type
+ */
+export type RouteLoader<T = any> = (args: LoaderArgs) => Promise<T> | T;
+/**
+ * Loader function arguments
+ */
+export interface LoaderArgs {
+    params: Record<string, string>;
+    request: Request;
+    signal: AbortSignal;
+}
+/**
+ * Route guard function type
+ */
+export type RouteGuard = (args: GuardArgs) => boolean | Promise<boolean> | string;
+/**
+ * Guard function arguments
+ */
+export interface GuardArgs {
+    pathname: string;
+    params: Record<string, string>;
+    search: string;
+}
+/**
+ * Route metadata
+ */
+export interface RouteMeta {
+    title?: string;
+    description?: string;
+    [key: string]: any;
+}
+/**
+ * Match result from route matching
+ */
+export interface RouteMatch {
+    route: Route;
+    params: Record<string, string>;
+    pathname: string;
+    pathnameBase: string;
+    pattern: string;
 }
 export interface GetComponent {
     (routes: Route[], currentPath: string, parentPath?: string): JSX.Element | null;
@@ -12,20 +74,96 @@ export interface Routes {
     fullPath: string;
     path: string;
 }
+/**
+ * Navigation options
+ */
 export interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
     replace?: boolean;
+    /** State to pass with navigation */
     state?: any;
+    /** Prevent scroll reset after navigation */
+    preventScrollReset?: boolean;
+    /** Relative navigation base */
+    relative?: "route" | "path";
 }
+/**
+ * Navigation function type
+ */
+export type NavigateFunction = {
+    (to: string, options?: NavigateOptions): void;
+    (delta: number): void;
+};
+/**
+ * Router context type
+ */
 export interface RouterContextType {
+    /** Current pathname */
+    pathname: string;
+    /** Full path pattern with params (e.g., /users/:id) */
+    pattern: string;
+    /** Current search string */
+    search: string;
+    /** Current hash */
+    hash: string;
+    /** History state */
+    state: any;
+    /** Route parameters */
+    params: Record<string, string>;
+    /** Current route match */
+    matches: RouteMatch[];
+    /** Navigate function */
+    navigate: NavigateFunction;
+    /** Go back in history */
+    back: () => void;
+    /** Go forward in history */
+    forward: () => void;
+    /** Navigation in progress */
+    isNavigating: boolean;
+    /** Loader data from current route */
+    loaderData: any;
+    /** Current route meta */
+    meta: RouteMeta | null;
+    /** @deprecated Use pathname instead */
     path: string;
+    /** @deprecated Use pattern instead */
     fullPathWithParams: string;
-    navigate: (to: string, options?: NavigateOptions) => void;
 }
+/**
+ * Location object
+ */
 export interface Location {
+    /** Current pathname */
     pathname: string;
+    /** Query string including leading ? */
     search: string;
+    /** Hash including leading # */
     hash: string;
+    /** History state */
     state: any;
+    /** Unique key for this location */
+    key: string;
+}
+/**
+ * History action types
+ */
+export type HistoryAction = "POP" | "PUSH" | "REPLACE";
+/**
+ * Navigation blocker function
+ */
+export type BlockerFunction = (args: {
+    currentLocation: Location;
+    nextLocation: Location;
+    action: HistoryAction;
+}) => boolean;
+/**
+ * Blocker state
+ */
+export interface Blocker {
+    state: "blocked" | "proceeding" | "unblocked";
+    proceed: () => void;
+    reset: () => void;
+    location?: Location;
 }
 export interface RouterError extends Error {
     code: "NAVIGATION_ABORTED" | "ROUTER_NOT_FOUND" | "INVALID_ROUTE";
@@ -33,4 +171,65 @@ export interface RouterError extends Error {
 export interface DynamicComponents {
     (dynamicComponentsObject: Record<string, JSX.Element>, variationParam: string): JSX.Element;
 }
+/**
+ * Link component props
+ */
+export interface LinkProps {
+    /** Target path */
+    to: string;
+    /** Children to render */
+    children: ReactNode;
+    /** CSS class name */
+    className?: string;
+    /** Navigation options */
+    replace?: boolean;
+    /** State to pass */
+    state?: any;
+    /** Prevent scroll reset */
+    preventScrollReset?: boolean;
+    /** Target attribute */
+    target?: string;
+    /** Rel attribute */
+    rel?: string;
+    /** Title attribute */
+    title?: string;
+    /** onClick handler */
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+}
+/**
+ * NavLink component props
+ */
+export interface NavLinkProps extends LinkProps {
+    /** Class name when active */
+    activeClassName?: string;
+    /** Style when active */
+    activeStyle?: React.CSSProperties;
+    /** Custom active check function */
+    isActive?: (match: RouteMatch | null, location: Location) => boolean;
+    /** Match end of path (exact matching) */
+    end?: boolean;
+    /** Case sensitive matching */
+    caseSensitive?: boolean;
+}
+/**
+ * Router provider props
+ */
+export interface RouterProviderProps {
+    routes: Route[];
+    /** Base path for all routes */
+    basename?: string;
+    /** Initial entries for memory history (SSR) */
+    initialEntries?: string[];
+    /** Fallback element during suspense */
+    fallbackElement?: JSX.Element;
+}
+/**
+ * Scroll restoration options
+ */
+export interface ScrollRestorationProps {
+    /** Custom scroll key generator */
+    getKey?: (location: Location, matches: RouteMatch[]) => string;
+    /** Storage key for scroll positions */
+    storageKey?: string;
+}
 export type { RouterKitError } from "../utils/error/errors";

package/package.json

@@ -5,10 +5,22 @@
     "email": "mohammed.bencheikh.dev@gmail.com",
     "url": "https://mohammedbencheikh.com/"
   },
-  "version": "1.3.4",
-  "description": "A small React routing provider library",
+  "version": "2.0.1",
+  "description": "A professional React routing library with guards, loaders, and navigation blocking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr/index.d.ts",
+      "import": "./dist/ssr/index.js",
+      "require": "./dist/ssr/index.js"
+    }
+  },
   "files": [
     "dist"
   ],