@real-router/core 0.34.1 → 0.35.1

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -10,13 +10,9 @@ import {
 } from "./validators";
 import { errorCodes, constants } from "../../constants";
 import { RouterError } from "../../RouterError";
-import { resolveOption } from "../OptionsNamespace";
+import { nameToIDs } from "../../transitionPath";
 
-import type {
-  NavigationDependencies,
-  TransitionDependencies,
-  TransitionOutput,
-} from "./types";
+import type { NavigationDependencies, TransitionOutput } from "./types";
 import type {
   NavigationOptions,
   Params,
@@ -24,20 +20,80 @@ import type {
   TransitionMeta,
 } from "@real-router/types";
 
+const FROZEN_ACTIVATED: string[] = [constants.UNKNOWN_ROUTE];
+
+Object.freeze(FROZEN_ACTIVATED);
+const FROZEN_REPLACE_OPTS: NavigationOptions = { replace: true };
+
+Object.freeze(FROZEN_REPLACE_OPTS);
+
+function forceReplaceFromUnknown(
+  opts: NavigationOptions,
+  fromState: State | undefined,
+): NavigationOptions {
+  return fromState?.name === constants.UNKNOWN_ROUTE && !opts.replace
+    ? { ...opts, replace: true }
+    : opts;
+}
+
+function stripSignal({
+  signal: _,
+  ...rest
+}: NavigationOptions): NavigationOptions {
+  return rest;
+}
+
+function routeTransitionError(
+  deps: NavigationDependencies,
+  error: unknown,
+  toState: State,
+  fromState: State | undefined,
+): void {
+  const routerError = error as RouterError;
+
+  if (
+    routerError.code === errorCodes.TRANSITION_CANCELLED ||
+    routerError.code === errorCodes.ROUTE_NOT_FOUND
+  ) {
+    return;
+  }
+
+  deps.sendTransitionFail(toState, fromState, routerError);
+}
+
+function buildSuccessState(
+  finalState: State,
+  transitionOutput: TransitionOutput["meta"],
+  fromState: State | undefined,
+  opts: NavigationOptions,
+): State {
+  const transitionMeta: TransitionMeta = {
+    phase: transitionOutput.phase,
+    ...(fromState?.name !== undefined && { from: fromState.name }),
+    reason: "success",
+    segments: transitionOutput.segments,
+    ...(opts.reload !== undefined && { reload: opts.reload }),
+    ...(opts.redirected !== undefined && { redirected: opts.redirected }),
+  };
+
+  Object.freeze(transitionMeta.segments.deactivated);
+  Object.freeze(transitionMeta.segments.activated);
+  Object.freeze(transitionMeta.segments);
+  Object.freeze(transitionMeta);
+
+  return {
+    ...finalState,
+    transition: transitionMeta,
+  };
+}
+
 /**
  * Independent namespace for managing navigation.
  *
- * Handles navigate(), navigateToDefault(), navigateToState(), and transition state.
+ * Handles navigate(), navigateToDefault(), navigateToNotFound(), and transition state.
  */
 export class NavigationNamespace {
-  // ═══════════════════════════════════════════════════════════════════════════
-  // Functional reference for cyclic dependency
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  // Dependencies injected via setDependencies (replaces full router reference)
-  #canNavigate!: () => boolean;
   #deps!: NavigationDependencies;
-  #transitionDeps!: TransitionDependencies;
   #currentController: AbortController | null = null;
 
   // =========================================================================
@@ -64,30 +120,10 @@ export class NavigationNamespace {
   // Dependency injection
   // =========================================================================
 
-  /**
-   * Sets the canNavigate check (cyclic dependency on EventBusNamespace).
-   * Must be called before using navigate().
-   */
-  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
   // =========================================================================
@@ -101,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);
     }
 
@@ -130,7 +166,10 @@ export class NavigationNamespace {
 
     const fromState = deps.getState();
 
+    opts = forceReplaceFromUnknown(opts, fromState);
+
     if (
+      fromState &&
       !opts.reload &&
       !opts.force &&
       deps.areStatesEqual(fromState, toState, false)
@@ -142,32 +181,7 @@ export class NavigationNamespace {
       throw err;
     }
 
-    return this.navigateToState(toState, fromState, opts);
-  }
-
-  /**
-   * Internal navigation function that accepts pre-built state.
-   * Used by RouterLifecycleNamespace for start() transitions.
-   */
-  async navigateToState(
-    toState: State,
-    fromState: State | undefined,
-    opts: NavigationOptions,
-  ): Promise<State> {
-    const deps = this.#deps;
-    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();
 
@@ -195,7 +209,7 @@ export class NavigationNamespace {
 
     try {
       const { state: finalState, meta: transitionOutput } = await transition(
-        transitionDeps,
+        deps,
         toState,
         fromState,
         opts,
@@ -206,7 +220,7 @@ export class NavigationNamespace {
         finalState.name === constants.UNKNOWN_ROUTE ||
         deps.hasRoute(finalState.name)
       ) {
-        const stateWithTransition = NavigationNamespace.#buildSuccessState(
+        const stateWithTransition = buildSuccessState(
           finalState,
           transitionOutput,
           fromState,
@@ -216,9 +230,7 @@ export class NavigationNamespace {
         deps.setState(stateWithTransition);
 
         const transitionOpts =
-          opts.signal === undefined
-            ? opts
-            : NavigationNamespace.#stripSignal(opts);
+          opts.signal === undefined ? opts : stripSignal(opts);
 
         deps.sendTransitionDone(stateWithTransition, fromState, transitionOpts);
 
@@ -228,16 +240,16 @@ export class NavigationNamespace {
           routeName: finalState.name,
         });
 
-        deps.sendTransitionError(finalState, fromState, err);
+        deps.sendTransitionFail(finalState, fromState, err);
 
         throw err;
       }
     } catch (error) {
-      this.#routeTransitionError(error, toState, fromState);
+      routeTransitionError(deps, error, toState, fromState);
 
       throw error;
     } finally {
-      controller.abort(); // Cleanup: removes listener on external signal
+      controller.abort();
       if (this.#currentController === controller) {
         this.#currentController = null;
       }
@@ -258,104 +270,77 @@ 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);
   }
 
-  /**
-   * Aborts the current in-flight navigation, if any.
-   */
-  abortCurrentNavigation(): void {
-    this.#currentController?.abort(
-      new RouterError(errorCodes.TRANSITION_CANCELLED),
-    );
-    this.#currentController = null;
-  }
+  navigateToNotFound(path: string): State {
+    this.#abortPreviousNavigation();
 
-  // =========================================================================
-  // Private methods
-  // =========================================================================
+    const fromState = this.#deps.getState();
+    const deactivated: string[] = fromState
+      ? nameToIDs(fromState.name).toReversed()
+      : [];
 
-  /**
-   * Strips the non-serializable `signal` field from NavigationOptions.
-   */
-  static #stripSignal(opts: NavigationOptions): NavigationOptions {
-    // eslint-disable-next-line sonarjs/no-unused-vars
-    const { signal: _, ...rest } = opts;
+    Object.freeze(deactivated);
 
-    return rest;
-  }
+    const segments: TransitionMeta["segments"] = {
+      deactivated,
+      activated: FROZEN_ACTIVATED,
+      intersection: "",
+    };
+
+    Object.freeze(segments);
 
-  /**
-   * Builds the final state with frozen TransitionMeta attached.
-   */
-  static #buildSuccessState(
-    finalState: State,
-    transitionOutput: TransitionOutput["meta"],
-    fromState: State | undefined,
-    opts: NavigationOptions,
-  ): State {
     const transitionMeta: TransitionMeta = {
-      phase: transitionOutput.phase,
-      ...(fromState?.name !== undefined && { from: fromState.name }),
+      phase: "activating",
+      ...(fromState && { from: fromState.name }),
       reason: "success",
-      segments: transitionOutput.segments,
-      ...(opts.reload !== undefined && { reload: opts.reload }),
-      ...(opts.redirected !== undefined && { redirected: opts.redirected }),
+      segments,
     };
 
-    Object.freeze(transitionMeta.segments.deactivated);
-    Object.freeze(transitionMeta.segments.activated);
-    Object.freeze(transitionMeta.segments);
     Object.freeze(transitionMeta);
 
-    return {
-      ...finalState,
+    const state: State = {
+      name: constants.UNKNOWN_ROUTE,
+      params: {} as Params,
+      path,
       transition: transitionMeta,
     };
+
+    Object.freeze(state);
+
+    this.#deps.setState(state);
+    this.#deps.emitTransitionSuccess(state, fromState, FROZEN_REPLACE_OPTS);
+
+    return state;
   }
 
-  /**
-   * Routes a caught transition error to the correct FSM event.
-   */
-  #routeTransitionError(
-    error: unknown,
-    toState: State,
-    fromState: State | undefined,
-  ): void {
-    const routerError = error as RouterError;
-
-    // Already routed: cancel/stop sent CANCEL, sendTransitionError called in try block
-    if (
-      routerError.code === errorCodes.TRANSITION_CANCELLED ||
-      routerError.code === errorCodes.ROUTE_NOT_FOUND
-    ) {
-      return;
-    }
+  abortCurrentNavigation(): void {
+    this.#currentController?.abort(
+      new RouterError(errorCodes.TRANSITION_CANCELLED),
+    );
+    this.#currentController = null;
+  }
 
-    /* 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
-    ) {
-      this.#deps.sendTransitionBlocked(toState, fromState, routerError);
-    } else {
-      this.#deps.sendTransitionError(toState, fromState, routerError);
+  #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,
@@ -90,24 +83,17 @@ export interface NavigationDependencies {
     fromState: State | undefined,
     error: unknown,
   ) => void;
-}
 
-export interface TransitionOutput {
-  state: State;
-  meta: {
-    phase: TransitionPhase;
-    segments: {
-      deactivated: string[];
-      activated: string[];
-      intersection: string;
-    };
-  };
-}
+  /** Emit TRANSITION_SUCCESS event to listeners (without FSM transition) */
+  emitTransitionSuccess: (
+    toState: State,
+    fromState?: State,
+    opts?: NavigationOptions,
+  ) => void;
+
+  /** 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>];
 
@@ -120,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;
 }