@real-router/core 0.22.0 → 0.23.0

package/src/namespaces/PluginsNamespace/validators.ts

@@ -0,0 +1,79 @@
+// packages/core/src/namespaces/PluginsNamespace/validators.ts
+
+/**
+ * Static validation functions for PluginsNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { getTypeDescription, isObjKey } from "type-guards";
+
+import { EVENTS_MAP } from "./constants";
+import { DEFAULT_LIMITS } from "../../constants";
+
+import type { PluginFactory } from "../../types";
+import type { DefaultDependencies, Plugin } from "@real-router/types";
+
+/**
+ * Validates usePlugin arguments - all must be functions.
+ */
+export function validateUsePluginArgs<D extends DefaultDependencies>(
+  plugins: unknown[],
+): asserts plugins is PluginFactory<D>[] {
+  for (const plugin of plugins) {
+    if (typeof plugin !== "function") {
+      throw new TypeError(
+        `[router.usePlugin] Expected plugin factory function, got ${typeof plugin}`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that a plugin factory returned a valid plugin object.
+ */
+export function validatePlugin(plugin: Plugin): void {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!(plugin && typeof plugin === "object") || Array.isArray(plugin)) {
+    throw new TypeError(
+      `[router.usePlugin] Plugin factory must return an object, got ${getTypeDescription(
+        plugin,
+      )}`,
+    );
+  }
+
+  // Detect async factory (returns Promise)
+  if (typeof (plugin as unknown as { then?: unknown }).then === "function") {
+    throw new TypeError(
+      `[router.usePlugin] Async plugin factories are not supported. ` +
+        `Factory returned a Promise instead of a plugin object.`,
+    );
+  }
+
+  for (const key in plugin) {
+    if (!(key === "teardown" || isObjKey<typeof EVENTS_MAP>(key, EVENTS_MAP))) {
+      throw new TypeError(
+        `[router.usePlugin] Unknown property '${key}'. ` +
+          `Plugin must only contain event handlers and optional teardown.`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that adding new plugins won't exceed the hard limit.
+ */
+export function validatePluginLimit(
+  currentCount: number,
+  newCount: number,
+  maxPlugins: number = DEFAULT_LIMITS.maxPlugins,
+): void {
+  if (maxPlugins === 0) {
+    return;
+  }
+
+  const totalCount = currentCount + newCount;
+
+  if (totalCount > maxPlugins) {
+    throw new Error(`[router.usePlugin] Plugin limit exceeded (${maxPlugins})`);
+  }
+}

package/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts

@@ -0,0 +1,389 @@
+// packages/core/src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts
+
+import { logger } from "@real-router/logger";
+import { isBoolean, isPromise, getTypeDescription } from "type-guards";
+
+import {
+  validateHandler,
+  validateHandlerLimit,
+  validateNotRegistering,
+} from "./validators";
+import { DEFAULT_LIMITS } from "../../constants";
+import { computeThresholds } from "../../helpers";
+
+import type { RouteLifecycleDependencies } from "./types";
+import type { Router } from "../../Router";
+import type { ActivationFnFactory, Limits } from "../../types";
+import type {
+  ActivationFn,
+  DefaultDependencies,
+  State,
+} from "@real-router/types";
+
+/**
+ * Converts a boolean value to an activation function factory.
+ * Used for the shorthand syntax where true/false is passed instead of a function.
+ */
+function booleanToFactory<Dependencies extends DefaultDependencies>(
+  value: boolean,
+): ActivationFnFactory<Dependencies> {
+  const activationFn: ActivationFn = () => value;
+
+  return () => activationFn;
+}
+
+/**
+ * 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,
+    ActivationFnFactory<Dependencies>
+  >();
+  readonly #canActivateFactories = new Map<
+    string,
+    ActivationFnFactory<Dependencies>
+  >();
+  readonly #canDeactivateFunctions = new Map<string, ActivationFn>();
+  readonly #canActivateFunctions = new Map<string, ActivationFn>();
+
+  readonly #registering = new Set<string>();
+
+  #router!: Router<Dependencies>;
+  #deps!: RouteLifecycleDependencies<Dependencies>;
+  #limits: Limits = DEFAULT_LIMITS;
+
+  // =========================================================================
+  // Static validation methods (called by facade for input validation)
+  // =========================================================================
+
+  static validateHandler<D extends DefaultDependencies>(
+    handler: unknown,
+    methodName: string,
+  ): asserts handler is ActivationFnFactory<D> | boolean {
+    validateHandler<D>(handler, methodName);
+  }
+
+  setRouter(router: Router<Dependencies>): void {
+    this.#router = router;
+  }
+
+  setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void {
+    this.#deps = deps;
+  }
+
+  setLimits(limits: Limits): void {
+    this.#limits = limits;
+  }
+
+  // =========================================================================
+  // Instance methods
+  // =========================================================================
+
+  /**
+   * Adds a canActivate guard for a route.
+   * Handles state-dependent validation, overwrite detection, and registration.
+   *
+   * @param name - Route name (input-validated by facade)
+   * @param handler - Guard function or boolean (input-validated by facade)
+   * @param skipValidation - True when called during route config building (#noValidate)
+   */
+  addCanActivate(
+    name: string,
+    handler: ActivationFnFactory<Dependencies> | boolean,
+    skipValidation: boolean,
+  ): void {
+    if (!skipValidation) {
+      validateNotRegistering(
+        this.#registering.has(name),
+        name,
+        "addActivateGuard",
+      );
+    }
+
+    const isOverwrite = this.#canActivateFactories.has(name);
+
+    if (!isOverwrite && !skipValidation) {
+      validateHandlerLimit(
+        this.#canActivateFactories.size + 1,
+        "addActivateGuard",
+        this.#limits.maxLifecycleHandlers,
+      );
+    }
+
+    this.#registerHandler(
+      "activate",
+      name,
+      handler,
+      this.#canActivateFactories,
+      this.#canActivateFunctions,
+      "canActivate",
+      isOverwrite,
+    );
+  }
+
+  /**
+   * Adds a canDeactivate guard for a route.
+   * Handles state-dependent validation, overwrite detection, and registration.
+   *
+   * @param name - Route name (input-validated by facade)
+   * @param handler - Guard function or boolean (input-validated by facade)
+   * @param skipValidation - True when called during route config building (#noValidate)
+   */
+  addCanDeactivate(
+    name: string,
+    handler: ActivationFnFactory<Dependencies> | boolean,
+    skipValidation: boolean,
+  ): void {
+    if (!skipValidation) {
+      validateNotRegistering(
+        this.#registering.has(name),
+        name,
+        "addDeactivateGuard",
+      );
+    }
+
+    const isOverwrite = this.#canDeactivateFactories.has(name);
+
+    if (!isOverwrite && !skipValidation) {
+      validateHandlerLimit(
+        this.#canDeactivateFactories.size + 1,
+        "addDeactivateGuard",
+        this.#limits.maxLifecycleHandlers,
+      );
+    }
+
+    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);
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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();
+  }
+
+  /**
+   * Returns lifecycle factories as records for cloning.
+   *
+   * @returns Tuple of [canDeactivateFactories, canActivateFactories]
+   */
+  getFactories(): [
+    Record<string, ActivationFnFactory<Dependencies>>,
+    Record<string, ActivationFnFactory<Dependencies>>,
+  ] {
+    const deactivateRecord: Record<
+      string,
+      ActivationFnFactory<Dependencies>
+    > = {};
+    const activateRecord: Record<
+      string,
+      ActivationFnFactory<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, ActivationFn>, Map<string, ActivationFn>] {
+    return [this.#canDeactivateFunctions, this.#canActivateFunctions];
+  }
+
+  checkActivateGuardSync(
+    name: string,
+    toState: State,
+    fromState: State | undefined,
+  ): boolean {
+    return this.#checkGuardSync(
+      this.#canActivateFunctions,
+      name,
+      toState,
+      fromState,
+      "checkActivateGuardSync",
+    );
+  }
+
+  checkDeactivateGuardSync(
+    name: string,
+    toState: State,
+    fromState: State | undefined,
+  ): boolean {
+    return this.#checkGuardSync(
+      this.#canDeactivateFunctions,
+      name,
+      toState,
+      fromState,
+      "checkDeactivateGuardSync",
+    );
+  }
+
+  // =========================================================================
+  // Private methods (business logic)
+  // =========================================================================
+
+  /**
+   * Registers a handler.
+   * Handles overwrite warning, count threshold warnings, and factory compilation.
+   */
+  #registerHandler(
+    type: "activate" | "deactivate",
+    name: string,
+    handler: ActivationFnFactory<Dependencies> | boolean,
+    factories: Map<string, ActivationFnFactory<Dependencies>>,
+    functions: Map<string, ActivationFn>,
+    methodName: string,
+    isOverwrite: boolean,
+  ): void {
+    // Emit warnings
+    if (isOverwrite) {
+      logger.warn(
+        `router.${methodName}`,
+        `Overwriting existing ${type} handler for route "${name}"`,
+      );
+    } else {
+      this.#checkCountThresholds(factories.size + 1, methodName);
+    }
+
+    // Convert boolean to factory if needed
+    const factory = isBoolean(handler)
+      ? booleanToFactory<Dependencies>(handler)
+      : handler;
+
+    // Store factory
+    factories.set(name, factory);
+
+    // Mark route as being registered before calling user factory
+    this.#registering.add(name);
+
+    try {
+      // Lifecycle factories receive full router as part of their public API
+      const fn = factory(this.#router, this.#deps.getDependency);
+
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          `[router.${methodName}] Factory must return a function, got ${getTypeDescription(fn)}`,
+        );
+      }
+
+      functions.set(name, fn);
+    } catch (error) {
+      // Rollback on failure to maintain consistency
+      factories.delete(name);
+
+      throw error;
+    } finally {
+      this.#registering.delete(name);
+    }
+  }
+
+  #checkGuardSync(
+    functions: Map<string, ActivationFn>,
+    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;
+      }
+
+      if (isPromise(result)) {
+        logger.warn(
+          `router.${methodName}`,
+          `Guard for "${name}" returned a Promise. Sync check cannot resolve async guards — returning false.`,
+        );
+
+        return false;
+      }
+
+      // Guard returned void/State — permissive default
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  #checkCountThresholds(currentSize: number, methodName: string): void {
+    const maxLifecycleHandlers = this.#limits.maxLifecycleHandlers;
+
+    if (maxLifecycleHandlers === 0) {
+      return;
+    }
+
+    const { warn, error } = computeThresholds(maxLifecycleHandlers);
+
+    if (currentSize >= error) {
+      logger.error(
+        `router.${methodName}`,
+        `${currentSize} lifecycle handlers registered! ` +
+          `This is excessive. Hard limit at ${maxLifecycleHandlers}.`,
+      );
+    } else if (currentSize >= warn) {
+      logger.warn(
+        `router.${methodName}`,
+        `${currentSize} lifecycle handlers registered. ` +
+          `Consider consolidating logic.`,
+      );
+    }
+  }
+}

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,17 @@
+// packages/core/src/namespaces/RouteLifecycleNamespace/types.ts
+
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Dependencies injected into RouteLifecycleNamespace.
+ *
+ * Note: Lifecycle factories still receive the router object directly
+ * as they need access to various router methods. This interface
+ * only covers the internal namespace operations.
+ */
+export interface RouteLifecycleDependencies<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  /** Get dependency value for lifecycle factory */
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+}

