@real-router/core 0.22.0 → 0.23.0

package/src/types.ts

@@ -0,0 +1,194 @@
+// packages/core/src/types.ts
+
+/**
+ * Router-dependent types.
+ *
+ * These types reference the Router class and are therefore defined in core
+ * rather than core-types to avoid circular dependencies.
+ */
+
+import type { events, plugins } from "./constants";
+import type { Router } from "./Router";
+import type {
+  ActivationFn,
+  DefaultDependencies,
+  EventsKeys,
+  ForwardToCallback,
+  LimitsConfig,
+  Middleware,
+  NavigationOptions,
+  Params,
+  Plugin,
+  RouterError as RouterErrorType,
+  RouteTreeState,
+  State,
+} from "@real-router/types";
+
+export type EventMethodMap = {
+  [K in EventsKeys as (typeof events)[K]]: (typeof plugins)[K];
+};
+
+/**
+ * Event argument tuples for the router's 6 events.
+ *
+ * Uses explicit `| undefined` unions (not optional `?`) to satisfy
+ * `exactOptionalPropertyTypes` when passing undefined args from FSM payloads.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- must be `type` for Record<string, unknown[]> constraint
+export type RouterEventMap = {
+  $start: [];
+  $stop: [];
+  $$start: [toState: State, fromState: State | undefined];
+  $$success: [
+    toState: State,
+    fromState: State | undefined,
+    opts: NavigationOptions | undefined,
+  ];
+  $$error: [
+    toState: State | undefined,
+    fromState: State | undefined,
+    error: RouterErrorType | undefined,
+  ];
+  $$cancel: [toState: State, fromState: State | undefined];
+};
+
+/**
+ * Immutable limits configuration type.
+ */
+export type Limits = Readonly<LimitsConfig>;
+
+/**
+ * Extended build result that includes segments for path building.
+ * Used internally to avoid duplicate getSegmentsByName calls.
+ *
+ * @param segments - Route segments from getSegmentsByName (typed as unknown[] for cross-package compatibility)
+ * @internal
+ */
+export interface BuildStateResultWithSegments<P extends Params = Params> {
+  readonly state: RouteTreeState<P>;
+  readonly segments: readonly unknown[];
+}
+
+/**
+ * Route configuration.
+ */
+export interface Route<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  [key: string]: unknown;
+  /** Route name (dot-separated for nested routes). */
+  name: string;
+  /** URL path pattern for this route. */
+  path: string;
+  /** Factory function that returns a guard for route activation. */
+  canActivate?: ActivationFnFactory<Dependencies>;
+  /** Factory function that returns a guard for route deactivation. */
+  canDeactivate?: ActivationFnFactory<Dependencies>;
+  /**
+   * Redirects navigation to another route.
+   *
+   * IMPORTANT: forwardTo creates a URL alias, not a transition chain.
+   * Guards (canActivate) on the source route are NOT executed.
+   * Only guards on the final destination are executed.
+   *
+   * This matches Vue Router and Angular Router behavior.
+   *
+   * @example
+   * // Correct: guard on target
+   * { name: "old", path: "/old", forwardTo: "new" }
+   * { name: "new", path: "/new", canActivate: myGuard }
+   *
+   * // Wrong: guard on source (will be ignored with warning)
+   * { name: "old", path: "/old", forwardTo: "new", canActivate: myGuard }
+   */
+  forwardTo?: string | ForwardToCallback<Dependencies>;
+  /** Nested child routes. */
+  children?: Route<Dependencies>[];
+  /** Encodes state params to URL params. */
+  encodeParams?: (stateParams: Params) => Params;
+  /** Decodes URL params to state params. */
+  decodeParams?: (pathParams: Params) => Params;
+  /**
+   * Default parameters for this route.
+   *
+   * @remarks
+   * **Type Contract:**
+   * The type of defaultParams MUST match the expected params type P
+   * when using `router.makeState<P>()` or `router.navigate<P>()`.
+   *
+   * These values are merged into state.params when creating route states.
+   * Missing URL params are filled from defaultParams.
+   *
+   * @example
+   * ```typescript
+   * // Define route with pagination defaults
+   * {
+   *   name: "users",
+   *   path: "/users",
+   *   defaultParams: { page: 1, limit: 10 }
+   * }
+   *
+   * // Navigate without specifying page/limit
+   * router.navigate("users", { filter: "active" });
+   * // Result: state.params = { page: 1, limit: 10, filter: "active" }
+   *
+   * // Correct typing — include defaultParams properties
+   * type UsersParams = { page: number; limit: number; filter?: string };
+   * ```
+   */
+  defaultParams?: Params;
+}
+
+/**
+ * Configuration update options for updateRoute().
+ * All properties are optional. Set to null to remove the configuration.
+ */
+export interface RouteConfigUpdate<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  /** Set to null to remove forwardTo */
+  forwardTo?: string | ForwardToCallback<Dependencies> | null;
+  /** Set to null to remove defaultParams */
+  defaultParams?: Params | null;
+  /** Set to null to remove decoder */
+  decodeParams?: ((params: Params) => Params) | null;
+  /** Set to null to remove encoder */
+  encodeParams?: ((params: Params) => Params) | null;
+  /** Set to null to remove canActivate */
+  canActivate?: ActivationFnFactory<Dependencies> | null;
+  /** Set to null to remove canDeactivate */
+  canDeactivate?: ActivationFnFactory<Dependencies> | null;
+}
+
+/**
+ * Factory function for creating activation guards.
+ * Receives the router instance and a dependency getter.
+ */
+export type ActivationFnFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
+) => ActivationFn;
+
+/**
+ * Factory function for creating middleware.
+ * Receives the router instance and a dependency getter.
+ */
+export type MiddlewareFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
+) => Middleware;
+
+/**
+ * Factory function for creating plugins.
+ * Receives the router instance and a dependency getter.
+ */
+export type PluginFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
+) => Plugin;

