@real-router/core 0.56.0 → 0.57.0

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -1,552 +0,0 @@
-import { logger } from "@real-router/logger";
-
-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 { EMPTY_PARAMS, errorCodes, constants } from "../../constants";
-import { RouterError } from "../../RouterError";
-import { getTransitionPath, nameToIDs } from "../../transitionPath";
-
-import type { NavigationContext, NavigationDependencies } from "./types";
-import type { TransitionPath } from "../../transitionPath";
-import type {
-  GuardFn,
-  NavigationOptions,
-  Params,
-  State,
-  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 isSameNavigation(
-  fromState: State | undefined,
-  opts: NavigationOptions,
-  toState: State,
-): boolean {
-  return (
-    !!fromState &&
-    !opts.reload &&
-    !opts.force &&
-    fromState.path === toState.path
-  );
-}
-
-/**
- * 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;
-
-  // =========================================================================
-  // Dependency injection
-  // =========================================================================
-
-  setDependencies(deps: NavigationDependencies): void {
-    this.#deps = deps;
-  }
-
-  // =========================================================================
-  // Instance methods
-  // =========================================================================
-
-  navigate(
-    name: string,
-    params: Params,
-    opts: NavigationOptions,
-  ): Promise<State> {
-    this.lastSyncResolved = false;
-    const deps = this.#deps;
-
-    // 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;
-
-      return CACHED_NOT_STARTED_REJECTION;
-    }
-
-    let toState: State | undefined;
-
-    try {
-      toState = deps.buildNavigateState(name, params);
-    } catch (error) {
-      /* v8 ignore next 3 -- @preserve: reachable only via validator-driven
-         throws from buildNavigateState (validateStateBuilderArgs) — covered
-         in @real-router/validation-plugin's suite, not in core. */
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from user-provided buildNavigateState
-      return Promise.reject(error);
-    }
-
-    if (!toState) {
-      deps.emitTransitionError(
-        undefined,
-        deps.getState(),
-        CACHED_ROUTE_NOT_FOUND_ERROR,
-      );
-      this.lastSyncRejected = true;
-
-      return CACHED_ROUTE_NOT_FOUND_REJECTION;
-    }
-
-    return this.#executeNavigation(toState, opts);
-  }
-
-  /**
-   * Navigate to a fully-built `State` directly, skipping `buildNavigateState`
-   * (forwardState + buildPath + meta lookup). Used by URL plugins after they
-   * have already produced a `State` from a browser-initiated event via
-   * `api.matchPath(url)` — see issue #525.
-   *
-   * Semantics vs. `navigate(name, params, opts)`:
-   * - `forwardState` is NOT re-applied. matchPath already runs it; reapplying
-   *   is redundant in the idempotent case and can race in the dynamic case.
-   * - `buildPath` is NOT re-run. The caller's `state.path` is used as-is —
-   *   so `trailingSlash:"preserve"` matchedState paths flow through unchanged
-   *   (closes #525 Q2). `buildPath` interceptors do NOT run; the URL the
-   *   user navigated to is the source of truth for this code path.
-   * - All other pipeline steps run unchanged: SAME_STATES check, FSM
-   *   transition, guards, `subscribeLeave`, `completeTransition`,
-   *   plugin lifecycle hooks.
-   */
-  navigateToState(state: State, opts: NavigationOptions): Promise<State> {
-    this.lastSyncResolved = false;
-    const deps = this.#deps;
-
-    if (!deps.canNavigate()) {
-      this.lastSyncRejected = true;
-
-      return CACHED_NOT_STARTED_REJECTION;
-    }
-
-    // Reject states whose route no longer exists (e.g. the route tree was
-    // mutated between matchPath and navigateToState). UNKNOWN_ROUTE is
-    // structurally legal — it is the navigateToNotFound output shape.
-    if (state.name !== constants.UNKNOWN_ROUTE && !deps.hasRoute(state.name)) {
-      const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-        routeName: state.name,
-      });
-
-      deps.emitTransitionError(undefined, deps.getState(), err);
-      this.lastSyncRejected = true;
-
-      return Promise.reject(err);
-    }
-
-    // States from `matchPath` are deeply frozen (`freezeStateInPlace`).
-    // `completeTransition` mutates `toState.transition` and `context` is
-    // intentionally extensible for plugin claim writes, so we hand the
-    // pipeline a writable shell — same shape `makeState(skipFreeze=true)`
-    // produces. `params` stays referentially shared (already frozen).
-    // `transition` is omitted so completeTransition can assign it.
-    const writableState = {
-      name: state.name,
-      params: state.params,
-      path: state.path,
-      context: { ...state.context },
-    } as State;
-
-    return this.#executeNavigation(writableState, opts);
-  }
-
-  navigateToDefault(opts: NavigationOptions): Promise<State> {
-    const deps = this.#deps;
-    const options = deps.getOptions();
-
-    if (!options.defaultRoute) {
-      return Promise.reject(
-        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-          routeName: "defaultRoute not configured",
-        }),
-      );
-    }
-
-    let route: string;
-    let params: Params;
-
-    try {
-      ({ route, params } = deps.resolveDefault());
-    } catch (error) {
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from user-provided resolveDefault callback
-      return Promise.reject(error);
-    }
-
-    if (!route) {
-      return Promise.reject(
-        new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-          routeName: "defaultRoute resolved to empty",
-        }),
-      );
-    }
-
-    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()
-      : [];
-
-    Object.freeze(deactivated);
-
-    const segments: TransitionMeta["segments"] = {
-      deactivated,
-      activated: FROZEN_ACTIVATED,
-      intersection: "",
-    };
-
-    Object.freeze(segments);
-
-    const transitionMeta: TransitionMeta = {
-      phase: "activating",
-      ...(fromState && { from: fromState.name }),
-      reason: "success",
-      replace: true,
-      segments,
-    };
-
-    Object.freeze(transitionMeta);
-
-    const state: State = {
-      name: constants.UNKNOWN_ROUTE,
-      params: EMPTY_PARAMS,
-      path,
-      transition: transitionMeta,
-      context: {},
-    };
-
-    Object.freeze(state);
-
-    this.#deps.setState(state);
-    this.#deps.emitTransitionSuccess(state, fromState, FROZEN_REPLACE_OPTS);
-
-    return state;
-  }
-
-  abortCurrentNavigation(): void {
-    this.#currentController?.abort(
-      new RouterError(errorCodes.TRANSITION_CANCELLED),
-    );
-    this.#currentController = null;
-  }
-
-  #executeNavigation(toState: State, opts: NavigationOptions): Promise<State> {
-    const deps = this.#deps;
-    let fromState: State | undefined;
-    let transitionStarted = false;
-    let controller: AbortController | null = null;
-
-    try {
-      fromState = deps.getState();
-      opts = forceReplaceFromUnknown(opts, fromState);
-
-      if (isSameNavigation(fromState, opts, toState)) {
-        deps.emitTransitionError(toState, fromState, CACHED_SAME_STATES_ERROR);
-        this.lastSyncRejected = true;
-
-        return CACHED_SAME_STATES_REJECTION;
-      }
-
-      this.#abortPreviousNavigation(opts.signal);
-
-      const myId = ++this.#navigationId;
-
-      deps.startTransition(toState, fromState);
-      transitionStarted = true;
-
-      // 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 transitionPath = getTransitionPath(toState, fromState);
-      const { toDeactivate, toActivate, intersection } = transitionPath;
-
-      const shouldDeactivate =
-        fromState && !opts.forceDeactivate && toDeactivate.length > 0;
-      const shouldActivate = !isUnknownRoute && toActivate.length > 0;
-      const hasGuards =
-        canDeactivateFunctions.size > 0 || canActivateFunctions.size > 0;
-
-      const confirmedToState = toState;
-
-      if (!hasGuards) {
-        const asyncLeave = this.#handleNoGuardsLeave(
-          confirmedToState,
-          fromState,
-          myId,
-          opts,
-          transitionPath,
-          canDeactivateFunctions,
-        );
-
-        /* v8 ignore start */
-        if (asyncLeave !== undefined) {
-          return asyncLeave;
-        }
-        /* v8 ignore stop */
-      }
-
-      if (hasGuards) {
-        controller = new AbortController();
-        this.#currentController = controller;
-        const isCurrentNav = () =>
-          this.#navigationId === myId && deps.isActive();
-
-        const signal = controller.signal;
-
-        const emitLeaveApproveCallback = (): Promise<void> | undefined => {
-          deps.sendLeaveApprove(confirmedToState, fromState);
-
-          if (deps.hasLeaveListeners()) {
-            return deps.awaitLeaveListeners(
-              confirmedToState,
-              fromState,
-              signal,
-            );
-          }
-
-          return undefined;
-        };
-
-        const guardCompletion = executeGuardPipeline(
-          canDeactivateFunctions,
-          canActivateFunctions,
-          toDeactivate,
-          toActivate,
-          !!shouldDeactivate,
-          shouldActivate,
-          toState,
-          fromState,
-          signal,
-          isCurrentNav,
-          emitLeaveApproveCallback,
-        );
-
-        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);
-      }
-
-      this.lastSyncResolved = true;
-
-      return Promise.resolve(
-        completeTransition(deps, {
-          toState,
-          fromState,
-          opts,
-          toDeactivate,
-          toActivate,
-          intersection,
-          canDeactivateFunctions,
-        }),
-      );
-    } catch (error) {
-      this.#handleNavigateError(
-        error,
-        controller,
-        transitionStarted,
-        toState,
-        fromState,
-      );
-
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- preserve original throw shape from guards or transition pipeline
-      return Promise.reject(error);
-    }
-  }
-
-  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);
-    }
-  }
-
-  #handleNoGuardsLeave(
-    toState: State,
-    fromState: State | undefined,
-    myId: number,
-    opts: NavigationOptions,
-    transitionPath: TransitionPath,
-    canDeactivateFunctions: Map<string, GuardFn>,
-  ): Promise<State> | undefined {
-    const deps = this.#deps;
-
-    deps.sendLeaveApprove(toState, fromState);
-
-    /* v8 ignore start */
-    if (deps.hasLeaveListeners()) {
-      const controller = new AbortController();
-      const leaveResult = deps.awaitLeaveListeners(
-        toState,
-        fromState,
-        controller.signal,
-      );
-
-      if (leaveResult !== undefined) {
-        this.#currentController = controller;
-
-        return this.#finishAsyncNavigation(
-          leaveResult,
-          {
-            toState,
-            fromState,
-            opts,
-            toDeactivate: transitionPath.toDeactivate,
-            toActivate: transitionPath.toActivate,
-            intersection: transitionPath.intersection,
-            canDeactivateFunctions,
-          },
-          controller,
-          myId,
-        );
-      }
-    }
-
-    if (this.#navigationId !== myId) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-    /* v8 ignore stop */
-
-    return undefined;
-  }
-
-  #cleanupController(controller: AbortController): void {
-    controller.abort();
-
-    if (this.#currentController === controller) {
-      this.#currentController = null;
-    }
-  }
-
-  #abortPreviousNavigation(externalSignal?: AbortSignal): 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();
-    }
-
-    if (externalSignal?.aborted) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED, {
-        reason: externalSignal.reason,
-      });
-    }
-  }
-}

package/src/namespaces/NavigationNamespace/constants.ts

@@ -1,55 +0,0 @@
-// 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

package/src/namespaces/NavigationNamespace/index.ts

@@ -1,5 +0,0 @@
-// packages/core/src/namespaces/NavigationNamespace/index.ts
-
-export { NavigationNamespace } from "./NavigationNamespace";
-
-export type { NavigationDependencies } from "./types";