@real-router/core 0.38.0 → 0.40.0

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -1,14 +1,10 @@
 // packages/core/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts
 
-import { logger } from "@real-router/logger";
-import { isBoolean, getTypeDescription } from "type-guards";
-
-import { validateHandlerLimit, validateNotRegistering } from "./validators";
 import { DEFAULT_LIMITS } from "../../constants";
-import { computeThresholds } from "../../helpers";
 
 import type { RouteLifecycleDependencies } from "./types";
 import type { GuardFnFactory, Limits } from "../../types";
+import type { RouterValidator } from "../../types/RouterValidator";
 import type { DefaultDependencies, GuardFn, State } from "@real-router/types";
 
 /**
@@ -54,6 +50,7 @@ export class RouteLifecycleNamespace<
 
   #deps!: RouteLifecycleDependencies<Dependencies>;
   #limits: Limits = DEFAULT_LIMITS;
+  #getValidator: (() => RouterValidator | null) | null = null;
 
   setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void {
     this.#deps = deps;
@@ -66,6 +63,18 @@ export class RouteLifecycleNamespace<
    */
   setLimits(limits: Limits): void {
     this.#limits = limits;
+    // eslint-disable-next-line sonarjs/void-use -- @preserve: Wave 3 validator reads limits via RouterInternals; void suppresses TS6133 until then
+    void this.#limits;
+  }
+
+  setValidatorGetter(getter: () => RouterValidator | null): void {
+    this.#getValidator = getter;
+  }
+
+  getHandlerCount(type: "activate" | "deactivate"): number {
+    return type === "activate"
+      ? this.#canActivateFactories.size
+      : this.#canDeactivateFactories.size;
   }
 
   // =========================================================================
@@ -74,17 +83,15 @@ export class RouteLifecycleNamespace<
 
   /**
    * Adds a canActivate guard for a route.
-   * Handles state-dependent validation, overwrite detection, and registration.
+   * Handles overwrite detection and registration.
    *
    * @param name - Route name (input-validated by facade)
    * @param handler - Guard function or boolean (input-validated by facade)
-   * @param skipValidation - True when called during route config building (#noValidate)
    * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
    */
   addCanActivate(
     name: string,
     handler: GuardFnFactory<Dependencies> | boolean,
-    skipValidation: boolean,
     isFromDefinition = false,
   ): void {
     if (isFromDefinition) {
@@ -92,24 +99,9 @@ export class RouteLifecycleNamespace<
     } else {
       this.#definitionActivateGuardNames.delete(name);
     }
-    if (!skipValidation) {
-      validateNotRegistering(
-        this.#registering.has(name),
-        name,
-        "addActivateGuard",
-      );
-    }
 
     const isOverwrite = this.#canActivateFactories.has(name);
 
-    if (!isOverwrite && !skipValidation) {
-      validateHandlerLimit(
-        this.#canActivateFactories.size + 1,
-        "addActivateGuard",
-        this.#limits.maxLifecycleHandlers,
-      );
-    }
-
     this.#registerHandler(
       "activate",
       name,
@@ -123,17 +115,15 @@ export class RouteLifecycleNamespace<
 
   /**
    * Adds a canDeactivate guard for a route.
-   * Handles state-dependent validation, overwrite detection, and registration.
+   * Handles overwrite detection and registration.
    *
    * @param name - Route name (input-validated by facade)
    * @param handler - Guard function or boolean (input-validated by facade)
-   * @param skipValidation - True when called during route config building (#noValidate)
    * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
    */
   addCanDeactivate(
     name: string,
     handler: GuardFnFactory<Dependencies> | boolean,
-    skipValidation: boolean,
     isFromDefinition = false,
   ): void {
     if (isFromDefinition) {
@@ -141,24 +131,9 @@ export class RouteLifecycleNamespace<
     } else {
       this.#definitionDeactivateGuardNames.delete(name);
     }
-    if (!skipValidation) {
-      validateNotRegistering(
-        this.#registering.has(name),
-        name,
-        "addDeactivateGuard",
-      );
-    }
 
     const isOverwrite = this.#canDeactivateFactories.has(name);
 
-    if (!isOverwrite && !skipValidation) {
-      validateHandlerLimit(
-        this.#canDeactivateFactories.size + 1,
-        "addDeactivateGuard",
-        this.#limits.maxLifecycleHandlers,
-      );
-    }
-
     this.#registerHandler(
       "deactivate",
       name,
@@ -321,18 +296,19 @@ export class RouteLifecycleNamespace<
   ): void {
     // Emit warnings
     if (isOverwrite) {
-      logger.warn(
-        `router.${methodName}`,
-        `Overwriting existing ${type} handler for route "${name}"`,
-      );
+      this.#getValidator?.()?.lifecycle.warnOverwrite(name, type, methodName);
     } else {
-      this.#checkCountThresholds(factories.size + 1, methodName);
+      this.#getValidator?.()?.lifecycle.validateCountThresholds(
+        factories.size + 1,
+        methodName,
+      );
     }
 
     // Convert boolean to factory if needed
-    const factory = isBoolean(handler)
-      ? booleanToFactory<Dependencies>(handler)
-      : handler;
+    const factory =
+      typeof handler === "boolean"
+        ? booleanToFactory<Dependencies>(handler)
+        : handler;
 
     // Store factory
     factories.set(name, factory);
@@ -345,7 +321,7 @@ export class RouteLifecycleNamespace<
 
       if (typeof fn !== "function") {
         throw new TypeError(
-          `[router.${methodName}] Factory must return a function, got ${getTypeDescription(fn)}`,
+          `[router.${methodName}] Factory must return a function, got ${typeof fn}`,
         );
       }
 
@@ -391,44 +367,11 @@ export class RouteLifecycleNamespace<
         return result;
       }
 
