@real-router/core 0.22.0 → 0.23.0

package/src/namespaces/DependenciesNamespace/validators.ts

@@ -0,0 +1,105 @@
+// packages/core/src/namespaces/DependenciesNamespace/validators.ts
+
+/**
+ * Static validation functions for DependenciesNamespace.
+ * Called by Router facade before instance methods.
+ *
+ * Extracted from DependenciesNamespace class for better separation of concerns.
+ */
+
+import { getTypeDescription } from "type-guards";
+
+import { DEFAULT_LIMITS } from "../../constants";
+
+/**
+ * Validates that dependency name is a string.
+ * Called by facade before get/remove/has operations.
+ */
+export function validateDependencyName(
+  name: unknown,
+  methodName: string,
+): asserts name is string {
+  if (typeof name !== "string") {
+    throw new TypeError(
+      `[router.${methodName}]: dependency name must be a string, got ${typeof name}`,
+    );
+  }
+}
+
+/**
+ * Validates setDependency name argument.
+ * Value is not validated - any value is valid.
+ */
+export function validateSetDependencyArgs(
+  name: unknown,
+): asserts name is string {
+  if (typeof name !== "string") {
+    throw new TypeError(
+      `[router.setDependency]: dependency name must be a string, got ${typeof name}`,
+    );
+  }
+}
+
+/**
+ * Validates that dependencies object is a plain object without getters.
+ * Called by facade before setMultiple/constructor.
+ */
+export function validateDependenciesObject(
+  deps: unknown,
+  methodName: string,
+): asserts deps is Record<string, unknown> {
+  // Reject non-plain objects (classes, Date, Map, Array)
+  if (!(deps && typeof deps === "object" && deps.constructor === Object)) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid argument: expected plain object, received ${getTypeDescription(deps)}`,
+    );
+  }
+
+  // Getters can throw, return different values, or have side effects
+  for (const key in deps) {
+    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
+      throw new TypeError(
+        `[router.${methodName}] Getters not allowed: "${key}"`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates that dependency exists (not undefined).
+ * Throws ReferenceError if dependency is not found.
+ */
+export function validateDependencyExists(
+  value: unknown,
+  dependencyName: string,
+): asserts value is NonNullable<unknown> {
+  if (value === undefined) {
+    throw new ReferenceError(
+      `[router.getDependency]: dependency "${dependencyName}" not found`,
+    );
+  }
+}
+
+/**
+ * Validates that adding dependencies won't exceed the hard limit.
+ * Called before bulk operations to ensure atomicity.
+ */
+export function validateDependencyLimit(
+  currentCount: number,
+  newCount: number,
+  methodName: string,
+  maxDependencies: number = DEFAULT_LIMITS.maxDependencies,
+): void {
+  if (maxDependencies === 0) {
+    return;
+  }
+
+  const totalCount = currentCount + newCount;
+
+  if (totalCount >= maxDependencies) {
+    throw new Error(
+      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
+        `Current: ${totalCount}. This is likely a bug in your code.`,
+    );
+  }
+}

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -0,0 +1,272 @@
+// packages/core/src/namespaces/EventBusNamespace/EventBusNamespace.ts
+
+import { events, validEventNames } from "../../constants";
+import { routerEvents, routerStates } from "../../fsm";
+
+import type { EventBusOptions } from "./types";
+import type { RouterEvent, RouterPayloads, RouterState } from "../../fsm";
+import type { RouterError } from "../../RouterError";
+import type { EventMethodMap, RouterEventMap } from "../../types";
+import type { FSM } from "@real-router/fsm";
+import type {
+  EventName,
+  NavigationOptions,
+  Plugin,
+  State,
+  SubscribeFn,
+  Unsubscribe,
+} from "@real-router/types";
+import type { EventEmitter } from "event-emitter";
+
+export class EventBusNamespace {
+  readonly #fsm: FSM<RouterState, RouterEvent, null, RouterPayloads>;
+  readonly #emitter: EventEmitter<RouterEventMap>;
+
+  #currentToState: State | undefined;
+
+  constructor(options: EventBusOptions) {
+    this.#fsm = options.routerFSM;
+    this.#emitter = options.emitter;
+    this.#currentToState = undefined;
+    this.#setupFSMActions();
+  }
+
+  static validateEventName(eventName: unknown): void {
+    if (!validEventNames.has(eventName as EventName)) {
+      throw new Error(`Invalid event name: ${String(eventName)}`);
+    }
+  }
+
+  static validateListenerArgs<E extends EventName>(
+    eventName: E,
+    cb: Plugin[EventMethodMap[E]],
+  ): void {
+    EventBusNamespace.validateEventName(eventName);
+
+    if (typeof cb !== "function") {
+      throw new TypeError(
+        `Expected callback to be a function for event ${eventName}`,
+      );
+    }
+  }
+
+  static validateSubscribeListener(listener: unknown): void {
+    if (typeof listener !== "function") {
+      throw new TypeError(
+        "[router.subscribe] Expected a function. " +
+          "For Observable pattern use @real-router/rx package",
+      );
+    }
+  }
+
+  emitRouterStart(): void {
+    this.#emitter.emit(events.ROUTER_START);
+  }
+
+  emitRouterStop(): void {
+    this.#emitter.emit(events.ROUTER_STOP);
+  }
+
+  emitTransitionStart(toState: State, fromState?: State): void {
+    this.#emitter.emit(events.TRANSITION_START, toState, fromState);
+  }
+
+  emitTransitionSuccess(
+    toState: State,
+    fromState?: State,
+    opts?: NavigationOptions,
+  ): void {
+    this.#emitter.emit(events.TRANSITION_SUCCESS, toState, fromState, opts);
+  }
+
+  emitTransitionError(
+    toState?: State,
+    fromState?: State,
+    error?: RouterError,
+  ): void {
+    this.#emitter.emit(events.TRANSITION_ERROR, toState, fromState, error);
+  }
+
+  emitTransitionCancel(toState: State, fromState?: State): void {
+    this.#emitter.emit(events.TRANSITION_CANCEL, toState, fromState);
+  }
+
+  sendStart(): void {
+    this.#fsm.send(routerEvents.START);
+  }
+
+  sendStop(): void {
+    this.#fsm.send(routerEvents.STOP);
+  }
+
+  sendDispose(): void {
+    this.#fsm.send(routerEvents.DISPOSE);
+  }
+
+  completeStart(): void {
+    this.#fsm.send(routerEvents.STARTED);
+  }
+
+  beginTransition(toState: State, fromState?: State): void {
+    this.#currentToState = toState;
+    this.#fsm.send(routerEvents.NAVIGATE, { toState, fromState });
+  }
+
+  completeTransition(
+    state: State,
+    fromState?: State,
+    opts: NavigationOptions = {},
+  ): void {
+    this.#fsm.send(routerEvents.COMPLETE, {
+      state,
+      fromState,
+      opts,
+    });
+    this.#currentToState = undefined;
+  }
+
+  failTransition(toState?: State, fromState?: State, error?: unknown): void {
+    this.#fsm.send(routerEvents.FAIL, { toState, fromState, error });
+    this.#currentToState = undefined;
+  }
+
+  cancelTransition(toState: State, fromState?: State): void {
+    this.#fsm.send(routerEvents.CANCEL, { toState, fromState });
+    this.#currentToState = undefined;
+  }
+
+  emitOrFailTransitionError(
+    toState?: State,
+    fromState?: State,
+    error?: unknown,
+  ): void {
+    if (this.#fsm.getState() === routerStates.READY) {
+      this.#fsm.send(routerEvents.FAIL, { toState, fromState, error });
+    } else {
+      // TRANSITIONING: concurrent navigation with invalid args.
+      // Direct emit to avoid disturbing the ongoing transition.
+      this.emitTransitionError(toState, fromState, error as RouterError);
+    }
+  }
+
+  canBeginTransition(): boolean {
+    return this.#fsm.canSend(routerEvents.NAVIGATE);
+  }
+
+  canStart(): boolean {
+    return this.#fsm.canSend(routerEvents.START);
+  }
+
+  canCancel(): boolean {
+    return this.#fsm.canSend(routerEvents.CANCEL);
+  }
+
+  isActive(): boolean {
+    const s = this.#fsm.getState();
+
+    return s !== routerStates.IDLE && s !== routerStates.DISPOSED;
+  }
+
+  isDisposed(): boolean {
+    return this.#fsm.getState() === routerStates.DISPOSED;
+  }
+
+  isTransitioning(): boolean {
+    return this.#fsm.getState() === routerStates.TRANSITIONING;
+  }
+
+  isReady(): boolean {
+    return this.#fsm.getState() === routerStates.READY;
+  }
+
+  getCurrentToState(): State | undefined {
+    return this.#currentToState;
+  }
+
+  addEventListener<E extends EventName>(
+    eventName: E,
+    cb: Plugin[EventMethodMap[E]],
+  ): Unsubscribe {
+    return this.#emitter.on(
+      eventName,
+      cb as (...args: RouterEventMap[typeof eventName]) => void,
+    );
+  }
+
+  subscribe(listener: SubscribeFn): Unsubscribe {
+    return this.#emitter.on(
+      events.TRANSITION_SUCCESS,
+      (toState: State, fromState?: State) => {
+        listener({ route: toState, previousRoute: fromState });
+      },
+    );
+  }
+
+  clearAll(): void {
+    this.#emitter.clearAll();
+  }
+
+  setLimits(limits: {
+    maxListeners: number;
+    warnListeners: number;
+    maxEventDepth: number;
+  }): void {
+    this.#emitter.setLimits(limits);
+  }
+
+  cancelTransitionIfRunning(fromState: State | undefined): void {
+    if (!this.canCancel()) {
+      return;
+    }
+
+    this.cancelTransition(this.#currentToState!, fromState); // eslint-disable-line @typescript-eslint/no-non-null-assertion -- guaranteed set before TRANSITIONING
+  }
+
+  #setupFSMActions(): void {
+    const fsm = this.#fsm;
+
+    fsm.on(routerStates.STARTING, routerEvents.STARTED, () => {
+      this.emitRouterStart();
+    });
+
+    fsm.on(routerStates.READY, routerEvents.STOP, () => {
+      this.emitRouterStop();
+    });
+
+    fsm.on(routerStates.READY, routerEvents.NAVIGATE, (params) => {
+      this.emitTransitionStart(params.toState, params.fromState);
+    });
+
+    fsm.on(routerStates.TRANSITIONING, routerEvents.COMPLETE, (params) => {
+      this.emitTransitionSuccess(params.state, params.fromState, params.opts);
+    });
+
+    fsm.on(routerStates.TRANSITIONING, routerEvents.CANCEL, (params) => {
+      this.emitTransitionCancel(params.toState, params.fromState);
+    });
+
+    fsm.on(routerStates.STARTING, routerEvents.FAIL, (params) => {
+      this.emitTransitionError(
+        params.toState,
+        params.fromState,
+        params.error as RouterError | undefined,
+      );
+    });
+
+    fsm.on(routerStates.READY, routerEvents.FAIL, (params) => {
+      this.emitTransitionError(
+        params.toState,
+        params.fromState,
+        params.error as RouterError | undefined,
+      );
+    });
+
+    fsm.on(routerStates.TRANSITIONING, routerEvents.FAIL, (params) => {
+      this.emitTransitionError(
+        params.toState,
+        params.fromState,
+        params.error as RouterError | undefined,
+      );
+    });
+  }
+}

package/src/namespaces/EventBusNamespace/index.ts

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

package/src/namespaces/EventBusNamespace/types.ts

@@ -0,0 +1,11 @@
+// packages/core/src/namespaces/EventBusNamespace/types.ts
+
+import type { RouterEvent, RouterPayloads, RouterState } from "../../fsm";
+import type { RouterEventMap } from "../../types";
+import type { FSM } from "@real-router/fsm";
+import type { EventEmitter } from "event-emitter";
+
+export interface EventBusOptions {
+  routerFSM: FSM<RouterState, RouterEvent, null, RouterPayloads>;
+  emitter: EventEmitter<RouterEventMap>;
+}

package/src/namespaces/MiddlewareNamespace/MiddlewareNamespace.ts

@@ -0,0 +1,206 @@
+// packages/core/src/namespaces/MiddlewareNamespace/MiddlewareNamespace.ts
+
+import { logger } from "@real-router/logger";
+
+import {
+  validateMiddleware,
+  validateMiddlewareLimit,
+  validateNoDuplicates,
+  validateUseMiddlewareArgs,
+} from "./validators";
+import { DEFAULT_LIMITS } from "../../constants";
+import { computeThresholds } from "../../helpers";
+
+import type { InitializedMiddleware, MiddlewareDependencies } from "./types";
+import type { Router } from "../../Router";
+import type { Limits, MiddlewareFactory } from "../../types";
+import type {
+  DefaultDependencies,
+  Middleware,
+  Unsubscribe,
+} from "@real-router/types";
+
+/**
+ * Independent namespace for managing middleware.
+ *
+ * Static methods handle validation (called by facade).
+ * Instance methods handle storage and business logic.
+ */
+export class MiddlewareNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly #factories = new Set<MiddlewareFactory<Dependencies>>();
+  readonly #factoryToMiddleware = new Map<
+    MiddlewareFactory<Dependencies>,
+    Middleware
+  >();
+
+  #router!: Router<Dependencies>;
+  #deps!: MiddlewareDependencies<Dependencies>;
+  #limits: Limits = DEFAULT_LIMITS;
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // Proxy to functions in validators.ts for separation of concerns
+  // =========================================================================
+
+  static validateUseMiddlewareArgs<D extends DefaultDependencies>(
+    middlewares: unknown[],
+  ): asserts middlewares is MiddlewareFactory<D>[] {
+    validateUseMiddlewareArgs<D>(middlewares);
+  }
+
+  static validateMiddleware<D extends DefaultDependencies>(
+    middleware: unknown,
+    factory: MiddlewareFactory<D>,
+  ): asserts middleware is Middleware {
+    validateMiddleware<D>(middleware, factory);
+  }
+
+  static validateNoDuplicates<D extends DefaultDependencies>(
+    newFactories: MiddlewareFactory<D>[],
+    existingFactories: MiddlewareFactory<D>[],
+  ): void {
+    validateNoDuplicates<D>(newFactories, existingFactories);
+  }
+
+  static validateMiddlewareLimit(
+    currentCount: number,
+    newCount: number,
+    maxMiddleware?: number,
+  ): void {
+    validateMiddlewareLimit(currentCount, newCount, maxMiddleware);
+  }
+
+  // =========================================================================
+  // Dependency injection
+  // =========================================================================
+
+  setRouter(router: Router<Dependencies>): void {
+    this.#router = router;
+  }
+
+  setDependencies(deps: MiddlewareDependencies<Dependencies>): void {
+    this.#deps = deps;
+  }
+
+  setLimits(limits: Limits): void {
+    this.#limits = limits;
+  }
+
+  // =========================================================================
+  // Instance methods (trust input - already validated by facade)
+  // =========================================================================
+
+  /**
+   * Returns the current number of registered middleware.
+   */
+  count(): number {
+    return this.#factories.size;
+  }
+
+  /**
+   * Initializes middleware factories without committing to storage.
+   * Returns array of initialized middleware for validation by facade.
+   *
+   * @param factories - Already validated by facade
+   */
+  initialize(
+    ...factories: MiddlewareFactory<Dependencies>[]
+  ): InitializedMiddleware<Dependencies>[] {
+    const initialized: InitializedMiddleware<Dependencies>[] = [];
+
+    for (const factory of factories) {
+      // Middleware factories receive full router as part of their public API
+      const middleware = factory(this.#router, this.#deps.getDependency);
+
+      initialized.push({ factory, middleware });
+    }
+
+    return initialized;
+  }
+
+  /**
+   * Commits initialized middleware to storage.
+   * Returns unsubscribe function to remove all added middleware.
+   *
+   * @param initialized - Already validated by facade
+   */
+  commit(initialized: InitializedMiddleware<Dependencies>[]): Unsubscribe {
+    // Check count thresholds and log warnings if needed
+    this.#checkCountThresholds(initialized.length);
+
+    // Add to storage
+    for (const { factory, middleware } of initialized) {
+      this.#factories.add(factory);
+      this.#factoryToMiddleware.set(factory, middleware);
+    }
+
+    // Return unsubscribe function specific to THIS call's middleware
+    let unsubscribed = false;
+
+    return (): void => {
+      if (unsubscribed) {
+        return;
+      }
+
+      unsubscribed = true;
+
+      for (const { factory } of initialized) {
+        this.#factories.delete(factory);
+        this.#factoryToMiddleware.delete(factory);
+      }
+    };
+  }
+
+  /**
+   * Returns a copy of registered middleware factories.
+   * Preserves insertion order.
+   */
+  getFactories(): MiddlewareFactory<Dependencies>[] {
+    return [...this.#factories];
+  }
+
+  /**
+   * Returns the actual middleware functions in execution order.
+   */
+  getFunctions(): Middleware[] {
+    return [...this.#factoryToMiddleware.values()];
+  }
+
+  clearAll(): void {
+    this.#factories.clear();
+    this.#factoryToMiddleware.clear();
+  }
+
+  // =========================================================================
+  // Private methods
+  // =========================================================================
+
+  #checkCountThresholds(newCount: number): void {
+    const maxMiddleware = this.#limits.maxMiddleware;
+
+    if (maxMiddleware === 0) {
+      return;
+    }
+
+    const totalSize = newCount + this.#factories.size;
+
+    const { warn, error } = computeThresholds(maxMiddleware);
+
+    if (totalSize >= error) {
+      logger.error(
+        "router.useMiddleware",
+        `${totalSize} middleware registered! ` +
+          `This is excessive and will impact performance. ` +
+          `Hard limit at ${maxMiddleware}.`,
+      );
+    } else if (totalSize >= warn) {
+      logger.warn(
+        "router.useMiddleware",
+        `${totalSize} middleware registered. ` +
+          `Consider if all are necessary.`,
+      );
+    }
+  }
+}

package/src/namespaces/MiddlewareNamespace/index.ts

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

package/src/namespaces/MiddlewareNamespace/types.ts

@@ -0,0 +1,28 @@
+// packages/core/src/namespaces/MiddlewareNamespace/types.ts
+
+import type { MiddlewareFactory } from "../../types";
+import type { DefaultDependencies, Middleware } from "@real-router/types";
+
+/**
+ * Dependencies injected into MiddlewareNamespace.
+ *
+ * Note: Middleware 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 MiddlewareDependencies<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  /** Get dependency value for middleware factory */
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+}
+
+/**
+ * Initialized middleware entry returned by initialize().
+ */
+export interface InitializedMiddleware<
+  Dependencies extends DefaultDependencies,
+> {
+  factory: MiddlewareFactory<Dependencies>;
+  middleware: Middleware;
+}