@real-router/core 0.45.1 → 0.45.3

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -0,0 +1,377 @@
+// packages/core/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts
+
+import { DEFAULT_LIMITS } from "../../constants";
+
+import type { RouteLifecycleDependencies } from "./types";
+import type { GuardFnFactory, Limits } from "../../types";
+import type { RouterValidator } from "../../types/RouterValidator";
+import type { DefaultDependencies, GuardFn, State } from "@real-router/types";
+
+/**
+ * Converts a boolean value to a guard function factory.
+ * Used for the shorthand syntax where true/false is passed instead of a function.
+ */
+function booleanToFactory<Dependencies extends DefaultDependencies>(
+  value: boolean,
+): GuardFnFactory<Dependencies> {
+  const guardFn: GuardFn = () => value;
+
+  return () => guardFn;
+}
+
+/**
+ * Independent namespace for managing route lifecycle handlers.
+ *
+ * Static methods handle input validation (called by facade).
+ * Instance methods handle state-dependent validation, storage and business logic.
+ */
+export class RouteLifecycleNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly #canDeactivateFactories = new Map<
+    string,
+    GuardFnFactory<Dependencies>
+  >();
+  readonly #canActivateFactories = new Map<
+    string,
+    GuardFnFactory<Dependencies>
+  >();
+  readonly #canDeactivateFunctions = new Map<string, GuardFn>();
+  readonly #canActivateFunctions = new Map<string, GuardFn>();
+  // Cached tuple — Maps never change reference, so this is stable
+  readonly #functionsTuple: [Map<string, GuardFn>, Map<string, GuardFn>] = [
+    this.#canDeactivateFunctions,
+    this.#canActivateFunctions,
+  ];
+
+  readonly #registering = new Set<string>();
+  readonly #definitionActivateGuardNames = new Set<string>();
+  readonly #definitionDeactivateGuardNames = new Set<string>();
+
+  #deps!: RouteLifecycleDependencies<Dependencies>;
+  #limits: Limits = DEFAULT_LIMITS;
+  #getValidator: (() => RouterValidator | null) | null = null;
+
+  setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void {
+    this.#deps = deps;
+  }
+
+  /**
+   * Updates handler registration limits (max lifecycle handlers threshold).
+   *
+   * @param limits - Limits configuration with maxLifecycleHandlers
+   */
+  setLimits(limits: Limits): void {
+    this.#limits = limits;
+    // eslint-disable-next-line sonarjs/void-use -- @preserve: Wave 3 validator reads limits via RouterInternals; void suppresses TS6133 until then
+    void this.#limits;
+  }
+
+  setValidatorGetter(getter: () => RouterValidator | null): void {
+    this.#getValidator = getter;
+  }
+
+  getHandlerCount(type: "activate" | "deactivate"): number {
+    return type === "activate"
+      ? this.#canActivateFactories.size
+      : this.#canDeactivateFactories.size;
+  }
+
+  // =========================================================================
+  // Instance methods
+  // =========================================================================
+
+  /**
+   * Adds a canActivate guard for a route.
+   * Handles overwrite detection and registration.
+   *
+   * @param name - Route name (input-validated by facade)
+   * @param handler - Guard function or boolean (input-validated by facade)
+   * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
+   */
+  addCanActivate(
+    name: string,
+    handler: GuardFnFactory<Dependencies> | boolean,
+    isFromDefinition = false,
+  ): void {
+    if (isFromDefinition) {
+      this.#definitionActivateGuardNames.add(name);
+    } else {
+      this.#definitionActivateGuardNames.delete(name);
+    }
+
+    const isOverwrite = this.#canActivateFactories.has(name);
+
+    this.#registerHandler(
+      "activate",
+      name,
+      handler,
+      this.#canActivateFactories,
+      this.#canActivateFunctions,
+      "canActivate",
+      isOverwrite,
+    );
+  }
+
+  /**
+   * Adds a canDeactivate guard for a route.
+   * Handles overwrite detection and registration.
+   *
+   * @param name - Route name (input-validated by facade)
+   * @param handler - Guard function or boolean (input-validated by facade)
+   * @param isFromDefinition - True when guard comes from route definition (tracked for HMR replace)
+   */
+  addCanDeactivate(
+    name: string,
+    handler: GuardFnFactory<Dependencies> | boolean,
+    isFromDefinition = false,
+  ): void {
+    if (isFromDefinition) {
+      this.#definitionDeactivateGuardNames.add(name);
+    } else {
+      this.#definitionDeactivateGuardNames.delete(name);
+    }
+
+    const isOverwrite = this.#canDeactivateFactories.has(name);
+
+    this.#registerHandler(
+      "deactivate",
+      name,
+      handler,
+      this.#canDeactivateFactories,
+      this.#canDeactivateFunctions,
+      "canDeactivate",
+      isOverwrite,
+    );
+  }
+
+  /**
+   * Removes a canActivate guard for a route.
+   * Input already validated by facade (not registering).
+   *
+   * @param name - Route name (already validated by facade)
+   */
+  clearCanActivate(name: string): void {
+    this.#canActivateFactories.delete(name);
+    this.#canActivateFunctions.delete(name);
+    this.#definitionActivateGuardNames.delete(name);
+  }
+
+  /**
+   * Removes a canDeactivate guard for a route.
+   * Input already validated by facade (not registering).
+   *
+   * @param name - Route name (already validated by facade)
+   */
+  clearCanDeactivate(name: string): void {
+    this.#canDeactivateFactories.delete(name);
+    this.#canDeactivateFunctions.delete(name);
+    this.#definitionDeactivateGuardNames.delete(name);
+  }
+
+  /**
+   * Clears all lifecycle handlers (canActivate and canDeactivate).
+   * Used by clearRoutes to reset all lifecycle state.
+   */
+  clearAll(): void {
+    this.#canActivateFactories.clear();
+    this.#canActivateFunctions.clear();
+    this.#canDeactivateFactories.clear();
+    this.#canDeactivateFunctions.clear();
+    this.#definitionActivateGuardNames.clear();
+    this.#definitionDeactivateGuardNames.clear();
+  }
+
+  /**
+   * Clears only lifecycle handlers that were registered from route definitions.
+   * Used by HMR to remove definition-sourced guards without touching externally-added guards.
+   */
+  clearDefinitionGuards(): void {
+    for (const name of this.#definitionActivateGuardNames) {
+      this.#canActivateFactories.delete(name);
+      this.#canActivateFunctions.delete(name);
+    }
+    for (const name of this.#definitionDeactivateGuardNames) {
+      this.#canDeactivateFactories.delete(name);
+      this.#canDeactivateFunctions.delete(name);
+    }
+
+    this.#definitionActivateGuardNames.clear();
+    this.#definitionDeactivateGuardNames.clear();
+  }
+
+  /**
+   * Returns lifecycle factories as records for cloning.
+   *
+   * @returns Tuple of [canDeactivateFactories, canActivateFactories]
+   */
+  getFactories(): [
+    Record<string, GuardFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
+  ] {
+    const deactivateRecord: Record<string, GuardFnFactory<Dependencies>> = {};
+    const activateRecord: Record<string, GuardFnFactory<Dependencies>> = {};
+
+    for (const [name, factory] of this.#canDeactivateFactories) {
+      deactivateRecord[name] = factory;
+    }
+
+    for (const [name, factory] of this.#canActivateFactories) {
+      activateRecord[name] = factory;
+    }
+
+    return [deactivateRecord, activateRecord];
+  }
+
+  /**
+   * Returns compiled lifecycle functions for transition execution.
+   *
+   * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
+   */
+  getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>] {
+    return this.#functionsTuple;
+  }
+
+  canNavigateTo(
+    toDeactivate: string[],
+    toActivate: string[],
+    toState: State,
+    fromState: State | undefined,
+  ): boolean {
+    for (const segment of toDeactivate) {
+      if (
+        !this.#checkGuardSync(
+          this.#canDeactivateFunctions,
+          segment,
+          toState,
+          fromState,
+          "canNavigateTo",
+        )
+      ) {
+        return false;
+      }
+    }
+
+    for (const segment of toActivate) {
+      if (
+        !this.#checkGuardSync(
+          this.#canActivateFunctions,
+          segment,
+          toState,
+          fromState,
+          "canNavigateTo",
+        )
+      ) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  // =========================================================================
+  // Private methods (business logic)
+  // =========================================================================
+
+  /**
+   * Registers a handler.
+   * Handles overwrite warning, count threshold warnings, and factory compilation.
+   *
+   * @param type - Guard type for log messages ("activate" or "deactivate")
+   * @param name - Route name to register the guard for
+   * @param handler - Guard factory function or boolean shorthand
+   * @param factories - Target factory map (canActivate or canDeactivate)
+   * @param functions - Target compiled functions map (canActivate or canDeactivate)
+   * @param methodName - Public API method name for error/warning messages
+   * @param isOverwrite - Whether this replaces an existing guard for the same route
+   */
+  #registerHandler(
+    type: "activate" | "deactivate",
+    name: string,
+    handler: GuardFnFactory<Dependencies> | boolean,
+    factories: Map<string, GuardFnFactory<Dependencies>>,
+    functions: Map<string, GuardFn>,
+    methodName: string,
+    isOverwrite: boolean,
+  ): void {
+    // Emit warnings
+    if (isOverwrite) {
+      this.#getValidator?.()?.lifecycle.warnOverwrite(name, type, methodName);
+    } else {
+      this.#getValidator?.()?.lifecycle.validateCountThresholds(
+        factories.size + 1,
+        methodName,
+      );
+    }
+
+    // Convert boolean to factory if needed
+    const factory =
+      typeof handler === "boolean"
+        ? booleanToFactory<Dependencies>(handler)
+        : handler;
+
+    // Store factory
+    factories.set(name, factory);
+
+    // Mark route as being registered before calling user factory
+    this.#registering.add(name);
+
+    try {
+      const fn = this.#deps.compileFactory(factory);
+
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          `[router.${methodName}] Factory must return a function, got ${typeof fn}`,
+        );
+      }
+
+      functions.set(name, fn);
+    } catch (error) {
+      // Rollback on failure to maintain consistency
+      factories.delete(name);
+
+      throw error;
+    } finally {
+      this.#registering.delete(name);
+    }
+  }
+
+  /**
+   * Shared implementation for synchronous guard checks.
+   * Warns if a guard returns a Promise (async guards are not supported in sync mode).
+   * Catches exceptions and treats them as navigation-blocking (`false`).
+   *
+   * @param functions - Map of compiled guard functions to look up
+   * @param name - Route name to check the guard for
+   * @param toState - Target navigation state
+   * @param fromState - Current state (`undefined` on initial navigation)
+   * @param methodName - Public API method name for warning messages
+   */
+  #checkGuardSync(
+    functions: Map<string, GuardFn>,
+    name: string,
+    toState: State,
+    fromState: State | undefined,
+    methodName: string,
+  ): boolean {
+    const guardFn = functions.get(name);
+
+    if (!guardFn) {
+      return true;
+    }
+
+    try {
+      const result = guardFn(toState, fromState);
+
+      if (typeof result === "boolean") {
+        return result;
+      }
+
+      this.#getValidator?.()?.lifecycle.warnAsyncGuardSync(name, methodName);
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/namespaces/RouteLifecycleNamespace/index.ts

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

package/src/namespaces/RouteLifecycleNamespace/types.ts

@@ -0,0 +1,10 @@
+// packages/core/src/namespaces/RouteLifecycleNamespace/types.ts
+
+import type { GuardFnFactory } from "../../types";
+import type { DefaultDependencies, GuardFn } from "@real-router/types";
+
+export interface RouteLifecycleDependencies<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  compileFactory: (factory: GuardFnFactory<Dependencies>) => GuardFn;
+}

package/src/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts

@@ -0,0 +1,81 @@
+// packages/core/src/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts
+
+import { errorCodes } from "../../constants";
+import { RouterError } from "../../RouterError";
+
+import type { RouterLifecycleDependencies } from "./types";
+import type { NavigationOptions, State } from "@real-router/types";
+
+const REPLACE_OPTS: NavigationOptions = { replace: true };
+
+Object.freeze(REPLACE_OPTS);
+
+/**
+ * Independent namespace for managing router lifecycle.
+ *
+ * Handles start() and stop(). Lifecycle state (isActive, isStarted) is managed
+ * by RouterFSM in the facade (Router.ts).
+ */
+export class RouterLifecycleNamespace {
+  #deps!: RouterLifecycleDependencies;
+
+  // =========================================================================
+  // Dependency injection
+  // =========================================================================
+
+  /**
+   * Sets dependencies for lifecycle operations.
+   * Must be called before using lifecycle methods.
+   */
+  setDependencies(deps: RouterLifecycleDependencies): void {
+    this.#deps = deps;
+  }
+
+  // =========================================================================
+  // Instance methods
+  // =========================================================================
+
+  /**
+   * Starts the router with the given path.
+   *
+   * Guards (concurrent start, already started) are handled by the facade via
+   * RouterFSM state checks before this method is called.
+   */
+  async start(startPath: string): Promise<State> {
+    const deps = this.#deps;
+    const options = deps.getOptions();
+
+    const matchedState = deps.matchPath(startPath);
+
+    if (!matchedState && !options.allowNotFound) {
+      const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {
+        path: startPath,
+      });
+
+      deps.emitTransitionError(undefined, undefined, err);
+
+      throw err;
+    }
+
+    deps.completeStart();
+
+    if (matchedState) {
+      return deps.navigate(
+        matchedState.name,
+        matchedState.params,
+        REPLACE_OPTS,
+      );
+    }
+
+    return deps.navigateToNotFound(startPath);
+  }
+
+  /**
+   * Stops the router and resets state.
+   *
+   * Called only for READY/TRANSITION_STARTED states (facade handles STARTING/IDLE/DISPOSED).
+   */
+  stop(): void {
+    this.#deps.clearState();
+  }
+}

