@real-router/core 0.45.1 → 0.45.3

package/src/createRouter.ts

@@ -0,0 +1,32 @@
+// packages/core/src/createRouter.ts
+
+import { Router } from "./Router";
+
+import type { Route } from "./types";
+import type { DefaultDependencies, Options } from "@real-router/types";
+
+/**
+ * Creates a new router instance.
+ *
+ * @param routes - Array of route definitions
+ * @param options - Router configuration options
+ * @param dependencies - Dependencies to inject into the router
+ * @returns A new Router instance
+ *
+ * @example
+ * const router = createRouter([
+ *   { name: 'home', path: '/' },
+ *   { name: 'users', path: '/users' },
+ * ]);
+ *
+ * router.start('/');
+ */
+export const createRouter = <
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routes: Route<Dependencies>[] = [],
+  options: Partial<Options> = {},
+  dependencies: Dependencies = {} as Dependencies,
+): Router<Dependencies> => {
+  return new Router<Dependencies>(routes, options, dependencies);
+};

package/src/fsm/index.ts

@@ -0,0 +1,5 @@
+// packages/core/src/fsm/index.ts
+
+export { createRouterFSM, routerStates, routerEvents } from "./routerFSM";
+
+export type { RouterEvent, RouterPayloads, RouterState } from "./routerFSM";

package/src/fsm/routerFSM.ts

@@ -0,0 +1,120 @@
+// packages/core/src/fsm/routerFSM.ts
+
+import { FSM } from "@real-router/fsm";
+
+import type { FSMConfig } from "@real-router/fsm";
+
+/**
+ * Router FSM states.
+ *
+ * - IDLE: Router not started or stopped
+ * - STARTING: Router is initializing
+ * - READY: Router is ready for navigation
+ * - TRANSITION_STARTED: Navigation in progress (before deactivation guards)
+ * - LEAVE_APPROVED: Deactivation guards passed, activation guards pending
+ * - DISPOSED: Router has been disposed (R2+)
+ */
+export const routerStates = {
+  IDLE: "IDLE",
+  STARTING: "STARTING",
+  READY: "READY",
+  TRANSITION_STARTED: "TRANSITION_STARTED",
+  LEAVE_APPROVED: "LEAVE_APPROVED",
+  DISPOSED: "DISPOSED",
+} as const;
+
+export type RouterState = (typeof routerStates)[keyof typeof routerStates];
+
+/**
+ * Router FSM events.
+ *
+ * - START: Begin router initialization
+ * - STARTED: Router initialization complete
+ * - NAVIGATE: Begin navigation
+ * - COMPLETE: Navigation completed successfully
+ * - FAIL: Navigation or initialization failed
+ * - CANCEL: Navigation cancelled
+ * - STOP: Stop router
+ * - DISPOSE: Dispose router (R2+)
+ */
+export const routerEvents = {
+  START: "START",
+  STARTED: "STARTED",
+  NAVIGATE: "NAVIGATE",
+  LEAVE_APPROVE: "LEAVE_APPROVE",
+  COMPLETE: "COMPLETE",
+  FAIL: "FAIL",
+  CANCEL: "CANCEL",
+  STOP: "STOP",
+  DISPOSE: "DISPOSE",
+} as const;
+
+export type RouterEvent = (typeof routerEvents)[keyof typeof routerEvents];
+
+/**
+ * Typed payloads for router FSM events.
+ *
+ * Events without entries have no payload.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- payloads stored in EventBusNamespace fields (N8+N9 optimization)
+export interface RouterPayloads {}
+
+/**
+ * Router FSM configuration.
+ *
+ * Transitions:
+ * - IDLE → STARTING (START), DISPOSED (DISPOSE)
+ * - STARTING → READY (STARTED), IDLE (FAIL)
+ * - READY → TRANSITION_STARTED (NAVIGATE), READY (FAIL, self-loop for early validation errors), IDLE (STOP)
+ * - TRANSITION_STARTED → LEAVE_APPROVED (LEAVE_APPROVE), TRANSITION_STARTED (NAVIGATE, self-loop), READY (CANCEL, FAIL)
+ * - LEAVE_APPROVED → READY (COMPLETE, CANCEL, FAIL), TRANSITION_STARTED (NAVIGATE)
+ * - DISPOSED → (no transitions)
+ */
+const routerFSMConfig: FSMConfig<RouterState, RouterEvent, null> = {
+  initial: routerStates.IDLE,
+  context: null,
+  transitions: {
+    [routerStates.IDLE]: {
+      [routerEvents.START]: routerStates.STARTING,
+      [routerEvents.DISPOSE]: routerStates.DISPOSED,
+    },
+    [routerStates.STARTING]: {
+      [routerEvents.STARTED]: routerStates.READY,
+      [routerEvents.FAIL]: routerStates.IDLE,
+    },
+    [routerStates.READY]: {
+      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
+      [routerEvents.FAIL]: routerStates.READY,
+      [routerEvents.STOP]: routerStates.IDLE,
+    },
+    [routerStates.TRANSITION_STARTED]: {
+      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
+      [routerEvents.LEAVE_APPROVE]: routerStates.LEAVE_APPROVED,
+      [routerEvents.CANCEL]: routerStates.READY,
+      [routerEvents.FAIL]: routerStates.READY,
+    },
+    [routerStates.LEAVE_APPROVED]: {
+      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
+      [routerEvents.COMPLETE]: routerStates.READY,
+      [routerEvents.CANCEL]: routerStates.READY,
+      [routerEvents.FAIL]: routerStates.READY,
+    },
+    [routerStates.DISPOSED]: {},
+  },
+};
+
+/**
+ * Factory function to create a router FSM instance.
+ *
+ * @returns FSM instance with initial state "IDLE"
+ */
+export function createRouterFSM(): FSM<
+  RouterState,
+  RouterEvent,
+  null,
+  RouterPayloads
+> {
+  return new FSM<RouterState, RouterEvent, null, RouterPayloads>(
+    routerFSMConfig,
+  );
+}

