@real-router/core 0.55.0 → 0.57.0

package/src/createRouter.ts

@@ -1,32 +0,0 @@
-// 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

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

package/src/fsm/routerFSM.ts

@@ -1,130 +0,0 @@
-// 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), DISPOSED (DISPOSE)
- * - READY → TRANSITION_STARTED (NAVIGATE), READY (FAIL, self-loop for early validation errors), IDLE (STOP), DISPOSED (DISPOSE)
- * - TRANSITION_STARTED → LEAVE_APPROVED (LEAVE_APPROVE), TRANSITION_STARTED (NAVIGATE, self-loop), READY (CANCEL, FAIL), DISPOSED (DISPOSE)
- * - LEAVE_APPROVED → READY (COMPLETE, CANCEL, FAIL), TRANSITION_STARTED (NAVIGATE), DISPOSED (DISPOSE)
- * - DISPOSED → (no transitions)
- *
- * DISPOSE is wired from every non-DISPOSED state so `router.dispose()` always
- * settles the FSM at DISPOSED. The facade orchestrates cleanup through IDLE
- * for healthy flows; the direct transitions guarantee the FSM is not left
- * stuck if cleanup is skipped (e.g. dispose mid-STARTING when the start
- * pipeline threw before STARTED/FAIL).
- */
-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,
-      [routerEvents.DISPOSE]: routerStates.DISPOSED,
-    },
-    [routerStates.READY]: {
-      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
-      [routerEvents.FAIL]: routerStates.READY,
-      [routerEvents.STOP]: routerStates.IDLE,
-      [routerEvents.DISPOSE]: routerStates.DISPOSED,
-    },
-    [routerStates.TRANSITION_STARTED]: {
-      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
-      [routerEvents.LEAVE_APPROVE]: routerStates.LEAVE_APPROVED,
-      [routerEvents.CANCEL]: routerStates.READY,
-      [routerEvents.FAIL]: routerStates.READY,
-      [routerEvents.DISPOSE]: routerStates.DISPOSED,
-    },
-    [routerStates.LEAVE_APPROVED]: {
-      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,
-      [routerEvents.COMPLETE]: routerStates.READY,
-      [routerEvents.CANCEL]: routerStates.READY,
-      [routerEvents.FAIL]: routerStates.READY,
-      [routerEvents.DISPOSE]: routerStates.DISPOSED,
-    },
-    [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

@@ -1,30 +0,0 @@
-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

@@ -1,46 +0,0 @@
-// 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

@@ -1,197 +0,0 @@
-// packages/core/src/helpers.ts
-
-import { DEFAULT_LIMITS } from "./constants";
-
-import type { Limits } from "./types";
-import type { Params, 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;
-}
-
-/**
- * Shallow-freezes a State object in place.
- *
- * Freezes only the top-level State object (blocks reassignment of `name`,
- * `params`, `path`, `transition`, `context`). Nested objects (`params`,
- * `transition`, `transition.segments`, `transition.segments.{deactivated,activated}`)
- * are expected to be **already frozen at creation time** by their producers:
- *
- * - `params` frozen in `makeState()` / `navigateToNotFound()`
- * - `transition`, `segments`, `deactivated`, `activated` frozen in
- *   `buildTransitionMeta()` (or inline in `navigateToNotFound()`)
- *
- * `state.context` is **intentionally not frozen** — plugins write to it via
- * `claim.write(state, value)` after state creation.
- *
- * @internal
- */
-export function freezeStateInPlace<T extends State>(state: T): T {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive guard against external misuse
-  if (!state) {
-    return state;
-  }
-
-  return Object.freeze(state);
-}
-
-/**
- * Merges user limits with defaults.
- * Returns frozen object for immutability.
- */
-export function createLimits(userLimits: Partial<LimitsConfig> = {}): Limits {
-  return { ...DEFAULT_LIMITS, ...userLimits };
-}
-
-// =============================================================================
-// Params Helpers
-// =============================================================================
-
-/**
- * Strips `undefined` values from a params object before handoff to the query
- * string engine and state storage.
- *
- * **Why this exists:** `router.navigate(name, { x: undefined })` must not put
- * `x` into the resulting URL (publicly documented contract). The underlying
- * query engine (`search-params`) already does this, but the contract belongs
- * to `@real-router/core` — this function guarantees it at the core boundary
- * so that:
- * - Plugin interceptors on `forwardState` that inject `undefined` values are
- *   caught before they reach the engine
- * - `state.params` never contains `undefined` values (roundtrip consistent
- *   with URL)
- * - The contract is verifiable at core's own test surface (doesn't depend on
- *   engine behavior for regression detection)
- *
- * Single pass. Always returns a fresh object when input is defined
- * (reference identity is not preserved — callers must not rely on it).
- */
-export function normalizeParams(params: Params): Params;
-
-export function normalizeParams(params: undefined): undefined;
-
-export function normalizeParams(params: Params | undefined): Params | undefined;
-
-export function normalizeParams(
-  params: Params | undefined,
-): Params | undefined {
-  if (params === undefined) {
-    return params;
-  }
-
-  const normalized: Params = {};
-
-  for (const key in params) {
-    if (!Object.hasOwn(params, key)) {
-      continue;
-    }
-
-    const value = params[key];
-
-    if (value !== undefined) {
-      normalized[key] = value;
-    }
-  }
-
-  return normalized;
-}

package/src/index.ts

@@ -1,50 +0,0 @@
-// 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

@@ -1,200 +0,0 @@
-import type { DependenciesStore } from "./namespaces";
-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 { SerializedRouterState } from "./utils";
-import type {
-  DefaultDependencies,
-  EventName,
-  NavigationOptions,
-  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 emitTransitionError: (error: Error) => void;
-
-  readonly start: (path: string) => Promise<State>;
-
-  /**
-   * Plugin-only navigation entry point — delegates to
-   * `NavigationNamespace.navigateToState` (`getPluginApi(router).navigateToState`).
-   * Hidden from `Router`/`Navigator` to keep the userland surface minimal;
-   * see `core-types/src/api.ts` for usage docs.
-   */
-  readonly navigateToState: (
-    state: State,
-    options?: NavigationOptions,
-  ) => 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[] }[];
-  readonly contextClaimRecords: Set<string>;
-
-  /**
-   * One-shot hydration scratchpad populated by `hydrateRouter` immediately
-   * before delegating to `router.start(parsed.path)` and cleared in the
-   * matching `finally`. SSR loader plugins read this slot directly via
-   * `getInternals(router).hydrationState` to short-circuit their own loader
-   * call when the server-resolved namespace value is already present in the
-   * parsed state (#596). `null` outside of an active `hydrateRouter`
-   * invocation.
-   */
-  hydrationState: SerializedRouterState | null;
-}
-
-// 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 */