@real-router/core 0.36.0 → 0.36.2

package/src/namespaces/NavigationNamespace/transition/guardPhase.ts

@@ -0,0 +1,214 @@
+import { handleGuardError } from "./errorHandling";
+import { errorCodes } from "../../../constants";
+import { RouterError } from "../../../RouterError";
+
+import type { GuardFn, State } from "@real-router/types";
+
+async function resolveAsyncGuard(
+  promise: Promise<boolean>,
+  errorCode: string,
+  segment: string,
+): Promise<void> {
+  let result: boolean;
+
+  try {
+    result = await promise;
+  } catch (error: unknown) {
+    handleGuardError(error, errorCode, segment);
+
+    return; // unreachable — handleGuardError returns never
+  }
+
+  if (!result) {
+    throw new RouterError(errorCode, { segment });
+  }
+}
+
+async function resolveRemainingGuards(
+  guards: Map<string, GuardFn>,
+  segments: string[],
+  errorCode: string,
+  toState: State,
+  fromState: State | undefined,
+  signal: AbortSignal | undefined,
+  isActive: () => boolean,
+  startIndex: number,
+  firstResult: Promise<boolean>,
+  firstSegment: string,
+): Promise<void> {
+  await resolveAsyncGuard(firstResult, errorCode, firstSegment);
+
+  for (let i = startIndex; i < segments.length; i++) {
+    if (!isActive()) {
+      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+    }
+
+    const segment = segments[i];
+    const guardFn = guards.get(segment);
+
+    if (!guardFn) {
+      continue;
+    }
+
+    let guardResult: boolean | Promise<boolean> = false;
+
+    try {
+      guardResult = guardFn(toState, fromState, signal);
+    } catch (error: unknown) {
+      handleGuardError(error, errorCode, segment);
+    }
+
+    if (guardResult instanceof Promise) {
+      await resolveAsyncGuard(guardResult, errorCode, segment);
+      continue;
+    }
+
+    if (!guardResult) {
+      throw new RouterError(errorCode, { segment });
+    }
+  }
+}
+
+async function finishAsyncPipeline(
+  deactivateCompletion: Promise<void>,
+  activateGuards: Map<string, GuardFn>,
+  toActivate: string[],
+  shouldActivate: boolean,
+  toState: State,
+  fromState: State | undefined,
+  signal: AbortSignal,
+  isActive: () => boolean,
+): Promise<void> {
+  await deactivateCompletion;
+
+  if (!isActive()) {
+    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+  }
+
+  if (shouldActivate) {
+    const pending = runGuards(
+      activateGuards,
+      toActivate,
+      errorCodes.CANNOT_ACTIVATE,
+      toState,
+      fromState,
+      signal,
+      isActive,
+    );
+
+    if (pending !== undefined) {
+      await pending;
+    }
+
+    if (!isActive()) {
+      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+    }
+  }
+}
+
+export function executeGuardPipeline(
+  deactivateGuards: Map<string, GuardFn>,
+  activateGuards: Map<string, GuardFn>,
+  toDeactivate: string[],
+  toActivate: string[],
+  shouldDeactivate: boolean,
+  shouldActivate: boolean,
+  toState: State,
+  fromState: State | undefined,
+  signal: AbortSignal,
+  isActive: () => boolean,
+): Promise<void> | undefined {
+  if (shouldDeactivate) {
+    const pending = runGuards(
+      deactivateGuards,
+      toDeactivate,
+      errorCodes.CANNOT_DEACTIVATE,
+      toState,
+      fromState,
+      signal,
+      isActive,
+    );
+
+    if (pending !== undefined) {
+      return finishAsyncPipeline(
+        pending,
+        activateGuards,
+        toActivate,
+        shouldActivate,
+        toState,
+        fromState,
+        signal,
+        isActive,
+      );
+    }
+  }
+
+  if (!isActive()) {
+    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+  }
+
+  if (shouldActivate) {
+    return runGuards(
+      activateGuards,
+      toActivate,
+      errorCodes.CANNOT_ACTIVATE,
+      toState,
+      fromState,
+      signal,
+      isActive,
+    );
+  }
+
+  return undefined;
+}
+
+function runGuards(
+  guards: Map<string, GuardFn>,
+  segments: string[],
+  errorCode: string,
+  toState: State,
+  fromState: State | undefined,
+  signal: AbortSignal | undefined,
+  isActive: () => boolean,
+): Promise<void> | undefined {
+  for (const [i, segment] of segments.entries()) {
+    if (!isActive()) {
+      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+    }
+
+    const guardFn = guards.get(segment);
+
+    if (!guardFn) {
+      continue;
+    }
+
+    let guardResult: boolean | Promise<boolean> = false;
+
+    try {
+      guardResult = guardFn(toState, fromState, signal);
+    } catch (error: unknown) {
+      handleGuardError(error, errorCode, segment);
+    }
+
+    if (guardResult instanceof Promise) {
+      return resolveRemainingGuards(
+        guards,
+        segments,
+        errorCode,
+        toState,
+        fromState,
+        signal,
+        isActive,
+        i + 1,
+        guardResult,
+        segment,
+      );
+    }
+
+    if (!guardResult) {
+      throw new RouterError(errorCode, { segment });
+    }
+  }
+
+  return undefined;
+}

