@bquery/bquery 1.6.0 → 1.8.1

package/src/router/router.ts

@@ -3,8 +3,17 @@
  * @module bquery/router
  */
 
+import { isPrototypePollutionKey } from '../core/utils/object';
 import { createRoute } from './match';
-import { currentRoute, getActiveRouter, routeSignal, setActiveRouter } from './state';
+import {
+  beginNavigation,
+  currentRoute,
+  endNavigation,
+  getActiveRouter,
+  resetNavigationState,
+  routeSignal,
+  setActiveRouter,
+} from './state';
 import type { NavigationGuard, Route, Router, RouterOptions } from './types';
 import { flattenRoutes } from './utils';
 
@@ -12,6 +21,19 @@ import { flattenRoutes } from './utils';
 // Router Creation
 // ============================================================================
 
+const MAX_SCROLL_POSITION_ENTRIES = 100;
+
+const sanitizeHistoryState = (state: Record<string, unknown>): Record<string, unknown> => {
+  const sanitized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(state)) {
+    if (isPrototypePollutionKey(key)) continue;
+    sanitized[key] = value;
+  }
+
+  return sanitized;
+};
+
 /**
  * Creates and initializes a router instance.
  *
@@ -26,10 +48,12 @@ import { flattenRoutes } from './utils';
  *   routes: [
  *     { path: '/', component: () => import('./pages/Home') },
  *     { path: '/about', component: () => import('./pages/About') },
- *     { path: '/user/:id', component: () => import('./pages/User') },
+ *     { path: '/user/:id(\\d+)', component: () => import('./pages/User') },
+ *     { path: '/old-page', redirectTo: '/new-page' },
  *     { path: '*', component: () => import('./pages/NotFound') },
  *   ],
  *   base: '/app',
+ *   scrollRestoration: true,
  * });
  *
  * router.beforeEach((to, from) => {
@@ -46,7 +70,7 @@ export const createRouter = (options: RouterOptions): Router => {
     existingRouter.destroy();
   }
 
-  const { routes, base = '', hash: useHash = false } = options;
+  const { routes, base = '', hash: useHash = false, scrollRestoration = false } = options;
 
   // Instance-specific guards and hooks (not shared globally)
   const beforeGuards: NavigationGuard[] = [];
@@ -55,6 +79,98 @@ export const createRouter = (options: RouterOptions): Router => {
   // Flatten nested routes (base-relative, not including the base path)
   const flatRoutes = flattenRoutes(routes);
 
+  // Scroll position storage keyed by history state id
+  const scrollPositions = new Map<string, { x: number; y: number }>();
+  let currentScrollKey = '0';
+  let scrollKeyCounter = 0;
+  let previousScrollRestoration: History['scrollRestoration'] | null = null;
+
+  // Enable manual scroll restoration if scrollRestoration is configured
+  if (scrollRestoration && typeof history !== 'undefined' && 'scrollRestoration' in history) {
+    previousScrollRestoration = history.scrollRestoration;
+    if (history.scrollRestoration !== 'manual') {
+      history.scrollRestoration = 'manual';
+    }
+
+    const state =
+      history.state && typeof history.state === 'object'
+        ? (history.state as Record<string, unknown>)
+        : {};
+
+    if (typeof state.__bqScrollKey !== 'string') {
+      const currentUrl = useHash
+        ? window.location.hash || '#/'
+        : `${window.location.pathname}${window.location.search}${window.location.hash}`;
+      history.replaceState({ ...state, __bqScrollKey: currentScrollKey }, '', currentUrl);
+    }
+  }
+
+  /**
+   * Generates a unique key for the current history entry.
+   * @internal
+   */
+  const getScrollKey = (): string => {
+    return (history.state && history.state.__bqScrollKey) || currentScrollKey;
+  };
+
+  /**
+   * Generates a unique key for a new history entry.
+   * @internal
+   */
+  const createScrollKey = (): string => `${Date.now()}-${scrollKeyCounter++}`;
+
+  /**
+   * Saves current scroll position for the current history entry.
+   * @internal
+   */
+  const saveScrollPosition = (key = getScrollKey()): void => {
+    if (!scrollRestoration) return;
+    if (scrollPositions.has(key)) {
+      // Refresh the insertion order so pruning behaves like an LRU cache.
+      scrollPositions.delete(key);
+    }
+    scrollPositions.set(key, { x: window.scrollX, y: window.scrollY });
+    while (scrollPositions.size > MAX_SCROLL_POSITION_ENTRIES) {
+      const oldestKey = scrollPositions.keys().next().value as string | undefined;
+      if (oldestKey === undefined) {
+        break;
+      }
+      scrollPositions.delete(oldestKey);
+    }
+  };
+
+  /**
+   * Restores scroll position for the current history entry.
+   * @internal
+   */
+  const restoreScrollPosition = (key = getScrollKey()): void => {
+    if (!scrollRestoration) return;
+    const pos = scrollPositions.get(key);
+    if (pos) {
+      window.scrollTo(pos.x, pos.y);
+    } else {
+      window.scrollTo(0, 0);
+    }
+  };
+
+  /**
+   * Builds history state for canceled navigations without dropping
+   * the scroll restoration key for the current entry.
+   * @internal
+   */
+  const getRestoreHistoryState = (): Record<string, unknown> => {
+    const state =
+      history.state && typeof history.state === 'object'
+        ? { ...(history.state as Record<string, unknown>) }
+        : {};
+
+    if (scrollRestoration) {
+      state.__bqScrollKey = currentScrollKey;
+    }
+
+    return state;
+  };
+
   /**
    * Gets the current path from the URL.
    */