package/src/getNavigator.ts

@@ -0,0 +1,30 @@
+import type {
+  Navigator,
+  DefaultDependencies,
+  Router,
+} from "@real-router/types";
+
+const cache = new WeakMap<Router, Navigator>();
+
+export const getNavigator = <
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  router: Router<Dependencies>,
+): Navigator => {
+  let nav = cache.get(router);
+
+  if (!nav) {
+    nav = Object.freeze({
+      navigate: router.navigate,
+      getState: router.getState,
+      isActiveRoute: router.isActiveRoute,
+      canNavigateTo: router.canNavigateTo,
+      subscribe: router.subscribe,
+      subscribeLeave: router.subscribeLeave,
+      isLeaveApproved: router.isLeaveApproved,
+    } as Navigator);
+    cache.set(router, nav);
+  }
+
+  return nav;
+};

package/src/guards.ts

@@ -0,0 +1,46 @@
+// packages/core/src/guards.ts
+
+import type { Route } from "./types";
+import type { RouterValidator } from "./types/RouterValidator";
+
+export function guardDependencies(deps: unknown): void {
+  if (
+    !deps ||
+    typeof deps !== "object" ||
+    (deps as { constructor: unknown }).constructor !== Object
+  ) {
+    throw new TypeError("dependencies must be a plain object");
+  }
+  for (const key in deps as Record<string, unknown>) {
+    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
+      throw new TypeError(`dependencies cannot contain getters: "${key}"`);
+    }
+  }
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- accepts any Route type */
+export function guardRouteStructure(
+  routes: Route<any>[],
+  validator?: RouterValidator | null,
+): void {
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+  for (const route of routes) {
+    const routeValue: unknown = route;
+
+    if (
+      routeValue === null ||
+      typeof routeValue !== "object" ||
+      Array.isArray(routeValue)
+    ) {
+      throw new TypeError("route must be a non-array object");
+    }
+
+    validator?.routes.guardRouteCallbacks(route as Route);
+    validator?.routes.guardNoAsyncCallbacks(route as Route);
+    const children = (route as Route).children;
+
+    if (children) {
+      guardRouteStructure(children, validator);
+    }
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,179 @@
+// packages/core/src/helpers.ts
+
+import { DEFAULT_LIMITS } from "./constants";
+
+import type { Limits } from "./types";
+import type { State, LimitsConfig } from "@real-router/types";
+
+// =============================================================================
+// State Helpers
+// =============================================================================
+
+/**
+ * Structural type guard for State object.
+ * Only checks required fields exist with correct types.
+ * Does NOT validate params serializability (allows circular refs).
+ *
+ * Use `isState` from type-guards for full validation (serializable params).
+ * Use this for internal operations like deepFreezeState that handle any object structure.
+ *
+ * @param value - Value to check
+ * @returns true if value has State structure
+ * @internal
+ */
+function isStateStructural(value: unknown): value is State {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  return (
+    typeof obj.name === "string" &&
+    typeof obj.path === "string" &&
+    typeof obj.params === "object" &&
+    obj.params !== null
+  );
+}
+
+/**
+ * Deep freezes State object to prevent mutations.
+ * Creates a deep clone first, then recursively freezes the clone and all nested objects.
+ * Uses simple recursive freezing after cloning (no need for WeakSet since clone has no circular refs).
+ *
+ * @param state - The State object to freeze
+ * @returns A frozen deep clone of the state
+ * @throws {TypeError} If state is not a valid State object
+ *
+ * @example
+ * const state = { name: 'home', params: {}, path: '/' };
+ * const frozen = deepFreezeState(state);
+ * // frozen.params is now immutable
+ * // original state is unchanged
+ */
+export function deepFreezeState<T extends State>(state: T): T {
+  // Early return for null/undefined
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!state) {
+    return state;
+  }
+
+  // Validate State structure (structural check, allows circular refs)
+  if (!isStateStructural(state)) {
+    throw new TypeError(
+      `[deepFreezeState] Expected valid State object, got: ${typeof state}`,
+    );
+  }
+
+  // Create a deep clone to avoid mutating the original
+  // structuredClone preserves circular references, so we need to track visited objects
+  const clonedState = structuredClone(state);
+
+  // WeakSet to track visited objects (prevent infinite recursion with circular refs)
+  const visited = new WeakSet<object>();
+
+  // Recursive freeze function with circular reference protection
+  function freezeClonedRecursive(obj: unknown): void {
+    // Skip primitives, null, undefined
+    // Note: typeof undefined === "undefined" !== "object", so checking undefined is redundant
+    if (obj === null || typeof obj !== "object") {
+      return;
+    }
+
+    // Skip already visited objects (circular reference protection)
+    if (visited.has(obj)) {
+      return;
+    }
+
+    // Mark as visited
+    visited.add(obj);
+
+    // Freeze the object/array itself
+    Object.freeze(obj);
+
+    // Iterate without Object.values() allocation
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        freezeClonedRecursive(item);
+      }
+    } else {
+      for (const key in obj) {
+        freezeClonedRecursive((obj as Record<string, unknown>)[key]);
+      }
+    }
+  }
+
+  // Freeze the entire cloned state tree
+  freezeClonedRecursive(clonedState);
+
+  return clonedState;
+}
+
+// WeakSet to track already frozen root objects for O(1) re-freeze check
+const frozenRoots = new WeakSet<object>();
+
+// Module-scope recursive freeze function - better JIT optimization, no allocation per call
+function freezeRecursive(obj: unknown): void {
+  // Skip primitives, null
+  if (obj === null || typeof obj !== "object") {
+    return;
+  }
+
+  // Skip already frozen objects (handles potential shared refs)
+  if (Object.isFrozen(obj)) {
+    return;
+  }
+
+  // Freeze the object/array
+  Object.freeze(obj);
+
+  // Iterate without Object.values() allocation
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      freezeRecursive(item);
+    }
+  } else {
+    for (const key in obj) {
+      freezeRecursive((obj as Record<string, unknown>)[key]);
+    }
+  }
+}
+
+/**
+ * Freezes State object in-place without cloning.
+ * Optimized for hot paths where state is known to be a fresh object.
+ *
+ * IMPORTANT: Only use this when you know the state is a fresh object
+ * that hasn't been exposed to external code yet (e.g., from makeState()).
+ *
+ * @param state - The State object to freeze (must be a fresh object)
+ * @returns The same state object, now frozen
+ * @internal
+ */
+export function freezeStateInPlace<T extends State>(state: T): T {
+  // Early return for null/undefined - state from makeState() is never null
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!state) {
+    return state;
+  }
+
+  // Fast path: already processed root object - O(1) check
+  if (frozenRoots.has(state)) {
+    return state;
+  }
+
+  freezeRecursive(state);
+
+  // Mark root as processed for future calls
+  frozenRoots.add(state);
+
+  return state;
+}
+
+/**
+ * Merges user limits with defaults.
+ * Returns frozen object for immutability.
+ */
+export function createLimits(userLimits: Partial<LimitsConfig> = {}): Limits {
+  return { ...DEFAULT_LIMITS, ...userLimits };
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// packages/core/src/index.ts
+
+// Router-dependent types (re-exported from @real-router/types)
+
+export type {
+  BuildStateResultWithSegments,
+  GuardFnFactory,
+  PluginFactory,
+  Route,
+  RouteConfigUpdate,
+} from "./types";
+
+export type { RouterValidator } from "./types/RouterValidator";
+
+// Router class (replaces Router interface from core-types)
+export { Router } from "./Router";
+
+// Types (re-exported from core-types - no Router dependency)
+export type {
+  Config,
+  DefaultDependencies,
+  GuardFn,
+  Listener,
+  Navigator,
+  NavigationOptions,
+  Options,
+  Params,
+  Plugin,
+  SimpleState,
+  State,
+  SubscribeFn,
+  SubscribeState,
+  Subscription,
+  Unsubscribe,
+} from "@real-router/types";
+
+export type { ErrorCodes, Constants } from "./constants";
+
+export { events, constants, errorCodes, UNKNOWN_ROUTE } from "./constants";
+
+// RouterError class (migrated from router-error package)
+export { RouterError } from "./RouterError";
+
+export { createRouter } from "./createRouter";
+
+export { getNavigator } from "./getNavigator";
+
+export { resolveForwardChain } from "./namespaces/RoutesNamespace/forwardChain";
+
+export type { RouteTree } from "route-tree";

package/src/internals.ts

@@ -0,0 +1,173 @@
+import type { DependenciesStore } from "./namespaces/DependenciesNamespace";
+import type { RoutesStore } from "./namespaces/RoutesNamespace";
+import type { Router as RouterClass } from "./Router";
+import type { EventMethodMap, GuardFnFactory, PluginFactory } from "./types";
+import type { RouterValidator } from "./types/RouterValidator";
+import type {
+  DefaultDependencies,
+  EventName,
+  Options,
+  Params,
+  Plugin,
+  Router as RouterInterface,
+  RouteTreeState,
+  SimpleState,
+  State,
+  Unsubscribe,
+} from "@real-router/types";
+import type { RouteTree } from "route-tree";
+
+export interface RouterInternals<
+  D extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly makeState: <P extends Params = Params>(
+    name: string,
+    params?: P,
+    path?: string,
+    meta?: Record<string, Record<string, "url" | "query">>,
+  ) => State<P>;
+
+  readonly forwardState: <P extends Params = Params>(
+    routeName: string,
+    routeParams: P,
+  ) => SimpleState<P>;
+
+  readonly buildStateResolved: (
+    resolvedName: string,
+    resolvedParams: Params,
+  ) => RouteTreeState | undefined;
+
+  readonly matchPath: <P extends Params = Params>(
+    path: string,
+    options?: Options,
+  ) => State<P> | undefined;
+
+  readonly getOptions: () => Options;
+
+  readonly addEventListener: <E extends EventName>(
+    eventName: E,
+    cb: Plugin[EventMethodMap[E]],
+  ) => Unsubscribe;
+
+  readonly buildPath: (route: string, params?: Params) => string;
+
+  readonly start: (path: string) => Promise<State>;
+
+  /* eslint-disable @typescript-eslint/no-explicit-any -- heterogeneous map: stores different InterceptorFn<M> types under different keys */
+  readonly interceptors: Map<
+    string,
+    ((next: (...args: any[]) => any, ...args: any[]) => any)[]
+  >;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+
+  readonly setRootPath: (rootPath: string) => void;
+  readonly getRootPath: () => string;
+
+  readonly getTree: () => RouteTree;
+
+  readonly isDisposed: () => boolean;
+
+  validator: RouterValidator | null;
+
+  // Dependencies (issue #172)
+  readonly dependenciesGetStore: () => DependenciesStore<D>;
+
+  // Clone support (issue #173)
+  readonly cloneOptions: () => Options;
+  readonly cloneDependencies: () => Record<string, unknown>;
+  readonly getLifecycleFactories: () => [
+    Record<string, GuardFnFactory<D>>,
+    Record<string, GuardFnFactory<D>>,
+  ];
+  readonly getPluginFactories: () => PluginFactory<D>[];
+
+  // Consolidated route data store (issue #174 Phase 2)
+  readonly routeGetStore: () => RoutesStore<D>;
+
+  // Cross-namespace state (issue #174)
+  readonly getStateName: () => string | undefined;
+  readonly isTransitioning: () => boolean;
+  readonly clearState: () => void;
+  readonly setState: (state: State) => void;
+  readonly routerExtensions: { keys: string[] }[];
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- existential type: stores RouterInternals for all Dependencies types
+const internals = new WeakMap<object, RouterInternals<any>>();
+
+export function getInternals<D extends DefaultDependencies>(
+  router: RouterInterface<D>,
+): RouterInternals<D> {
+  const ctx = internals.get(router);
+
+  if (!ctx) {
+    throw new TypeError(
+      "[real-router] Invalid router instance — not found in internals registry",
+    );
+  }
+
+  return ctx as RouterInternals<D>;
+}
+
+export function registerInternals<D extends DefaultDependencies>(
+  router: RouterClass<D>,
+  ctx: RouterInternals<D>,
+): void {
+  internals.set(router, ctx);
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument -- internal chain execution: type safety enforced at public API boundary (PluginApi.addInterceptor) */
+function executeInterceptorChain<T>(
+  interceptors: ((next: (...args: any[]) => any, ...args: any[]) => any)[],
+  original: (...args: any[]) => T,
+  args: any[],
+): T {
+  let chain = original as (...args: any[]) => any;
+
+  for (const interceptor of interceptors) {
+    const prev = chain;
+
+    chain = (...chainArgs: any[]) => interceptor(prev, ...chainArgs);
+  }
+
+  return chain(...args) as T;
+}
+
+export function createInterceptable<T extends (...args: any[]) => any>(
+  name: string,
+  original: T,
+  interceptors: Map<
+    string,
+    ((next: (...args: any[]) => any, ...args: any[]) => any)[]
+  >,
+): T {
+  return ((...args: any[]) => {
+    const chain = interceptors.get(name);
+
+    if (!chain || chain.length === 0) {
+      return original(...args);
+    }
+
+    return executeInterceptorChain(chain, original, args);
+  }) as T;
+}
+
+export function createInterceptable2<A, B, R>(
+  name: string,
+  original: (a: A, b: B) => R,
+  interceptors: Map<
+    string,
+    ((next: (...args: any[]) => any, ...args: any[]) => any)[]
+  >,
+): (a: A, b: B) => R {
+  return (arg1: A, arg2: B) => {
+    const chain = interceptors.get(name);
+
+    if (!chain || chain.length === 0) {
+      return original(arg1, arg2);
+    }
+
+    return executeInterceptorChain(chain, original, [arg1, arg2]);
+  };
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument */

package/src/namespaces/DependenciesNamespace/dependenciesStore.ts

@@ -0,0 +1,30 @@
+import { DEFAULT_LIMITS } from "../../constants";
+
+import type { Limits } from "../../types";
+import type { DefaultDependencies } from "@real-router/types";
+
+export interface DependenciesStore<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  dependencies: Partial<Dependencies>;
+  limits: Limits;
+}
+
+export function createDependenciesStore<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  initialDependencies: Partial<Dependencies> = {} as Dependencies,
+): DependenciesStore<Dependencies> {
+  const dependencies = Object.create(null) as Partial<Dependencies>;
+
+  for (const key in initialDependencies) {
+    if (initialDependencies[key] !== undefined) {
+      dependencies[key] = initialDependencies[key];
+    }
+  }
+
+  return {
+    dependencies,
+    limits: DEFAULT_LIMITS,
+  };
+}

package/src/namespaces/DependenciesNamespace/index.ts

@@ -0,0 +1,5 @@
+// packages/core/src/namespaces/DependenciesNamespace/index.ts
+
+export { createDependenciesStore } from "./dependenciesStore";
+
+export type { DependenciesStore } from "./dependenciesStore";