@real-router/core 0.40.1 → 0.42.0

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -1,8 +1,9 @@
 // packages/core/src/namespaces/StateNamespace/StateNamespace.ts
 
-import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
+import { areParamValuesEqual } from "./helpers";
 import { EMPTY_PARAMS } from "../../constants";
 import { freezeStateInPlace } from "../../helpers";
+import { setStateMetaParams } from "../../stateMetaStore";
 
 import type { StateNamespaceDependencies } from "./types";
 import type { Params, State } from "@real-router/types";
@@ -15,11 +16,6 @@ import type { RouteTreeStateMeta } from "route-tree";
  * Instance methods handle state storage, freezing, and creation.
  */
 export class StateNamespace {
-  /**
-   * Auto-incrementing state ID for tracking navigation history.
-   */
-  #stateId = 0;
-
   /**
    * Cached frozen state - avoids structuredClone on every getState() call.
    */
@@ -50,10 +46,8 @@ export class StateNamespace {
    * The returned state is deeply frozen (immutable) for safety.
    * Returns `undefined` if the router has not been started or has been stopped.
    */
-  get<P extends Params = Params, MP extends Params = Params>():
-    | State<P, MP>
-    | undefined {
-    return this.#frozenState as State<P, MP> | undefined; // NOSONAR -- generic narrowing needed for public API
+  get<P extends Params = Params>(): State<P> | undefined {
+    return this.#frozenState as State<P> | undefined; // NOSONAR -- generic narrowing needed for public API
   }
 
   /**
@@ -84,7 +78,6 @@ export class StateNamespace {
     this.#frozenState = undefined;
     this.#previousState = undefined;
     this.#urlParamsCache.clear();
-    this.#stateId = 0;
   }
 
   // =========================================================================
@@ -106,18 +99,13 @@ export class StateNamespace {
   /**
    * Creates a frozen state object for a route.
    */
-  makeState<P extends Params = Params, MP extends Params = Params>(
+  makeState<P extends Params = Params>(
     name: string,
     params?: P,
     path?: string,
     meta?: RouteTreeStateMeta,
-    forceId?: number,
     skipFreeze?: boolean,
-  ): State<P, MP> {
-    const madeMeta = meta
-      ? { id: forceId ?? ++this.#stateId, params: meta as unknown as MP }
-      : undefined;
-
+  ): State<P> {
     // Optimization: O(1) lookup instead of O(depth) ancestor iteration
     const defaultParamsConfig = this.#deps.getDefaultParams();
     const hasDefaultParams = Object.hasOwn(defaultParamsConfig, name);
@@ -133,13 +121,16 @@ export class StateNamespace {
       mergedParams = { ...params };
     }
 
-    const state: State<P, MP> = {
+    const state: State<P> = {
       name,
       params: mergedParams,
       path: path ?? this.#deps.buildPath(name, params),
-      meta: madeMeta,
     };
 
+    if (meta) {
+      setStateMetaParams(state, meta as unknown as Params);
+    }
+
     return skipFreeze ? state : freezeStateInPlace(state);
   }
 
@@ -165,17 +156,17 @@ export class StateNamespace {
     }
 
     if (ignoreQueryParams) {
-      const stateMeta = (state1.meta?.params ?? state2.meta?.params) as  // NOSONAR -- narrowing from Params to RouteTreeStateMeta
-        | RouteTreeStateMeta
-        | undefined;
+      const urlParams = this.#getUrlParams(state1.name);
 
-      const urlParams = stateMeta
-        ? getUrlParamsFromMeta(stateMeta)
-        : this.#getUrlParams(state1.name);
+      for (const urlParam of urlParams) {
+        if (
+          !areParamValuesEqual(state1.params[urlParam], state2.params[urlParam])
+        ) {
+          return false;
+        }
+      }
 
-      return urlParams.every((param) =>
-        areParamValuesEqual(state1.params[param], state2.params[param]),
-      );
+      return true;
     }
 
     const state1Keys = Object.keys(state1.params);
@@ -185,11 +176,16 @@ export class StateNamespace {
       return false;
     }
 
-    return state1Keys.every(
-      (param) =>
-        param in state2.params &&
-        areParamValuesEqual(state1.params[param], state2.params[param]),
-    );
+    for (const param of state1Keys) {
+      if (
+        !(param in state2.params) ||
+        !areParamValuesEqual(state1.params[param], state2.params[param])
+      ) {
+        return false;
+      }
+    }
+
+    return true;
   }
 
   // =========================================================================

package/src/namespaces/StateNamespace/helpers.ts

@@ -1,31 +1,5 @@
 // packages/core/src/namespaces/StateNamespace/helpers.ts
 
-import type { RouteTreeStateMeta } from "route-tree";
-
-/**
- * Extracts URL param names from RouteTreeStateMeta.
- * This is an O(segments × params) operation but avoids tree traversal.
- */
-export function getUrlParamsFromMeta(meta: RouteTreeStateMeta): string[] {
-  const urlParams: string[] = [];
-
-  for (const segmentName in meta) {
-    const paramMap = meta[segmentName];
-
-    for (const param in paramMap) {
-      if (paramMap[param] === "url") {
-        urlParams.push(param);
-      }
-    }
-  }
-
-  return urlParams;
-}
-
-/**
- * Compares two parameter values for equality.
- * Supports deep equality for arrays (common in route params like tags, ids).
- */
 export function areParamValuesEqual(val1: unknown, val2: unknown): boolean {
   if (val1 === val2) {
     return true;
@@ -36,7 +10,14 @@ export function areParamValuesEqual(val1: unknown, val2: unknown): boolean {
       return false;
     }
 
-    return val1.every((value, i) => areParamValuesEqual(value, val2[i]));
+    // eslint-disable-next-line unicorn/no-for-loop -- hot path: for-of entries() allocates iterator per recursive call
+    for (let i = 0; i < val1.length; i++) {
+      if (!areParamValuesEqual(val1[i], val2[i])) {
+        return false;
+      }
+    }
+
+    return true;
   }
 
   return false;

package/src/stateMetaStore.ts

@@ -0,0 +1,15 @@
+// packages/core/src/stateMetaStore.ts
+
+import type { Params, State } from "@real-router/types";
+
+const store = new WeakMap<State, Params>();
+
+/** @internal */
+export function getStateMetaParams(state: State): Params | undefined {
+  return store.get(state);
+}
+
+/** @internal */
+export function setStateMetaParams(state: State, params: Params): void {
+  store.set(state, params);
+}

package/src/transitionPath.ts

@@ -1,5 +1,7 @@
 // packages/core/src/transitionPath.ts
 
+import { getStateMetaParams } from "./stateMetaStore";
+
 import type { State } from "@real-router/types";
 
 /**
@@ -96,10 +98,11 @@ function isPrimitive(value: unknown): value is PrimitiveParam {
  */
 function segmentParamsEqual(
   name: string,
+  toMetaParams: Record<string, unknown>,
   toState: State,
   fromState: State,
 ): boolean {
-  const keys = toState.meta?.params[name];
+  const keys = toMetaParams[name];
 
   if (!keys || typeof keys !== "object") {
     return true;
@@ -125,6 +128,7 @@ function segmentParamsEqual(
  * Finds the point where two state paths diverge based on segments and parameters.
  * Compares both segment names and their parameters to find the first difference.
  *
+ * @param toMetaParams - Cached meta.params from toState (avoids per-segment WeakMap lookup)
  * @param toState - Target state
  * @param fromState - Source state
  * @param toStateIds - Segment IDs for target state
@@ -133,6 +137,7 @@ function segmentParamsEqual(
  * @returns Index of first difference, or maxI if all checked segments match
  */
 function pointOfDifference(
+  toMetaParams: Record<string, unknown>,
   toState: State,
   fromState: State,
   toStateIds: string[],
@@ -148,7 +153,7 @@ function pointOfDifference(
       return i;
     }
 
-    if (!segmentParamsEqual(toSegment, toState, fromState)) {
+    if (!segmentParamsEqual(toSegment, toMetaParams, toState, fromState)) {
       return i;
     }
   }
@@ -339,13 +344,12 @@ function computeTransitionPath(
     };
   }
 
-  // ===== FAST PATH 3: Missing meta or meta.params requires full reload =====
-  // Check if meta or meta.params is actually missing (not just empty)
-  const toHasMeta = toState.meta?.params !== undefined;
-  const fromHasMeta = fromState.meta?.params !== undefined;
+  // ===== FAST PATH 3: Missing meta requires full reload =====
+  // Single WeakMap lookup per state, reused in pointOfDifference/segmentParamsEqual
+  const toMetaParams = getStateMetaParams(toState);
+  const fromMetaParams = getStateMetaParams(fromState);
 
-  if (!toHasMeta && !fromHasMeta) {
-    // Both states missing meta.params - require full reload
+  if (!toMetaParams && !fromMetaParams) {
     return {
       intersection: EMPTY_INTERSECTION,
       toActivate: nameToIDs(toState.name),
@@ -354,14 +358,12 @@ function computeTransitionPath(
   }
 
   // ===== STANDARD PATH: Routes with parameters =====
-  // Use original algorithm for complex cases with parameters
   const toStateIds = nameToIDs(toState.name);
   const fromStateIds = nameToIDs(fromState.name);
   const maxI = Math.min(fromStateIds.length, toStateIds.length);
 
-  // Find where paths diverge based on segments and parameters
-  // not obvious validate toState and fromState
   const i = pointOfDifference(
+    (toMetaParams ?? fromMetaParams) as Record<string, unknown>,
     toState,
     fromState,
     toStateIds,
@@ -402,12 +404,7 @@ function computeTransitionPath(
 export function getTransitionPath(
   toState: State,
   fromState?: State,
-  reload?: boolean,
 ): TransitionPath {
-  if (reload) {
-    return computeTransitionPath(toState, fromState);
-  }
-
   if (
     cached1Result !== null &&
     toState === cached1To &&

package/src/types/RouterValidator.ts

@@ -136,7 +136,6 @@ export interface RouterValidator {
       name: unknown,
       params: unknown,
       path: unknown,
-      forceId: unknown,
     ) => void;
     validateAreStatesEqualArgs: (
       s1: unknown,

package/src/wiring/RouterWiringBuilder.ts

@@ -149,7 +149,7 @@ export class RouterWiringBuilder<
 
         const path = ctx.buildPath(name, params);
 
-        return this.state.makeState(name, params, path, meta, undefined, true);
+        return this.state.makeState(name, params, path, meta, true);
       },
       resolveDefault: () => {
         const options = this.options.get();

package/dist/cjs/Router-B-Pev7K2.d.ts

@@ -1,46 +0,0 @@
-import { DefaultDependencies, Router as Router$1, Route, Options, Params, State, PluginFactory, Unsubscribe, SubscribeFn, NavigationOptions } from '@real-router/types';
-
-/**
- * Router class with integrated namespace architecture.
- *
- * All functionality is provided by namespace classes:
- * - OptionsNamespace: getOptions (immutable)
- * - DependenciesStore: get/set/remove dependencies
- * - EventEmitter: subscribe
- * - StateNamespace: state storage (getState, setState, getPreviousState)
- * - RoutesNamespace: route tree operations
- * - RouteLifecycleNamespace: canActivate/canDeactivate guards
- * - PluginsNamespace: plugin lifecycle
- * - NavigationNamespace: navigate
- * - RouterLifecycleNamespace: start, stop, isStarted
- *
- * @internal This class implementation is internal. Use createRouter() instead.
- */
-declare class Router<Dependencies extends DefaultDependencies = DefaultDependencies> implements Router$1<Dependencies> {
-    #private;
-    [key: string]: unknown;
-    /**
-     * @param routes - Route definitions
-     * @param options - Router options
-     * @param dependencies - DI dependencies
-     */
-    constructor(routes?: Route<Dependencies>[], options?: Partial<Options>, dependencies?: Dependencies);
-    isActiveRoute(name: string, params?: Params, strictEquality?: boolean, ignoreQueryParams?: boolean): boolean;
-    buildPath(route: string, params?: Params): string;
-    getState<P extends Params = Params, MP extends Params = Params>(): State<P, MP> | undefined;
-    getPreviousState(): State | undefined;
-    areStatesEqual(state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean): boolean;
-    shouldUpdateNode(nodeName: string): (toState: State, fromState?: State) => boolean;
-    isActive(): boolean;
-    start(startPath: string): Promise<State>;
-    stop(): this;
-    dispose(): void;
-    canNavigateTo(name: string, params?: Params): boolean;
-    usePlugin(...plugins: (PluginFactory<Dependencies> | false | null | undefined)[]): Unsubscribe;
-    subscribe(listener: SubscribeFn): Unsubscribe;
-    navigate(routeName: string, routeParams?: Params, options?: NavigationOptions): Promise<State>;
-    navigateToDefault(options?: NavigationOptions): Promise<State>;
-    navigateToNotFound(path?: string): State;
-}
-
-export { Router as R };

package/dist/cjs/RouterValidator-mx2Zooya.d.ts

@@ -1,136 +0,0 @@
-import { Params, RouteTreeState, LimitsConfig } from '@real-router/types';
-
-/**
- * Core-internal types + re-exports from @real-router/types.
- *
- * Factory types (PluginFactory, GuardFnFactory) and
- * route config types (Route, RouteConfigUpdate) are canonical in @real-router/types
- * and re-exported here for backward compatibility.
- */
-
-/**
- * Immutable limits configuration type.
- */
-type Limits = Readonly<LimitsConfig>;
-/**
- * Extended build result that includes segments for path building.
- * Used internally to avoid duplicate getSegmentsByName calls.
- *
- * @param segments - Route segments from getSegmentsByName (typed as unknown[] for cross-package compatibility)
- * @internal
- */
-interface BuildStateResultWithSegments<P extends Params = Params> {
-    readonly state: RouteTreeState<P>;
-    readonly segments: readonly unknown[];
-}
-
-/**
- * RouterValidator interface - defines all validation methods used by the router.
- *
- * This interface is implemented by the validation plugin and injected into RouterInternals.
- * When ctx.validator is null (default), validation is skipped.
- * When ctx.validator is set (by validation plugin), all methods are called.
- *
- * All parameters use `unknown` type to avoid coupling to internal type names.
- */
-interface RouterValidator {
-    /**
-     * Route validation methods
-     */
-    routes: {
-        validateBuildPathArgs: (route: unknown) => void;
-        validateMatchPathArgs: (path: unknown) => void;
-        validateIsActiveRouteArgs: (name: unknown, params: unknown, strict: unknown, ignoreQP: unknown) => void;
-        validateShouldUpdateNodeArgs: (name: unknown) => void;
-        validateStateBuilderArgs: (name: unknown, params: unknown, caller: string) => void;
-        validateAddRouteArgs: (routes: unknown) => void;
-        validateRoutes: (routes: unknown[], tree: unknown) => void;
-        validateRemoveRouteArgs: (name: unknown) => void;
-        validateUpdateRouteBasicArgs: (name: unknown, updates: unknown) => void;
-        validateUpdateRoutePropertyTypes: (name: string, updates: unknown) => void;
-        validateUpdateRoute: (name: string, updates: unknown, tree: unknown) => void;
-        validateParentOption: (parent: unknown, tree: unknown) => void;
-        validateRouteName: (name: unknown, caller: string) => void;
-        throwIfInternalRoute: (name: unknown, caller: string) => void;
-        throwIfInternalRouteInArray: (routes: unknown[], caller: string) => void;
-        validateExistingRoutes: (store: unknown) => void;
-        validateForwardToConsistency: (store: unknown) => void;
-        validateSetRootPathArgs: (rootPath: unknown) => void;
-        guardRouteCallbacks: (route: unknown) => void;
-        guardNoAsyncCallbacks: (route: unknown) => void;
-    };
-    /**
-     * Options validation methods
-     */
-    options: {
-        validateLimitValue: (name: string, value: unknown) => void;
-        validateLimits: (limits: unknown) => void;
-        validateOptions: (options: unknown, methodName: string) => void;
-    };
-    /**
-     * Dependencies validation methods
-     */
-    dependencies: {
-        validateDependencyName: (name: unknown, caller: string) => void;
-        validateSetDependencyArgs: (name: unknown, value: unknown, caller: string) => void;
-        validateDependenciesObject: (deps: unknown, caller: string) => void;
-        validateDependencyExists: (name: string, store: unknown) => void;
-        validateDependencyLimit: (store: unknown, limits: unknown) => void;
-        validateDependenciesStructure: (store: unknown) => void;
-        validateDependencyCount: (store: unknown, methodName: string) => void;
-        validateCloneArgs: (dependencies: unknown) => void;
-        warnOverwrite: (name: string, methodName: string) => void;
-        warnBatchOverwrite: (keys: string[], methodName: string) => void;
-        warnRemoveNonExistent: (name: unknown) => void;
-    };
-    /**
-     * Plugin validation methods
-     */
-    plugins: {
-        validatePluginLimit: (count: number, limits: unknown) => void;
-        validateNoDuplicatePlugins: (factory: unknown, factories: unknown[]) => void;
-        validatePluginKeys: (plugin: unknown) => void;
-        validateCountThresholds: (count: number) => void;
-        warnBatchDuplicates: (plugins: unknown[]) => void;
-        warnPluginMethodType: (methodName: string) => void;
-        warnPluginAfterStart: (methodName: string) => void;
-        validateAddInterceptorArgs: (method: unknown, fn: unknown) => void;
-    };
-    /**
-     * Lifecycle guard validation methods
-     */
-    lifecycle: {
-        validateHandler: (handler: unknown, caller: string) => void;
-        validateNotRegistering: (name: string, guards: unknown, caller: string) => void;
-        validateHandlerLimit: (count: number, limits: unknown, caller: string) => void;
-        validateCountThresholds: (count: number, methodName: string) => void;
-        warnOverwrite: (name: string, type: string, methodName: string) => void;
-        warnAsyncGuardSync: (name: string, methodName: string) => void;
-    };
-    /**
-     * Navigation validation methods
-     */
-    navigation: {
-        validateNavigateArgs: (name: unknown) => void;
-        validateNavigateToDefaultArgs: (options: unknown) => void;
-        validateNavigationOptions: (options: unknown, caller: string) => void;
-        validateParams: (params: unknown, methodName: string) => void;
-        validateStartArgs: (path: unknown) => void;
-    };
-    /**
-     * State validation methods
-     */
-    state: {
-        validateMakeStateArgs: (name: unknown, params: unknown, path: unknown, forceId: unknown) => void;
-        validateAreStatesEqualArgs: (s1: unknown, s2: unknown, ignoreQP: unknown) => void;
-    };
-    /**
-     * Event bus validation methods
-     */
-    eventBus: {
-        validateEventName: (name: unknown) => void;
-        validateListenerArgs: (name: unknown, cb: unknown) => void;
-    };
-}
-
-export type { BuildStateResultWithSegments as B, Limits as L, RouterValidator as R };