package/src/namespaces/RouteLifecycleNamespace/validators.ts

@@ -0,0 +1,65 @@
+// packages/core/src/namespaces/RouteLifecycleNamespace/validators.ts
+
+/**
+ * Static validation functions for RouteLifecycleNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { isBoolean, getTypeDescription } from "type-guards";
+
+import { DEFAULT_LIMITS } from "../../constants";
+
+import type { ActivationFnFactory } from "../../types";
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Validates that a handler is either a boolean or a factory function.
+ */
+export function validateHandler<D extends DefaultDependencies>(
+  handler: unknown,
+  methodName: string,
+): asserts handler is ActivationFnFactory<D> | boolean {
+  if (!isBoolean(handler) && typeof handler !== "function") {
+    throw new TypeError(
+      `[router.${methodName}] Handler must be a boolean or factory function, ` +
+        `got ${getTypeDescription(handler)}`,
+    );
+  }
+}
+
+/**
+ * Validates that a route is not currently being registered.
+ * Prevents self-modification during factory compilation.
+ */
+export function validateNotRegistering(
+  isRegistering: boolean,
+  name: string,
+  methodName: string,
+): void {
+  if (isRegistering) {
+    throw new Error(
+      `[router.${methodName}] Cannot modify route "${name}" during its own registration`,
+    );
+  }
+}
+
+/**
+ * Validates that adding a new handler won't exceed the hard limit.
+ */
+export function validateHandlerLimit(
+  currentCount: number,
+  methodName: string,
+  maxLifecycleHandlers: number = DEFAULT_LIMITS.maxLifecycleHandlers,
+): void {
+  if (maxLifecycleHandlers === 0) {
+    return;
+  }
+
+  if (currentCount >= maxLifecycleHandlers) {
+    throw new Error(
+      `[router.${methodName}] Lifecycle handler limit exceeded (${maxLifecycleHandlers}). ` +
+        `This indicates too many routes with individual handlers. ` +
+        `Consider using middleware for cross-cutting concerns.`,
+    );
+  }
+}