-      logger.warn(
-        `router.${methodName}`,
-        `Guard for "${name}" returned a Promise. Sync check cannot resolve async guards — returning false.`,
-      );
+      this.#getValidator?.()?.lifecycle.warnAsyncGuardSync(name, methodName);
 
       return false;
     } catch {
       return false;
     }
   }
-
-  /**
-   * Emits warn/error log messages when handler count approaches the configured limit.
-   *
-   * @param currentSize - Current handler count (after adding the new one)
-   * @param methodName - Public API method name for warning messages
-   */
-  #checkCountThresholds(currentSize: number, methodName: string): void {
-    const maxLifecycleHandlers = this.#limits.maxLifecycleHandlers;
-
-    if (maxLifecycleHandlers === 0) {
-      return;
-    }
-
-    const { warn, error } = computeThresholds(maxLifecycleHandlers);
-
-    if (currentSize >= error) {
-      logger.error(
-        `router.${methodName}`,
-        `${currentSize} lifecycle handlers registered! ` +
-          `This is excessive. Hard limit at ${maxLifecycleHandlers}.`,
-      );
-    } else if (currentSize >= warn) {
-      logger.warn(
-        `router.${methodName}`,
-        `${currentSize} lifecycle handlers registered. ` +
-          `Consider consolidating logic.`,
-      );
-    }
-  }
 }

package/src/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts

