@bquery/bquery 1.6.0 → 1.7.0

package/src/router/match.ts

@@ -1,106 +1,312 @@
-/**
- * Route matching helpers.
- * @module bquery/router
- */
-
-import { parseQuery } from './query';
-import type { Route, RouteDefinition } from './types';
-
-// ============================================================================
-// Route Matching
-// ============================================================================
-
-/**
- * Converts a route path pattern to a RegExp for matching.
- * Uses placeholder approach to preserve :param and * patterns during escaping.
- * Returns positional capture groups for maximum compatibility.
- * @internal
- */
-const pathToRegex = (path: string): RegExp => {
-  // Handle wildcard-only route
-  if (path === '*') {
-    return /^.*$/;
-  }
-
-  // Unique placeholders using null chars (won't appear in normal paths)
-  const PARAM_MARKER = '\u0000P\u0000';
-  const WILDCARD_MARKER = '\u0000W\u0000';
-
-  // Step 1: Extract :param patterns before escaping
-  let pattern = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, () => {
-    return PARAM_MARKER;
-  });
-
-  // Step 2: Extract * wildcards before escaping
-  pattern = pattern.replace(/\*/g, WILDCARD_MARKER);
-
-  // Step 3: Escape ALL regex metacharacters: \ ^ $ . * + ? ( ) [ ] { } |
-  pattern = pattern.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
-
-  // Step 4: Restore param capture groups (positional, not named)
-  pattern = pattern.replace(/\u0000P\u0000/g, () => `([^/]+)`);
-
-  // Step 5: Restore wildcards as .*
-  pattern = pattern.replace(/\u0000W\u0000/g, '.*');
-
-  return new RegExp(`^${pattern}$`);
-};
-
-/**
- * Extracts param names from a route path.
- * @internal
- */
-const extractParamNames = (path: string): string[] => {
-  const matches = path.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g);
-  return matches ? matches.map((m) => m.slice(1)) : [];
-};
-
-/**
- * Matches a path against route definitions and extracts params.
- * Uses positional captures for maximum compatibility.
- * @internal
- */
-export const matchRoute = (
-  path: string,
-  routes: RouteDefinition[]
-): { matched: RouteDefinition; params: Record<string, string> } | null => {
-  for (const route of routes) {
-    const regex = pathToRegex(route.path);
-    const match = path.match(regex);
-
-    if (match) {
-      const paramNames = extractParamNames(route.path);
-      const params: Record<string, string> = {};
-
-      // Map positional captures to param names
-      paramNames.forEach((name, index) => {
-        params[name] = match[index + 1] || '';
-      });
-
-      return { matched: route, params };
-    }
-  }
-
-  return null;
-};
-
-/**
- * Creates a Route object from the current URL.
- * @internal
- */
-export const createRoute = (
-  pathname: string,
-  search: string,
-  hash: string,
-  routes: RouteDefinition[]
-): Route => {
-  const result = matchRoute(pathname, routes);
-
-  return {
-    path: pathname,
-    params: result?.params ?? {},
-    query: parseQuery(search),
-    matched: result?.matched ?? null,
-    hash: hash.replace(/^#/, ''),
-  };
-};
+/**
+ * Route matching helpers.
+ * @module bquery/router
+ */
+
+import { parseQuery } from './query';
+import { getNormalizedRouteConstraint, getRouteConstraintRegex } from './constraints';
+import { isParamChar, isParamStart, readConstraint } from './path-pattern';
+import type { Route, RouteDefinition } from './types';
+
+const readConstraintOrThrow = (
+  path: string,
+  startIndex: number
+): { constraint: string; endIndex: number } => {
+  const parsedConstraint = readConstraint(path, startIndex);
+  if (!parsedConstraint) {
+    throw new Error(
+      `bQuery router: Invalid route param constraint syntax in path "${path}" at index ${startIndex}.`
+    );
+  }
+  return parsedConstraint;
+};
+
+type RouteParamDescriptor = {
+  name: string;
+  constraint?: string;
+  nextIndex: number;
+};
+
+const validatedRoutePathCache = new Set<string>();
+
+const readParamDescriptor = (path: string, index: number): RouteParamDescriptor | null => {
+  if (path[index] !== ':' || !isParamStart(path[index + 1])) {
+    return null;
+  }
+
+  let nameEnd = index + 2;
+  while (nameEnd < path.length && isParamChar(path[nameEnd])) {
+    nameEnd++;
+  }
+
+  let nextIndex = nameEnd;
+  let constraint: string | undefined;
+
+  if (path[nameEnd] === '(') {
+    const parsedConstraint = readConstraintOrThrow(path, nameEnd);
+    constraint = parsedConstraint.constraint;
+    nextIndex = parsedConstraint.endIndex;
+  }
+
+  return {
+    name: path.slice(index + 1, nameEnd),
+    constraint,
+    nextIndex,
+  };
+};
+
+const validateRoutePathPattern = (path: string): void => {
+  if (validatedRoutePathCache.has(path)) {
+    return;
+  }
+
+  for (let i = 0; i < path.length; ) {
+    const char = path[i];
+
+    if (char === ':' && isParamStart(path[i + 1])) {
+      const param = readParamDescriptor(path, i);
+      if (param?.constraint) {
+        getNormalizedRouteConstraint(param.constraint);
+      }
+      i = param?.nextIndex ?? i + 1;
+      continue;
+    }
+
+    i++;
+  }
+
+  validatedRoutePathCache.add(path);
+};
+
+const findSegmentBoundary = (value: string, startIndex: number): number => {
+  const slashIndex = value.indexOf('/', startIndex);
+  return slashIndex === -1 ? value.length : slashIndex;
+};
+
+const readNextStaticChunk = (path: string, startIndex: number): string => {
+  let chunkEnd = startIndex;
+
+  while (chunkEnd < path.length) {
+    if (path[chunkEnd] === '*') {
+      break;
+    }
+
+    if (path[chunkEnd] === ':' && isParamStart(path[chunkEnd + 1])) {
+      break;
+    }
+
+    chunkEnd++;
+  }
+
+  return path.slice(startIndex, chunkEnd);
+};
+
+const findAnchoredCandidateEnds = (
+  actualPath: string,
+  startIndex: number,
+  limit: number,
+  nextStaticChunk: string
+): number[] => {
+  const candidates: number[] = [];
+  let searchIndex = startIndex;
+
+  while (searchIndex <= limit) {
+    const candidateEnd = actualPath.indexOf(nextStaticChunk, searchIndex);
+    if (candidateEnd === -1 || candidateEnd > limit) {
+      break;
+    }
+
+    candidates.push(candidateEnd);
+    searchIndex = candidateEnd + 1;
+  }
+
+  return candidates.reverse();
+};
+
+const matchPathPattern = (routePath: string, actualPath: string): Record<string, string> | null => {
+  // Memoization keeps wildcard/param backtracking linear for repeated subproblems
+  // within a single route/path match attempt.
+  const memo = new Map<string, Record<string, string> | null>();
+
+  const matchFrom = (routeIndex: number, pathIndex: number): Record<string, string> | null => {
+    const memoKey = `${routeIndex}:${pathIndex}`;
+    if (memo.has(memoKey)) {
+      return memo.get(memoKey) ?? null;
+    }
+
+    if (routeIndex === routePath.length) {
+      const result = pathIndex === actualPath.length ? {} : null;
+      memo.set(memoKey, result);
+      return result;
+    }
+
+    const routeChar = routePath[routeIndex];
+
+    if (routeChar === '*') {
+      if (routeIndex === routePath.length - 1) {
+        const result = {};
+        memo.set(memoKey, result);
+        return result;
+      }
+
+      const nextStaticChunk = readNextStaticChunk(routePath, routeIndex + 1);
+      const anchoredCandidateEnds =
+        nextStaticChunk.length > 0
+          ? findAnchoredCandidateEnds(actualPath, pathIndex, actualPath.length, nextStaticChunk)
+          : null;
+
+      const iterateCandidateEnds = anchoredCandidateEnds
+        ? (callback: (candidateEnd: number) => Record<string, string> | null) => {
+            for (const candidateEnd of anchoredCandidateEnds) {
+              const result = callback(candidateEnd);
+              if (result) {
+                return result;
+              }
+            }
+            return null;
+          }
+        : (callback: (candidateEnd: number) => Record<string, string> | null) => {
+            for (let candidateEnd = actualPath.length; candidateEnd >= pathIndex; candidateEnd--) {
+              const result = callback(candidateEnd);
+              if (result) {
+                return result;
+              }
+            }
+            return null;
+          };
+
+      const wildcardMatch = iterateCandidateEnds((candidateEnd) => {
+        const suffixMatch = matchFrom(routeIndex + 1, candidateEnd);
+        if (suffixMatch) {
+          memo.set(memoKey, suffixMatch);
+          return suffixMatch;
+        }
+        return null;
+      });
+
+      if (wildcardMatch) {
+        return wildcardMatch;
+      }
+
+      memo.set(memoKey, null);
+      return null;
+    }
+
+    const param = readParamDescriptor(routePath, routeIndex);
+    if (param) {
+      const constraintRegex = param.constraint
+        ? getRouteConstraintRegex(param.constraint)
+        : undefined;
+      const candidateLimit = param.constraint
+        ? actualPath.length
+        : findSegmentBoundary(actualPath, pathIndex);
+      const nextStaticChunk = readNextStaticChunk(routePath, param.nextIndex);
+      const anchoredCandidateEnds =
+        nextStaticChunk.length > 0
+          ? findAnchoredCandidateEnds(actualPath, pathIndex, candidateLimit, nextStaticChunk)
+          : null;
+
+      const iterateCandidateEnds = anchoredCandidateEnds
+        ? (callback: (candidateEnd: number) => Record<string, string> | null) => {
+            for (const candidateEnd of anchoredCandidateEnds) {
+              if (candidateEnd <= pathIndex) {
+                continue;
+              }
+              const result = callback(candidateEnd);
+              if (result) {
+                return result;
+              }
+            }
+            return null;
+          }
+        : (callback: (candidateEnd: number) => Record<string, string> | null) => {
+            for (let candidateEnd = candidateLimit; candidateEnd > pathIndex; candidateEnd--) {
+              const result = callback(candidateEnd);
+              if (result) {
+                return result;
+              }
+            }
+            return null;
+          };
+
+      const paramMatch = iterateCandidateEnds((candidateEnd) => {
+        const candidateValue = actualPath.slice(pathIndex, candidateEnd);
+
+        if (constraintRegex) {
+          if (!constraintRegex.test(candidateValue)) {
+            return null;
+          }
+        }
+
+        const suffixMatch = matchFrom(param.nextIndex, candidateEnd);
+        if (suffixMatch) {
+          const result = {
+            [param.name]: candidateValue,
+            ...suffixMatch,
+          };
+          memo.set(memoKey, result);
+          return result;
+        }
+        return null;
+      });
+
+      if (paramMatch) {
+        return paramMatch;
+      }
+
+      memo.set(memoKey, null);
+      return null;
+    }
+
+    if (pathIndex >= actualPath.length || routeChar !== actualPath[pathIndex]) {
+      memo.set(memoKey, null);
+      return null;
+    }
+
+    const result = matchFrom(routeIndex + 1, pathIndex + 1);
+    memo.set(memoKey, result);
+    return result;
+  };
+
+  return matchFrom(0, 0);
+};
+
+/**
+ * Matches a path against route definitions and extracts params.
+ * @internal
+ */
+export const matchRoute = (
+  path: string,
+  routes: RouteDefinition[]
+): { matched: RouteDefinition; params: Record<string, string> } | null => {
+  for (const route of routes) {
+    validateRoutePathPattern(route.path);
+    const params = matchPathPattern(route.path, path);
+    if (params) {
+      return { matched: route, params };
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Creates a Route object from the current URL.
+ * @internal
+ */
+export const createRoute = (
+  pathname: string,
+  search: string,
+  hash: string,
+  routes: RouteDefinition[]
+): Route => {
+  const result = matchRoute(pathname, routes);
+
+  return {
+    path: pathname,
+    params: result?.params ?? {},
+    query: parseQuery(search),
+    matched: result?.matched ?? null,
+    hash: hash.replace(/^#/, ''),
+  };
+};

package/src/router/path-pattern.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared helpers for parsing route path params and constraints.
+ * @internal
+ */
+
+/** Validates whether a character can start a route param name. @internal */
+export const isParamStart = (char: string | undefined): boolean =>
+  char !== undefined &&
+  ((char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || char === '_');
+
+/** Validates whether a character can appear after the start of a route param name. @internal */
+export const isParamChar = (char: string | undefined): boolean =>
+  isParamStart(char) || (char !== undefined && char >= '0' && char <= '9');
+
+/** Reads a route param constraint while preserving escaped chars and nested groups. @internal */
+export const readConstraint = (
+  path: string,
+  startIndex: number
+): { constraint: string; endIndex: number } | null => {
+  let depth = 1;
+  let constraint = '';
+  let i = startIndex + 1;
+  let inCharacterClass = false;
+
+  while (i < path.length) {
+    const char = path[i];
+
+    if (char === '\\' && i + 1 < path.length) {
+      constraint += char + path[i + 1];
+      i += 2;
+      continue;
+    }
+
+    if (char === '[' && !inCharacterClass) {
+      inCharacterClass = true;
+    } else if (char === ']' && inCharacterClass) {
+      inCharacterClass = false;
+    } else if (!inCharacterClass && char === '(') {
+      depth++;
+    } else if (!inCharacterClass && char === ')') {
+      depth--;
+      if (depth === 0) {
+        return { constraint, endIndex: i + 1 };
+      }
+    }
+
+    constraint += char;
+    i++;
+  }
+
+  return null;
+};

package/src/router/query.ts

@@ -1,35 +1,38 @@
-/**
- * Query string helpers.
- * @module bquery/router
- */
-
-/**
- * Parses query string into an object.
- * Single values are stored as strings, duplicate keys become arrays.
- * @internal
- *
- * @example
- * parseQuery('?foo=1') // { foo: '1' }
- * parseQuery('?tag=a&tag=b') // { tag: ['a', 'b'] }
- * parseQuery('?x=1&y=2&x=3') // { x: ['1', '3'], y: '2' }
- */
-export const parseQuery = (search: string): Record<string, string | string[]> => {
-  const query: Record<string, string | string[]> = {};
-  const params = new URLSearchParams(search);
-
-  params.forEach((value, key) => {
-    const existing = query[key];
-    if (existing === undefined) {
-      // First occurrence: store as string
-      query[key] = value;
-    } else if (Array.isArray(existing)) {
-      // Already an array: append
-      existing.push(value);
-    } else {
-      // Second occurrence: convert to array
-      query[key] = [existing, value];
-    }
-  });
-
-  return query;
-};
+/**
+ * Query string helpers.
+ * @module bquery/router
+ */
+
+import { isPrototypePollutionKey } from '../core/utils/object';
+
+/**
+ * Parses query string into an object.
+ * Single values are stored as strings, duplicate keys become arrays.
+ * @internal
+ *
+ * @example
+ * parseQuery('?foo=1') // { foo: '1' }
+ * parseQuery('?tag=a&tag=b') // { tag: ['a', 'b'] }
+ * parseQuery('?x=1&y=2&x=3') // { x: ['1', '3'], y: '2' }
+ */
+export const parseQuery = (search: string): Record<string, string | string[]> => {
+  const query: Record<string, string | string[]> = {};
+  const params = new URLSearchParams(search);
+
+  params.forEach((value, key) => {
+    if (isPrototypePollutionKey(key)) return;
+    const existing = query[key];
+    if (existing === undefined) {
+      // First occurrence: store as string
+      query[key] = value;
+    } else if (Array.isArray(existing)) {
+      // Already an array: append
+      existing.push(value);
+    } else {
+      // Second occurrence: convert to array
+      query[key] = [existing, value];
+    }
+  });
+
+  return query;
+};