@real-router/core 0.36.1 → 0.37.0

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -23,6 +23,9 @@ export class EventBusNamespace {
   readonly #emitter: EventEmitter<RouterEventMap>;
 
   #currentToState: State | undefined;
+  #pendingToState: State | undefined;
+  #pendingFromState: State | undefined;
+  #pendingError: unknown;
 
   constructor(options: EventBusOptions) {
     this.#fsm = options.routerFSM;
@@ -90,7 +93,9 @@ export class EventBusNamespace {
 
   sendNavigate(toState: State, fromState?: State): void {
     this.#currentToState = toState;
-    this.#fsm.send(routerEvents.NAVIGATE, { toState, fromState });
+    // Bypass FSM dispatch — forceState + direct emit (no action lookup, no rest params)
+    this.#fsm.forceState(routerStates.TRANSITIONING);
+    this.emitTransitionStart(toState, fromState);
   }
 
   sendComplete(
@@ -98,15 +103,11 @@ export class EventBusNamespace {
     fromState?: State,
     opts: NavigationOptions = {},
   ): void {
-    const prev = this.#currentToState;
-
-    this.#fsm.send(routerEvents.COMPLETE, {
-      state,
-      fromState,
-      opts,
-    });
+    // Bypass FSM dispatch — forceState + direct emit
+    this.#fsm.forceState(routerStates.READY);
+    this.emitTransitionSuccess(state, fromState, opts);
 
-    if (this.#currentToState === prev) {
+    if (this.#currentToState === state) {
       this.#currentToState = undefined;
     }
   }
@@ -114,7 +115,10 @@ export class EventBusNamespace {
   sendFail(toState?: State, fromState?: State, error?: unknown): void {
     const prev = this.#currentToState;
 
-    this.#fsm.send(routerEvents.FAIL, { toState, fromState, error });
+    this.#pendingToState = toState;
+    this.#pendingFromState = fromState;
+    this.#pendingError = error;
+    this.#fsm.send(routerEvents.FAIL);
 
     if (this.#currentToState === prev) {
       this.#currentToState = undefined;
@@ -132,7 +136,9 @@ export class EventBusNamespace {
   sendCancel(toState: State, fromState?: State): void {
     const prev = this.#currentToState;
 
-    this.#fsm.send(routerEvents.CANCEL, { toState, fromState });
+    this.#pendingToState = toState;
+    this.#pendingFromState = fromState;
+    this.#fsm.send(routerEvents.CANCEL);
 
     if (this.#currentToState === prev) {
       this.#currentToState = undefined;
@@ -212,6 +218,14 @@ export class EventBusNamespace {
     this.sendCancel(this.#currentToState!, fromState); // eslint-disable-line @typescript-eslint/no-non-null-assertion -- guaranteed set before TRANSITIONING
   }
 
+  #emitPendingError(): void {
+    this.emitTransitionError(
+      this.#pendingToState,
+      this.#pendingFromState,
+      this.#pendingError as RouterError | undefined,
+    );
+  }
+
   #setupFSMActions(): void {
     const fsm = this.#fsm;
 
@@ -223,40 +237,29 @@ export class EventBusNamespace {
       this.emitRouterStop();
     });
 
-    fsm.on(routerStates.READY, routerEvents.NAVIGATE, (params) => {
-      this.emitTransitionStart(params.toState, params.fromState);
-    });
+    // NAVIGATE and COMPLETE actions bypassed — sendNavigate/sendComplete
+    // use fsm.forceState() + direct emit for zero-allocation hot path.
+    fsm.on(routerStates.TRANSITIONING, routerEvents.CANCEL, () => {
+      const toState = this.#pendingToState;
 
-    fsm.on(routerStates.TRANSITIONING, routerEvents.COMPLETE, (params) => {
-      this.emitTransitionSuccess(params.state, params.fromState, params.opts);
-    });
+      /* v8 ignore next -- @preserve: #pendingToState guaranteed set by sendCancel before send() */
+      if (toState === undefined) {
+        return;
+      }
 
-    fsm.on(routerStates.TRANSITIONING, routerEvents.CANCEL, (params) => {
-      this.emitTransitionCancel(params.toState, params.fromState);
+      this.emitTransitionCancel(toState, this.#pendingFromState);
     });
 
-    fsm.on(routerStates.STARTING, routerEvents.FAIL, (params) => {
-      this.emitTransitionError(
-        params.toState,
-        params.fromState,
-        params.error as RouterError | undefined,
-      );
+    fsm.on(routerStates.STARTING, routerEvents.FAIL, () => {
+      this.#emitPendingError();
     });
 
-    fsm.on(routerStates.READY, routerEvents.FAIL, (params) => {
-      this.emitTransitionError(
-        params.toState,
-        params.fromState,
-        params.error as RouterError | undefined,
-      );
+    fsm.on(routerStates.READY, routerEvents.FAIL, () => {
+      this.#emitPendingError();
     });
 
-    fsm.on(routerStates.TRANSITIONING, routerEvents.FAIL, (params) => {
-      this.emitTransitionError(
-        params.toState,
-        params.fromState,
-        params.error as RouterError | undefined,
-      );
+    fsm.on(routerStates.TRANSITIONING, routerEvents.FAIL, () => {
+      this.#emitPendingError();
     });
   }
 }

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -1,8 +1,15 @@
-// packages/core/src/namespaces/NavigationNamespace/NavigationNamespace.ts
-
 import { logger } from "@real-router/logger";
 
-import { transition } from "./transition";
+import {
+  CACHED_NOT_STARTED_REJECTION,
+  CACHED_ROUTE_NOT_FOUND_ERROR,
+  CACHED_ROUTE_NOT_FOUND_REJECTION,
+  CACHED_SAME_STATES_ERROR,
+  CACHED_SAME_STATES_REJECTION,
+} from "./constants";
+import { completeTransition } from "./transition/completeTransition";
+import { routeTransitionError } from "./transition/errorHandling";
+import { executeGuardPipeline } from "./transition/guardPhase";
 import {
   validateNavigateArgs,
   validateNavigateToDefaultArgs,
@@ -10,9 +17,9 @@ import {
 } from "./validators";
 import { errorCodes, constants } from "../../constants";
 import { RouterError } from "../../RouterError";
-import { nameToIDs } from "../../transitionPath";
+import { getTransitionPath, nameToIDs } from "../../transitionPath";
 
-import type { NavigationDependencies, TransitionOutput } from "./types";
+import type { NavigationContext, NavigationDependencies } from "./types";
 import type {
   NavigationOptions,
   Params,
@@ -36,65 +43,35 @@ function forceReplaceFromUnknown(
     : 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"],
+function isSameNavigation(
   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,
-  };
+  toState: State,
+  areStatesEqual: (a: State, b: State, ignoreQuery: boolean) => boolean,
+): boolean {
+  return (
+    !!fromState &&
+    !opts.reload &&
+    !opts.force &&
+    areStatesEqual(fromState, toState, false)
+  );
 }
 
 /**
  * Independent namespace for managing navigation.
  *
  * Handles navigate(), navigateToDefault(), navigateToNotFound(), and transition state.
+ *
+ * Performance: navigate() uses optimistic sync execution — guards run synchronously
+ * until one returns a Promise, then switches to async. This eliminates Promise/AbortController
+ * overhead for the common case (no guards or sync guards).
  */
 export class NavigationNamespace {
+  lastSyncResolved = false;
+  lastSyncRejected = false;
   #deps!: NavigationDependencies;
   #currentController: AbortController | null = null;
+  #navigationId = 0;
 
   // =========================================================================
   // Static validation methods (called by facade before instance methods)
@@ -128,154 +105,176 @@ export class NavigationNamespace {
   // Instance methods
   // =========================================================================
 
-  /**
-   * Navigates to a route by name.
-   * Arguments should be pre-parsed and validated by facade.
-   */
-  async navigate(
+  navigate(
     name: string,
     params: Params,
     opts: NavigationOptions,
   ): Promise<State> {
-    if (!this.#deps.canNavigate()) {
-      throw new RouterError(errorCodes.ROUTER_NOT_STARTED);
-    }
-
+    this.lastSyncResolved = false;
     const deps = this.#deps;
 
-    const result = deps.buildStateWithSegments(name, params);
-
-    if (!result) {
-      const err = new RouterError(errorCodes.ROUTE_NOT_FOUND);
+    // Fast-path sync rejections: cached error + cached Promise.reject
+    // No allocations, no throw/catch overhead, facade skips .catch() suppression
+    if (!deps.canNavigate()) {
+      this.lastSyncRejected = true;
 
-      deps.emitTransitionError(undefined, deps.getState(), err);
-
-      throw err;
+      return CACHED_NOT_STARTED_REJECTION;
     }
 
-    const { state: route } = result;
-
-    const toState = deps.makeState(
-      route.name,
-      route.params,
-      deps.buildPath(route.name, route.params),
-      {
-        params: route.meta,
-      },
-    );
-
-    const fromState = deps.getState();
+    let toState: State | undefined;
+    let fromState: State | undefined;
+    let transitionStarted = false;
+    let controller: AbortController | null = null;
 
-    opts = forceReplaceFromUnknown(opts, fromState);
-
-    if (
-      fromState &&
-      !opts.reload &&
-      !opts.force &&
-      deps.areStatesEqual(fromState, toState, false)
-    ) {
-      const err = new RouterError(errorCodes.SAME_STATES);
+    try {
+      toState = deps.buildNavigateState(name, params);
 
-      deps.emitTransitionError(toState, fromState, err);
+      if (!toState) {
+        deps.emitTransitionError(
+          undefined,
+          deps.getState(),
+          CACHED_ROUTE_NOT_FOUND_ERROR,
+        );
+        this.lastSyncRejected = true;
 
-      throw err;
-    }
+        return CACHED_ROUTE_NOT_FOUND_REJECTION;
+      }
 
-    this.#abortPreviousNavigation();
+      fromState = deps.getState();
+      opts = forceReplaceFromUnknown(opts, fromState);
 
-    const controller = new AbortController();
+      if (isSameNavigation(fromState, opts, toState, deps.areStatesEqual)) {
+        deps.emitTransitionError(toState, fromState, CACHED_SAME_STATES_ERROR);
+        this.lastSyncRejected = true;
 
-    this.#currentController = controller;
+        return CACHED_SAME_STATES_REJECTION;
+      }
 
-    if (opts.signal) {
-      if (opts.signal.aborted) {
-        this.#currentController = null;
+      this.#abortPreviousNavigation();
 
+      if (opts.signal?.aborted) {
         throw new RouterError(errorCodes.TRANSITION_CANCELLED, {
           reason: opts.signal.reason,
         });
       }
 
-      opts.signal.addEventListener(
-        "abort",
-        () => {
-          controller.abort(opts.signal?.reason);
-        },
-        { once: true, signal: controller.signal },
-      );
-    }
+      const myId = ++this.#navigationId;
 
-    deps.startTransition(toState, fromState);
+      deps.startTransition(toState, fromState);
+      transitionStarted = true;
 
-    try {
-      const { state: finalState, meta: transitionOutput } = await transition(
-        deps,
+      // Reentrant navigate from TRANSITION_START listener superseded this navigation
+      if (this.#navigationId !== myId) {
+        throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+      }
+
+      const [canDeactivateFunctions, canActivateFunctions] =
+        deps.getLifecycleFunctions();
+      const isUnknownRoute = toState.name === constants.UNKNOWN_ROUTE;
+
+      const { toDeactivate, toActivate, intersection } = getTransitionPath(
         toState,
         fromState,
-        opts,
-        controller.signal,
+        opts.reload,
       );
 
-      if (
-        finalState.name === constants.UNKNOWN_ROUTE ||
-        deps.hasRoute(finalState.name)
-      ) {
-        const stateWithTransition = buildSuccessState(
-          finalState,
-          transitionOutput,
+      const shouldDeactivate =
+        fromState && !opts.forceDeactivate && toDeactivate.length > 0;
+      const shouldActivate = !isUnknownRoute && toActivate.length > 0;
+      const hasGuards =
+        canDeactivateFunctions.size > 0 || canActivateFunctions.size > 0;
+
+      if (hasGuards) {
+        controller = new AbortController();
+        this.#currentController = controller;
+
+        const signal = controller.signal;
+        const isCurrentNav = () =>
+          this.#navigationId === myId && deps.isActive();
+
+        const guardCompletion = executeGuardPipeline(
+          canDeactivateFunctions,
+          canActivateFunctions,
+          toDeactivate,
+          toActivate,
+          !!shouldDeactivate,
+          shouldActivate,
+          toState,
           fromState,
-          opts,
+          signal,
+          isCurrentNav,
         );
 
-        deps.setState(stateWithTransition);
-
-        const transitionOpts =
-          opts.signal === undefined ? opts : stripSignal(opts);
-
-        deps.sendTransitionDone(stateWithTransition, fromState, transitionOpts);
-
-        return stateWithTransition;
-      } else {
-        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-          routeName: finalState.name,
-        });
+        if (guardCompletion !== undefined) {
+          return this.#finishAsyncNavigation(
+            guardCompletion,
+            {
+              toState,
+              fromState,
+              opts,
+              toDeactivate,
+              toActivate,
+              intersection,
+              canDeactivateFunctions,
+            },
+            controller,
+            myId,
+          );
+        }
+
+        if (!isCurrentNav()) {
+          throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+        }
+
+        this.#cleanupController(controller);
+      }
 
-        deps.sendTransitionFail(finalState, fromState, err);
+      this.lastSyncResolved = true;
 
-        throw err;
-      }
+      return Promise.resolve(
+        completeTransition(deps, {
+          toState,
+          fromState,
+          opts,
+          toDeactivate,
+          toActivate,
+          intersection,
+          canDeactivateFunctions,
+        }),
+      );
     } catch (error) {
-      routeTransitionError(deps, error, toState, fromState);
+      this.#handleNavigateError(
+        error,
+        controller,
+        transitionStarted,
+        toState,
+        fromState,
+      );
 
-      throw error;
-    } finally {
-      controller.abort();
-      if (this.#currentController === controller) {
-        this.#currentController = null;
-      }
+      return Promise.reject(error as Error);
     }
   }
 
-  /**
-   * Navigates to the default route if configured.
-   * Arguments should be pre-parsed and validated by facade.
-   */
-  async navigateToDefault(opts: NavigationOptions): Promise<State> {
+  navigateToDefault(opts: NavigationOptions): Promise<State> {
     const deps = this.#deps;
     const options = deps.getOptions();
 
     if (!options.defaultRoute) {
-      throw new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-        routeName: "defaultRoute not configured",
-      });
+      return Promise.reject(
+        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+          routeName: "defaultRoute not configured",
+        }),
+      );
     }
 
     const { route, params } = deps.resolveDefault();
 
     if (!route) {
-      throw new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-        routeName: "defaultRoute resolved to empty",
-      });
+      return Promise.reject(
+        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+          routeName: "defaultRoute resolved to empty",
+        }),
+      );
     }
 
     return this.navigate(route, params, opts);
@@ -330,6 +329,75 @@ export class NavigationNamespace {
     this.#currentController = null;
   }
 
+  async #finishAsyncNavigation(
+    guardCompletion: Promise<void>,
+    nav: NavigationContext,
+    controller: AbortController,
+    myId: number,
+  ): Promise<State> {
+    const deps = this.#deps;
+    const isActive = () =>
+      this.#navigationId === myId &&
+      !controller.signal.aborted &&
+      deps.isActive();
+
+    try {
+      if (nav.opts.signal) {
+        if (nav.opts.signal.aborted) {
+          throw new RouterError(errorCodes.TRANSITION_CANCELLED, {
+            reason: nav.opts.signal.reason,
+          });
+        }
+
+        nav.opts.signal.addEventListener(
+          "abort",
+          () => {
+            controller.abort(nav.opts.signal?.reason);
+          },
+          { once: true, signal: controller.signal },
+        );
+      }
+
+      await guardCompletion;
+
+      if (!isActive()) {
+        throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+      }
+
+      return completeTransition(deps, nav);
+    } catch (error) {
+      routeTransitionError(deps, error, nav.toState, nav.fromState);
+
+      throw error;
+    } finally {
+      this.#cleanupController(controller);
+    }
+  }
+
+  #handleNavigateError(
+    error: unknown,
+    controller: AbortController | null,
+    transitionStarted: boolean,
+    toState: State | undefined,
+    fromState: State | undefined,
+  ): void {
+    if (controller) {
+      this.#cleanupController(controller);
+    }
+
+    if (transitionStarted && toState) {
+      routeTransitionError(this.#deps, error, toState, fromState);
+    }
+  }
+
+  #cleanupController(controller: AbortController): void {
+    controller.abort();
+
+    if (this.#currentController === controller) {
+      this.#currentController = null;
+    }
+  }
+
   #abortPreviousNavigation(): void {
     if (this.#deps.isTransitioning()) {
       logger.warn(

package/src/namespaces/NavigationNamespace/constants.ts

@@ -0,0 +1,55 @@
+// packages/core/src/namespaces/NavigationNamespace/constants.ts
+
+import { errorCodes } from "../../constants";
+import { RouterError } from "../../RouterError";
+
+import type { State } from "@real-router/types";
+
+// =============================================================================
+// Cached Errors & Rejected Promises (Performance Optimization)
+// =============================================================================
+// Pre-create error instances and rejected promises for sync error paths
+// in navigate(). Eliminates per-call allocations:
+//   - new RouterError() — object + stack trace capture (~500ns-2μs)
+//   - Promise.reject()  — promise allocation
+//   - .catch(handler)   — derived promise from suppression
+//
+// Trade-off: All error instances share the same stack trace (points here).
+// This is acceptable because:
+// 1. These errors indicate expected conditions, not internal bugs
+// 2. Error code and message are sufficient for debugging
+// 3. The facade skips .catch() suppression for cached promises (zero alloc)
+// =============================================================================
+
+export const CACHED_NOT_STARTED_ERROR = new RouterError(
+  errorCodes.ROUTER_NOT_STARTED,
+);
+
+export const CACHED_ROUTE_NOT_FOUND_ERROR = new RouterError(
+  errorCodes.ROUTE_NOT_FOUND,
+);
+
+export const CACHED_SAME_STATES_ERROR = new RouterError(errorCodes.SAME_STATES);
+
+// Pre-suppressed rejected promises — .catch() at module load prevents
+// unhandled rejection warnings. The facade skips additional .catch() calls
+// via the lastSyncRejected flag (zero derived-promise allocation).
+export const CACHED_NOT_STARTED_REJECTION: Promise<State> = Promise.reject(
+  CACHED_NOT_STARTED_ERROR,
+);
+
+export const CACHED_ROUTE_NOT_FOUND_REJECTION: Promise<State> = Promise.reject(
+  CACHED_ROUTE_NOT_FOUND_ERROR,
+);
+
+export const CACHED_SAME_STATES_REJECTION: Promise<State> = Promise.reject(
+  CACHED_SAME_STATES_ERROR,
+);
+
+// Suppress once at module load — prevents unhandled rejection events.
+// Subsequent .catch() / await by user code still works correctly:
+// a rejected promise stays rejected forever, each .catch() creates
+// its own derived promise and fires its handler.
+CACHED_NOT_STARTED_REJECTION.catch(() => {}); // NOSONAR -- intentional suppression, not a promise chain
+CACHED_ROUTE_NOT_FOUND_REJECTION.catch(() => {}); // NOSONAR
+CACHED_SAME_STATES_REJECTION.catch(() => {}); // NOSONAR