@real-router/core 0.45.0 → 0.45.1

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -1,405 +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 { errorCodes, constants } from "../../constants";
-import { RouterError } from "../../RouterError";
-import { getTransitionPath, nameToIDs } from "../../transitionPath";
-
-import type { NavigationContext, NavigationDependencies } from "./types";
-import type {
-  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;
-    let fromState: State | undefined;
-    let transitionStarted = false;
-    let controller: AbortController | null = null;
-
-    try {
-      toState = deps.buildNavigateState(name, params);
-
-      if (!toState) {
-        deps.emitTransitionError(
-          undefined,
-          deps.getState(),
-          CACHED_ROUTE_NOT_FOUND_ERROR,
-        );
-        this.lastSyncRejected = true;
-
-        return CACHED_ROUTE_NOT_FOUND_REJECTION;
-      }
-
-      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 { toDeactivate, toActivate, intersection } = getTransitionPath(
-        toState,
-        fromState,
-      );
-
-      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;
-      const emitLeaveApproveCallback = () => {
-        deps.sendLeaveApprove(confirmedToState, fromState);
-      };
-
-      const isCurrentNav = () => this.#navigationId === myId && deps.isActive();
-
-      if (!hasGuards) {
-        // No guards — emitLeaveApprove directly before completeTransition
-        emitLeaveApproveCallback();
-
-        // Reentrant check: subscribeLeave() listener may have called router.navigate()
-        // Same pattern as reentrant check after emitTransitionStart (line 141-143)
-        /* v8 ignore next 3 -- @preserve: reentrant navigate from TRANSITION_LEAVE_APPROVE listener; tested but V8 cannot track the branch through the synchronous callback chain */
-        if (this.#navigationId !== myId) {
-          throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-        }
-      }
-
-      if (hasGuards) {
-        controller = new AbortController();
-        this.#currentController = controller;
-
-        const signal = controller.signal;
-
-        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,
-      );
-
-      return Promise.reject(error as Error);
-    }
-  }
-
-  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",
-        }),
-      );
-    }
-
-    const { route, params } = deps.resolveDefault();
-
-    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",
-      segments,
-    };
-
-    Object.freeze(transitionMeta);
-
-    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;
-  }
-
-  abortCurrentNavigation(): void {
-    this.#currentController?.abort(
-      new RouterError(errorCodes.TRANSITION_CANCELLED),
-    );
-    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(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";

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

@@ -1,100 +0,0 @@
-import { errorCodes, constants } from "../../../constants";
-import { freezeStateInPlace } from "../../../helpers";
-import { RouterError } from "../../../RouterError";
-
-import type { NavigationDependencies, NavigationContext } from "../types";
-import type {
-  NavigationOptions,
-  State,
-  TransitionMeta,
-} from "@real-router/types";
-
-type MutableTransitionMeta = {
-  -readonly [K in keyof TransitionMeta]: TransitionMeta[K];
-};
-
-function buildTransitionMeta(
-  fromState: State | undefined,
-  opts: NavigationOptions,
-  toDeactivate: string[],
-  toActivate: string[],
-  intersection: string,
-): TransitionMeta {
-  const meta: MutableTransitionMeta = {
-    phase: "activating",
-    reason: "success",
-    segments: {
-      deactivated: toDeactivate,
-      activated: toActivate,
-      intersection,
-    },
-  };
-
-  if (fromState?.name !== undefined) {
-    meta.from = fromState.name;
-  }
-
-  if (opts.reload !== undefined) {
-    meta.reload = opts.reload;
-  }
-
-  if (opts.redirected !== undefined) {
-    meta.redirected = opts.redirected;
-  }
-
-  return meta;
-}
-
-function stripSignal({
-  signal: _,
-  ...rest
-}: NavigationOptions): NavigationOptions {
-  return rest;
-}
-
-export function completeTransition(
-  deps: NavigationDependencies,
-  nav: NavigationContext,
-): State {
-  const { toState, fromState, opts, toDeactivate, toActivate, intersection } =
-    nav;
-
-  if (
-    toState.name !== constants.UNKNOWN_ROUTE &&
-    !deps.hasRoute(toState.name)
-  ) {
-    const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
-      routeName: toState.name,
-    });
-
-    deps.sendTransitionFail(toState, fromState, err);
-
-    throw err;
-  }
-
-  if (fromState) {
-    for (const name of toDeactivate) {
-      if (!toActivate.includes(name) && nav.canDeactivateFunctions.has(name)) {
-        deps.clearCanDeactivate(name);
-      }
-    }
-  }
-
-  (toState as { transition: TransitionMeta }).transition = buildTransitionMeta(
-    fromState,
-    opts,
-    toDeactivate,
-    toActivate,
-    intersection,
-  );
-
-  const finalState = freezeStateInPlace(toState);
-
-  deps.setState(finalState);
-
-  const transitionOpts = opts.signal === undefined ? opts : stripSignal(opts);
-
-  deps.sendTransitionDone(finalState, fromState, transitionOpts);
-
-  return finalState;
-}

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

