@real-router/core 0.38.0 → 0.40.0

package/dist/esm/validation.d.mts

@@ -0,0 +1,184 @@
+import { L as Limits, R as RouterValidator } from './RouterValidator-mx2Zooya.mjs';
+import { DefaultDependencies, Params, ForwardToCallback, GuardFnFactory, State, SimpleState, GuardFn, RouteTreeState, Options, EventName, Plugin, EventMethodMap, Unsubscribe, PluginFactory, Router } from '@real-router/types';
+import { a as RouteDefinition, R as RouteTree, M as Matcher, C as CreateMatcherOptions } from './index.d-y2b-8_3Y.mjs';
+
+interface DependenciesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    dependencies: Partial<Dependencies>;
+    limits: Limits;
+}
+
+/**
+ * Dependencies injected into RoutesNamespace.
+ *
+ * These are function references from the Router facade,
+ * avoiding the need to pass the entire Router object.
+ */
+interface RoutesDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    /** Register canActivate handler for a route */
+    addActivateGuard: (name: string, handler: GuardFnFactory<Dependencies>) => void;
+    /** Register canDeactivate handler for a route */
+    addDeactivateGuard: (name: string, handler: GuardFnFactory<Dependencies>) => void;
+    /** Create state object */
+    makeState: <P extends Params = Params, MP extends Params = Params>(name: string, params?: P, path?: string, meta?: Record<string, Record<string, "url" | "query">>) => State<P, MP>;
+    /** Get current router state */
+    getState: () => State | undefined;
+    /** Compare two states for equality */
+    areStatesEqual: (state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean) => boolean;
+    /** Get a dependency by name */
+    getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K];
+    /** Forward state through facade (allows plugin interception) */
+    forwardState: <P extends Params = Params>(name: string, params: P) => SimpleState<P>;
+}
+/**
+ * Configuration storage for routes.
+ * Stores decoders, encoders, default params, and forward mappings.
+ */
+interface RouteConfig {
+    /** Custom param decoders per route */
+    decoders: Record<string, (params: Params) => Params>;
+    /** Custom param encoders per route */
+    encoders: Record<string, (params: Params) => Params>;
+    /** Default params per route */
+    defaultParams: Record<string, Params>;
+    /** Forward mappings (source -> target) */
+    forwardMap: Record<string, string>;
+    /** Dynamic forward callbacks (source -> callback) */
+    forwardFnMap: Record<string, ForwardToCallback<any>>;
+}
+
+interface RouteLifecycleDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    compileFactory: (factory: GuardFnFactory<Dependencies>) => GuardFn;
+}
+
+/**
+ * Independent namespace for managing route lifecycle handlers.
+ *
+ * Static methods handle input validation (called by facade).
+ * Instance methods handle state-dependent validation, storage and business logic.
+ */
+declare class RouteLifecycleNamespace<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    #private;
+    setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void;
+    /**
+     * Updates handler registration limits (max lifecycle handlers threshold).
+     *
+     * @param limits - Limits configuration with maxLifecycleHandlers
+     */
+    setLimits(limits: Limits): void;
+    setValidatorGetter(getter: () => RouterValidator | null): void;
+    getHandlerCount(type: "activate" | "deactivate"): number;
+    /**
+     * Adds a canActivate guard for a route.
+     * Handles overwrite detection and registration.
+     *
+     * @param name - Route name (input-validated by facade)
+     * @param handler - Guard function or boolean (input-validated by facade)
+     * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
+     */
+    addCanActivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean): void;
+    /**
+     * Adds a canDeactivate guard for a route.
+     * Handles overwrite detection and registration.
+     *
+     * @param name - Route name (input-validated by facade)
+     * @param handler - Guard function or boolean (input-validated by facade)
+     * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
+     */
+    addCanDeactivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean): void;
+    /**
+     * Removes a canActivate guard for a route.
+     * Input already validated by facade (not registering).
+     *
+     * @param name - Route name (already validated by facade)
+     */
+    clearCanActivate(name: string): void;
+    /**
+     * Removes a canDeactivate guard for a route.
+     * Input already validated by facade (not registering).
+     *
+     * @param name - Route name (already validated by facade)
+     */
+    clearCanDeactivate(name: string): void;
+    /**
+     * Clears all lifecycle handlers (canActivate and canDeactivate).
+     * Used by clearRoutes to reset all lifecycle state.
+     */
+    clearAll(): void;
+    /**
+     * Clears only lifecycle handlers that were registered from route definitions.
+     * Used by HMR to remove definition-sourced guards without touching externally-added guards.
+     */
+    clearDefinitionGuards(): void;
+    /**
+     * Returns lifecycle factories as records for cloning.
+     *
+     * @returns Tuple of [canDeactivateFactories, canActivateFactories]
+     */
+    getFactories(): [
+        Record<string, GuardFnFactory<Dependencies>>,
+        Record<string, GuardFnFactory<Dependencies>>
+    ];
+    /**
+     * Returns compiled lifecycle functions for transition execution.
+     *
+     * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
+     */
+    getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>];
+    canNavigateTo(toDeactivate: string[], toActivate: string[], toState: State, fromState: State | undefined): boolean;
+}
+
+interface RoutesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
+    readonly definitions: RouteDefinition[];
+    readonly config: RouteConfig;
+    tree: RouteTree;
+    matcher: Matcher;
+    resolvedForwardMap: Record<string, string>;
+    routeCustomFields: Record<string, Record<string, unknown>>;
+    rootPath: string;
+    readonly matcherOptions: CreateMatcherOptions | undefined;
+    depsStore: RoutesDependencies<Dependencies> | undefined;
+    lifecycleNamespace: RouteLifecycleNamespace<Dependencies> | undefined;
+    readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
+    readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
+    readonly treeOperations: {
+        readonly commitTreeChanges: (store: RoutesStore<Dependencies>) => void;
+        readonly resetStore: (store: RoutesStore<Dependencies>) => void;
+        readonly nodeToDefinition: (node: RouteTree) => RouteDefinition;
+    };
+}
+
+interface RouterInternals<D extends DefaultDependencies = DefaultDependencies> {
+    readonly makeState: <P extends Params = Params, MP extends Params = Params>(name: string, params?: P, path?: string, meta?: Record<string, Record<string, "url" | "query">>, forceId?: number) => State<P, MP>;
+    readonly forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+    readonly buildStateResolved: (resolvedName: string, resolvedParams: Params) => RouteTreeState | undefined;
+    readonly matchPath: <P extends Params = Params, MP extends Params = Params>(path: string, options?: Options) => State<P, MP> | undefined;
+    readonly getOptions: () => Options;
+    readonly addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
+    readonly buildPath: (route: string, params?: Params) => string;
+    readonly start: (path: string) => Promise<State>;
+    readonly interceptors: Map<string, ((next: (...args: any[]) => any, ...args: any[]) => any)[]>;
+    readonly setRootPath: (rootPath: string) => void;
+    readonly getRootPath: () => string;
+    readonly getTree: () => RouteTree;
+    readonly isDisposed: () => boolean;
+    validator: RouterValidator | null;
+    readonly dependenciesGetStore: () => DependenciesStore<D>;
+    readonly cloneOptions: () => Options;
+    readonly cloneDependencies: () => Record<string, unknown>;
+    readonly getLifecycleFactories: () => [
+        Record<string, GuardFnFactory<D>>,
+        Record<string, GuardFnFactory<D>>
+    ];
+    readonly getPluginFactories: () => PluginFactory<D>[];
+    readonly routeGetStore: () => RoutesStore<D>;
+    readonly getStateName: () => string | undefined;
+    readonly isTransitioning: () => boolean;
+    readonly clearState: () => void;
+    readonly setState: (state: State) => void;
+    readonly routerExtensions: {
+        keys: string[];
+    }[];
+}
+declare function getInternals<D extends DefaultDependencies>(router: Router<D>): RouterInternals<D>;
+
+export { type RouterInternals, RouterValidator, getInternals };