package/src/namespaces/RouterLifecycleNamespace/RouterLifecycleNamespace.ts

@@ -0,0 +1,140 @@
+// 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";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CYCLIC DEPENDENCIES
+// ═══════════════════════════════════════════════════════════════════════════════
+// RouterLifecycle → Navigation.navigateToState() (for start transitions)
+//
+// Solution: functional references configured in Router.#setupDependencies()
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 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 {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Functional references for cyclic dependencies
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // Dependencies injected via setDependencies (replaces full router reference)
+  #navigateToState!: (
+    toState: State,
+    fromState: State | undefined,
+    opts: NavigationOptions,
+  ) => Promise<State>;
+
+  #deps!: RouterLifecycleDependencies;
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // =========================================================================
+
+  /**
+   * Validates start() arguments.
+   */
+  static validateStartArgs(args: unknown[]): void {
+    /* v8 ignore next 4 -- @preserve: facade enforces 1 arg via TypeScript signature */
+    if (args.length !== 1 || typeof args[0] !== "string") {
+      throw new Error(
+        "[router.start] Expected exactly 1 string argument (startPath).",
+      );
+    }
+  }
+
+  // =========================================================================
+  // Dependency injection
+  // =========================================================================
+
+  /**
+   * Sets the navigateToState reference (cyclic dependency on NavigationNamespace).
+   * Must be called before using start().
+   */
+  setNavigateToState(
+    fn: (
+      toState: State,
+      fromState: State | undefined,
+      opts: NavigationOptions,
+    ) => Promise<State>,
+  ): void {
+    this.#navigateToState = fn;
+  }
+
+  /**
+   * 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 startOptions: NavigationOptions = {
+      replace: true,
+    };
+
+    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();
+
+    let finalState: State;
+
+    if (matchedState) {
+      finalState = await this.#navigateToState(
+        matchedState,
+        undefined,
+        startOptions,
+      );
+    } else {
+      const notFoundState = deps.makeNotFoundState(startPath, startOptions);
+
+      finalState = await this.#navigateToState(
+        notFoundState,
+        undefined,
+        startOptions,
+      );
+    }
+
+    return finalState;
+  }
+
+  /**
+   * Stops the router and resets state.
+   *
+   * Called only for READY/TRANSITIONING states (facade handles STARTING/IDLE/DISPOSED).
+   */
+  stop(): void {
+    this.#deps.setState();
+  }
+}