@real-router/core 0.22.0 → 0.23.0

package/src/namespaces/MiddlewareNamespace/validators.ts

@@ -0,0 +1,96 @@
+// packages/core/src/namespaces/MiddlewareNamespace/validators.ts
+
+/**
+ * Static validation functions for MiddlewareNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { getTypeDescription } from "type-guards";
+
+import { DEFAULT_LIMITS } from "../../constants";
+
+import type { MiddlewareFactory } from "../../types";
+import type { DefaultDependencies, Middleware } from "@real-router/types";
+
+/**
+ * Gets a displayable name for a factory function.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+function getFactoryName(factory: Function): string {
+  return factory.name || "anonymous";
+}
+
+/**
+ * Validates useMiddleware arguments - each must be a function.
+ */
+export function validateUseMiddlewareArgs<D extends DefaultDependencies>(
+  middlewares: unknown[],
+): asserts middlewares is MiddlewareFactory<D>[] {
+  for (const [i, middleware] of middlewares.entries()) {
+    if (typeof middleware !== "function") {
+      throw new TypeError(
+        `[router.useMiddleware] Expected middleware factory function at index ${i}, ` +
+          `got ${getTypeDescription(middleware)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that a middleware factory returned a valid middleware function.
+ */
+export function validateMiddleware<D extends DefaultDependencies>(
+  middleware: unknown,
+  factory: MiddlewareFactory<D>,
+): asserts middleware is Middleware {
+  if (typeof middleware !== "function") {
+    throw new TypeError(
+      `[router.useMiddleware] Middleware factory must return a function, ` +
+        `got ${getTypeDescription(middleware)}. ` +
+        `Factory: ${getFactoryName(factory)}`,
+    );
+  }
+}
+
+/**
+ * Validates that no duplicate factories are being registered.
+ */
+export function validateNoDuplicates<D extends DefaultDependencies>(
+  newFactories: MiddlewareFactory<D>[],
+  existingFactories: MiddlewareFactory<D>[],
+): void {
+  const existingSet = new Set(existingFactories);
+
+  for (const factory of newFactories) {
+    if (existingSet.has(factory)) {
+      throw new Error(
+        `[router.useMiddleware] Middleware factory already registered. ` +
+          `To re-register, first unsubscribe the existing middleware. ` +
+          `Factory: ${getFactoryName(factory)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that adding middleware won't exceed the hard limit.
+ */
+export function validateMiddlewareLimit(
+  currentCount: number,
+  newCount: number,
+  maxMiddleware: number = DEFAULT_LIMITS.maxMiddleware,
+): void {
+  if (maxMiddleware === 0) {
+    return;
+  }
+
+  const totalSize = currentCount + newCount;
+
+  if (totalSize > maxMiddleware) {
+    throw new Error(
+      `[router.useMiddleware] Middleware limit exceeded (${maxMiddleware}). ` +
+        `Current: ${currentCount}, Attempting to add: ${newCount}. ` +
+        `This indicates an architectural problem. Consider consolidating middleware.`,
+    );
+  }
+}

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -0,0 +1,308 @@
+// packages/core/src/namespaces/NavigationNamespace/NavigationNamespace.ts
+
+import { logger } from "@real-router/logger";
+
+import { transition } from "./transition";
+import {
+  validateNavigateArgs,
+  validateNavigateToDefaultArgs,
+  validateNavigateToStateArgs,
+  validateNavigationOptions,
+} from "./validators";
+import { errorCodes, constants } from "../../constants";
+import { RouterError } from "../../RouterError";
+import { resolveOption } from "../OptionsNamespace";
+
+import type {
+  NavigationDependencies,
+  TransitionDependencies,
+  TransitionOutput,
+} from "./types";
+import type {
+  NavigationOptions,
+  Params,
+  State,
+  TransitionMeta,
+} from "@real-router/types";
+
+/**
+ * Independent namespace for managing navigation.
+ *
+ * Handles navigate(), navigateToDefault(), navigateToState(), 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;
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // Proxy to functions in validators.ts for separation of concerns
+  // =========================================================================
+
+  static validateNavigateArgs(name: unknown): asserts name is string {
+    validateNavigateArgs(name);
+  }
+
+  static validateNavigateToStateArgs(
+    toState: unknown,
+    fromState: unknown,
+    opts: unknown,
+  ): void {
+    validateNavigateToStateArgs(toState, fromState, opts);
+  }
+
+  static validateNavigateToDefaultArgs(opts: unknown): void {
+    validateNavigateToDefaultArgs(opts);
+  }
+
+  static validateNavigationOptions(
+    opts: unknown,
+    methodName: string,
+  ): asserts opts is NavigationOptions {
+    validateNavigationOptions(opts, methodName);
+  }
+
+  // =========================================================================
+  // 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
+  // =========================================================================
+
+  /**
+   * Navigates to a route by name.
+   * Arguments should be pre-parsed and validated by facade.
+   */
+  async navigate(
+    name: string,
+    params: Params,
+    opts: NavigationOptions,
+  ): Promise<State> {
+    if (!this.#canNavigate()) {
+      throw new RouterError(errorCodes.ROUTER_NOT_STARTED);
+    }
+
+    const deps = this.#deps;
+
+    const result = deps.buildStateWithSegments(name, params);
+
+    if (!result) {
+      const err = new RouterError(errorCodes.ROUTE_NOT_FOUND);
+
+      deps.emitTransitionError(undefined, deps.getState(), err);
+
+      throw err;
+    }
+
+    const { state: route } = result;
+
+    const toState = deps.makeState(
+      route.name,
+      route.params,
+      deps.buildPath(route.name, route.params),
+      {
+        params: route.meta,
+        options: opts,
+      },
+    );
+
+    const fromState = deps.getState();
+
+    if (
+      !opts.reload &&
+      !opts.force &&
+      deps.areStatesEqual(fromState, toState, false)
+    ) {
+      const err = new RouterError(errorCodes.SAME_STATES);
+
+      deps.emitTransitionError(toState, fromState, err);
+
+      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 router.clone() to create isolated instance per request.",
+      );
+      deps.cancelNavigation();
+    }
+
+    deps.startTransition(toState, fromState);
+
+    try {
+      const { state: finalState, meta: transitionOutput } = await transition(
+        transitionDeps,
+        toState,
+        fromState,
+        opts,
+      );
+
+      if (
+        finalState.name === constants.UNKNOWN_ROUTE ||
+        deps.hasRoute(finalState.name)
+      ) {
+        const stateWithTransition = NavigationNamespace.#buildSuccessState(
+          finalState,
+          transitionOutput,
+          fromState,
+        );
+
+        deps.setState(stateWithTransition);
+        deps.sendTransitionDone(stateWithTransition, fromState, opts);
+
+        return stateWithTransition;
+      } else {
+        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+          routeName: finalState.name,
+        });
+
+        deps.sendTransitionError(finalState, fromState, err);
+
+        throw err;
+      }
+    } catch (error) {
+      this.#routeTransitionError(error, toState, fromState);
+
+      throw error;
+    }
+  }
+
+  /**
+   * Navigates to the default route if configured.
+   * Arguments should be pre-parsed and validated by facade.
+   */
+  async 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",
+      });
+    }
+
+    const resolvedRoute = resolveOption(
+      options.defaultRoute,
+      deps.getDependency,
+    );
+
+    if (!resolvedRoute) {
+      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);
+  }
+
+  // =========================================================================
+  // Private methods
+  // =========================================================================
+
+  /**
+   * Builds the final state with frozen TransitionMeta attached.
+   */
+  static #buildSuccessState(
+    finalState: State,
+    transitionOutput: TransitionOutput["meta"],
+    fromState: State | undefined,
+  ): State {
+    const transitionMeta: TransitionMeta = {
+      phase: transitionOutput.phase,
+      ...(fromState?.name !== undefined && { from: fromState.name }),
+      reason: "success",
+      segments: transitionOutput.segments,
+    };
+
+    Object.freeze(transitionMeta.segments.deactivated);
+    Object.freeze(transitionMeta.segments.activated);
+    Object.freeze(transitionMeta.segments);
+    Object.freeze(transitionMeta);
+
+    return {
+      ...finalState,
+      transition: transitionMeta,
+    };
+  }
+
+  /**
+   * 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;
+    }
+
+    if (
+      routerError.code === errorCodes.CANNOT_ACTIVATE ||
+      routerError.code === errorCodes.CANNOT_DEACTIVATE
+    ) {
+      this.#deps.sendTransitionBlocked(toState, fromState, routerError);
+    } else {
+      this.#deps.sendTransitionError(toState, fromState, routerError);
+    }
+  }
+}

package/src/namespaces/NavigationNamespace/index.ts

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

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

@@ -0,0 +1,84 @@
+// packages/real-router/modules/transition/executeLifecycleHooks.ts
+
+import { logger } from "@real-router/logger";
+import { isState } from "type-guards";
+
+import { rethrowAsRouterError } from "./makeError";
+import { mergeStates } from "./mergeStates";
+import { processLifecycleResult } from "./processLifecycleResult";
+import { errorCodes } from "../../../constants";
+import { RouterError } from "../../../RouterError";
+
+import type { State, ActivationFn } from "@real-router/types";
+
+// Helper: execution of the Lifecycle Hooks group
+export const executeLifecycleHooks = async (
+  hooks: Map<string, ActivationFn>,
+  toState: State,
+  fromState: State | undefined,
+  segments: string[],
+  errorCode: string,
+  isCancelled: () => boolean,
+): Promise<State> => {
+  let currentState = toState;
+  const segmentsToProcess = segments.filter((name) => hooks.has(name));
+
+  if (segmentsToProcess.length === 0) {
+    return currentState;
+  }
+
+  for (const segment of segmentsToProcess) {
+    if (isCancelled()) {
+      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+    }
+
+    // Safe cast: segmentsToProcess only contains names that exist in hooks (filtered above)
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed by filter
+    const hookFn = hooks.get(segment)!;
+
+    try {
+      const result = hookFn(currentState, fromState);
+      const newState = await processLifecycleResult(
+        result,
+        currentState,
+        segment,
+      );
+
+      // Optimization: Early return for undefined newState (most common case ~90%+)
+      // This avoids isState() call and subsequent checks
+      if (newState !== currentState && isState(newState)) {
+        // Guards cannot redirect to a different route
+        if (newState.name !== currentState.name) {
+          throw new RouterError(errorCode, {
+            message:
+              "Guards cannot redirect to different route. Use middleware.",
+            attemptedRedirect: {
+              name: newState.name,
+              params: newState.params,
+              path: newState.path,
+            },
+          });
+        }
+
+        // Same route - safe to merge (param modifications, meta changes)
+        const hasChanged =
+          newState.params !== currentState.params ||
+          newState.path !== currentState.path;
+
+        if (hasChanged) {
+          logger.error(
+            "core:transition",
+            "Warning: State mutated during transition",
+            { from: currentState, to: newState },
+          );
+        }
+
+        currentState = mergeStates(newState, currentState);
+      }
+    } catch (error: unknown) {
+      rethrowAsRouterError(error, errorCode, segment);
+    }
+  }
+
+  return currentState;
+};

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

@@ -0,0 +1,56 @@
+// packages/real-router/modules/transition/executeMiddleware.ts
+
+import { logger } from "@real-router/logger";
+import { isState } from "type-guards";
+
+import { rethrowAsRouterError } from "./makeError";
+import { mergeStates } from "./mergeStates";
+import { processLifecycleResult } from "./processLifecycleResult";
+import { errorCodes } from "../../../constants";
+import { RouterError } from "../../../RouterError";
+
+import type { State, ActivationFn } from "@real-router/types";
+
+// Helper: processing middleware
+export const executeMiddleware = async (
+  middlewareFunctions: ActivationFn[],
+  toState: State,
+  fromState: State | undefined,
+  isCancelled: () => boolean,
+): Promise<State> => {
+  let currentState = toState;
+
+  for (const middlewareFn of middlewareFunctions) {
+    if (isCancelled()) {
+      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+    }
+
+    try {
+      const result = middlewareFn(currentState, fromState);
+      const newState = await processLifecycleResult(result, currentState);
+
+      // Optimization: Early return for undefined newState (most common case ~90%+)
+      // This avoids isState() call and subsequent checks
+      if (newState !== currentState && isState(newState)) {
+        const hasChanged =
+          newState.name !== currentState.name ||
+          newState.params !== currentState.params ||
+          newState.path !== currentState.path;
+
+        if (hasChanged) {
+          logger.error(
+            "core:middleware",
+            "Warning: State mutated during middleware execution",
+            { from: currentState, to: newState },
+          );
+        }
+
+        currentState = mergeStates(newState, currentState);
+      }
+    } catch (error: unknown) {
+      rethrowAsRouterError(error, errorCodes.TRANSITION_ERR);
+    }
+  }
+
+  return currentState;
+};

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

@@ -0,0 +1,107 @@
+// packages/real-router/modules/transition/index.ts
+
+import { executeLifecycleHooks } from "./executeLifecycleHooks";
+import { executeMiddleware } from "./executeMiddleware";
+import { constants, errorCodes } from "../../../constants";
+import { RouterError } from "../../../RouterError";
+import { getTransitionPath, nameToIDs } from "../../../transitionPath";
+
+import type { TransitionDependencies, TransitionOutput } from "../types";
+import type { NavigationOptions, State } from "@real-router/types";
+
+export async function transition(
+  deps: TransitionDependencies,
+  toState: State,
+  fromState: State | undefined,
+  opts: NavigationOptions,
+): Promise<TransitionOutput> {
+  // We're caching the necessary data
+  const [canDeactivateFunctions, canActivateFunctions] =
+    deps.getLifecycleFunctions();
+  const middlewareFunctions = deps.getMiddlewareFunctions();
+  const isUnknownRoute = toState.name === constants.UNKNOWN_ROUTE;
+
+  // State management functions
+  // Issue #36: Check both explicit cancellation AND router shutdown
+  const isCancelled = () => !deps.isActive();
+
+  const { toDeactivate, toActivate, intersection } = getTransitionPath(
+    toState,
+    fromState,
+  );
+
+  // determine the necessary steps
+  const shouldDeactivate =
+    fromState && !opts.forceDeactivate && toDeactivate.length > 0;
+  const shouldActivate = !isUnknownRoute && toActivate.length > 0;
+  const shouldRunMiddleware = middlewareFunctions.length > 0;
+
+  let currentState = toState;
+
+  if (shouldDeactivate) {
+    currentState = await executeLifecycleHooks(
+      canDeactivateFunctions,
+      toState,
+      fromState,
+      toDeactivate,
+      errorCodes.CANNOT_DEACTIVATE,
+      isCancelled,
+    );
+  }
+
+  if (isCancelled()) {
+    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+  }
+
+  if (shouldActivate) {
+    currentState = await executeLifecycleHooks(
+      canActivateFunctions,
+      currentState,
+      fromState,
+      toActivate,
+      errorCodes.CANNOT_ACTIVATE,
+      isCancelled,
+    );
+  }
+
+  if (isCancelled()) {
+    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+  }
+
+  if (shouldRunMiddleware) {
+    currentState = await executeMiddleware(
+      middlewareFunctions,
+      currentState,
+      fromState,
+      isCancelled,
+    );
+  }
+
+  if (isCancelled()) {
+    throw new RouterError(errorCodes.TRANSITION_CANCELLED);
+  }
+
+  // Automatic cleaning of inactive segments
+  if (fromState) {
+    const activeSegments = nameToIDs(toState.name);
+    const previousActiveSegments = nameToIDs(fromState.name);
+
+    for (const name of previousActiveSegments) {
+      if (!activeSegments.includes(name) && canDeactivateFunctions.has(name)) {
+        deps.clearCanDeactivate(name);
+      }
+    }
+  }
+
+  return {
+    state: currentState,
+    meta: {
+      phase: "middleware",
+      segments: {
+        deactivated: toDeactivate,
+        activated: toActivate,
+        intersection,
+      },
+    },
+  };
+}

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

@@ -0,0 +1,37 @@
+// packages/real-router/modules/transition/makeError.ts
+
+import { wrapSyncError } from "./wrapSyncError";
+import { RouterError } from "../../../RouterError";
+
+// Helper: Creating an error with code
+export const makeError = (
+  code: string,
+  err?: RouterError,
+): RouterError | undefined => {
+  if (!err) {
+    return undefined;
+  }
+
+  err.setCode(code);
+
+  return err;
+};
+
+/**
+ * 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));
+}