package/src/namespaces/NavigationNamespace/types.ts

@@ -1,16 +1,23 @@
 // packages/core/src/namespaces/NavigationNamespace/types.ts
 
-import type { BuildStateResultWithSegments } from "../../types";
 import type {
   GuardFn,
   NavigationOptions,
   Options,
   Params,
   State,
-  StateMetaInput,
-  TransitionPhase,
 } from "@real-router/types";
 
+export interface NavigationContext {
+  toState: State;
+  fromState: State | undefined;
+  opts: NavigationOptions;
+  toDeactivate: string[];
+  toActivate: string[];
+  intersection: string;
+  canDeactivateFunctions: Map<string, GuardFn>;
+}
+
 /**
  * Dependencies injected into NavigationNamespace.
  *
@@ -30,22 +37,11 @@ export interface NavigationDependencies {
   /** Set router state */
   setState: (state: State) => void;
 
-  /** Build state with segments from route name and params */
-  buildStateWithSegments: <P extends Params = Params>(
+  /** Build complete navigate state: forwardState + route check + buildPath + makeState in one step */
+  buildNavigateState: (
     routeName: string,
-    routeParams: P,
-  ) => BuildStateResultWithSegments<P> | undefined;
-
-  /** Make state object with path and meta */
-  makeState: <P extends Params = Params, MP extends Params = Params>(
-    name: string,
-    params?: P,
-    path?: string,
-    meta?: StateMetaInput<MP>,
-  ) => State<P, MP>;
-
-  /** Build path from route name and params */
-  buildPath: (route: string, params?: Params) => string;
+    routeParams: Params,
+  ) => State | undefined;
 
   /** Check if states are equal */
   areStatesEqual: (
@@ -106,15 +102,3 @@ export interface NavigationDependencies {
   /** Clear canDeactivate guard for a route */
   clearCanDeactivate: (name: string) => void;
 }
-
-export interface TransitionOutput {
-  state: State;
-  meta: {
-    phase: TransitionPhase;
-    segments: {
-      deactivated: string[];
-      activated: string[];
-      intersection: string;
-    };
-  };
-}

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -42,6 +42,11 @@ export class RouteLifecycleNamespace<
   >();
   readonly #canDeactivateFunctions = new Map<string, GuardFn>();
   readonly #canActivateFunctions = new Map<string, GuardFn>();
+  // Cached tuple — Maps never change reference, so this is stable
+  readonly #functionsTuple: [Map<string, GuardFn>, Map<string, GuardFn>] = [
+    this.#canDeactivateFunctions,
+    this.#canActivateFunctions,
+  ];
 
   readonly #registering = new Set<string>();
   readonly #definitionActivateGuardNames = new Set<string>();
