@real-router/core 0.56.0 → 0.57.0

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

@@ -1,108 +0,0 @@
-import { errorCodes, constants } from "../../../constants";
-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 {
-  Object.freeze(toDeactivate);
-  Object.freeze(toActivate);
-
-  const segments = Object.freeze({
-    deactivated: toDeactivate,
-    activated: toActivate,
-    intersection,
-  });
-
-  const meta: MutableTransitionMeta = {
-    phase: "activating",
-    reason: "success",
-    segments,
-  };
-
-  if (fromState?.name !== undefined) {
-    meta.from = fromState.name;
-  }
-
-  if (opts.reload !== undefined) {
-    meta.reload = opts.reload;
-  }
-
-  if (opts.replace !== undefined) {
-    meta.replace = opts.replace;
-  }
-
-  if (opts.redirected !== undefined) {
-    meta.redirected = opts.redirected;
-  }
-
-  return Object.freeze(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 = Object.freeze(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;
-}

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

@@ -1,283 +0,0 @@
-import { handleGuardError } from "./errorHandling";
-import { errorCodes } from "../../../constants";
-import { RouterError } from "../../../RouterError";
-
-import type { GuardFn, State } from "@real-router/types";
-
-async function resolveAsyncGuard(
-  promise: Promise<boolean>,
-  errorCode: string,
-  segment: string,
-): Promise<void> {
-  let result: boolean;
-
-  try {
-    result = await promise;
-  } catch (error: unknown) {
-    handleGuardError(error, errorCode, segment);
-
-    return; // unreachable — handleGuardError returns never
-  }
-
-  if (!result) {
-    throw new RouterError(errorCode, { segment });
-  }
-}
-
-async function resolveRemainingGuards( // NOSONAR -- params kept flat to avoid object allocation on hot path
-  guards: Map<string, GuardFn>,
-  segments: string[],
-  errorCode: string,
-  toState: State,
-  fromState: State | undefined,
-  signal: AbortSignal | undefined,
-  isActive: () => boolean,
-  startIndex: number,
-  firstResult: Promise<boolean>,
-  firstSegment: string,
-): Promise<void> {
-  await resolveAsyncGuard(firstResult, errorCode, firstSegment);
-
-  for (let i = startIndex; i < segments.length; i++) {
-    if (!isActive()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-
-    const segment = segments[i];
-    const guardFn = guards.get(segment);
-
-    if (!guardFn) {
-      continue;
-    }
-
-    let guardResult: boolean | Promise<boolean> = false;
-
-    try {
-      guardResult = guardFn(toState, fromState, signal);
-    } catch (error: unknown) {
-      handleGuardError(error, errorCode, segment);
-    }
-
-    if (guardResult instanceof Promise) {
-      await resolveAsyncGuard(guardResult, errorCode, segment);
-      continue;
-    }
-
-    if (!guardResult) {
-      throw new RouterError(errorCode, { segment });
-    }
-  }
-}
-
-async function finishAsyncPipeline( // NOSONAR
-  deactivateCompletion: Promise<void>,
-  activateGuards: Map<string, GuardFn>,
-  toActivate: string[],
-  shouldActivate: boolean,
-  toState: State,
-  fromState: State | undefined,
-  signal: AbortSignal,
-  isActive: () => boolean,
-  emitLeaveApprove: () => Promise<void> | undefined,
-): Promise<void> {
-  await deactivateCompletion;
-
-  if (!isActive()) {
-    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-  }
-
-  const leaveResult = emitLeaveApprove();
-
-  if (leaveResult !== undefined) {
-    await leaveResult;
-
-    /* v8 ignore next 3 -- @preserve: V8 cannot track cancellation check through async leave continuation after Promise.allSettled */
-    if (!isActive()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-  }
-
-  if (shouldActivate) {
-    const pending = runGuards(
-      activateGuards,
-      toActivate,
-      errorCodes.CANNOT_ACTIVATE,
-      toState,
-      fromState,
-      signal,
-      isActive,
-    );
-
-    if (pending !== undefined) {
-      await pending;
-    }
-
-    if (!isActive()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-  }
-}
-
-export function executeGuardPipeline( // NOSONAR
-  deactivateGuards: Map<string, GuardFn>,
-  activateGuards: Map<string, GuardFn>,
-  toDeactivate: string[],
-  toActivate: string[],
-  shouldDeactivate: boolean,
-  shouldActivate: boolean,
-  toState: State,
-  fromState: State | undefined,
-  signal: AbortSignal,
-  isActive: () => boolean,
-  emitLeaveApprove: () => Promise<void> | undefined,
-): Promise<void> | undefined {
-  if (shouldDeactivate) {
-    const pending = runGuards(
-      deactivateGuards,
-      toDeactivate,
-      errorCodes.CANNOT_DEACTIVATE,
-      toState,
-      fromState,
-      signal,
-      isActive,
-    );
-
-    if (pending !== undefined) {
-      return finishAsyncPipeline(
-        pending,
-        activateGuards,
-        toActivate,
-        shouldActivate,
-        toState,
-        fromState,
-        signal,
-        isActive,
-        emitLeaveApprove,
-      );
-    }
-  }
-
-  if (!isActive()) {
-    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-  }
-
-  const leaveResult = emitLeaveApprove();
-
-  if (leaveResult !== undefined) {
-    return finishAfterAsyncLeave(
-      leaveResult,
-      /* v8 ignore next -- @preserve: false-branch unreachable — navigateToNotFound bypasses guards pipeline */
-      shouldActivate ? activateGuards : undefined,
-      toActivate,
-      toState,
-      fromState,
-      signal,
-      isActive,
-    );
-  }
-
-  if (shouldActivate) {
-    return runGuards(
-      activateGuards,
-      toActivate,
-      errorCodes.CANNOT_ACTIVATE,
-      toState,
-      fromState,
-      signal,
-      isActive,
-    );
-  }
-
-  return undefined;
-}
-
-async function finishAfterAsyncLeave(
-  leaveCompletion: Promise<void>,
-  activateGuards: Map<string, GuardFn> | undefined,
-  toActivate: string[],
-  toState: State,
-  fromState: State | undefined,
-  signal: AbortSignal,
-  isActive: () => boolean,
-): Promise<void> {
-  await leaveCompletion;
-
-  /* v8 ignore next 3 -- @preserve: unreachable after #663 — signal abort
-     mid-leave rejects via settleLeavePromises, so `await leaveCompletion`
-     throws directly instead of completing with a stale isActive() */
-  if (!isActive()) {
-    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-  }
-
-  /* v8 ignore next -- @preserve: false-branch unreachable — navigateToNotFound bypasses guards pipeline */
-  if (activateGuards !== undefined) {
-    const pending = runGuards(
-      activateGuards,
-      toActivate,
-      errorCodes.CANNOT_ACTIVATE,
-      toState,
-      fromState,
-      signal,
-      isActive,
-    );
-
-    if (pending !== undefined) {
-      await pending;
-    }
-
-    if (!isActive()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-  }
-}
-
-function runGuards(
-  guards: Map<string, GuardFn>,
-  segments: string[],
-  errorCode: string,
-  toState: State,
-  fromState: State | undefined,
-  signal: AbortSignal | undefined,
-  isActive: () => boolean,
-): Promise<void> | undefined {
-  for (const [i, segment] of segments.entries()) {
-    if (!isActive()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-
-    const guardFn = guards.get(segment);
-
-    if (!guardFn) {
-      continue;
-    }
-
-    let guardResult: boolean | Promise<boolean> = false;
-
-    try {
-      guardResult = guardFn(toState, fromState, signal);
-    } catch (error: unknown) {
-      handleGuardError(error, errorCode, segment);
-    }
-
-    if (guardResult instanceof Promise) {
-      return resolveRemainingGuards(
-        guards,
-        segments,
-        errorCode,
-        toState,
-        fromState,
-        signal,
-        isActive,
-        i + 1,
-        guardResult,
-        segment,
-      );
-    }
-
-    if (!guardResult) {
-      throw new RouterError(errorCode, { segment });
-    }
-  }
-
-  return undefined;
-}

package/src/namespaces/NavigationNamespace/types.ts

@@ -1,110 +0,0 @@
-// packages/core/src/namespaces/NavigationNamespace/types.ts
-
-import type {
-  GuardFn,
-  NavigationOptions,
-  Options,
-  Params,
-  State,
-} from "@real-router/types";
-
-export interface NavigationContext {
-  toState: State;
-  fromState: State | undefined;
-  opts: NavigationOptions;
-  toDeactivate: string[];
-  toActivate: string[];
-  intersection: string;
-  canDeactivateFunctions: Map<string, GuardFn>;
-}
-
-/**
- * Dependencies injected into NavigationNamespace.
- *
- * 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;
-
-  /** Check if route exists */
-  hasRoute: (name: string) => boolean;
-
-  /** Get current state */
-  getState: () => State | undefined;
-
-  /** Set router state */
-  setState: (state: State) => void;
-
-  /** Build complete navigate state: forwardState + route check + buildPath + makeState in one step */
-  buildNavigateState: (
-    routeName: string,
-    routeParams: Params,
-  ) => State | undefined;
-
-  /** 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;
-
-  /** Cancel navigation if transition is running */
-  cancelNavigation: () => void;
-
-  /** Send COMPLETE event to routerFSM */
-  sendTransitionDone: (
-    state: State,
-    fromState: State | undefined,
-    opts: NavigationOptions,
-  ) => void;
-
-  /** Send FAIL event to routerFSM */
-  sendTransitionFail: (
-    toState: State,
-    fromState: State | undefined,
-    error: unknown,
-  ) => void;
-
-  /** Emit TRANSITION_ERROR event to listeners */
-  emitTransitionError: (
-    toState: State | undefined,
-    fromState: State | undefined,
-    error: unknown,
-  ) => void;
-
-  /** Emit TRANSITION_SUCCESS event to listeners (without FSM transition) */
-  emitTransitionSuccess: (
-    toState: State,
-    fromState?: State,
-    opts?: NavigationOptions,
-  ) => void;
-
-  /** Send LEAVE_APPROVE event to routerFSM and emit to listeners */
-  sendLeaveApprove: (toState: State, fromState: State | undefined) => void;
-
-  /** Check if navigation can begin (router is started) */
-  canNavigate: () => boolean;
-
-  /** Get lifecycle functions (canDeactivate, canActivate maps) */
-  getLifecycleFunctions: () => [Map<string, GuardFn>, Map<string, GuardFn>];
-
-  /** Check if router is active (for cancellation check on stop()) */
-  isActive: () => boolean;
-
-  /** Check if a transition is currently in progress */
-  isTransitioning: () => boolean;
-
-  /** Clear canDeactivate guard for a route */
-  clearCanDeactivate: (name: string) => void;
-
-  /** Check if any leave listeners are registered */
-  hasLeaveListeners: () => boolean;
-
-  /** Call all leave listeners — returns Promise if any are async, undefined otherwise */
-  awaitLeaveListeners: (
-    toState: State,
-    fromState: State | undefined,
-    signal: AbortSignal,
-  ) => Promise<void> | undefined;
-}

package/src/namespaces/OptionsNamespace/OptionsNamespace.ts

@@ -1,28 +0,0 @@
-// packages/core/src/namespaces/OptionsNamespace/OptionsNamespace.ts
-
-import { defaultOptions } from "./constants";
-import { deepFreeze } from "./helpers";
-import { validateOptionsIsObject } from "./validators";
-
-import type { Options } from "@real-router/types";
-
-export class OptionsNamespace {
-  readonly #options: Readonly<Options>;
-
-  constructor(initialOptions: Partial<Options> = {}) {
-    this.#options = deepFreeze({
-      ...defaultOptions,
-      ...initialOptions,
-    });
-  }
-
-  static validateOptionsIsObject(
-    options: unknown,
-  ): asserts options is Record<string, unknown> {
-    validateOptionsIsObject(options);
-  }
-
-  get(): Readonly<Options> {
-    return this.#options;
-  }
-}

package/src/namespaces/OptionsNamespace/constants.ts

@@ -1,19 +0,0 @@
-// packages/core/src/namespaces/OptionsNamespace/constants.ts
-
-import { DEFAULT_QUERY_PARAMS } from "route-tree";
-
-import type { Options } from "@real-router/types";
-
-/**
- * Default options for the router.
- */
-export const defaultOptions: Options = {
-  defaultRoute: "",
-  defaultParams: {},
-  trailingSlash: "preserve",
-  queryParamsMode: "loose",
-  queryParams: DEFAULT_QUERY_PARAMS,
-  urlParamsEncoding: "default",
-  allowNotFound: true,
-  rewritePathOnMatch: true,
-} satisfies Options;