@@ -1,124 +0,0 @@
-// packages/core/src/namespaces/NavigationNamespace/transition/errorHandling.ts
-
-import { errorCodes } from "../../../constants";
-import { RouterError } from "../../../RouterError";
-
-import type { NavigationDependencies } from "../types";
-import type { State } from "@real-router/types";
-
-export 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);
-}
-
-export function handleGuardError(
-  error: unknown,
-  errorCode: string,
-  segment: string,
-): never {
-  if (error instanceof DOMException && error.name === "AbortError") {
-    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-  }
-
-  rethrowAsRouterError(error, errorCode, segment);
-}
-
-/**
- * Error metadata structure for transition errors.
- * Contains information extracted from caught exceptions.
- */
-export interface SyncErrorMetadata {
-  [key: string]: unknown;
-  message?: string;
-  stack?: string | undefined;
-  cause?: unknown;
-  segment?: string;
-}
-
-/**
- * Re-throws a caught error as a RouterError with the given error code.
- * If the error is already a RouterError, sets the code directly.
- * Otherwise wraps it with wrapSyncError metadata.
- */
-export function rethrowAsRouterError(
-  error: unknown,
-  errorCode: string,
-  segment: string,
-): never {
-  if (error instanceof RouterError) {
-    error.setCode(errorCode);
-
-    throw error;
-  }
-
-  throw new RouterError(errorCode, wrapSyncError(error, segment));
-}
-
-const reservedRouterErrorProps = new Set([
-  "code",
-  "segment",
-  "path",
-  "redirect",
-]);
-
-/**
- * Wraps a synchronously thrown value into structured error metadata.
- *
- * This helper extracts useful debugging information from various thrown values:
- * - Error instances: extracts message, stack, and cause (ES2022+)
- * - Plain objects: spreads properties into metadata
- * - Primitives (string, number, etc.): returns minimal metadata
- *
- * @param thrown - The value caught in a try-catch block
- * @param segment - Route segment name (for lifecycle hooks)
- * @returns Structured error metadata for RouterError
- */
-export function wrapSyncError(
-  thrown: unknown,
-  segment: string,
-): SyncErrorMetadata {
-  const base: SyncErrorMetadata = { segment };
-
-  // Handle Error instances - extract all useful properties
-  if (thrown instanceof Error) {
-    return {
-      ...base,
-      message: thrown.message,
-      stack: thrown.stack,
-      // Error.cause requires ES2022+ - safely access if present
-      ...("cause" in thrown &&
-        thrown.cause !== undefined && { cause: thrown.cause }),
-    };
-  }
-
-  // Handle plain objects - spread properties into metadata, filtering reserved props
-  if (thrown && typeof thrown === "object") {
-    const filtered: Record<string, unknown> = {};
-
-    for (const [key, value] of Object.entries(thrown)) {
-      // Issue #39: Skip reserved properties to avoid RouterError constructor TypeError
-      if (!reservedRouterErrorProps.has(key)) {
-        filtered[key] = value;
-      }
-    }
-
-    return { ...base, ...filtered };
-  }
-
-  // Primitives (string, number, boolean, null, undefined, symbol, bigint)
-  // Return base metadata only - the primitive value isn't useful as metadata
-  return base;
-}