package/src/wiring/RouterWiringBuilder.ts

@@ -0,0 +1,235 @@
+// packages/core/src/wiring/RouterWiringBuilder.ts
+
+import type { EventBusNamespace } from "../namespaces";
+import type { WiringOptions } from "./types";
+import type { MiddlewareDependencies } from "../namespaces/MiddlewareNamespace";
+import type {
+  NavigationDependencies,
+  TransitionDependencies,
+} from "../namespaces/NavigationNamespace";
+import type { PluginsDependencies } from "../namespaces/PluginsNamespace";
+import type { RouteLifecycleDependencies } from "../namespaces/RouteLifecycleNamespace";
+import type { RouterLifecycleDependencies } from "../namespaces/RouterLifecycleNamespace";
+import type { RoutesDependencies } from "../namespaces/RoutesNamespace";
+import type { DefaultDependencies } from "@real-router/types";
+
+export class RouterWiringBuilder<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  private readonly router: WiringOptions<Dependencies>["router"];
+  private readonly options: WiringOptions<Dependencies>["options"];
+  private readonly limits: WiringOptions<Dependencies>["limits"];
+  private readonly dependencies: WiringOptions<Dependencies>["dependencies"];
+  private readonly state: WiringOptions<Dependencies>["state"];
+  private readonly routes: WiringOptions<Dependencies>["routes"];
+  private readonly routeLifecycle: WiringOptions<Dependencies>["routeLifecycle"];
+  private readonly middleware: WiringOptions<Dependencies>["middleware"];
+  private readonly plugins: WiringOptions<Dependencies>["plugins"];
+  private readonly navigation: WiringOptions<Dependencies>["navigation"];
+  private readonly lifecycle: WiringOptions<Dependencies>["lifecycle"];
+  private readonly clone: WiringOptions<Dependencies>["clone"];
+  private readonly eventBus: EventBusNamespace;
+
+  constructor(wiringOptions: WiringOptions<Dependencies>) {
+    this.router = wiringOptions.router;
+    this.options = wiringOptions.options;
+    this.limits = wiringOptions.limits;
+    this.dependencies = wiringOptions.dependencies;
+    this.state = wiringOptions.state;
+    this.routes = wiringOptions.routes;
+    this.routeLifecycle = wiringOptions.routeLifecycle;
+    this.middleware = wiringOptions.middleware;
+    this.plugins = wiringOptions.plugins;
+    this.navigation = wiringOptions.navigation;
+    this.lifecycle = wiringOptions.lifecycle;
+    this.clone = wiringOptions.clone;
+    this.eventBus = wiringOptions.eventBus;
+  }
+
+  wireLimits(): void {
+    this.dependencies.setLimits(this.limits);
+    this.plugins.setLimits(this.limits);
+    this.middleware.setLimits(this.limits);
+    this.eventBus.setLimits({
+      maxListeners: this.limits.maxListeners,
+      warnListeners: this.limits.warnListeners,
+      maxEventDepth: this.limits.maxEventDepth,
+    });
+    this.routeLifecycle.setLimits(this.limits);
+  }
+
+  wireRouteLifecycleDeps(): void {
+    this.routeLifecycle.setRouter(this.router);
+
+    const routeLifecycleDeps: RouteLifecycleDependencies<Dependencies> = {
+      getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
+        this.dependencies.get(dependencyName),
+    };
+
+    this.routeLifecycle.setDependencies(routeLifecycleDeps);
+  }
+
+  wireRoutesDeps(): void {
+    const routesDeps: RoutesDependencies<Dependencies> = {
+      addActivateGuard: (name, handler) => {
+        this.router.addActivateGuard(name, handler);
+      },
+      addDeactivateGuard: (name, handler) => {
+        this.router.addDeactivateGuard(name, handler);
+      },
+      makeState: (name, params, path, meta) =>
+        this.state.makeState(name, params, path, meta),
+      getState: () => this.state.get(),
+      areStatesEqual: (state1, state2, ignoreQueryParams) =>
+        this.state.areStatesEqual(state1, state2, ignoreQueryParams),
+      getDependency: (name) => this.dependencies.get(name),
+      forwardState: (name, params) => this.router.forwardState(name, params),
+    };
+
+    this.routes.setDependencies(routesDeps);
+    this.routes.setLifecycleNamespace(this.routeLifecycle);
+  }
+
+  wireMiddlewareDeps(): void {
+    this.middleware.setRouter(this.router);
+
+    const middlewareDeps: MiddlewareDependencies<Dependencies> = {
+      getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
+        this.dependencies.get(dependencyName),
+    };
+
+    this.middleware.setDependencies(middlewareDeps);
+  }
+
+  wirePluginsDeps(): void {
+    this.plugins.setRouter(this.router);
+
+    const pluginsDeps: PluginsDependencies<Dependencies> = {
+      addEventListener: (eventName, cb) =>
+        this.eventBus.addEventListener(eventName, cb),
+      canNavigate: () => this.eventBus.canBeginTransition(),
+      getDependency: <K extends keyof Dependencies>(dependencyName: K) =>
+        this.dependencies.get(dependencyName),
+    };
+
+    this.plugins.setDependencies(pluginsDeps);
+  }
+
+  wireNavigationDeps(): void {
+    const navigationDeps: NavigationDependencies = {
+      getOptions: () => this.options.get(),
+      hasRoute: (name) => this.routes.hasRoute(name),
+      getState: () => this.state.get(),
+      setState: (state) => {
+        this.state.set(state);
+      },
+      buildStateWithSegments: (routeName, routeParams) => {
+        const { name, params } = this.router.forwardState(
+          routeName,
+          routeParams,
+        );
+
+        return this.routes.buildStateWithSegmentsResolved(name, params);
+      },
+      makeState: (name, params, path, meta) =>
+        this.state.makeState(name, params, path, meta),
+      buildPath: (route, params) =>
+        this.routes.buildPath(route, params, this.options.get()),
+      areStatesEqual: (state1, state2, ignoreQueryParams) =>
+        this.state.areStatesEqual(state1, state2, ignoreQueryParams),
+      getDependency: (name: string) =>
+        this.dependencies.get(name as keyof Dependencies),
+      startTransition: (toState, fromState) => {
+        this.eventBus.beginTransition(toState, fromState);
+      },
+      cancelNavigation: () => {
+        this.eventBus.cancelTransition(
+          this.eventBus.getCurrentToState()!, // eslint-disable-line @typescript-eslint/no-non-null-assertion -- guaranteed set before TRANSITIONING
+          this.state.get(),
+        );
+      },
+      sendTransitionDone: (state, fromState, opts) => {
+        this.eventBus.completeTransition(state, fromState, opts);
+      },
+      sendTransitionBlocked: (toState, fromState, error) => {
+        this.eventBus.failTransition(toState, fromState, error);
+      },
+      sendTransitionError: (toState, fromState, error) => {
+        this.eventBus.failTransition(toState, fromState, error);
+      },
+      emitTransitionError: (toState, fromState, error) => {
+        this.eventBus.emitOrFailTransitionError(toState, fromState, error);
+      },
+    };
+
+    this.navigation.setDependencies(navigationDeps);
+
+    const transitionDeps: TransitionDependencies = {
+      getLifecycleFunctions: () => this.routeLifecycle.getFunctions(),
+      getMiddlewareFunctions: () => this.middleware.getFunctions(),
+      isActive: () => this.router.isActive(),
+      isTransitioning: () => this.eventBus.isTransitioning(),
+      clearCanDeactivate: (name) => {
+        this.routeLifecycle.clearCanDeactivate(name);
+      },
+    };
+
+    this.navigation.setTransitionDependencies(transitionDeps);
+  }
+
+  wireLifecycleDeps(): void {
+    const lifecycleDeps: RouterLifecycleDependencies = {
+      getOptions: () => this.options.get(),
+      makeNotFoundState: (path, options) =>
+        this.state.makeNotFoundState(path, options),
+      setState: (state) => {
+        this.state.set(state);
+      },
+      matchPath: (path) => this.routes.matchPath(path, this.options.get()),
+      completeStart: () => {
+        this.eventBus.completeStart();
+      },
+      emitTransitionError: (toState, fromState, error) => {
+        this.eventBus.failTransition(toState, fromState, error);
+      },
+    };
+
+    this.lifecycle.setDependencies(lifecycleDeps);
+  }
+
+  wireStateDeps(): void {
+    this.state.setDependencies({
+      getDefaultParams: () => this.routes.getConfig().defaultParams,
+      buildPath: (name, params) =>
+        this.routes.buildPath(name, params, this.options.get()),
+      getUrlParams: (name) => this.routes.getUrlParams(name),
+    });
+  }
+
+  wireCloneCallbacks(): void {
+    this.clone.setGetCloneData(() => {
+      const [canDeactivateFactories, canActivateFactories] =
+        this.routeLifecycle.getFactories();
+
+      return {
+        routes: this.routes.cloneRoutes(),
+        options: { ...this.options.get() },
+        dependencies: this.dependencies.getAll(),
+        canDeactivateFactories,
+        canActivateFactories,
+        middlewareFactories: this.middleware.getFactories(),
+        pluginFactories: this.plugins.getAll(),
+        routeConfig: this.routes.getConfig(),
+        resolvedForwardMap: this.routes.getResolvedForwardMap(),
+      };
+    });
+  }
+
+  wireCyclicDeps(): void {
+    this.navigation.setCanNavigate(() => this.eventBus.canBeginTransition());
+
+    this.lifecycle.setNavigateToState((toState, fromState, opts) =>
+      this.navigation.navigateToState(toState, fromState, opts),
+    );
+  }
+}