@@ -99,68 +215,152 @@ export const createRouter = (options: RouterOptions): Router => {
    */
   const performNavigation = async (
     path: string,
-    method: 'pushState' | 'replaceState'
+    method: 'pushState' | 'replaceState',
+    visitedPaths: Set<string> = new Set()
   ): Promise<void> => {
-    const { pathname, search, hash } = getCurrentPath();
-    const from = createRoute(pathname, search, hash, flatRoutes);
+    beginNavigation();
+    try {
+      const { pathname, search, hash } = getCurrentPath();
+      const from = createRoute(pathname, search, hash, flatRoutes);
 
-    // Parse the target path
-    const url = new URL(path, window.location.origin);
-    const to = createRoute(url.pathname, url.search, url.hash, flatRoutes);
+      // Parse the target path
+      const url = new URL(path, window.location.origin);
+      const resolvedPath = `${url.pathname}${url.search}${url.hash}`;
+      if (visitedPaths.has(resolvedPath)) {
+        throw new Error(`bQuery router: redirect loop detected for path "${resolvedPath}"`);
+      }
+      visitedPaths.add(resolvedPath);
+      const to = createRoute(url.pathname, url.search, url.hash, flatRoutes);
 
-    // Run beforeEach guards
-    for (const guard of beforeGuards) {
-      const result = await guard(to, from);
-      if (result === false) {
-        return; // Cancel navigation
+      // Check for redirectTo on the matched route
+      if (to.matched?.redirectTo) {
+        // Navigate to the redirect target instead
+        await performNavigation(to.matched.redirectTo, method, visitedPaths);
+        return;
       }
-    }
 
-    // Update browser history
-    const fullPath = useHash ? `#${path}` : `${base}${path}`;
-    history[method]({}, '', fullPath);
+      // Run route-level beforeEnter guard
+      if (to.matched?.beforeEnter) {
+        const result = await to.matched.beforeEnter(to, from);
+        if (result === false) {
+          return; // Cancel navigation
+        }
+      }
+
+      // Run beforeEach guards
+      for (const guard of beforeGuards) {
+        const result = await guard(to, from);
+        if (result === false) {
+          return; // Cancel navigation
+        }
+      }
+
+      // Save scroll position before navigation
+      saveScrollPosition();
+
+      // Update browser history
+      const existingScrollKey = scrollRestoration ? getScrollKey() : undefined;
+      const scrollKey =
+        method === 'replaceState' && existingScrollKey ? existingScrollKey : createScrollKey();
+      const fullPath = useHash ? `#${path}` : `${base}${path}`;
+      const baseState =
+        scrollRestoration && history.state && typeof history.state === 'object'
+          ? sanitizeHistoryState(history.state as Record<string, unknown>)
+          : {};
+      const state = scrollRestoration ? { ...baseState, __bqScrollKey: scrollKey } : {};
+      history[method](state, '', fullPath);
+      currentScrollKey = scrollKey;
 
-    // Update route signal
-    syncRoute();
+      // Update route signal
+      syncRoute();
 
-    // Run afterEach hooks
-    for (const hook of afterHooks) {
-      hook(routeSignal.value, from);
+      // Scroll to top on push navigation
+      if (scrollRestoration && method === 'pushState') {
+        window.scrollTo(0, 0);
+      }
+
+      // Run afterEach hooks
+      for (const hook of afterHooks) {
+        hook(routeSignal.value, from);
+      }
+    } finally {
+      endNavigation();
     }
   };
 
   /**
    * Handle popstate events (back/forward).
    */
-  const handlePopState = async (): Promise<void> => {
-    const { pathname, search, hash } = getCurrentPath();
-    const from = routeSignal.value;
-    const to = createRoute(pathname, search, hash, flatRoutes);
-
-    // Run beforeEach guards (supports async guards)
-    for (const guard of beforeGuards) {
-      const result = await guard(to, from);
-      if (result === false) {
-        // Restore previous state with full URL (including query/hash)
-        const queryString = new URLSearchParams(
-          Object.entries(from.query).flatMap(([key, value]) =>
-            Array.isArray(value) ? value.map((v) => [key, v]) : [[key, value]]
-          )
-        ).toString();
-        const search = queryString ? `?${queryString}` : '';
-        const hash = from.hash ? `#${from.hash}` : '';
-        const restorePath = useHash
-          ? `#${from.path}${search}${hash}`
-          : `${base}${from.path}${search}${hash}`;
-        history.replaceState({}, '', restorePath);
+  const handlePopState = async (event: PopStateEvent): Promise<void> => {
+    beginNavigation();
+    try {
+      const { pathname, search, hash } = getCurrentPath();
+      const from = routeSignal.value;
+      const to = createRoute(pathname, search, hash, flatRoutes);
+
+      // Check for redirectTo on the matched route
+      if (to.matched?.redirectTo) {
+        await performNavigation(to.matched.redirectTo, 'replaceState');
         return;
       }
-    }
 
-    syncRoute();
+      // Run route-level beforeEnter guard
+      if (to.matched?.beforeEnter) {
+        const result = await to.matched.beforeEnter(to, from);
+        if (result === false) {
+          // Restore previous state with full URL (including query/hash)
+          const queryString = new URLSearchParams(
+            Object.entries(from.query).flatMap(([key, value]) =>
+              Array.isArray(value) ? value.map((v) => [key, v]) : [[key, value]]
+            )
+          ).toString();
+          const searchStr = queryString ? `?${queryString}` : '';
+          const hashStr = from.hash ? `#${from.hash}` : '';
+          const restorePath = useHash
+            ? `#${from.path}${searchStr}${hashStr}`
+            : `${base}${from.path}${searchStr}${hashStr}`;
+          history.replaceState(getRestoreHistoryState(), '', restorePath);
+          return;
+        }
+      }
 
-    for (const hook of afterHooks) {
-      hook(routeSignal.value, from);
+      // Run beforeEach guards (supports async guards)
+      for (const guard of beforeGuards) {
+        const result = await guard(to, from);
+        if (result === false) {
+          // Restore previous state with full URL (including query/hash)
+          const queryString = new URLSearchParams(
+            Object.entries(from.query).flatMap(([key, value]) =>
+              Array.isArray(value) ? value.map((v) => [key, v]) : [[key, value]]
+            )
+          ).toString();
+          const search = queryString ? `?${queryString}` : '';
+          const hash = from.hash ? `#${from.hash}` : '';
+          const restorePath = useHash
+            ? `#${from.path}${search}${hash}`
+            : `${base}${from.path}${search}${hash}`;
+          history.replaceState(getRestoreHistoryState(), '', restorePath);
+          return;
+        }
+      }
+
+      // Save scroll position of the page we're leaving
+      saveScrollPosition(currentScrollKey);
+
+      // Update scroll key from history state
+      currentScrollKey =
+        (event.state as { __bqScrollKey?: string } | null)?.__bqScrollKey ?? getScrollKey();
+
+      syncRoute();
+
+      // Restore scroll position for the entry we're navigating to
+      restoreScrollPosition(currentScrollKey);
+
+      for (const hook of afterHooks) {
+        hook(routeSignal.value, from);
+      }
+    } finally {
+      endNavigation();
     }
   };
 
@@ -202,6 +402,16 @@ export const createRouter = (options: RouterOptions): Router => {
       window.removeEventListener('popstate', handlePopState);
       beforeGuards.length = 0;
       afterHooks.length = 0;
+      scrollPositions.clear();
+      // Restore the previous scroll restoration mode on destroy
+      if (
+        previousScrollRestoration !== null &&
+        typeof history !== 'undefined' &&
+        'scrollRestoration' in history
+      ) {
+        history.scrollRestoration = previousScrollRestoration;
+      }
+      resetNavigationState();
       setActiveRouter(null);
     },
   };

package/src/router/state.ts

@@ -3,7 +3,7 @@
  * @module bquery/router
  */
 
-import { computed, signal, type ReadonlySignal, type Signal } from '../reactive/index';
+import { computed, readonly, signal, type ReadonlySignal, type Signal } from '../reactive/index';
 import type { Route, Router } from './types';
 
 // ============================================================================
@@ -27,8 +27,8 @@ export const routeSignal: Signal<Route> = signal<Route>({
  *
  * @example
  * ```ts
- * import { currentRoute } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
+ * import { currentRoute } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
  *
  * effect(() => {
  *   document.title = `Page: ${currentRoute.value.path}`;
@@ -37,6 +37,54 @@ export const routeSignal: Signal<Route> = signal<Route>({
  */
 export const currentRoute: ReadonlySignal<Route> = computed(() => routeSignal.value);
 
+/** @internal */
+const navigationCountSignal: Signal<number> = signal(0);
+
+/** @internal */
+const isNavigatingSignal: Signal<boolean> = signal(false);
+
+/**
+ * Reactive signal indicating whether a navigation is currently in progress.
+ *
+ * This becomes `true` while async guards or redirect resolution are running,
+ * then flips back to `false` once navigation finishes or is canceled.
+ *
+ * @example
+ * ```ts
+ * import { isNavigating } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * effect(() => {
+ *   document.body.toggleAttribute('data-loading-route', isNavigating.value);
+ * });
+ * ```
+ */
+export const isNavigating: ReadonlySignal<boolean> = readonly(isNavigatingSignal);
+
+/** @internal */
+export const beginNavigation = (): void => {
+  if (navigationCountSignal.value === 0) {
+    isNavigatingSignal.value = true;
+  }
+  navigationCountSignal.value += 1;
+};
+
+/** @internal */
+export const endNavigation = (): void => {
+  const nextCount = Math.max(0, navigationCountSignal.value - 1);
+  navigationCountSignal.value = nextCount;
+
+  if (nextCount === 0) {
+    isNavigatingSignal.value = false;
+  }
+};
+
+/** @internal */
+export const resetNavigationState = (): void => {
+  navigationCountSignal.value = 0;
+  isNavigatingSignal.value = false;
+};
+
 /** @internal */
 export const getActiveRouter = (): Router | null => activeRouter;
 

package/src/router/types.ts

@@ -32,19 +32,59 @@ export type Route = {
 /**
  * Route definition for configuration.
  */
-export type RouteDefinition = {
-  /** Path pattern (e.g., '/user/:id', '/posts/*') */
+type BaseRouteDefinition = {
+  /**
+   * Path pattern (e.g., '/user/:id', '/posts/*').
+   * Supports regex constraints on params: `/user/:id(\\d+)`.
+   * Constraint backreferences are not supported.
+   */
   path: string;
-  /** Component loader (sync or async) */
-  component: () => unknown | Promise<unknown>;
   /** Optional route name for programmatic navigation */
   name?: string;
   /** Optional metadata */
   meta?: Record<string, unknown>;
   /** Nested child routes */
   children?: RouteDefinition[];
+  /**
+   * Per-route navigation guard. Called before entering this route.
+   * Return `false` to cancel navigation.
+   *
+   * @example
+   * ```ts
+   * {
+   *   path: '/admin',
+   *   component: () => import('./Admin'),
+   *   beforeEnter: (to, from) => isAuthenticated() || false,
+   * }
+   * ```
+   */
+  beforeEnter?: NavigationGuard;
 };
 
+type ComponentRouteDefinition = BaseRouteDefinition & {
+  /** Component loader (sync or async) */
+  component: () => unknown | Promise<unknown>;
+  redirectTo?: never;
+};
+
+type RedirectRouteDefinition = BaseRouteDefinition & {
+  /**
+   * Redirect target path. When the route is matched, the router
+   * automatically navigates to this path instead.
+   *
+   * @example
+   * ```ts
+   * { path: '/old-page', redirectTo: '/new-page' }
+   * ```
+   */
+  redirectTo: string;
+  component?: never;
+  children?: never;
+  beforeEnter?: never;
+};
+
+export type RouteDefinition = ComponentRouteDefinition | RedirectRouteDefinition;
+
 /**
  * Router configuration options.
  */
@@ -55,6 +95,12 @@ export type RouterOptions = {
   base?: string;
   /** Use hash-based routing instead of history (default: false) */
   hash?: boolean;
+  /**
+   * Restore scroll position on back/forward navigation (default: false).
+   * When enabled, the router saves scroll positions for each history entry
+   * and restores them on popstate events.
+   */
+  scrollRestoration?: boolean;
 };
 
 /**

package/src/router/use-route.ts

@@ -0,0 +1,68 @@
+/**
+ * Reactive route composable.
+ * @module bquery/router
+ */
+
+import { computed, type ReadonlySignal } from '../reactive/index';
+import { routeSignal } from './state';
+import type { Route, RouteDefinition } from './types';
+
+// ============================================================================
+// useRoute Composable
+// ============================================================================
+
+/**
+ * Return type for {@link useRoute}.
+ * Provides reactive access to individual route properties.
+ */
+export type UseRouteReturn = {
+  /** Full reactive route object */
+  route: ReadonlySignal<Route>;
+  /** Reactive current path */
+  path: ReadonlySignal<string>;
+  /** Reactive route params */
+  params: ReadonlySignal<Record<string, string>>;
+  /** Reactive query params */
+  query: ReadonlySignal<Record<string, string | string[]>>;
+  /** Reactive hash fragment (without #) */
+  hash: ReadonlySignal<string>;
+  /** Reactive matched route definition */
+  matched: ReadonlySignal<RouteDefinition | null>;
+};
+
+const route = computed(() => routeSignal.value);
+const path = computed(() => route.value.path);
+const params = computed(() => route.value.params);
+const query = computed(() => route.value.query);
+const hash = computed(() => route.value.hash);
+const matched = computed(() => route.value.matched);
+
+const routeHandle: UseRouteReturn = { route, path, params, query, hash, matched };
+
+/**
+ * Returns reactive access to the current route, params, query, and hash.
+ *
+ * Each property is a readonly computed signal that updates automatically
+ * when the route changes. This is useful for fine-grained reactivity
+ * where you only need to subscribe to specific route parts.
+ *
+ * @returns An object with reactive route properties
+ *
+ * @example
+ * ```ts
+ * import { useRoute } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const { path, params, query, hash } = useRoute();
+ *
+ * effect(() => {
+ *   console.log('Path:', path.value);
+ *   console.log('Params:', params.value);
+ *   console.log('Query:', query.value);
+ *   console.log('Hash:', hash.value);
+ * });
+ * ```
+ */
+export const useRoute = (): UseRouteReturn => {
+  return routeHandle;
+};

package/src/router/utils.ts

@@ -4,6 +4,8 @@
  */
 
 import { computed, type ReadonlySignal } from '../reactive/index';
+import { getRouteConstraintRegex } from './constraints';
+import { isParamChar, isParamStart, readConstraint } from './path-pattern';
 import { getActiveRouter, routeSignal } from './state';
 import type { RouteDefinition } from './types';
 
@@ -41,6 +43,9 @@ export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): Route
  * @param name - The route name
  * @param params - Route params to interpolate
  * @returns The resolved path
+ * @throws {Error} If no router is initialized, the route name is unknown,
+ * a required path param is missing from `params`, a param value does not satisfy
+ * its route regex constraint, or a route param constraint has invalid syntax
  *
  * @example
  * ```ts
@@ -61,9 +66,45 @@ export const resolve = (name: string, params: Record<string, string> = {}): stri
     throw new Error(`bQuery router: Route "${name}" not found.`);
   }
 
-  let path = route.path;
-  for (const [key, value] of Object.entries(params)) {
-    path = path.replace(`:${key}`, encodeURIComponent(value));
+  let path = '';
+  for (let i = 0; i < route.path.length; ) {
+    if (route.path[i] === ':' && isParamStart(route.path[i + 1])) {
+      let nameEnd = i + 2;
+      while (nameEnd < route.path.length && isParamChar(route.path[nameEnd])) {
+        nameEnd++;
+      }
+
+      let nextIndex = nameEnd;
+      let constraint: string | null = null;
+      if (route.path[nameEnd] === '(') {
+        const parsedConstraint = readConstraint(route.path, nameEnd);
+        if (!parsedConstraint) {
+          throw new Error(
+            `bQuery router: Invalid constraint syntax in path "${route.path}" for route "${name}".`
+          );
+        }
+        constraint = parsedConstraint.constraint;
+        nextIndex = parsedConstraint.endIndex;
+      }
+
+      const key = route.path.slice(i + 1, nameEnd);
+      const value = params[key];
+      if (value === undefined) {
+        throw new Error(`bQuery router: Missing required param "${key}" for route "${name}".`);
+      }
+      if (constraint && !getRouteConstraintRegex(constraint).test(value)) {
+        throw new Error(
+          `bQuery router: Param "${key}" with value "${value}" does not satisfy the route constraint "${constraint}" for route "${name}".`
+        );
+      }
+
+      path += encodeURIComponent(value);
+      i = nextIndex;
+      continue;
+    }
+
+    path += route.path[i];
+    i++;
   }
 
   return path;

package/src/security/index.ts

@@ -1,17 +1,12 @@
-/**
- * Security module providing sanitization, CSP compatibility, and Trusted Types.
- *
- * @module bquery/security
- */
-
-export { generateNonce, hasCSPDirective } from './csp';
-export {
-  escapeHtml,
-  sanitizeHtml as sanitize,
-  sanitizeHtml,
-  stripTags,
-} from './sanitize';
-export { trusted } from './trusted-html';
-export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
-export type { SanitizedHtml, TrustedHtml } from './trusted-html';
-export type { SanitizeOptions } from './sanitize';
+/**
+ * Security module providing sanitization, CSP compatibility, and Trusted Types.
+ *
+ * @module bquery/security
+ */
+
+export { generateNonce, hasCSPDirective } from './csp';
+export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
+export { trusted } from './trusted-html';
+export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
+export type { SanitizeOptions } from './types';