package/dist/esm/validation.mjs

@@ -0,0 +1 @@
+export{getInternals}from"./chunk-QUUNDESP.mjs";//# sourceMappingURL=validation.mjs.map

package/dist/esm/validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"validation.mjs"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/core",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "type": "commonjs",
   "description": "A simple, powerful, view-agnostic, modular and extensible router",
   "main": "./dist/cjs/index.js",
@@ -13,6 +13,9 @@
       ],
       "utils": [
         "./dist/cjs/utils.d.ts"
+      ],
+      "validation": [
+        "./dist/cjs/validation.d.ts"
       ]
     }
   },
@@ -43,6 +46,15 @@
       },
       "import": "./dist/esm/utils.mjs",
       "require": "./dist/cjs/utils.js"
+    },
+    "./validation": {
+      "development": "./src/validation.ts",
+      "types": {
+        "import": "./dist/esm/validation.d.mts",
+        "require": "./dist/cjs/validation.d.ts"
+      },
+      "import": "./dist/esm/validation.mjs",
+      "require": "./dist/cjs/validation.js"
     }
   },
   "files": [
@@ -73,16 +85,17 @@
     "url": "https://github.com/greydragon888/real-router/issues"
   },
   "homepage": "https://github.com/greydragon888/real-router",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/esm/chunk-*.mjs"
