@real-router/core 0.38.0 → 0.40.0

package/src/api/getRoutesApi.ts

@@ -1,30 +1,22 @@
 import { logger } from "@real-router/logger";
-import { validateRouteName } from "type-guards";
 
 import { throwIfDisposed } from "./helpers";
+import { guardRouteStructure } from "../guards";
 import { getInternals } from "../internals";
 import {
   clearConfigEntries,
   removeFromDefinitions,
   sanitizeRoute,
 } from "../namespaces/RoutesNamespace/helpers";
+import {
+  validateClearRoutes,
+  validateRemoveRoute,
+} from "../namespaces/RoutesNamespace/routeGuards";
 import {
   clearRouteData,
   refreshForwardMap,
   registerAllRouteHandlers,
 } from "../namespaces/RoutesNamespace/routesStore";
-import {
-  throwIfInternalRoute,
-  throwIfInternalRouteInArray,
-  validateAddRouteArgs,
-  validateClearRoutes,
-  validateParentOption,
-  validateRemoveRoute,
-  validateRemoveRouteArgs,
-  validateUpdateRoute,
-  validateUpdateRouteBasicArgs,
-  validateUpdateRoutePropertyTypes,
-} from "../namespaces/RoutesNamespace/validators";
 
 import type { RoutesApi } from "./types";
 import type { RouterInternals } from "../internals";