@@ -19,22 +19,6 @@ Object.freeze(REPLACE_OPTS);
 export class RouterLifecycleNamespace {
   #deps!: RouterLifecycleDependencies;
 
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // =========================================================================
-
-  /**
-   * Validates start() arguments.
-   */
-  static validateStartArgs(args: unknown[]): void {
-    /* v8 ignore next 4 -- @preserve: facade enforces 1 arg via TypeScript signature */
-    if (args.length !== 1 || typeof args[0] !== "string") {
-      throw new Error(
-        "[router.start] Expected exactly 1 string argument (startPath).",
-      );
-    }
-  }
-
   // =========================================================================
   // Dependency injection
   // =========================================================================

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -1,8 +1,6 @@
 // packages/core/src/namespaces/RoutesNamespace/RoutesNamespace.ts
 
-import { isString, validateRouteName } from "type-guards";
-
-import { DEFAULT_ROUTE_NAME, validatedRouteNames } from "./constants";
+import { DEFAULT_ROUTE_NAME } from "./constants";
 import { paramsMatch, paramsMatchExcluding } from "./helpers";
 import {
   createRoutesStore,
@@ -89,10 +87,9 @@ export class RoutesNamespace<
 
   constructor(
     routes: Route<Dependencies>[] = [],
-    noValidate = false,
     matcherOptions?: CreateMatcherOptions,
   ) {
-    this.#store = createRoutesStore(routes, noValidate, matcherOptions);
+    this.#store = createRoutesStore(routes, matcherOptions);
   }
 
   /**
@@ -200,7 +197,7 @@ export class RoutesNamespace<
    */
   buildPath(route: string, params?: Params, options?: Options): string {
     if (route === constants.UNKNOWN_ROUTE) {
-      return isString(params?.path) ? params.path : "";
+      return typeof params?.path === "string" ? params.path : "";
     }
 
     const paramsWithDefault = Object.hasOwn(
@@ -374,12 +371,6 @@ export class RoutesNamespace<
     strictEquality = false,
     ignoreQueryParams = true,
   ): boolean {
-    // Fast path: skip regex validation for already-validated route names
-    if (!validatedRouteNames.has(name)) {
-      validateRouteName(name, "isActiveRoute");
-      validatedRouteNames.add(name);
-    }
-
     // Note: empty string check is handled by Router.ts facade
     const activeState = this.#deps.getState();
 

package/src/namespaces/RoutesNamespace/constants.ts

@@ -4,11 +4,3 @@
  * Default route name for the root node.
  */
 export const DEFAULT_ROUTE_NAME = "";
-
-/**
- * Cache for validated route names to skip regex validation on repeated calls.
- * Key insight: validateRouteName() regex takes ~40ns, but cache lookup is ~1ns.
- * This cache is module-level (shared across all router instances) since route name
- * validity is independent of router instance.
- */
-export const validatedRouteNames = new Set<string>();

package/src/namespaces/RoutesNamespace/forwardChain.ts

@@ -0,0 +1,34 @@
+// packages/core/src/namespaces/RoutesNamespace/forwardChain.ts
+
+export function resolveForwardChain(
+  startRoute: string,
+  forwardMap: Record<string, string>,
+  maxDepth = 100,
+): string {
+  const visited = new Set<string>();
+  const chain: string[] = [startRoute];
+  let current = startRoute;
+
+  while (forwardMap[current]) {
+    const next = forwardMap[current];
+
+    if (visited.has(next)) {
+      const cycleStart = chain.indexOf(next);
+      const cycle = [...chain.slice(cycleStart), next];
+
+      throw new Error(`Circular forwardTo: ${cycle.join(" → ")}`);
+    }
+
+    visited.add(current);
+    chain.push(next);
+    current = next;
+
+    if (chain.length > maxDepth) {
+      throw new Error(
+        `forwardTo chain exceeds maximum depth (${maxDepth}): ${chain.join(" → ")}`,
+      );
+    }
+  }
+
+  return current;
+}

package/src/namespaces/RoutesNamespace/index.ts

@@ -2,7 +2,7 @@
 
 export { RoutesNamespace } from "./RoutesNamespace";
 
-export { DEFAULT_ROUTE_NAME, validatedRouteNames } from "./constants";
+export { DEFAULT_ROUTE_NAME } from "./constants";
 
 export { createEmptyConfig } from "./helpers";
 

package/src/namespaces/RoutesNamespace/routeGuards.ts

@@ -0,0 +1,62 @@
+import { logger } from "@real-router/logger";
+
+/**
+ * Validates removeRoute constraints.
+ * Returns false if removal should be blocked (route is active).
+ * Logs warnings for edge cases.
+ *
+ * @param name - Route name to remove
+ * @param currentStateName - Current active route name (or undefined)
+ * @param isNavigating - Whether navigation is in progress
+ * @returns true if removal can proceed, false if blocked
+ */
+export function validateRemoveRoute(
+  name: string,
+  currentStateName: string | undefined,
+  isNavigating: boolean,
+): boolean {
+  if (currentStateName) {
+    const isExactMatch = currentStateName === name;
+    const isParentOfCurrent = currentStateName.startsWith(`${name}.`);
+
+    if (isExactMatch || isParentOfCurrent) {
+      const suffix = isExactMatch ? "" : ` (current: "${currentStateName}")`;
+
+      logger.warn(
+        "router.removeRoute",
+        `Cannot remove route "${name}" — it is currently active${suffix}. Navigate away first.`,
+      );
+
+      return false;
+    }
+  }
+
+  if (isNavigating) {
+    logger.warn(
+      "router.removeRoute",
+      `Route "${name}" removed while navigation is in progress. This may cause unexpected behavior.`,
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validates clearRoutes operation.
+ * Returns false if operation should be blocked (navigation in progress).
+ *
+ * @param isNavigating - Whether navigation is in progress
+ * @returns true if clearRoutes can proceed, false if blocked
+ */
+export function validateClearRoutes(isNavigating: boolean): boolean {
+  if (isNavigating) {
+    logger.error(
+      "router.clearRoutes",
+      "Cannot clear routes while navigation is in progress. Wait for navigation to complete.",
+    );
+
+    return false;
+  }
+
+  return true;
+}

package/src/namespaces/RoutesNamespace/routesStore.ts

@@ -4,9 +4,8 @@ import { logger } from "@real-router/logger";
 import { createMatcher, createRouteTree, nodeToDefinition } from "route-tree";
 
 import { DEFAULT_ROUTE_NAME } from "./constants";
-import { resolveForwardChain } from "./forwardToValidation";
+import { resolveForwardChain } from "./forwardChain";
 import { createEmptyConfig, sanitizeRoute } from "./helpers";
-import { validateRoutes } from "./validators";
 
 import type { RouteConfig, RoutesDependencies } from "./types";
 import type { GuardFnFactory, Route } from "../../types";
@@ -39,18 +38,9 @@ export interface RoutesStore<
   readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
   readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
   readonly treeOperations: {
-    readonly commitTreeChanges: (
-      store: RoutesStore<Dependencies>,
-      noValidate: boolean,
-    ) => void;
+    readonly commitTreeChanges: (store: RoutesStore<Dependencies>) => void;
     readonly resetStore: (store: RoutesStore<Dependencies>) => void;
     readonly nodeToDefinition: (node: RouteTree) => RouteDefinition;
-    readonly validateRoutes: (
-      routes: Route<Dependencies>[],
-      tree?: RouteTree,
-      forwardMap?: Record<string, string>,
-      parentName?: string,
-    ) => void;
   };
 }
 
@@ -73,7 +63,7 @@ function rebuildTree(
 
 export function commitTreeChanges<
   Dependencies extends DefaultDependencies = DefaultDependencies,
->(store: RoutesStore<Dependencies>, noValidate: boolean): void {
+>(store: RoutesStore<Dependencies>): void {
   const result = rebuildTree(
     store.definitions,
     store.rootPath,
@@ -82,7 +72,7 @@ export function commitTreeChanges<
 
   store.tree = result.tree;
   store.matcher = result.matcher;
-  store.resolvedForwardMap = refreshForwardMap(store.config, noValidate);
+  store.resolvedForwardMap = refreshForwardMap(store.config);
 }
 
 export function rebuildTreeInPlace<
@@ -135,20 +125,7 @@ export function clearRouteData<
 // Forward map
 // =============================================================================
 
-export function refreshForwardMap(
-  config: RouteConfig,
-  noValidate: boolean,
-): Record<string, string> {
-  if (noValidate) {
-    return cacheForwardMap(config);
-  }
-
-  return validateAndCacheForwardMap(config);
-}
-
-function validateAndCacheForwardMap(
-  config: RouteConfig,
-): Record<string, string> {
+export function refreshForwardMap(config: RouteConfig): Record<string, string> {
   const map = Object.create(null) as Record<string, string>;
 
   for (const fromRoute of Object.keys(config.forwardMap)) {
@@ -158,22 +135,6 @@ function validateAndCacheForwardMap(
   return map;
 }
 
-function cacheForwardMap(config: RouteConfig): Record<string, string> {
-  const map = Object.create(null) as Record<string, string>;
-
-  for (const fromRoute of Object.keys(config.forwardMap)) {
-    let current = fromRoute;
-
-    while (config.forwardMap[current]) {
-      current = config.forwardMap[current];
-    }
-
-    map[fromRoute] = current;
-  }
-
-  return map;
-}
-
 // =============================================================================
 // Route handler registration
 // =============================================================================
@@ -209,7 +170,6 @@ function registerForwardTo<Dependencies extends DefaultDependencies>(
     );
   }
 
-  // Async validation ALWAYS runs (even with noValidate=true)
   if (typeof route.forwardTo === "function") {
     const isNativeAsync =
       (route.forwardTo as { constructor: { name: string } }).constructor
@@ -254,7 +214,7 @@ function registerSingleRouteHandlers<Dependencies extends DefaultDependencies>(
     "defaultParams",
   ]);
   const customFields = Object.fromEntries(
-    Object.entries(route).filter(([k]) => !standardKeys.has(k)),
+    Object.entries(route).filter(([key]) => !standardKeys.has(key)),
   );
 
   if (Object.keys(customFields).length > 0) {
@@ -342,7 +302,6 @@ export function createRoutesStore<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
   routes: Route<Dependencies>[],
-  noValidate: boolean,
   matcherOptions?: CreateMatcherOptions,
 ): RoutesStore<Dependencies> {
   const definitions: RouteDefinition[] = [];
@@ -370,9 +329,7 @@ export function createRoutesStore<
     "",
   );
 
-  const resolvedForwardMap: Record<string, string> = noValidate
-    ? cacheForwardMap(config)
-    : validateAndCacheForwardMap(config);
+  const resolvedForwardMap = refreshForwardMap(config);
 
   return {
     definitions,
@@ -391,7 +348,6 @@ export function createRoutesStore<
       commitTreeChanges,
       resetStore,
       nodeToDefinition,
-      validateRoutes,
     },
   };
 }

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -1,7 +1,5 @@
 // packages/core/src/namespaces/StateNamespace/StateNamespace.ts
 
-import { getTypeDescription, validateState } from "type-guards";
-
 import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
 import { EMPTY_PARAMS } from "../../constants";
 import { freezeStateInPlace } from "../../helpers";
@@ -42,37 +40,6 @@ export class StateNamespace {
    */
   readonly #urlParamsCache = new Map<string, string[]>();
 
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // =========================================================================
-
-  /**
-   * Validates areStatesEqual arguments.
-   */
-  static validateAreStatesEqualArgs(
-    state1: unknown,
-    state2: unknown,
-    ignoreQueryParams: unknown,
-  ): void {
-    // null/undefined are valid (represent "no state")
-    if (state1 != null) {
-      validateState(state1, "areStatesEqual");
-    }
-
-    if (state2 != null) {
-      validateState(state2, "areStatesEqual");
-    }
-
-    if (
-      ignoreQueryParams !== undefined &&
-      typeof ignoreQueryParams !== "boolean"
-    ) {
-      throw new TypeError(
-        `[router.areStatesEqual] Invalid ignoreQueryParams: ${getTypeDescription(ignoreQueryParams)}. Expected boolean.`,
-      );
-    }
-  }
-
   // =========================================================================
   // Instance methods (trust input - already validated by facade)
   // =========================================================================

package/src/namespaces/StateNamespace/helpers.ts

@@ -36,7 +36,7 @@ export function areParamValuesEqual(val1: unknown, val2: unknown): boolean {
       return false;
     }
 
-    return val1.every((v, i) => areParamValuesEqual(v, val2[i]));
+    return val1.every((value, i) => areParamValuesEqual(value, val2[i]));
   }
 
   return false;

package/src/namespaces/index.ts

@@ -8,8 +8,6 @@ export {
   deepFreeze,
   defaultOptions,
   OptionsNamespace,
-  VALID_OPTION_VALUES,
-  VALID_QUERY_PARAMS,
 } from "./OptionsNamespace";
 
 export { StateNamespace } from "./StateNamespace";
@@ -25,7 +23,6 @@ export { RouteLifecycleNamespace } from "./RouteLifecycleNamespace";
 export {
   RoutesNamespace,
   DEFAULT_ROUTE_NAME,
-  validatedRouteNames,
   createEmptyConfig,
 } from "./RoutesNamespace";
 

package/src/typeGuards.ts

@@ -1,23 +1,9 @@
 // packages/core/src/typeGuards.ts
 
-/**
- * Re-export common type guards from centralized type-guards package
- */
-import type { LoggerConfig, LogLevelConfig } from "@real-router/logger";
-
-export {
-  isObjKey,
-  isString,
-  isState,
-  isParams,
-  isNavigationOptions,
-  isBoolean,
-  validateRouteName,
-} from "type-guards";
-
 /**
  * RealRouter-specific type guards for logger configuration
  */
+import type { LoggerConfig, LogLevelConfig } from "@real-router/logger";
 
 const VALID_LEVELS_SET = new Set<string>(["all", "warn-error", "error-only"]);