package/src/wiring/index.ts

@@ -0,0 +1,7 @@
+// packages/core/src/wiring/index.ts
+
+export { RouterWiringBuilder } from "./RouterWiringBuilder";
+
+export { wireRouter } from "./wireRouter";
+
+export type { WiringOptions } from "./types";

package/src/wiring/types.ts

@@ -0,0 +1,53 @@
+// packages/core/src/wiring/types.ts
+
+import type {
+  CloneNamespace,
+  DependenciesNamespace,
+  EventBusNamespace,
+  MiddlewareNamespace,
+  NavigationNamespace,
+  OptionsNamespace,
+  PluginsNamespace,
+  RouteLifecycleNamespace,
+  RouterLifecycleNamespace,
+  RoutesNamespace,
+  StateNamespace,
+} from "../namespaces";
+import type { Router } from "../Router";
+import type { Limits } from "../types";
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Constructor options bag for RouterWiringBuilder.
+ *
+ * Contains all namespaces, FSM, emitter, and accessors needed to wire
+ * inter-namespace dependencies.
+ */
+export interface WiringOptions<Dependencies extends DefaultDependencies> {
+  /** Router instance — passed to namespaces for factory initialization */
+  router: Router<Dependencies>;
+  /** Options namespace */
+  options: OptionsNamespace;
+  /** Immutable limits configuration */
+  limits: Limits;
+  /** Dependencies namespace */
+  dependencies: DependenciesNamespace<Dependencies>;
+  /** State namespace */
+  state: StateNamespace;
+  /** Routes namespace */
+  routes: RoutesNamespace<Dependencies>;
+  /** Route lifecycle namespace (canActivate/canDeactivate guards) */
+  routeLifecycle: RouteLifecycleNamespace<Dependencies>;
+  /** Middleware namespace */
+  middleware: MiddlewareNamespace<Dependencies>;
+  /** Plugins namespace */
+  plugins: PluginsNamespace<Dependencies>;
+  /** Navigation namespace */
+  navigation: NavigationNamespace;
+  /** Router lifecycle namespace (start/stop) */
+  lifecycle: RouterLifecycleNamespace;
+  /** Clone namespace (SSR cloning) */
+  clone: CloneNamespace<Dependencies>;
+  /** EventBus namespace — unified FSM + EventEmitter abstraction */
+  eventBus: EventBusNamespace;
+}

