@real-router/core 0.34.1 → 0.35.1

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/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts

@@ -6,13 +6,9 @@ import { RouterError } from "../../RouterError";
 import type { RouterLifecycleDependencies } from "./types";
 import type { NavigationOptions, State } from "@real-router/types";
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// CYCLIC DEPENDENCIES
-// ═══════════════════════════════════════════════════════════════════════════════
-// RouterLifecycle → Navigation.navigateToState() (for start transitions)
-//
-// Solution: functional references configured in Router.#setupDependencies()
-// ═══════════════════════════════════════════════════════════════════════════════
+const REPLACE_OPTS: NavigationOptions = { replace: true };
+
+Object.freeze(REPLACE_OPTS);
 
 /**
  * Independent namespace for managing router lifecycle.
@@ -21,17 +17,6 @@ import type { NavigationOptions, State } from "@real-router/types";
  * by RouterFSM in the facade (Router.ts).
  */
 export class RouterLifecycleNamespace {
-  // ═══════════════════════════════════════════════════════════════════════════
-  // Functional references for cyclic dependencies
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  // Dependencies injected via setDependencies (replaces full router reference)
-  #navigateToState!: (
-    toState: State,
-    fromState: State | undefined,
-    opts: NavigationOptions,
-  ) => Promise<State>;
-
   #deps!: RouterLifecycleDependencies;
 
   // =========================================================================
@@ -54,20 +39,6 @@ export class RouterLifecycleNamespace {
   // Dependency injection
   // =========================================================================
 
-  /**
-   * Sets the navigateToState reference (cyclic dependency on NavigationNamespace).
-   * Must be called before using start().
-   */
-  setNavigateToState(
-    fn: (
-      toState: State,
-      fromState: State | undefined,
-      opts: NavigationOptions,
-    ) => Promise<State>,
-  ): void {
-    this.#navigateToState = fn;
-  }
-
   /**
    * Sets dependencies for lifecycle operations.
    * Must be called before using lifecycle methods.
@@ -90,10 +61,6 @@ export class RouterLifecycleNamespace {
     const deps = this.#deps;
     const options = deps.getOptions();
 
-    const startOptions: NavigationOptions = {
-      replace: true,
-    };
-
     const matchedState = deps.matchPath(startPath);
 
     if (!matchedState && !options.allowNotFound) {
@@ -108,25 +75,15 @@ export class RouterLifecycleNamespace {
 
     deps.completeStart();
 
-    let finalState: State;
-
     if (matchedState) {
-      finalState = await this.#navigateToState(
-        matchedState,
-        undefined,
-        startOptions,
-      );
-    } else {
-      const notFoundState = deps.makeNotFoundState(startPath);
-
-      finalState = await this.#navigateToState(
-        notFoundState,
-        undefined,
-        startOptions,
+      return deps.navigate(
+        matchedState.name,
+        matchedState.params,
+        REPLACE_OPTS,
       );
     }
 
-    return finalState;
+    return deps.navigateToNotFound(startPath);
   }
 
   /**

package/src/namespaces/RouterLifecycleNamespace/types.ts

@@ -1,10 +1,20 @@
 // packages/core/src/namespaces/RouterLifecycleNamespace/types.ts
 
-import type { Options, Params, State } from "@real-router/types";
+import type {
+  NavigationOptions,
+  Options,
+  Params,
+  State,
+} from "@real-router/types";
 
 export interface RouterLifecycleDependencies {
   getOptions: () => Options;
-  makeNotFoundState: (path: string) => State;
+  navigate: (
+    name: string,
+    params: Params,
+    opts: NavigationOptions,
+  ) => Promise<State>;
+  navigateToNotFound: (path: string) => State;
   clearState: () => void;
   matchPath: <P extends Params = Params, MP extends Params = Params>(
     path: string,

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -3,7 +3,6 @@
 import { getTypeDescription, validateState } from "type-guards";
 
 import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
-import { constants } from "../../constants";
 import { freezeStateInPlace } from "../../helpers";
 
 import type { StateNamespaceDependencies } from "./types";
@@ -181,20 +180,6 @@ export class StateNamespace {
     return freezeStateInPlace(state);
   }
 
-  /**
-   * Creates a frozen state object for the "not found" route.
-   */
-  makeNotFoundState(path: string): State {
-    return this.makeState<{ path: string }>(
-      constants.UNKNOWN_ROUTE,
-      { path },
-      path,
-      {
-        params: {},
-      },
-    );
-  }
-
   // =========================================================================
   // State Comparison Methods
   // =========================================================================

package/src/transitionPath.ts

@@ -181,7 +181,7 @@ function pointOfDifference(
  * Validation significantly slows down nameToIDs execution.
  * The input should be validated by the function/method that calls nameToIDs.
  */
-function nameToIDs(name: string): string[] {
+export function nameToIDs(name: string): string[] {
   // ===== FAST PATH 1: Empty string (root route) =====
   // Most common in initial navigation
   if (!name) {

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,58 +133,71 @@ 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);
       },
-    };
-
-    this.navigation.setDependencies(navigationDeps);
-
-    const transitionDeps: TransitionDependencies = {
+      emitTransitionSuccess: (toState, fromState, opts) => {
+        this.eventBus.emitTransitionSuccess(toState, fromState, opts);
+      },
+      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 {
     const lifecycleDeps: RouterLifecycleDependencies = {
       getOptions: () => this.options.get(),
-      makeNotFoundState: (path) => this.state.makeNotFoundState(path),
+      navigate: (name, params, opts) =>
+        this.navigation.navigate(name, params, opts),
+      navigateToNotFound: (path) => this.navigation.navigateToNotFound(path),
       clearState: () => {
         this.state.set(undefined);
       },
       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);
       },
     };
 
@@ -211,11 +216,21 @@ export class RouterWiringBuilder<
     });
   }
 
-  wireCyclicDeps(): void {
-    this.navigation.setCanNavigate(() => this.eventBus.canBeginTransition());
-
-    this.lifecycle.setNavigateToState((toState, fromState, opts) =>
-      this.navigation.navigateToState(toState, fromState, opts),
-    );
+  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],
+      );
   }
 }

package/src/wiring/wireRouter.ts

@@ -10,8 +10,8 @@ import type { DefaultDependencies } from "@real-router/types";
  * - `wireLimits()` first: all namespaces must have limits before any other setup
  * - `wireRouteLifecycleDeps()` BEFORE `wireRoutesDeps()`: RoutesNamespace.setDependencies()
  *   registers pending canActivate handlers which require RouteLifecycleNamespace to be ready
- * - `wireCyclicDeps()` LAST: resolves circular references between NavigationNamespace and
- *   RouterLifecycleNamespace (they depend on each other via direct property assignment)
+ * - `wireNavigationDeps()` BEFORE `wireLifecycleDeps()`: lifecycle deps reference
+ *   NavigationNamespace.navigate() which requires navigation deps to be set
  */
 export function wireRouter<Dependencies extends DefaultDependencies>(
   builder: RouterWiringBuilder<Dependencies>,
@@ -23,5 +23,4 @@ export function wireRouter<Dependencies extends DefaultDependencies>(
   builder.wireNavigationDeps();
   builder.wireLifecycleDeps();
   builder.wireStateDeps();
-  builder.wireCyclicDeps();
 }