@real-router/core 0.56.0 → 0.57.0

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -1,522 +0,0 @@
-// packages/core/src/namespaces/EventBusNamespace/EventBusNamespace.ts
-
-import { events } 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,
-  LeaveFn,
-  LeaveState,
-  NavigationOptions,
-  Plugin,
-  State,
-  SubscribeFn,
-  TreeChangedEvent,
-  Unsubscribe,
-} from "@real-router/types";
-import type { EventEmitter } from "event-emitter";
-
-/**
- * Internal-only event key for route-tree mutations. Lives on the same
- * `EventEmitter` as the 7 transition events but never enters the public
- * `EventName` union — reachable only through
- * `getRoutesApi(router).subscribeChanges()`.
- */
-const TREE_CHANGED = "TREE_CHANGED";
-
-function ensureError(value: unknown): Error {
-  /* v8 ignore next -- @preserve: defensive guard — listeners should always throw Error objects */
-  return value instanceof Error ? value : new Error(String(value));
-}
-
-function settleLeavePromises(
-  promises: Promise<void>[],
-  firstSyncError: unknown,
-  signal: AbortSignal,
-): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    const onAbort = (): void => {
-      reject(ensureError(signal.reason));
-    };
-
-    if (signal.aborted) {
-      onAbort();
-
-      return;
-    }
-
-    signal.addEventListener("abort", onAbort, { once: true });
-
-    void Promise.allSettled(promises).then((results) => {
-      signal.removeEventListener("abort", onAbort);
-
-      if (signal.aborted) {
-        // Race lost to abort — the abort handler already rejected; do nothing
-        return;
-      }
-
-      if (firstSyncError !== undefined) {
-        reject(ensureError(firstSyncError));
-
-        return;
-      }
-
-      const rejected = results.find(
-        (result): result is PromiseRejectedResult =>
-          result.status === "rejected",
-      );
-
-      if (rejected !== undefined) {
-        reject(ensureError(rejected.reason));
-
-        return;
-      }
-
-      resolve();
-    });
-  });
-}
-
-export class EventBusNamespace {
-  readonly #fsm: FSM<RouterState, RouterEvent, null, RouterPayloads>;
-  readonly #emitter: EventEmitter<RouterEventMap>;
-  readonly #leaveListeners: LeaveFn[] = [];
-
-  #currentToState: State | undefined;
-  #pendingToState: State | undefined;
-  #pendingFromState: State | undefined;
-  #pendingError: unknown;
-
-  constructor(options: EventBusOptions) {
-    this.#fsm = options.routerFSM;
-    this.#emitter = options.emitter;
-    this.#currentToState = undefined;
-    this.#setupFSMActions();
-  }
-
-  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",
-      );
-    }
-  }
-
-  static validateSubscribeLeaveListener(listener: unknown): void {
-    if (typeof listener !== "function") {
-      throw new TypeError("[router.subscribeLeave] Expected a function");
-    }
-  }
-
-  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);
-  }
-
-  emitTransitionLeaveApprove(toState: State, fromState?: State): void {
-    this.#emitter.emit(events.TRANSITION_LEAVE_APPROVE, toState, fromState);
-  }
-
-  /**
-   * Emits the internal `TREE_CHANGED` event after a structural route-tree
-   * mutation. Reuses the shared `EventEmitter` — so depth tracking
-   * (`maxEventDepth`) and per-listener error isolation (`onListenerError`)
-   * apply automatically.
-   */
-  emitTreeChanged(event: TreeChangedEvent): void {
-    this.#emitter.emit(TREE_CHANGED, event);
-  }
-
-  /**
-   * Subscribes to `TREE_CHANGED`. **Lenient** duplicate semantics (mirrors
-   * {@link subscribe}): each call wraps the handler in a fresh closure, so N
-   * registrations of the same reference produce N independent subscriptions.
-   */
-  subscribeTreeChanged(
-    handler: (event: TreeChangedEvent) => void,
-  ): Unsubscribe {
-    return this.#emitter.on(TREE_CHANGED, (event: TreeChangedEvent) => {
-      handler(event);
-    });
-  }
-
-  /** Number of active `TREE_CHANGED` listeners (drives conditional emit). */
-  treeChangedListenerCount(): number {
-    return this.#emitter.listenerCount(TREE_CHANGED);
-  }
-
-  sendStart(): void {
-    this.#fsm.send(routerEvents.START);
-  }
-
-  sendStop(): void {
-    this.#fsm.send(routerEvents.STOP);
-  }
-
-  sendDispose(): void {
-    this.#fsm.send(routerEvents.DISPOSE);
-  }
-
-  sendStarted(): void {
-    this.#fsm.send(routerEvents.STARTED);
-  }
-
-  sendNavigate(toState: State, fromState?: State): void {
-    this.#currentToState = toState;
-    // Bypass FSM dispatch — forceState + direct emit (no action lookup, no rest params)
-    this.#fsm.forceState(routerStates.TRANSITION_STARTED);
-    this.emitTransitionStart(toState, fromState);
-  }
-
-  sendComplete(
-    state: State,
-    fromState?: State,
-    opts: NavigationOptions = {},
-  ): void {
-    // Bypass FSM dispatch — forceState + direct emit
-    this.#fsm.forceState(routerStates.READY);
-    this.emitTransitionSuccess(state, fromState, opts);
-
-    if (this.#currentToState === state) {
-      this.#currentToState = undefined;
-    }
-  }
-
-  sendLeaveApprove(toState: State, fromState?: State): void {
-    // Bypass FSM dispatch — forceState + direct emit (no action lookup, no rest params)
-    this.#fsm.forceState(routerStates.LEAVE_APPROVED);
-    this.emitTransitionLeaveApprove(toState, fromState);
-  }
-
-  sendFail(toState?: State, fromState?: State, error?: unknown): void {
-    const prev = this.#currentToState;
-
-    this.#pendingToState = toState;
-    this.#pendingFromState = fromState;
-    this.#pendingError = error;
-    this.#fsm.send(routerEvents.FAIL);
-
-    if (this.#currentToState === prev) {
-      this.#currentToState = undefined;
-    }
-  }
-
-  sendFailSafe(toState?: State, fromState?: State, error?: unknown): void {
-    if (this.isReady()) {
-      this.sendFail(toState, fromState, error);
-    } else {
-      this.emitTransitionError(toState, fromState, error as RouterError);
-    }
-  }
-
-  sendCancel(toState: State, fromState?: State): void {
-    const prev = this.#currentToState;
-
-    this.#pendingToState = toState;
-    this.#pendingFromState = fromState;
-    this.#fsm.send(routerEvents.CANCEL);
-
-    if (this.#currentToState === prev) {
-      this.#currentToState = undefined;
-    }
-  }
-
-  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 fsmState = this.#fsm.getState();
-
-    return fsmState !== routerStates.IDLE && fsmState !== routerStates.DISPOSED;
-  }
-
-  isDisposed(): boolean {
-    return this.#fsm.getState() === routerStates.DISPOSED;
-  }
-
-  isTransitioning(): boolean {
-    const state = this.#fsm.getState();
-
-    return (
-      state === routerStates.TRANSITION_STARTED ||
-      state === routerStates.LEAVE_APPROVED
-    );
-  }
-
-  isLeaveApproved(): boolean {
-    return this.#fsm.getState() === routerStates.LEAVE_APPROVED;
-  }
-
-  isReady(): boolean {
-    return this.#fsm.getState() === routerStates.READY;
-  }
-
-  isStarting(): boolean {
-    return this.#fsm.getState() === routerStates.STARTING;
-  }
-
-  getCurrentToState(): State | undefined {
-    return this.#currentToState;
-  }
-
-  /**
-   * Plugin-author API for subscribing to internal router events.
-   *
-   * @remarks
-   *
-   * **Duplicate-registration semantics — strict (throws).** Passing the same
-   * callback reference twice for the same event throws
-   * `Error("Duplicate listener for ...")` from the underlying `EventEmitter`.
-   * This is loud-on-misuse by design: plugin code is expected to register
-   * each callback once. The contract differs from {@link subscribe} /
-   * {@link subscribeLeave}, which are end-user surfaces and silently accept
-   * duplicates.
-   */
-  addEventListener<E extends EventName>(
-    eventName: E,
-    cb: Plugin[EventMethodMap[E]],
-  ): Unsubscribe {
-    return this.#emitter.on(
-      eventName,
-      cb as (...args: RouterEventMap[typeof eventName]) => void,
-    );
-  }
-
-  /**
-   * End-user / UI-binding API for subscribing to successful transitions.
-   *
-   * @remarks
-   *
-   * **Duplicate-registration semantics — independent.** Each call wraps
-   * `listener` in a fresh closure and registers it as a distinct internal
-   * slot. `router.subscribe(fn)` twice produces **two** active subscriptions;
-   * `fn` fires twice per `TRANSITION_SUCCESS`. The returned `Unsubscribe` is
-   * paired with its specific call — invoking it removes exactly that
-   * registration.
-   *
-   * This contract differs from {@link addEventListener} (plugin API, throws
-   * on duplicate). End-user code that wants idempotent registration must
-   * gate itself, e.g. `if (!unsub) unsub = router.subscribe(fn);`.
-   */
-  subscribe(listener: SubscribeFn): Unsubscribe {
-    return this.#emitter.on(
-      events.TRANSITION_SUCCESS,
-      (toState: State, fromState?: State) => {
-        listener({ route: toState, previousRoute: fromState });
-      },
-    );
-  }
-
-  /**
-   * End-user / UI-binding API for subscribing to confirmed route departures
-   * (`LEAVE_APPROVED` phase). Async listeners block the activation phase.
-   *
-   * @remarks
-   *
-   * **Duplicate-registration semantics — independent (with internal quirk).**
-   * Each call pushes `listener` onto the internal array; `router.subscribeLeave(fn)`
-   * twice produces two array entries. `fn` fires **once** per leave when
-   * iteration snapshots the array (a snapshot is taken on entry to
-   * `awaitLeaveListeners`), but the function reference is invoked once per
-   * array slot — so in practice the wrapper fires twice through the same
-   * closure (no observable difference for stateless `fn`).
-   *
-   * The returned `Unsubscribe` removes the **first** array entry matching the
-   * function reference (`indexOf` semantic), not the most recently added one.
-   * Net effect of N subscribes + M unsubscribes is correct (N - M entries
-   * remain), but the specific physical entry that survives is reverse of the
-   * unsubscribe-call order. Irrelevant in practice — the function reference
-   * is the same; observable behaviour is identical regardless of which
-   * physical entry is removed.
-   *
-   * Contract differs from {@link addEventListener} (throws on duplicate).
-   * For idempotent registration, gate at the call site.
-   */
-  subscribeLeave(listener: LeaveFn): Unsubscribe {
-    this.#leaveListeners.push(listener);
-
-    return () => {
-      const idx = this.#leaveListeners.indexOf(listener);
-
-      if (idx !== -1) {
-        this.#leaveListeners.splice(idx, 1);
-      }
-    };
-  }
-
-  hasLeaveListeners(): boolean {
-    return this.#leaveListeners.length > 0;
-  }
-
-  awaitLeaveListeners(
-    toState: State,
-    fromState: State | undefined,
-    signal: AbortSignal,
-  ): Promise<void> | undefined {
-    if (fromState === undefined) {
-      return undefined;
-    }
-
-    // Freeze the payload wrapper so listeners cannot mutate it (`payload.route`
-    // is already deep-frozen via the State immutability invariant; this closes
-    // the wrapper-mutation gap surfaced by audit `probe-05-payload-frozen`).
-    const leaveState: LeaveState = Object.freeze({
-      route: fromState,
-      nextRoute: toState,
-      signal,
-    });
-
-    let promises: Promise<void>[] | undefined;
-    let firstSyncError: unknown;
-
-    // Snapshot before iteration — a listener that reentrantly calls
-    // `subscribeLeave(newFn)` or its own `unsubscribe()` must not affect the
-    // current emit cycle. Symmetric with the EventEmitter snapshot invariant
-    // (PR #666 / #659). Use `Array.from` rather than `[...array]` to keep the
-    // intent explicit (some lint rules treat spread-of-own-array as
-    // redundant and silently revert it).
-    const snapshot = [...this.#leaveListeners];
-
-    for (const listener of snapshot) {
-      try {
-        const result = listener(leaveState);
-
-        if (result !== undefined && typeof result.then === "function") {
-          promises ??= [];
-          promises.push(result);
-        }
-      } catch (error: unknown) {
-        if (firstSyncError === undefined) {
-          firstSyncError = error;
-        }
-      }
-    }
-
-    if (promises === undefined) {
-      if (firstSyncError !== undefined) {
-        throw ensureError(firstSyncError);
-      }
-
-      return undefined;
-    }
-
-    return settleLeavePromises(promises, firstSyncError, signal);
-  }
-
-  clearAll(): void {
-    this.#emitter.clearAll();
-    this.#leaveListeners.length = 0;
-  }
-
-  setLimits(limits: {
-    maxListeners: number;
-    warnListeners: number;
-    maxEventDepth: number;
-  }): void {
-    this.#emitter.setLimits(limits);
-  }
-
-  sendCancelIfPossible(fromState: State | undefined): void {
-    const toState = this.#currentToState;
-
-    if (!this.canCancel() || toState === undefined) {
-      return;
-    }
-
-    this.sendCancel(toState, fromState);
-  }
-
-  #emitPendingError(): void {
-    this.emitTransitionError(
-      this.#pendingToState,
-      this.#pendingFromState,
-      this.#pendingError as RouterError | undefined,
-    );
-  }
-
-  #setupFSMActions(): void {
-    const fsm = this.#fsm;
-
-    fsm.on(routerStates.STARTING, routerEvents.STARTED, () => {
-      this.emitRouterStart();
-    });
-
-    fsm.on(routerStates.READY, routerEvents.STOP, () => {
-      this.emitRouterStop();
-    });
-
-    // NAVIGATE and COMPLETE actions bypassed — sendNavigate/sendComplete
-    // use fsm.forceState() + direct emit for zero-allocation hot path.
-    const handleCancel = () => {
-      const toState = this.#pendingToState;
-
-      /* v8 ignore next -- @preserve: #pendingToState guaranteed set by sendCancel before send() */
-      if (toState === undefined) {
-        return;
-      }
-
-      this.emitTransitionCancel(toState, this.#pendingFromState);
-    };
-
-    fsm.on(routerStates.TRANSITION_STARTED, routerEvents.CANCEL, handleCancel);
-    fsm.on(routerStates.LEAVE_APPROVED, routerEvents.CANCEL, handleCancel);
-
-    fsm.on(routerStates.LEAVE_APPROVED, routerEvents.FAIL, () => {
-      this.#emitPendingError();
-    });
-
-    fsm.on(routerStates.STARTING, routerEvents.FAIL, () => {
-      this.#emitPendingError();
-    });
-
-    fsm.on(routerStates.READY, routerEvents.FAIL, () => {
-      this.#emitPendingError();
-    });
-
-    fsm.on(routerStates.TRANSITION_STARTED, routerEvents.FAIL, () => {
-      this.#emitPendingError();
-    });
-  }
-}

package/src/namespaces/EventBusNamespace/index.ts

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

package/src/namespaces/EventBusNamespace/types.ts

@@ -1,11 +0,0 @@
-// 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>;
-}