@real-router/core 0.35.0 → 0.35.2

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -11,13 +11,8 @@ import {
 import { errorCodes, constants } from "../../constants";
 import { RouterError } from "../../RouterError";
 import { nameToIDs } from "../../transitionPath";
-import { resolveOption } from "../OptionsNamespace";
 
-import type {
-  NavigationDependencies,
-  TransitionDependencies,
-  TransitionOutput,
-} from "./types";
+import type { NavigationDependencies, TransitionOutput } from "./types";
 import type {
   NavigationOptions,
   Params,
@@ -63,15 +58,7 @@ function routeTransitionError(
     return;
   }
 
-  /* v8 ignore next 7 -- @preserve: defensive guard for unexpected error codes (e.g. future error types); else branch unreachable after middleware became fire-and-forget */
-  if (
-    routerError.code === errorCodes.CANNOT_ACTIVATE ||
-    routerError.code === errorCodes.CANNOT_DEACTIVATE
-  ) {
-    deps.sendTransitionBlocked(toState, fromState, routerError);
-  } else {
-    deps.sendTransitionError(toState, fromState, routerError);
-  }
+  deps.sendTransitionFail(toState, fromState, routerError);
 }
 
 function buildSuccessState(
@@ -106,9 +93,7 @@ function buildSuccessState(
  * Handles navigate(), navigateToDefault(), navigateToNotFound(), and transition state.
  */
 export class NavigationNamespace {
-  #canNavigate!: () => boolean;
   #deps!: NavigationDependencies;
-  #transitionDeps!: TransitionDependencies;
   #currentController: AbortController | null = null;
 
   // =========================================================================
@@ -135,26 +120,10 @@ export class NavigationNamespace {
   // Dependency injection
   // =========================================================================
 
-  setCanNavigate(fn: () => boolean): void {
-    this.#canNavigate = fn;
-  }
-
-  /**
-   * Sets dependencies for navigation operations.
-   * Must be called before using navigation methods.
-   */
   setDependencies(deps: NavigationDependencies): void {
     this.#deps = deps;
   }
 
-  /**
-   * Sets dependencies for transition operations.
-   * Must be called before using navigation methods.
-   */
-  setTransitionDependencies(deps: TransitionDependencies): void {
-    this.#transitionDeps = deps;
-  }
-
   // =========================================================================
   // Instance methods
   // =========================================================================
@@ -168,7 +137,7 @@ export class NavigationNamespace {
     params: Params,
     opts: NavigationOptions,
   ): Promise<State> {
-    if (!this.#canNavigate()) {
+    if (!this.#deps.canNavigate()) {
       throw new RouterError(errorCodes.ROUTER_NOT_STARTED);
     }
 
@@ -212,19 +181,7 @@ export class NavigationNamespace {
       throw err;
     }
 
-    const transitionDeps = this.#transitionDeps;
-
-    if (transitionDeps.isTransitioning()) {
-      logger.warn(
-        "router.navigate",
-        "Concurrent navigation detected on shared router instance. " +
-          "For SSR, use cloneRouter() to create isolated instance per request.",
-      );
-      this.#currentController?.abort(
-        new RouterError(errorCodes.TRANSITION_CANCELLED),
-      );
-      deps.cancelNavigation();
-    }
+    this.#abortPreviousNavigation();
 
     const controller = new AbortController();
 
@@ -252,7 +209,7 @@ export class NavigationNamespace {
 
     try {
       const { state: finalState, meta: transitionOutput } = await transition(
-        transitionDeps,
+        deps,
         toState,
         fromState,
         opts,
@@ -283,7 +240,7 @@ export class NavigationNamespace {
           routeName: finalState.name,
         });
 
-        deps.sendTransitionError(finalState, fromState, err);
+        deps.sendTransitionFail(finalState, fromState, err);
 
         throw err;
       }
@@ -313,26 +270,20 @@ export class NavigationNamespace {
       });
     }
 
-    const resolvedRoute = resolveOption(
-      options.defaultRoute,
-      deps.getDependency,
-    );
+    const { route, params } = deps.resolveDefault();
 
-    if (!resolvedRoute) {
+    if (!route) {
       throw new RouterError(errorCodes.ROUTE_NOT_FOUND, {
         routeName: "defaultRoute resolved to empty",
       });
     }
 
-    const resolvedParams = resolveOption(
-      options.defaultParams,
-      deps.getDependency,
-    );
-
-    return this.navigate(resolvedRoute, resolvedParams, opts);
+    return this.navigate(route, params, opts);
   }
 
   navigateToNotFound(path: string): State {
+    this.#abortPreviousNavigation();
+
     const fromState = this.#deps.getState();
     const deactivated: string[] = fromState
       ? nameToIDs(fromState.name).toReversed()
@@ -378,4 +329,18 @@ export class NavigationNamespace {
     );
     this.#currentController = null;
   }
+
+  #abortPreviousNavigation(): void {
+    if (this.#deps.isTransitioning()) {
+      logger.warn(
+        "router.navigate",
+        "Concurrent navigation detected on shared router instance. " +
+          "For SSR, use cloneRouter() to create isolated instance per request.",
+      );
+      this.#currentController?.abort(
+        new RouterError(errorCodes.TRANSITION_CANCELLED),
+      );
+      this.#deps.cancelNavigation();
+    }
+  }
 }

package/src/namespaces/NavigationNamespace/index.ts

@@ -2,4 +2,4 @@
 
 export { NavigationNamespace } from "./NavigationNamespace";
 
-export type { NavigationDependencies, TransitionDependencies } from "./types";
+export type { NavigationDependencies } from "./types";

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

@@ -5,11 +5,14 @@ import { constants, errorCodes } from "../../../constants";
 import { RouterError } from "../../../RouterError";
 import { getTransitionPath } from "../../../transitionPath";
 
-import type { TransitionDependencies, TransitionOutput } from "../types";
+import type { NavigationDependencies, TransitionOutput } from "../types";
 import type { NavigationOptions, State } from "@real-router/types";
 
 export async function transition(
-  deps: TransitionDependencies,
+  deps: Pick<
+    NavigationDependencies,
+    "getLifecycleFunctions" | "isActive" | "clearCanDeactivate"
+  >,
   toState: State,
   fromState: State | undefined,
   opts: NavigationOptions,

package/src/namespaces/NavigationNamespace/types.ts

@@ -16,7 +16,7 @@ import type {
  *
  * These are function references from other namespaces/facade,
  * avoiding the need to pass the entire Router object.
- */
+ **/
 export interface NavigationDependencies {
   /** Get router options */
   getOptions: () => Options;
@@ -54,8 +54,8 @@ export interface NavigationDependencies {
     ignoreQueryParams?: boolean,
   ) => boolean;
 
-  /** Get a dependency by name (untyped — used only for resolveOption) */
-  getDependency: (name: string) => unknown;
+  /** Resolve defaultRoute and defaultParams options (static value or callback) */
+  resolveDefault: () => { route: string; params: Params };
 
   /** Start transition and send NAVIGATE event to routerFSM */
   startTransition: (toState: State, fromState: State | undefined) => void;
@@ -70,15 +70,8 @@ export interface NavigationDependencies {
     opts: NavigationOptions,
   ) => void;
 
-  /** Send FAIL event to routerFSM (transition blocked) */
-  sendTransitionBlocked: (
-    toState: State,
-    fromState: State | undefined,
-    error: unknown,
-  ) => void;
-
-  /** Send FAIL event to routerFSM (transition error) */
-  sendTransitionError: (
+  /** Send FAIL event to routerFSM */
+  sendTransitionFail: (
     toState: State,
     fromState: State | undefined,
     error: unknown,
@@ -97,24 +90,10 @@ export interface NavigationDependencies {
     fromState?: State,
     opts?: NavigationOptions,
   ) => void;
-}
 
-export interface TransitionOutput {
-  state: State;
-  meta: {
-    phase: TransitionPhase;
-    segments: {
-      deactivated: string[];
-      activated: string[];
-      intersection: string;
-    };
-  };
-}
+  /** Check if navigation can begin (router is started) */
+  canNavigate: () => boolean;
 
-/**
- * Dependencies required for the transition function.
- */
-export interface TransitionDependencies {
   /** Get lifecycle functions (canDeactivate, canActivate maps) */
   getLifecycleFunctions: () => [Map<string, GuardFn>, Map<string, GuardFn>];
 
@@ -127,3 +106,15 @@ export interface TransitionDependencies {
   /** 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/PluginsNamespace/PluginsNamespace.ts

@@ -12,7 +12,6 @@ import { DEFAULT_LIMITS } from "../../constants";
 import { computeThresholds } from "../../helpers";
 
 import type { PluginsDependencies } from "./types";
-import type { Router } from "../../Router";
 import type { Limits, PluginFactory } from "../../types";
 import type {
   DefaultDependencies,
@@ -32,7 +31,6 @@ export class PluginsNamespace<
   readonly #plugins = new Set<PluginFactory<Dependencies>>();
   readonly #unsubscribes = new Set<Unsubscribe>();
 
-  #router!: Router<Dependencies>;
   #deps!: PluginsDependencies<Dependencies>;
   #limits: Limits = DEFAULT_LIMITS;
 
@@ -77,10 +75,6 @@ export class PluginsNamespace<
   // Dependency injection
   // =========================================================================
 
-  setRouter(router: Router<Dependencies>): void {
-    this.#router = router;
-  }
-
   setDependencies(deps: PluginsDependencies<Dependencies>): void {
     this.#deps = deps;
   }
@@ -289,9 +283,7 @@ export class PluginsNamespace<
   }
 
   #startPlugin(pluginFactory: PluginFactory<Dependencies>): Unsubscribe {
-    // Bind getDependency to preserve 'this' context when called from factory
-    // Plugin factories receive full router as part of their public API
-    const appliedPlugin = pluginFactory(this.#router, this.#deps.getDependency);
+    const appliedPlugin = this.#deps.compileFactory(pluginFactory);
 
     PluginsNamespace.validatePlugin(appliedPlugin);
 

package/src/namespaces/PluginsNamespace/types.ts

@@ -1,6 +1,6 @@
 // packages/core/src/namespaces/PluginsNamespace/types.ts
 
-import type { EventMethodMap } from "../../types";
+import type { EventMethodMap, PluginFactory } from "../../types";
 import type {
   DefaultDependencies,
   EventName,
@@ -8,25 +8,15 @@ import type {
   Unsubscribe,
 } from "@real-router/types";
 
-/**
- * Dependencies injected into PluginsNamespace.
- *
- * Note: Plugin factories still receive the router object directly
- * as they need access to various router methods. This interface
- * only covers the internal namespace operations.
- */
 export interface PluginsDependencies<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 > {
-  /** Add event listener for plugin subscription */
   addEventListener: <E extends EventName>(
     eventName: E,
     cb: Plugin[EventMethodMap[E]],
   ) => Unsubscribe;
 
-  /** Check if navigation is possible (for warning about late onStart) */
   canNavigate: () => boolean;
 
-  /** Get dependency value for plugin factory */
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+  compileFactory: (factory: PluginFactory<Dependencies>) => Plugin;
 }

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -8,7 +8,6 @@ import { DEFAULT_LIMITS } from "../../constants";
 import { computeThresholds } from "../../helpers";
 
 import type { RouteLifecycleDependencies } from "./types";
-import type { Router } from "../../Router";
 import type { GuardFnFactory, Limits } from "../../types";
 import type { DefaultDependencies, GuardFn, State } from "@real-router/types";
 
@@ -48,24 +47,9 @@ export class RouteLifecycleNamespace<
   readonly #definitionActivateGuardNames = new Set<string>();
   readonly #definitionDeactivateGuardNames = new Set<string>();
 
-  #router!: Router<Dependencies>;
   #deps!: RouteLifecycleDependencies<Dependencies>;
   #limits: Limits = DEFAULT_LIMITS;
 
-  /**
-   * Injects the router instance during wiring phase.
-   *
-   * @param router - Router instance to use for factory compilation
-   */
-  setRouter(router: Router<Dependencies>): void {
-    this.#router = router;
-  }
-
-  /**
-   * Injects namespace dependencies (getDependency accessor) during wiring phase.
-   *
-   * @param deps - Dependencies object containing getDependency accessor
-   */
   setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void {
     this.#deps = deps;
   }
@@ -268,50 +252,41 @@ export class RouteLifecycleNamespace<
     return [this.#canDeactivateFunctions, this.#canActivateFunctions];
   }
 
-  /**
-   * Synchronously checks the canActivate guard for a route.
-   * Returns `true` if no guard is registered or the guard allows activation.
-   * Returns `false` if the guard blocks, returns a Promise, or throws.
-   *
-   * @param name - Route name to check the guard for
-   * @param toState - Target navigation state
-   * @param fromState - Current state (`undefined` on initial navigation)
-   */
-  checkActivateGuardSync(
-    name: string,
+  canNavigateTo(
+    toDeactivate: string[],
+    toActivate: string[],
     toState: State,
     fromState: State | undefined,
   ): boolean {
-    return this.#checkGuardSync(
-      this.#canActivateFunctions,
-      name,
-      toState,
-      fromState,
-      "checkActivateGuardSync",
-    );
-  }
+    for (const segment of toDeactivate) {
+      if (
+        !this.#checkGuardSync(
+          this.#canDeactivateFunctions,
+          segment,
+          toState,
+          fromState,
+          "canNavigateTo",
+        )
+      ) {
+        return false;
+      }
+    }
 
-  /**
-   * Synchronously checks the canDeactivate guard for a route.
-   * Returns `true` if no guard is registered or the guard allows deactivation.
-   * Returns `false` if the guard blocks, returns a Promise, or throws.
-   *
-   * @param name - Route name to check the guard for
-   * @param toState - Target navigation state
-   * @param fromState - Current state (`undefined` on initial navigation)
-   */
-  checkDeactivateGuardSync(
-    name: string,
-    toState: State,
-    fromState: State | undefined,
-  ): boolean {
-    return this.#checkGuardSync(
-      this.#canDeactivateFunctions,
-      name,
-      toState,
-      fromState,
-      "checkDeactivateGuardSync",
-    );
+    for (const segment of toActivate) {
+      if (
+        !this.#checkGuardSync(
+          this.#canActivateFunctions,
+          segment,
+          toState,
+          fromState,
+          "canNavigateTo",
+        )
+      ) {
+        return false;
+      }
+    }
+
+    return true;
   }
 
   // =========================================================================
@@ -361,8 +336,7 @@ export class RouteLifecycleNamespace<
     this.#registering.add(name);
 
     try {
-      // Lifecycle factories receive full router as part of their public API
-      const fn = factory(this.#router, this.#deps.getDependency);
+      const fn = this.#deps.compileFactory(factory);
 
       if (typeof fn !== "function") {
         throw new TypeError(

package/src/namespaces/RouteLifecycleNamespace/types.ts

@@ -1,17 +1,10 @@
 // packages/core/src/namespaces/RouteLifecycleNamespace/types.ts
 
-import type { DefaultDependencies } from "@real-router/types";
+import type { GuardFnFactory } from "../../types";
+import type { DefaultDependencies, GuardFn } from "@real-router/types";
 
-/**
- * Dependencies injected into RouteLifecycleNamespace.
- *
- * Note: Lifecycle factories still receive the router object directly
- * as they need access to various router methods. This interface
- * only covers the internal namespace operations.
- */
 export interface RouteLifecycleDependencies<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 > {
-  /** Get dependency value for lifecycle factory */
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+  compileFactory: (factory: GuardFnFactory<Dependencies>) => GuardFn;
 }

package/src/wiring/RouterWiringBuilder.ts

@@ -1,14 +1,12 @@
 // packages/core/src/wiring/RouterWiringBuilder.ts
 
 import { getInternals } from "../internals";
+import { resolveOption } from "../namespaces/OptionsNamespace";
 import { validateStateBuilderArgs } from "../namespaces/RoutesNamespace/validators";
 
 import type { EventBusNamespace } from "../namespaces";
 import type { WiringOptions } from "./types";
-import type {
-  NavigationDependencies,
-  TransitionDependencies,
-} from "../namespaces/NavigationNamespace";
+import type { NavigationDependencies } from "../namespaces/NavigationNamespace";
 import type { PluginsDependencies } from "../namespaces/PluginsNamespace";
 import type { RouteLifecycleDependencies } from "../namespaces/RouteLifecycleNamespace";
 import type { RouterLifecycleDependencies } from "../namespaces/RouterLifecycleNamespace";
@@ -56,11 +54,8 @@ export class RouterWiringBuilder<
   }
 
   wireRouteLifecycleDeps(): void {
-    this.routeLifecycle.setRouter(this.router);
-
     const routeLifecycleDeps: RouteLifecycleDependencies<Dependencies> = {
-      getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
-        this.dependenciesStore.dependencies[dependencyName] as Dependencies[K],
+      compileFactory: this.createCompileFactory(),
     };
 
     this.routeLifecycle.setDependencies(routeLifecycleDeps);
@@ -97,14 +92,11 @@ export class RouterWiringBuilder<
   }
 
   wirePluginsDeps(): void {
-    this.plugins.setRouter(this.router);
-
     const pluginsDeps: PluginsDependencies<Dependencies> = {
       addEventListener: (eventName, cb) =>
         this.eventBus.addEventListener(eventName, cb),
       canNavigate: () => this.eventBus.canBeginTransition(),
-      getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
-        this.dependenciesStore.dependencies[dependencyName] as Dependencies[K],
+      compileFactory: this.createCompileFactory(),
     };
 
     this.plugins.setDependencies(pluginsDeps);
@@ -141,47 +133,54 @@ export class RouterWiringBuilder<
       },
       areStatesEqual: (state1, state2, ignoreQueryParams) =>
         this.state.areStatesEqual(state1, state2, ignoreQueryParams),
-      getDependency: (name: string) =>
-        this.dependenciesStore.dependencies[name as keyof Dependencies],
+      resolveDefault: () => {
+        const options = this.options.get();
+
+        return {
+          route: resolveOption(
+            options.defaultRoute,
+            (name: string) =>
+              this.dependenciesStore.dependencies[name as keyof Dependencies],
+          ),
+          params: resolveOption(
+            options.defaultParams,
+            /* v8 ignore next -- @preserve: unreachable unless defaultParams is a callback that calls getDependency */
+            (name: string) =>
+              this.dependenciesStore.dependencies[name as keyof Dependencies],
+          ),
+        };
+      },
       startTransition: (toState, fromState) => {
-        this.eventBus.beginTransition(toState, fromState);
+        this.eventBus.sendNavigate(toState, fromState);
       },
       cancelNavigation: () => {
-        this.eventBus.cancelTransition(
+        this.eventBus.sendCancel(
           this.eventBus.getCurrentToState()!, // eslint-disable-line @typescript-eslint/no-non-null-assertion -- guaranteed set before TRANSITIONING
           this.state.get(),
         );
       },
       sendTransitionDone: (state, fromState, opts) => {
-        this.eventBus.completeTransition(state, fromState, opts);
+        this.eventBus.sendComplete(state, fromState, opts);
       },
-      sendTransitionBlocked: (toState, fromState, error) => {
-        this.eventBus.failTransition(toState, fromState, error);
-      },
-      sendTransitionError: (toState, fromState, error) => {
-        this.eventBus.failTransition(toState, fromState, error);
+      sendTransitionFail: (toState, fromState, error) => {
+        this.eventBus.sendFail(toState, fromState, error);
       },
       emitTransitionError: (toState, fromState, error) => {
-        this.eventBus.emitOrFailTransitionError(toState, fromState, error);
+        this.eventBus.sendFailSafe(toState, fromState, error);
       },
       emitTransitionSuccess: (toState, fromState, opts) => {
         this.eventBus.emitTransitionSuccess(toState, fromState, opts);
       },
-    };
-
-    this.navigation.setDependencies(navigationDeps);
-    this.navigation.setCanNavigate(() => this.eventBus.canBeginTransition());
-
-    const transitionDeps: TransitionDependencies = {
+      canNavigate: () => this.eventBus.canBeginTransition(),
       getLifecycleFunctions: () => this.routeLifecycle.getFunctions(),
       isActive: () => this.router.isActive(),
       isTransitioning: () => this.eventBus.isTransitioning(),
-      clearCanDeactivate: (name) => {
+      clearCanDeactivate: (name: string) => {
         this.routeLifecycle.clearCanDeactivate(name);
       },
     };
 
-    this.navigation.setTransitionDependencies(transitionDeps);
+    this.navigation.setDependencies(navigationDeps);
   }
 
   wireLifecycleDeps(): void {
@@ -195,10 +194,10 @@ export class RouterWiringBuilder<
       },
       matchPath: (path) => this.routes.matchPath(path, this.options.get()),
       completeStart: () => {
-        this.eventBus.completeStart();
+        this.eventBus.sendStarted();
       },
       emitTransitionError: (toState, fromState, error) => {
-        this.eventBus.failTransition(toState, fromState, error);
+        this.eventBus.sendFail(toState, fromState, error);
       },
     };
 
@@ -216,4 +215,22 @@ export class RouterWiringBuilder<
       getUrlParams: (name) => this.routes.getUrlParams(name),
     });
   }
+
+  private createCompileFactory() {
+    const { router, dependenciesStore } = this;
+
+    return <T>(
+      factory: (
+        router: WiringOptions<Dependencies>["router"],
+        getDependency: <K extends keyof Dependencies>(
+          name: K,
+        ) => Dependencies[K],
+      ) => T,
+    ): T =>
+      factory(
+        router,
+        <K extends keyof Dependencies>(name: K) =>
+          dependenciesStore.dependencies[name] as Dependencies[K],
+      );
+  }
 }