@bquery/bquery 1.5.0 → 1.7.0

package/src/router/types.ts

@@ -1,93 +1,139 @@
-/**
- * Router types and public contracts.
- * @module bquery/router
- */
-
-import type { ReadonlySignal } from '../reactive/index';
-
-/**
- * Represents a parsed route with matched params.
- */
-export type Route = {
-  /** The current path (e.g., '/user/42') */
-  path: string;
-  /** Extracted route params (e.g., { id: '42' }) */
-  params: Record<string, string>;
-  /**
-   * Query string params.
-   * Each key maps to a single string value by default.
-   * Only keys that appear multiple times in the query string become arrays.
-   * @example
-   * // ?foo=1 → { foo: '1' }
-   * // ?tag=a&tag=b → { tag: ['a', 'b'] }
-   * // ?x=1&y=2&x=3 → { x: ['1', '3'], y: '2' }
-   */
-  query: Record<string, string | string[]>;
-  /** The matched route definition */
-  matched: RouteDefinition | null;
-  /** Hash fragment without # */
-  hash: string;
-};
-
-/**
- * Route definition for configuration.
- */
-export type RouteDefinition = {
-  /** Path pattern (e.g., '/user/:id', '/posts/*') */
-  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[];
-};
-
-/**
- * Router configuration options.
- */
-export type RouterOptions = {
-  /** Array of route definitions */
-  routes: RouteDefinition[];
-  /** Base path for all routes (default: '') */
-  base?: string;
-  /** Use hash-based routing instead of history (default: false) */
-  hash?: boolean;
-};
-
-/**
- * Navigation guard function type.
- */
-export type NavigationGuard = (to: Route, from: Route) => boolean | void | Promise<boolean | void>;
-
-/**
- * Router instance returned by createRouter.
- */
-export type Router = {
-  /** Navigate to a path */
-  push: (path: string) => Promise<void>;
-  /** Replace current history entry */
-  replace: (path: string) => Promise<void>;
-  /** Go back in history */
-  back: () => void;
-  /** Go forward in history */
-  forward: () => void;
-  /** Go to a specific history entry */
-  go: (delta: number) => void;
-  /** Add a beforeEach guard */
-  beforeEach: (guard: NavigationGuard) => () => void;
-  /** Add an afterEach hook */
-  afterEach: (hook: (to: Route, from: Route) => void) => () => void;
-  /** Current route (reactive) */
-  currentRoute: ReadonlySignal<Route>;
-  /** All route definitions */
-  routes: RouteDefinition[];
-  /** Base path for all routes */
-  base: string;
-  /** Whether hash-based routing is enabled */
-  hash: boolean;
-  /** Destroy the router and cleanup listeners */
-  destroy: () => void;
-};
+/**
+ * Router types and public contracts.
+ * @module bquery/router
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+/**
+ * Represents a parsed route with matched params.
+ */
+export type Route = {
+  /** The current path (e.g., '/user/42') */
+  path: string;
+  /** Extracted route params (e.g., { id: '42' }) */
+  params: Record<string, string>;
+  /**
+   * Query string params.
+   * Each key maps to a single string value by default.
+   * Only keys that appear multiple times in the query string become arrays.
+   * @example
+   * // ?foo=1 → { foo: '1' }
+   * // ?tag=a&tag=b → { tag: ['a', 'b'] }
+   * // ?x=1&y=2&x=3 → { x: ['1', '3'], y: '2' }
+   */
+  query: Record<string, string | string[]>;
+  /** The matched route definition */
+  matched: RouteDefinition | null;
+  /** Hash fragment without # */
+  hash: string;
+};
+
+/**
+ * Route definition for configuration.
+ */
+type BaseRouteDefinition = {
+  /**
+   * Path pattern (e.g., '/user/:id', '/posts/*').
+   * Supports regex constraints on params: `/user/:id(\\d+)`.
+   * Constraint backreferences are not supported.
+   */
+  path: string;
+  /** 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.
+ */
+export type RouterOptions = {
+  /** Array of route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes (default: '') */
+  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;
+};
+
+/**
+ * Navigation guard function type.
+ */
+export type NavigationGuard = (to: Route, from: Route) => boolean | void | Promise<boolean | void>;
+
+/**
+ * Router instance returned by createRouter.
+ */
+export type Router = {
+  /** Navigate to a path */
+  push: (path: string) => Promise<void>;
+  /** Replace current history entry */
+  replace: (path: string) => Promise<void>;
+  /** Go back in history */
+  back: () => void;
+  /** Go forward in history */
+  forward: () => void;
+  /** Go to a specific history entry */
+  go: (delta: number) => void;
+  /** Add a beforeEach guard */
+  beforeEach: (guard: NavigationGuard) => () => void;
+  /** Add an afterEach hook */
+  afterEach: (hook: (to: Route, from: Route) => void) => () => void;
+  /** Current route (reactive) */
+  currentRoute: ReadonlySignal<Route>;
+  /** All route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes */
+  base: string;
+  /** Whether hash-based routing is enabled */
+  hash: boolean;
+  /** Destroy the router and cleanup listeners */
+  destroy: () => void;
+};

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

@@ -1,116 +1,157 @@
-/**
- * Router utilities.
- * @module bquery/router
- */
-
-import { computed, type ReadonlySignal } from '../reactive/index';
-import { getActiveRouter, routeSignal } from './state';
-import type { RouteDefinition } from './types';
-
-// ============================================================================
-// Utilities
-// ============================================================================
-
-/**
- * Flattens nested routes into a single array with full paths.
- * Does NOT include the router base - base is only for browser history.
- * @internal
- */
-export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): RouteDefinition[] => {
-  const result: RouteDefinition[] = [];
-
-  for (const route of routes) {
-    const fullPath = route.path === '*' ? '*' : `${parentPath}${route.path}`.replace(/\/+/g, '/');
-
-    result.push({
-      ...route,
-      path: fullPath,
-    });
-
-    if (route.children) {
-      result.push(...flattenRoutes(route.children, fullPath));
-    }
-  }
-
-  return result;
-};
-
-/**
- * Resolves a route by name and params.
- *
- * @param name - The route name
- * @param params - Route params to interpolate
- * @returns The resolved path
- *
- * @example
- * ```ts
- * import { resolve } from 'bquery/router';
- *
- * const path = resolve('user', { id: '42' });
- * // Returns '/user/42' if route is defined as { name: 'user', path: '/user/:id' }
- * ```
- */
-export const resolve = (name: string, params: Record<string, string> = {}): string => {
-  const activeRouter = getActiveRouter();
-  if (!activeRouter) {
-    throw new Error('bQuery router: No router initialized.');
-  }
-
-  const route = activeRouter.routes.find((r) => r.name === name);
-  if (!route) {
-    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));
-  }
-
-  return path;
-};
-
-/**
- * Checks if a path matches the current route.
- *
- * @param path - Path to check
- * @param exact - Whether to match exactly (default: false)
- * @returns True if the path matches
- *
- * @example
- * ```ts
- * import { isActive } from 'bquery/router';
- *
- * if (isActive('/dashboard')) {
- *   // Highlight nav item
- * }
- * ```
- */
-export const isActive = (path: string, exact = false): boolean => {
-  const current = routeSignal.value.path;
-  return exact ? current === path : current.startsWith(path);
-};
-
-/**
- * Creates a computed signal that checks if a path is active.
- *
- * @param path - Path to check
- * @param exact - Whether to match exactly
- * @returns A reactive signal
- *
- * @example
- * ```ts
- * import { isActiveSignal } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
- *
- * const dashboardActive = isActiveSignal('/dashboard');
- * effect(() => {
- *   navItem.classList.toggle('active', dashboardActive.value);
- * });
- * ```
- */
-export const isActiveSignal = (path: string, exact = false): ReadonlySignal<boolean> => {
-  return computed(() => {
-    const current = routeSignal.value.path;
-    return exact ? current === path : current.startsWith(path);
-  });
-};
+/**
+ * Router utilities.
+ * @module bquery/router
+ */
+
+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';
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Flattens nested routes into a single array with full paths.
+ * Does NOT include the router base - base is only for browser history.
+ * @internal
+ */
+export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): RouteDefinition[] => {
+  const result: RouteDefinition[] = [];
+
+  for (const route of routes) {
+    const fullPath = route.path === '*' ? '*' : `${parentPath}${route.path}`.replace(/\/+/g, '/');
+
+    result.push({
+      ...route,
+      path: fullPath,
+    });
+
+    if (route.children) {
+      result.push(...flattenRoutes(route.children, fullPath));
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Resolves a route by name and params.
+ *
+ * @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
+ * import { resolve } from 'bquery/router';
+ *
+ * const path = resolve('user', { id: '42' });
+ * // Returns '/user/42' if route is defined as { name: 'user', path: '/user/:id' }
+ * ```
+ */
+export const resolve = (name: string, params: Record<string, string> = {}): string => {
+  const activeRouter = getActiveRouter();
+  if (!activeRouter) {
+    throw new Error('bQuery router: No router initialized.');
+  }
+
+  const route = activeRouter.routes.find((r) => r.name === name);
+  if (!route) {
+    throw new Error(`bQuery router: Route "${name}" not found.`);
+  }
+
+  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;
+};
+
+/**
+ * Checks if a path matches the current route.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly (default: false)
+ * @returns True if the path matches
+ *
+ * @example
+ * ```ts
+ * import { isActive } from 'bquery/router';
+ *
+ * if (isActive('/dashboard')) {
+ *   // Highlight nav item
+ * }
+ * ```
+ */
+export const isActive = (path: string, exact = false): boolean => {
+  const current = routeSignal.value.path;
+  return exact ? current === path : current.startsWith(path);
+};
+
+/**
+ * Creates a computed signal that checks if a path is active.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly
+ * @returns A reactive signal
+ *
+ * @example
+ * ```ts
+ * import { isActiveSignal } from 'bquery/router';
+ * import { effect } from 'bquery/reactive';
+ *
+ * const dashboardActive = isActiveSignal('/dashboard');
+ * effect(() => {
+ *   navItem.classList.toggle('active', dashboardActive.value);
+ * });
+ * ```
+ */
+export const isActiveSignal = (path: string, exact = false): ReadonlySignal<boolean> => {
+  return computed(() => {
+    const current = routeSignal.value.path;
+    return exact ? current === path : current.startsWith(path);
+  });
+};