package/src/wiring/wireRouter.ts

@@ -0,0 +1,29 @@
+// packages/core/src/wiring/wireRouter.ts
+
+import type { RouterWiringBuilder } from "./RouterWiringBuilder";
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Director function — calls RouterWiringBuilder methods in the correct dependency order.
+ *
+ * ORDER MATTERS:
+ * - `wireLimits()` first: all namespaces must have limits before any other setup
+ * - `wireRouteLifecycleDeps()` BEFORE `wireRoutesDeps()`: RoutesNamespace.setDependencies()
+ *   registers pending canActivate handlers which require RouteLifecycleNamespace to be ready
+ * - `wireCyclicDeps()` LAST: resolves circular references between NavigationNamespace and
+ *   RouterLifecycleNamespace (they depend on each other via direct property assignment)
+ */
+export function wireRouter<Dependencies extends DefaultDependencies>(
+  builder: RouterWiringBuilder<Dependencies>,
+): void {
+  builder.wireLimits();
+  builder.wireRouteLifecycleDeps();
+  builder.wireRoutesDeps();
+  builder.wireMiddlewareDeps();
+  builder.wirePluginsDeps();
+  builder.wireNavigationDeps();
+  builder.wireLifecycleDeps();
+  builder.wireStateDeps();
+  builder.wireCloneCallbacks();
+  builder.wireCyclicDeps();
+}