+  ],
   "dependencies": {
     "@real-router/fsm": "^0.2.2",
     "@real-router/logger": "^0.2.1",
-    "@real-router/types": "^0.24.0"
+    "@real-router/types": "^0.26.0"
   },
   "devDependencies": {
     "event-emitter": "^0.1.2",
-    "route-tree": "^0.3.4",
-    "type-guards": "^0.3.7"
+    "route-tree": "^0.3.4"
   },
   "scripts": {
     "build": "tsup",

package/src/Router.ts

@@ -8,10 +8,10 @@
 
 import { logger } from "@real-router/logger";
 import { EventEmitter } from "event-emitter";
-import { validateRouteName } from "type-guards";
 
 import { EMPTY_PARAMS, errorCodes } from "./constants";
 import { createRouterFSM } from "./fsm";
+import { guardDependencies, guardRouteStructure } from "./guards";
 import { createLimits } from "./helpers";
 import {
   createInterceptable,
@@ -30,15 +30,7 @@ import {
   StateNamespace,
   createDependenciesStore,
 } from "./namespaces";
-import { validateDependenciesObject } from "./namespaces/DependenciesNamespace/validators";
 import { CACHED_ALREADY_STARTED_ERROR } from "./namespaces/RouterLifecycleNamespace/constants";
-import {
-  validateAddRouteArgs,
-  validateBuildPathArgs,
-  validateIsActiveRouteArgs,
-  validateRoutes,
-  validateShouldUpdateNodeArgs,
-} from "./namespaces/RoutesNamespace/validators";
 import { RouterError } from "./RouterError";
 import { getTransitionPath } from "./transitionPath";
 import { isLoggerConfig } from "./typeGuards";
@@ -98,12 +90,6 @@ export class Router<
 
   readonly #eventBus: EventBusNamespace;
 
-  /**
-   * When true, skips argument validation in public methods for production performance.
-   * Constructor options are always validated (needed to validate noValidate itself).
-   */
-  readonly #noValidate: boolean;
-
   // ============================================================================
   // Constructor
   // ============================================================================
@@ -128,22 +114,14 @@ export class Router<
     // Validate inputs before creating namespaces
     // =========================================================================
 
-    // Always validate options (needed to validate noValidate itself)
-    OptionsNamespace.validateOptions(options, "constructor");
+    // Always validate options
+    OptionsNamespace.validateOptionsIsObject(options);
 
-    // Extract noValidate BEFORE creating namespaces
-    const noValidate = options.noValidate ?? false;
+    // Unconditional guard-level validation before creating namespaces
+    guardDependencies(dependencies);
 
-    // Conditional validation for dependencies
-    if (!noValidate) {
-      validateDependenciesObject(dependencies, "constructor");
-    }
-
-    // Conditional validation for initial routes - structure and batch duplicates
-    // Validation happens BEFORE tree is built, so tree is not passed
-    if (!noValidate && routes.length > 0) {
-      validateAddRouteArgs(routes);
-      validateRoutes(routes);
+    if (routes.length > 0) {
+      guardRouteStructure(routes);
     }
 
     // =========================================================================
@@ -157,14 +135,12 @@ export class Router<
     this.#state = new StateNamespace();
     this.#routes = new RoutesNamespace<Dependencies>(
       routes,
-      noValidate,
       deriveMatcherOptions(this.#options.get()),
     );
     this.#routeLifecycle = new RouteLifecycleNamespace<Dependencies>();
     this.#plugins = new PluginsNamespace<Dependencies>();
     this.#navigation = new NavigationNamespace();
     this.#lifecycle = new RouterLifecycleNamespace();
-    this.#noValidate = noValidate;
 
     // =========================================================================
     // Initialize EventBus
@@ -241,10 +217,6 @@ export class Router<
       start: createInterceptable(
         "start",
         (path: string) => {
-          if (!noValidate) {
-            RouterLifecycleNamespace.validateStartArgs([path]);
-          }
-
           return this.#lifecycle.start(path);
         },
         interceptorsMap,
@@ -256,7 +228,7 @@ export class Router<
       getRootPath: () => this.#routes.getStore().rootPath,
       getTree: () => this.#routes.getStore().tree,
       isDisposed: () => this.#eventBus.isDisposed(),
-      noValidate,
+      validator: null,
       // Dependencies (issue #172)
       dependenciesGetStore: () => this.#dependenciesStore,
       // Clone support (issue #173)
@@ -330,14 +302,17 @@ export class Router<
     strictEquality?: boolean,
     ignoreQueryParams?: boolean,
   ): boolean {
-    if (!this.#noValidate) {
-      validateIsActiveRouteArgs(
-        name,
-        params,
-        strictEquality,
-        ignoreQueryParams,
-      );
-    }
+    getInternals(this).validator?.routes.validateIsActiveRouteArgs(
+      name,
+      params,
+      strictEquality,
+      ignoreQueryParams,
+    );
+
+    getInternals(this).validator?.routes.validateRouteName(
+      name,
+      "isActiveRoute",
+    );
 
     // Empty string is special case - warn and return false (root node is not a parent)
     if (name === "") {
@@ -358,11 +333,12 @@ export class Router<
   }
 
   buildPath(route: string, params?: Params): string {
-    if (!this.#noValidate) {
-      validateBuildPathArgs(route);
-    }
+    const ctx = getInternals(this);
 
-    return getInternals(this).buildPath(route, params);
+    ctx.validator?.routes.validateBuildPathArgs(route);
+    ctx.validator?.navigation.validateParams(params, "buildPath");
+
+    return ctx.buildPath(route, params);
   }
 
   // ============================================================================
@@ -384,13 +360,11 @@ export class Router<
     state2: State | undefined,
     ignoreQueryParams = true,
   ): boolean {
-    if (!this.#noValidate) {
-      StateNamespace.validateAreStatesEqualArgs(
-        state1,
-        state2,
-        ignoreQueryParams,
-      );
-    }
+    getInternals(this).validator?.state.validateAreStatesEqualArgs(
+      state1,
+      state2,
+      ignoreQueryParams,
+    );
 
     return this.#state.areStatesEqual(state1, state2, ignoreQueryParams);
   }
@@ -398,9 +372,7 @@ export class Router<
   shouldUpdateNode(
     nodeName: string,
   ): (toState: State, fromState?: State) => boolean {
-    if (!this.#noValidate) {
-      validateShouldUpdateNodeArgs(nodeName);
-    }
+    getInternals(this).validator?.routes.validateShouldUpdateNodeArgs(nodeName);
 
     return RoutesNamespace.shouldUpdateNode(nodeName);
   }
@@ -418,6 +390,8 @@ export class Router<
       return Promise.reject(CACHED_ALREADY_STARTED_ERROR);
     }
 
+    getInternals(this).validator?.navigation.validateStartArgs(startPath);
+
     this.#eventBus.sendStart();
 
     const promiseState = getInternals(this)
@@ -494,15 +468,15 @@ export class Router<
   // ============================================================================
 
   canNavigateTo(name: string, params?: Params): boolean {
-    if (!this.#noValidate) {
-      validateRouteName(name, "canNavigateTo");
-    }
+    const ctx = getInternals(this);
+
+    ctx.validator?.routes.validateRouteName(name, "canNavigateTo");
+    ctx.validator?.navigation.validateParams(params, "canNavigateTo");
 
     if (!this.#routes.hasRoute(name)) {
       return false;
     }
 
-    const ctx = getInternals(this);
     const { name: resolvedName, params: resolvedParams } = ctx.forwardState(
       name,
       params ?? {},
@@ -524,27 +498,29 @@ export class Router<
   // Plugins
   // ============================================================================
 
-  usePlugin(...plugins: PluginFactory<Dependencies>[]): Unsubscribe {
-    if (!this.#noValidate) {
-      // 1. Validate input arguments
-      PluginsNamespace.validateUsePluginArgs<Dependencies>(plugins);
+  usePlugin(
+    ...plugins: (PluginFactory<Dependencies> | false | null | undefined)[]
+  ): Unsubscribe {
+    const filtered = plugins.filter(Boolean) as PluginFactory<Dependencies>[];
 
-      // 2. Validate limit
-      PluginsNamespace.validatePluginLimit(
-        this.#plugins.count(),
-        plugins.length,
-        this.#limits.maxPlugins,
-      );
+    if (filtered.length === 0) {
+      return () => {};
+    }
+
+    const ctx = getInternals(this);
 
-      // 3. Validate no duplicates with existing plugins
-      PluginsNamespace.validateNoDuplicatePlugins(
-        plugins,
-        this.#plugins.has.bind(this.#plugins),
+    ctx.validator?.plugins.validatePluginLimit(
+      this.#plugins.count(),
+      this.#limits,
+    );
+    for (const plugin of filtered) {
+      ctx.validator?.plugins.validateNoDuplicatePlugins(
+        plugin,
+        this.#plugins.getAll(),
       );
     }
 
-    // 4. Execute (warnings, deduplication, initialization, commit)
-    return this.#plugins.use(...plugins);
+    return this.#plugins.use(...filtered);
   }
 
   // ============================================================================
@@ -552,9 +528,7 @@ export class Router<
   // ============================================================================
 
   subscribe(listener: SubscribeFn): Unsubscribe {
-    if (!this.#noValidate) {
-      EventBusNamespace.validateSubscribeListener(listener);
-    }
+    EventBusNamespace.validateSubscribeListener(listener);
 
     return this.#eventBus.subscribe(listener);
   }
@@ -568,19 +542,15 @@ export class Router<
     routeParams?: Params,
     options?: NavigationOptions,
   ): Promise<State> {
-    // 1. Validate route name
-    if (!this.#noValidate) {
-      NavigationNamespace.validateNavigateArgs(routeName);
-    }
+    const ctx = getInternals(this);
+
+    ctx.validator?.navigation.validateNavigateArgs(routeName);
+    ctx.validator?.navigation.validateParams(routeParams, "navigate");
 
-    // 2. Validate parsed options
     const opts = options ?? EMPTY_OPTS;
 
-    if (!this.#noValidate) {
-      NavigationNamespace.validateNavigationOptions(opts, "navigate");
-    }
+    ctx.validator?.navigation.validateNavigationOptions(opts, "navigate");
 
-    // 3. Execute navigation with parsed arguments
     const promiseState = this.#navigation.navigate(
       routeName,
       routeParams ?? EMPTY_PARAMS,
@@ -600,19 +570,17 @@ export class Router<
   }
 
   navigateToDefault(options?: NavigationOptions): Promise<State> {
-    // 1. Validate arguments
-    if (!this.#noValidate) {
-      NavigationNamespace.validateNavigateToDefaultArgs(options);
-    }
+    const ctx = getInternals(this);
+
+    ctx.validator?.navigation.validateNavigateToDefaultArgs(options);
 
-    // 2. Validate parsed options
     const opts = options ?? EMPTY_OPTS;
 
-    if (!this.#noValidate) {
-      NavigationNamespace.validateNavigationOptions(opts, "navigateToDefault");
-    }
+    ctx.validator?.navigation.validateNavigationOptions(
+      opts,
+      "navigateToDefault",
+    );
 
-    // 3. Execute navigation with parsed arguments
     const promiseState = this.#navigation.navigateToDefault(opts);
 
     if (this.#navigation.lastSyncResolved) {
@@ -631,6 +599,12 @@ export class Router<
       throw new RouterError(errorCodes.ROUTER_NOT_STARTED);
     }
 
+    if (path !== undefined && typeof path !== "string") {
+      throw new TypeError(
+        `[router.navigateToNotFound] path must be a string, got ${typeof path}`,
+      );
+    }
+
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- isActive() guarantees state exists
     const resolvedPath = path ?? this.#state.get()!.path;
 

package/src/api/cloneRouter.ts

@@ -1,5 +1,4 @@
 import { routeTreeToDefinitions } from "route-tree";
-import { getTypeDescription } from "type-guards";
 
 import { errorCodes } from "../constants";
 import { getInternals } from "../internals";
@@ -10,32 +9,6 @@ import { getLifecycleApi } from "./getLifecycleApi";
 import type { Route } from "../types";
 import type { DefaultDependencies, Router } from "@real-router/types";
 
-function validateCloneArgs(dependencies: unknown): void {
-  if (dependencies === undefined) {
-    return;
-  }
-
-  if (
-    !(
-      dependencies &&
-      typeof dependencies === "object" &&
-      dependencies.constructor === Object
-    )
-  ) {
-    throw new TypeError(
-      `[cloneRouter] Invalid dependencies: expected plain object or undefined, received ${getTypeDescription(dependencies)}`,
-    );
-  }
-
-  for (const key in dependencies) {
-    if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
-      throw new TypeError(
-        `[cloneRouter] Getters not allowed in dependencies: "${key}"`,
-      );
-    }
-  }
-}
-
 export function cloneRouter<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
@@ -48,9 +21,7 @@ export function cloneRouter<
     throw new RouterError(errorCodes.ROUTER_DISPOSED);
   }
 
-  if (!ctx.noValidate) {
-    validateCloneArgs(dependencies);
-  }
+  ctx.validator?.dependencies.validateCloneArgs(dependencies);
 
   // Get source store directly
   const sourceStore = ctx.routeGetStore();