@@ -249,7 +254,7 @@ export class RouteLifecycleNamespace<
    * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
    */
   getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>] {
-    return [this.#canDeactivateFunctions, this.#canActivateFunctions];
+    return this.#functionsTuple;
   }
 
   canNavigateTo(

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -14,7 +14,7 @@ import { getTransitionPath } from "../../transitionPath";
 
 import type { RoutesStore } from "./routesStore";
 import type { RoutesDependencies } from "./types";
-import type { BuildStateResultWithSegments, Route } from "../../types";
+import type { Route } from "../../types";
 import type { RouteLifecycleNamespace } from "../RouteLifecycleNamespace";
 import type {
   DefaultDependencies,
@@ -65,6 +65,11 @@ export function createRouteState<P extends RouteParams = RouteParams>(
   };
 }
 
+interface CachedBuildPathOpts {
+  readonly trailingSlash?: "always" | "never" | undefined;
+  readonly queryParamsMode?: "default" | "strict" | "loose" | undefined;
+}
+
 /**
  * Independent namespace for managing routes.
  *
@@ -75,6 +80,7 @@ export class RoutesNamespace<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 > {
   readonly #store: RoutesStore<Dependencies>;
+  #cachedBuildPathOpts: CachedBuildPathOpts | undefined;
 
   get #deps(): RoutesDependencies<Dependencies> {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -210,13 +216,11 @@ export class RoutesNamespace<
         ? this.#store.config.encoders[route]({ ...paramsWithDefault })
         : paramsWithDefault;
 
-    const ts = options?.trailingSlash;
-    const trailingSlash = ts === "never" || ts === "always" ? ts : undefined;
-
-    return this.#store.matcher.buildPath(route, encodedParams, {
-      trailingSlash,
-      queryParamsMode: options?.queryParamsMode,
-    });
+    return this.#store.matcher.buildPath(
+      route,
+      encodedParams,
+      this.#getBuildPathOptions(options),
+    );
   }
 
   /**
@@ -267,9 +271,7 @@ export class RoutesNamespace<
       });
     }
 
-    return this.#deps.makeState<P, MP>(routeName, routeParams, builtPath, {
-      params: meta as MP,
-    });
+    return this.#deps.makeState<P, MP>(routeName, routeParams, builtPath, meta);
   }
 
   /**
@@ -359,30 +361,6 @@ export class RoutesNamespace<
     );
   }
 
-  buildStateWithSegmentsResolved<P extends Params = Params>(
-    resolvedName: string,
-    resolvedParams: P,
-  ): BuildStateResultWithSegments<P> | undefined {
-    const segments = this.#store.matcher.getSegmentsByName(resolvedName);
-
-    if (!segments) {
-      return undefined;
-    }
-
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const meta = this.#store.matcher.getMetaByName(resolvedName)!;
-    const state = createRouteState<P>(
-      {
-        segments: segments as readonly RouteTree[],
-        params: resolvedParams,
-        meta,
-      },
-      resolvedName,
-    );
-
-    return { state, segments: segments as readonly RouteTree[] };
-  }
-
   // =========================================================================
   // Query operations
   // =========================================================================
@@ -457,6 +435,14 @@ export class RoutesNamespace<
     );
   }
 
+  getMetaForState(
+    name: string,
+  ): Record<string, Record<string, "url" | "query">> | undefined {
+    return this.#store.matcher.hasRoute(name)
+      ? this.#store.matcher.getMetaByName(name)
+      : undefined;
+  }
+
   getUrlParams(name: string): string[] {
     const segments = this.#store.matcher.getSegmentsByName(name);
 
@@ -485,6 +471,21 @@ export class RoutesNamespace<
     return params;
   }
 
+  #getBuildPathOptions(options?: Options): CachedBuildPathOpts {
+    if (this.#cachedBuildPathOpts) {
+      return this.#cachedBuildPathOpts;
+    }
+
+    const ts = options?.trailingSlash;
+
+    this.#cachedBuildPathOpts = Object.freeze({
+      trailingSlash: ts === "never" || ts === "always" ? ts : undefined,
+      queryParamsMode: options?.queryParamsMode,
+    });
+
+    return this.#cachedBuildPathOpts;
+  }
+
   #resolveDynamicForward(
     startName: string,
     startFn: ForwardToCallback<Dependencies>,

package/src/namespaces/RoutesNamespace/forwardToValidation.ts

@@ -284,11 +284,8 @@ function getTargetParams<Dependencies extends DefaultDependencies>(
   routes: readonly Route<Dependencies>[],
 ): Set<string> {
   if (existsInTree) {
-    const toSegments = getSegmentsByName(tree, targetRoute);
-
-    // toSegments won't be null since we checked existsInTree
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    return getRequiredParams(toSegments!);
+    /* v8 ignore next -- @preserve: ?? fallback unreachable — existsInTree guarantees non-null */
+    return getRequiredParams(getSegmentsByName(tree, targetRoute) ?? []);
   }
 
   // Target is in batch

package/src/namespaces/RoutesNamespace/types.ts

@@ -7,7 +7,6 @@ import type {
   Params,
   SimpleState,
   State,
-  StateMetaInput,
 } from "@real-router/types";
 
 /**
@@ -36,7 +35,7 @@ export interface RoutesDependencies<
     name: string,
     params?: P,
     path?: string,
-    meta?: StateMetaInput<MP>,
+    meta?: Record<string, Record<string, "url" | "query">>,
   ) => State<P, MP>;
 
   /** Get current router state */

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -3,10 +3,11 @@
 import { getTypeDescription, validateState } from "type-guards";
 
 import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
+import { EMPTY_PARAMS } from "../../constants";
 import { freezeStateInPlace } from "../../helpers";
 
 import type { StateNamespaceDependencies } from "./types";
-import type { Params, State, StateMetaInput } from "@real-router/types";
+import type { Params, State } from "@real-router/types";
 import type { RouteTreeStateMeta } from "route-tree";
 
 /**
@@ -85,7 +86,7 @@ export class StateNamespace {
   get<P extends Params = Params, MP extends Params = Params>():
     | State<P, MP>
     | undefined {
-    return this.#frozenState as State<P, MP> | undefined;
+    return this.#frozenState as State<P, MP> | undefined; // NOSONAR -- generic narrowing needed for public API
   }
 
   /**
@@ -108,10 +109,8 @@ export class StateNamespace {
   /**
    * Returns the previous router state (before the last navigation).
    */
-  getPrevious<P extends Params = Params, MP extends Params = Params>():
-    | State<P, MP>
-    | undefined {
-    return this.#previousState as State<P, MP> | undefined;
+  getPrevious(): State | undefined {
+    return this.#previousState;
   }
 
   reset(): void {
@@ -144,15 +143,12 @@ export class StateNamespace {
     name: string,
     params?: P,
     path?: string,
-    meta?: StateMetaInput<MP>,
+    meta?: RouteTreeStateMeta,
     forceId?: number,
+    skipFreeze?: boolean,
   ): State<P, MP> {
     const madeMeta = meta
-      ? {
-          ...meta,
-          id: forceId ?? ++this.#stateId,
-          params: meta.params,
-        }
+      ? { id: forceId ?? ++this.#stateId, params: meta as unknown as MP }
       : undefined;
 
     // Optimization: O(1) lookup instead of O(depth) ancestor iteration
@@ -164,10 +160,10 @@ export class StateNamespace {
 
     if (hasDefaultParams) {
       mergedParams = { ...defaultParamsConfig[name], ...params } as P;
-    } else if (params) {
-      mergedParams = { ...params };
+    } else if (!params || params === EMPTY_PARAMS) {
+      mergedParams = EMPTY_PARAMS as P;
     } else {
-      mergedParams = {} as P;
+      mergedParams = { ...params };
     }
 
     const state: State<P, MP> = {
@@ -177,7 +173,7 @@ export class StateNamespace {
       meta: madeMeta,
     };
 
-    return freezeStateInPlace(state);
+    return skipFreeze ? state : freezeStateInPlace(state);
   }
 
   // =========================================================================
@@ -202,7 +198,7 @@ export class StateNamespace {
     }
 
     if (ignoreQueryParams) {
-      const stateMeta = (state1.meta?.params ?? state2.meta?.params) as
+      const stateMeta = (state1.meta?.params ?? state2.meta?.params) as  // NOSONAR -- narrowing from Params to RouteTreeStateMeta
         | RouteTreeStateMeta
         | undefined;