package/src/namespaces/RouterLifecycleNamespace/constants.ts

@@ -0,0 +1,25 @@
+// packages/core/src/namespaces/RouterLifecycleNamespace/constants.ts
+
+import { errorCodes } from "../../constants";
+import { RouterError } from "../../RouterError";
+
+// =============================================================================
+// Cached Errors (Performance Optimization)
+// =============================================================================
+// Pre-create error instances to avoid object allocation on hot paths.
+// Error creation involves: new object, stack trace capture (~500ns-2μs).
+// Cached errors skip this overhead entirely.
+//
+// Trade-off: All error instances share the same stack trace (points here).
+// This is acceptable because:
+// 1. These errors indicate user misconfiguration, not internal bugs
+// 2. Error code and message are sufficient for debugging
+// 3. Performance gain (~80% for error paths) outweighs stack trace loss
+// =============================================================================
+
+/**
+ * Cached error for start() called when router is already started/starting.
+ */
+export const CACHED_ALREADY_STARTED_ERROR = new RouterError(
+  errorCodes.ROUTER_ALREADY_STARTED,
+);

package/src/namespaces/RouterLifecycleNamespace/index.ts

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

package/src/namespaces/RouterLifecycleNamespace/types.ts

@@ -0,0 +1,26 @@
+// packages/core/src/namespaces/RouterLifecycleNamespace/types.ts
+
+import type {
+  NavigationOptions,
+  Options,
+  Params,
+  State,
+} from "@real-router/types";
+
+export interface RouterLifecycleDependencies {
+  getOptions: () => Options;
+  navigate: (
+    name: string,
+    params: Params,
+    opts: NavigationOptions,
+  ) => Promise<State>;
+  navigateToNotFound: (path: string) => State;
+  clearState: () => void;
+  matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
+  completeStart: () => void;
+  emitTransitionError: (
+    toState: State | undefined,
+    fromState: State | undefined,
+    error: Error,
+  ) => void;
+}