@@ -81,8 +73,8 @@ function clearRouteConfigurations<
   routeCustomFields: Record<string, Record<string, unknown>>,
   lifecycleNamespace: RouteLifecycleNamespace<Dependencies>,
 ): void {
-  const shouldClear = (n: string): boolean =>
-    n === routeName || n.startsWith(`${routeName}.`);
+  const shouldClear = (name: string): boolean =>
+    name === routeName || name.startsWith(`${routeName}.`);
 
   clearConfigEntries(config.decoders, shouldClear);
   clearConfigEntries(config.encoders, shouldClear);
@@ -100,15 +92,15 @@ function clearRouteConfigurations<
   const [canDeactivateFactories, canActivateFactories] =
     lifecycleNamespace.getFactories();
 
-  for (const n of Object.keys(canActivateFactories)) {
-    if (shouldClear(n)) {
-      lifecycleNamespace.clearCanActivate(n);
+  for (const name of Object.keys(canActivateFactories)) {
+    if (shouldClear(name)) {
+      lifecycleNamespace.clearCanActivate(name);
     }
   }
 
-  for (const n of Object.keys(canDeactivateFactories)) {
-    if (shouldClear(n)) {
-      lifecycleNamespace.clearCanDeactivate(n);
+  for (const name of Object.keys(canDeactivateFactories)) {
+    if (shouldClear(name)) {
+      lifecycleNamespace.clearCanDeactivate(name);
     }
   }
 }
@@ -123,11 +115,7 @@ function updateForwardTo<
   name: string,
   forwardTo: string | ForwardToCallback<Dependencies> | null,
   config: RouteConfig,
-  noValidate: boolean,
-  refreshForwardMapFn: (
-    config: RouteConfig,
-    noValidate: boolean,
-  ) => Record<string, string>,
+  refreshForwardMapFn: (config: RouteConfig) => Record<string, string>,
 ): Record<string, string> {
   if (forwardTo === null) {
     delete config.forwardMap[name];
@@ -140,7 +128,7 @@ function updateForwardTo<
     config.forwardFnMap[name] = forwardTo;
   }
 
-  return refreshForwardMapFn(config, noValidate);
+  return refreshForwardMapFn(config);
 }
 
 /**
@@ -220,7 +208,6 @@ function addRoutes<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
   store: RoutesStore<Dependencies>,
-  noValidate: boolean,
   routes: Route<Dependencies>[],
   parentName?: string,
 ): void {
@@ -249,7 +236,7 @@ function addRoutes<
     parentName ?? "",
   );
 
-  store.treeOperations.commitTreeChanges(store, noValidate);
+  store.treeOperations.commitTreeChanges(store);
 }
 
 /**
@@ -260,7 +247,6 @@ function replaceRoutes<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
   store: RoutesStore<Dependencies>,
-  noValidate: boolean,
   routes: Route<Dependencies>[],
   ctx: RouterInternals<Dependencies>,
   currentPath: string | undefined,
@@ -288,7 +274,7 @@ function replaceRoutes<
   );
 
   // Step 5: One tree rebuild
-  store.treeOperations.commitTreeChanges(store, noValidate);
+  store.treeOperations.commitTreeChanges(store);
 
   // Step 6: Revalidate state
   if (currentPath !== undefined) {
@@ -309,11 +295,7 @@ function replaceRoutes<
  */
 function removeRoute<
   Dependencies extends DefaultDependencies = DefaultDependencies,
->(
-  store: RoutesStore<Dependencies>,
-  noValidate: boolean,
-  name: string,
-): boolean {
+>(store: RoutesStore<Dependencies>, name: string): boolean {
   const wasRemoved = removeFromDefinitions(store.definitions, name);
 
   if (!wasRemoved) {
@@ -328,7 +310,7 @@ function removeRoute<
     store.lifecycleNamespace!,
   );
 
-  store.treeOperations.commitTreeChanges(store, noValidate);
+  store.treeOperations.commitTreeChanges(store);
 
   return true;
 }
@@ -340,7 +322,6 @@ function updateRouteConfig<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
   store: RoutesStore<Dependencies>,
-  noValidate: boolean,
   name: string,
   updates: {
     forwardTo?: string | ForwardToCallback<Dependencies> | null | undefined;
@@ -354,8 +335,7 @@ function updateRouteConfig<
       name,
       updates.forwardTo,
       store.config,
-      noValidate,
-      refreshForwardMap,
+      (config) => refreshForwardMap(config),
     );
   }
 
@@ -424,7 +404,6 @@ export function getRoutesApi<
   const ctx = getInternals(router);
 
   const store = ctx.routeGetStore();
-  const noValidate = ctx.noValidate;
 
   return {
     add: (routes, options) => {
@@ -433,32 +412,24 @@ export function getRoutesApi<
       const routeArray = Array.isArray(routes) ? routes : [routes];
       const parentName = options?.parent;
 
-      if (!ctx.noValidate) {
-        if (parentName !== undefined) {
-          validateParentOption(parentName);
-        }
-
-        throwIfInternalRouteInArray(routeArray, "addRoute");
-        validateAddRouteArgs(routeArray);
+      guardRouteStructure(routeArray, ctx.validator);
 
-        store.treeOperations.validateRoutes(
-          routeArray,
-          store.tree,
-          store.config.forwardMap,
-          parentName,
-        );
+      if (parentName !== undefined) {
+        ctx.validator?.routes.validateParentOption(parentName, store.tree);
       }
 
-      addRoutes(store, noValidate, routeArray, parentName);
+      ctx.validator?.routes.throwIfInternalRouteInArray(routeArray, "addRoute");
+      ctx.validator?.routes.validateAddRouteArgs(routeArray);
+      ctx.validator?.routes.validateRoutes(routeArray, store);
+
+      addRoutes(store, routeArray, parentName);
     },
 
     remove: (name) => {
       throwIfDisposed(ctx.isDisposed);
 
-      if (!ctx.noValidate) {
-        validateRemoveRouteArgs(name);
-        throwIfInternalRoute(name, "removeRoute");
-      }
+      ctx.validator?.routes.validateRemoveRouteArgs(name);
+      ctx.validator?.routes.throwIfInternalRoute(name, "removeRoute");
 
       const canRemove = validateRemoveRoute(
         name,
@@ -470,7 +441,7 @@ export function getRoutesApi<
         return;
       }
 
-      const wasRemoved = removeRoute(store, noValidate, name);
+      const wasRemoved = removeRoute(store, name);
 
       if (!wasRemoved) {
         logger.warn(
@@ -483,10 +454,8 @@ export function getRoutesApi<
     update: (name, updates) => {
       throwIfDisposed(ctx.isDisposed);
 
-      if (!ctx.noValidate) {
-        validateUpdateRouteBasicArgs(name, updates);
-        throwIfInternalRoute(name, "updateRoute");
-      }
+      ctx.validator?.routes.validateUpdateRouteBasicArgs(name, updates);
+      ctx.validator?.routes.throwIfInternalRoute(name, "updateRoute");
 
       const {
         forwardTo,
@@ -497,14 +466,7 @@ export function getRoutesApi<
         canDeactivate,
       } = updates;
 
-      if (!ctx.noValidate) {
-        validateUpdateRoutePropertyTypes(
-          forwardTo,
-          defaultParams,
-          decodeParams,
-          encodeParams,
-        );
-      }
+      ctx.validator?.routes.validateUpdateRoutePropertyTypes(name, updates);
 
       /* v8 ignore next 6 -- @preserve: race condition guard, mirrors Router.updateRoute() same-path guard tested via Router.ts unit tests */
       if (ctx.isTransitioning()) {
@@ -514,17 +476,9 @@ export function getRoutesApi<
         );
       }
 
-      if (!ctx.noValidate) {
-        validateUpdateRoute(
-          name,
-          forwardTo,
-          (n) => store.matcher.hasRoute(n),
-          store.matcher,
-          store.config,
-        );
-      }
+      ctx.validator?.routes.validateUpdateRoute(name, updates, store);
 
-      updateRouteConfig(store, noValidate, name, {
+      updateRouteConfig(store, name, {
         forwardTo,
         defaultParams,
         decodeParams,
@@ -537,12 +491,7 @@ export function getRoutesApi<
           store.lifecycleNamespace!.clearCanActivate(name);
         } else {
           // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
-          store.lifecycleNamespace!.addCanActivate(
-            name,
-            canActivate,
-            noValidate,
-            true,
-          );
+          store.lifecycleNamespace!.addCanActivate(name, canActivate, true);
         }
       }
 
@@ -552,12 +501,7 @@ export function getRoutesApi<
           store.lifecycleNamespace!.clearCanDeactivate(name);
         } else {
           // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
-          store.lifecycleNamespace!.addCanDeactivate(
-            name,
-            canDeactivate,
-            noValidate,
-            true,
-          );
+          store.lifecycleNamespace!.addCanDeactivate(name, canDeactivate, true);
         }
       }
     },
@@ -579,17 +523,13 @@ export function getRoutesApi<
     },
 
     has: (name) => {
-      if (!ctx.noValidate) {
-        validateRouteName(name, "hasRoute");
-      }
+      ctx.validator?.routes.validateRouteName(name, "hasRoute");
 
       return store.matcher.hasRoute(name);
     },
 
     get: (name) => {
-      if (!ctx.noValidate) {
-        validateRouteName(name, "getRoute");
-      }
+      ctx.validator?.routes.validateRouteName(name, "getRoute");
 
       return getRoute(store, name);
     },
@@ -605,15 +545,18 @@ export function getRoutesApi<
         return;
       }
 
-      if (!ctx.noValidate) {
-        throwIfInternalRouteInArray(routeArray, "replaceRoutes");
-        validateAddRouteArgs(routeArray);
-        store.treeOperations.validateRoutes(routeArray);
-      }
+      guardRouteStructure(routeArray, ctx.validator);
+
+      ctx.validator?.routes.throwIfInternalRouteInArray(
+        routeArray,
+        "replaceRoutes",
+      );
+      ctx.validator?.routes.validateAddRouteArgs(routeArray);
+      ctx.validator?.routes.validateRoutes(routeArray, store);
 
       const currentPath = router.getState()?.path;
 
-      replaceRoutes(store, noValidate, routeArray, ctx, currentPath);
+      replaceRoutes(store, routeArray, ctx, currentPath);
     },
   };
 }

package/src/constants.ts

@@ -1,7 +1,6 @@
 // packages/core/src/constants.ts
 
 import type {
-  EventName,
   EventToNameMap,
   EventToPluginMap,
   ErrorCodeToValueMap,
@@ -74,22 +73,6 @@ export const events: EventToNameMap = {
   TRANSITION_ERROR: "$$error", // Emitted when navigation fails
 };
 
-/**
- * Valid event names for validation.
- */
-export const validEventNames = new Set<EventName>([
-  events.ROUTER_START,
-  events.TRANSITION_START,
-  events.TRANSITION_SUCCESS,
-  events.TRANSITION_ERROR,
-  events.TRANSITION_CANCEL,
-  events.ROUTER_STOP,
-]);
-
-/**
- * Default limits configuration for the router.
- * These values match the hardcoded constants from the current codebase.
- */
 export const DEFAULT_LIMITS = {
   maxDependencies: 100,
   maxPlugins: 50,
@@ -100,16 +83,3 @@ export const DEFAULT_LIMITS = {
 } as const;
 
 export const EMPTY_PARAMS: Readonly<Record<string, never>> = Object.freeze({});
-
-/**
- * Bounds for each limit - defines min and max allowed values.
- * Used for runtime validation in setLimit/withLimits.
- */
-export const LIMIT_BOUNDS = {
-  maxDependencies: { min: 0, max: 10_000 },
-  maxPlugins: { min: 0, max: 1000 },
-  maxListeners: { min: 0, max: 100_000 },
-  warnListeners: { min: 0, max: 100_000 },
-  maxEventDepth: { min: 0, max: 100 },
-  maxLifecycleHandlers: { min: 0, max: 10_000 },
-} as const;

package/src/guards.ts

@@ -0,0 +1,46 @@
+// packages/core/src/guards.ts
+
+import type { Route } from "./types";
+import type { RouterValidator } from "./types/RouterValidator";
+
+export function guardDependencies(deps: unknown): void {
+  if (
+    !deps ||
+    typeof deps !== "object" ||
+    (deps as { constructor: unknown }).constructor !== Object
+  ) {
+    throw new TypeError("dependencies must be a plain object");
+  }
+  for (const key in deps as Record<string, unknown>) {
+    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
+      throw new TypeError(`dependencies cannot contain getters: "${key}"`);
+    }
+  }
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- accepts any Route type */
+export function guardRouteStructure(
+  routes: Route<any>[],
+  validator?: RouterValidator | null,
+): void {
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+  for (const route of routes) {
+    const routeValue: unknown = route;
+
+    if (
+      routeValue === null ||
+      typeof routeValue !== "object" ||
+      Array.isArray(routeValue)
+    ) {
+      throw new TypeError("route must be a non-array object");
+    }
+
+    validator?.routes.guardRouteCallbacks(route as Route);
+    validator?.routes.guardNoAsyncCallbacks(route as Route);
+    const children = (route as Route).children;
+
+    if (children) {
+      guardRouteStructure(children, validator);
+    }
+  }
+}

package/src/helpers.ts

@@ -5,8 +5,6 @@ import { DEFAULT_LIMITS } from "./constants";
 import type { Limits } from "./types";
 import type { State, LimitsConfig } from "@real-router/types";
 
-export { getTypeDescription } from "type-guards";
-
 // =============================================================================
 // State Helpers
 // =============================================================================
@@ -170,21 +168,6 @@ export function freezeStateInPlace<T extends State>(state: T): T {
   return state;
 }
 
-/**
- * Computes warning and error thresholds for a given limit.
- * WARN threshold: 20% of limit
- * ERROR threshold: 50% of limit
- */
-export function computeThresholds(limit: number): {
-  warn: number;
-  error: number;
-} {
-  return {
-    warn: Math.floor(limit * 0.2),
-    error: Math.floor(limit * 0.5),
-  };
-}
-
 /**
  * Merges user limits with defaults.
  * Returns frozen object for immutability.

package/src/index.ts

@@ -10,6 +10,8 @@ export type {
   RouteConfigUpdate,
 } from "./types";
 
+export type { RouterValidator } from "./types/RouterValidator";
+
 // Router class (replaces Router interface from core-types)
 export { Router } from "./Router";
 
@@ -44,4 +46,6 @@ export { createRouter } from "./createRouter";
 
 export { getNavigator } from "./getNavigator";
 
+export { resolveForwardChain } from "./namespaces/RoutesNamespace/forwardChain";
+
 export type { RouteTree } from "route-tree";

package/src/internals.ts

@@ -2,6 +2,7 @@ import type { DependenciesStore } from "./namespaces/DependenciesNamespace";
 import type { RoutesStore } from "./namespaces/RoutesNamespace";
 import type { Router as RouterClass } from "./Router";
 import type { EventMethodMap, GuardFnFactory, PluginFactory } from "./types";
+import type { RouterValidator } from "./types/RouterValidator";
 import type {
   DefaultDependencies,
   EventName,
@@ -67,7 +68,7 @@ export interface RouterInternals<
 
   readonly isDisposed: () => boolean;
 
-  readonly noValidate: boolean;
+  validator: RouterValidator | null;
 
   // Dependencies (issue #172)
   readonly dependenciesGetStore: () => DependenciesStore<D>;
@@ -127,7 +128,7 @@ function executeInterceptorChain<T>(
   for (const interceptor of interceptors) {
     const prev = chain;
 
-    chain = (...a: any[]) => interceptor(prev, ...a);
+    chain = (...chainArgs: any[]) => interceptor(prev, ...chainArgs);
   }
 
   return chain(...args) as T;
@@ -160,14 +161,14 @@ export function createInterceptable2<A, B, R>(
     ((next: (...args: any[]) => any, ...args: any[]) => any)[]
   >,
 ): (a: A, b: B) => R {
-  return (a: A, b: B) => {
+  return (arg1: A, arg2: B) => {
     const chain = interceptors.get(name);
 
     if (!chain || chain.length === 0) {
-      return original(a, b);
+      return original(arg1, arg2);
     }
 
-    return executeInterceptorChain(chain, original, [a, b]);
+    return executeInterceptorChain(chain, original, [arg1, arg2]);
   };
 }
 /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument */

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -158,9 +158,9 @@ export class EventBusNamespace {
   }
 
   isActive(): boolean {
-    const s = this.#fsm.getState();
+    const fsmState = this.#fsm.getState();
 
-    return s !== routerStates.IDLE && s !== routerStates.DISPOSED;
+    return fsmState !== routerStates.IDLE && fsmState !== routerStates.DISPOSED;
   }
 
   isDisposed(): boolean {

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -10,11 +10,6 @@ import {
 import { completeTransition } from "./transition/completeTransition";
 import { routeTransitionError } from "./transition/errorHandling";
 import { executeGuardPipeline } from "./transition/guardPhase";
-import {
-  validateNavigateArgs,
-  validateNavigateToDefaultArgs,
-  validateNavigationOptions,
-} from "./validators";
 import { errorCodes, constants } from "../../constants";
 import { RouterError } from "../../RouterError";
 import { getTransitionPath, nameToIDs } from "../../transitionPath";
@@ -73,26 +68,6 @@ export class NavigationNamespace {
   #currentController: AbortController | null = null;
   #navigationId = 0;
 
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // Proxy to functions in validators.ts for separation of concerns
-  // =========================================================================
-
-  static validateNavigateArgs(name: unknown): asserts name is string {
-    validateNavigateArgs(name);
-  }
-
-  static validateNavigateToDefaultArgs(opts: unknown): void {
-    validateNavigateToDefaultArgs(opts);
-  }
-
-  static validateNavigationOptions(
-    opts: unknown,
-    methodName: string,
-  ): asserts opts is NavigationOptions {
-    validateNavigationOptions(opts, methodName);
-  }
-
   // =========================================================================
   // Dependency injection
   // =========================================================================

package/src/namespaces/OptionsNamespace/OptionsNamespace.ts

@@ -2,48 +2,26 @@
 
 import { defaultOptions } from "./constants";
 import { deepFreeze } from "./helpers";
-import { validateOptions } from "./validators";
+import { validateOptionsIsObject } from "./validators";
 
 import type { Options } from "@real-router/types";
 
-/**
- * Independent namespace for managing router options.
- *
- * Options are immutable after construction.
- * Static methods handle validation (called by facade).
- * Instance methods provide read-only access.
- */
 export class OptionsNamespace {
   readonly #options: Readonly<Options>;
 
   constructor(initialOptions: Partial<Options> = {}) {
-    // Note: validation should be done by facade before calling constructor
     this.#options = deepFreeze({
       ...defaultOptions,
       ...initialOptions,
     });
   }
 
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // Proxy to functions in validators.ts for separation of concerns
-  // =========================================================================
-
-  static validateOptions(
+  static validateOptionsIsObject(
     options: unknown,
-    methodName: string,
-  ): asserts options is Partial<Options> {
-    validateOptions(options, methodName);
+  ): asserts options is Record<string, unknown> {
+    validateOptionsIsObject(options);
   }
 
-  // =========================================================================
-  // Instance methods (read-only access)
-  // =========================================================================
-
-  /**
-   * Returns the frozen options object.
-   * Safe to return directly - mutations will throw in strict mode.
-   */
   get(): Readonly<Options> {
     return this.#options;
   }

package/src/namespaces/OptionsNamespace/constants.ts

@@ -18,24 +18,4 @@ export const defaultOptions: Options = {
   urlParamsEncoding: "default",
   allowNotFound: true,
   rewritePathOnMatch: true,
-  noValidate: false,
 } satisfies Options;
-
-/**
- * Valid values for string enum options.
- * Used for runtime validation in constructor options.
- */
-export const VALID_OPTION_VALUES = {
-  trailingSlash: ["strict", "never", "always", "preserve"] as const,
-  queryParamsMode: ["default", "strict", "loose"] as const,
-  urlParamsEncoding: ["default", "uri", "uriComponent", "none"] as const,
-} as const;
-
-/**
- * Valid keys and values for queryParams option.
- */
-export const VALID_QUERY_PARAMS = {
-  arrayFormat: ["none", "brackets", "index", "comma"] as const,
-  booleanFormat: ["none", "string", "empty-true"] as const,
-  nullFormat: ["default", "hidden"] as const,
-} as const;

package/src/namespaces/OptionsNamespace/index.ts

@@ -2,10 +2,6 @@
 
 export { OptionsNamespace } from "./OptionsNamespace";
 
-export {
-  defaultOptions,
-  VALID_OPTION_VALUES,
-  VALID_QUERY_PARAMS,
-} from "./constants";
+export { defaultOptions } from "./constants";
 
 export { deepFreeze, resolveOption } from "./helpers";