@real-router/core 0.56.0 → 0.57.0

package/src/api/helpers.ts

@@ -1,10 +0,0 @@
-// packages/core/src/api/helpers.ts
-
-import { errorCodes } from "../constants";
-import { RouterError } from "../RouterError";
-
-export function throwIfDisposed(isDisposed: () => boolean): void {
-  if (isDisposed()) {
-    throw new RouterError(errorCodes.ROUTER_DISPOSED);
-  }
-}

package/src/api/index.ts

@@ -1,16 +0,0 @@
-export { getPluginApi } from "./getPluginApi";
-
-export { getRoutesApi } from "./getRoutesApi";
-
-export { getDependenciesApi } from "./getDependenciesApi";
-
-export { getLifecycleApi } from "./getLifecycleApi";
-
-export { cloneRouter } from "./cloneRouter";
-
-export type {
-  PluginApi,
-  RoutesApi,
-  DependenciesApi,
-  LifecycleApi,
-} from "./types";

package/src/api/types.ts

@@ -1,12 +0,0 @@
-import type { PluginApi as BasePluginApi } from "@real-router/types";
-import type { RouteTree } from "route-tree";
-
-export interface PluginApi extends Omit<BasePluginApi, "getTree"> {
-  getTree: () => RouteTree;
-}
-
-export {
-  type RoutesApi,
-  type LifecycleApi,
-  type DependenciesApi,
-} from "@real-router/types";

package/src/constants.ts

@@ -1,101 +0,0 @@
-// packages/core/src/constants.ts
-
-import type {
-  EventToNameMap,
-  EventToPluginMap,
-  ErrorCodeToValueMap,
-  ErrorCodeKeys,
-  ErrorCodeValues,
-  TransitionMeta,
-} from "@real-router/types";
-
-export type ConstantsKeys = "UNKNOWN_ROUTE";
-
-export type Constants = Record<ConstantsKeys, string>;
-
-// =============================================================================
-// Error Codes (migrated from router-error)
-// =============================================================================
-
-export type ErrorCodes = Record<ErrorCodeKeys, ErrorCodeValues>;
-
-/**
- * Error codes for router operations.
- * Used to identify specific failure scenarios in navigation and lifecycle.
- * Frozen to prevent accidental modifications.
- */
-export const errorCodes: ErrorCodeToValueMap = Object.freeze({
-  ROUTER_NOT_STARTED: "NOT_STARTED", // navigate() called before start()
-  NO_START_PATH_OR_STATE: "NO_START_PATH_OR_STATE", // start() without initial route
-  ROUTER_ALREADY_STARTED: "ALREADY_STARTED", // start() called twice
-  ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND", // Navigation to non-existent route
-  SAME_STATES: "SAME_STATES", // Navigate to current route without reload
-  CANNOT_DEACTIVATE: "CANNOT_DEACTIVATE", // canDeactivate guard blocked navigation
-  CANNOT_ACTIVATE: "CANNOT_ACTIVATE", // canActivate guard blocked navigation
-  TRANSITION_ERR: "TRANSITION_ERR", // Generic transition failure
-  TRANSITION_CANCELLED: "CANCELLED", // Navigation cancelled by user or new navigation
-  ROUTER_DISPOSED: "DISPOSED", // Router has been disposed
-  PLUGIN_CONFLICT: "PLUGIN_CONFLICT", // Plugin tried to extend router with already-existing property
-  CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED", // Plugin tried to claim a context namespace already owned by another plugin
-});
-
-/**
- * General router constants.
- * Special route names and identifiers.
- */
-export const UNKNOWN_ROUTE = "@@router/UNKNOWN_ROUTE";
-
-export const constants: Constants = {
-  UNKNOWN_ROUTE,
-};
-
-/**
- * Plugin method names.
- * Maps to methods that plugins can implement to hook into router lifecycle.
- */
-export const plugins: EventToPluginMap = {
-  ROUTER_START: "onStart", // Plugin method called when router starts
-  ROUTER_STOP: "onStop", // Plugin method called when router stops
-  TRANSITION_START: "onTransitionStart", // Plugin method called when navigation begins
-  TRANSITION_LEAVE_APPROVE: "onTransitionLeaveApprove", // Plugin method called when deactivation guards pass
-  TRANSITION_CANCEL: "onTransitionCancel", // Plugin method called when navigation cancelled
-  TRANSITION_SUCCESS: "onTransitionSuccess", // Plugin method called when navigation succeeds
-  TRANSITION_ERROR: "onTransitionError", // Plugin method called when navigation fails
-};
-
-/**
- * Event names for router event system.
- * Used with addEventListener/removeEventListener for reactive subscriptions.
- */
-export const events: EventToNameMap = {
-  ROUTER_START: "$start", // Emitted when router.start() succeeds
-  ROUTER_STOP: "$stop", // Emitted when router.stop() is called
-  TRANSITION_START: "$$start", // Emitted when navigation begins
-  TRANSITION_LEAVE_APPROVE: "$$leaveApprove", // Emitted when deactivation guards pass
-  TRANSITION_CANCEL: "$$cancel", // Emitted when navigation is cancelled
-  TRANSITION_SUCCESS: "$$success", // Emitted when navigation completes successfully
-  TRANSITION_ERROR: "$$error", // Emitted when navigation fails
-};
-
-export const DEFAULT_LIMITS = {
-  maxDependencies: 100,
-  maxPlugins: 50,
-  maxListeners: 10_000,
-  warnListeners: 1000,
-  maxEventDepth: 5,
-  maxLifecycleHandlers: 200,
-} as const;
-
-export const EMPTY_PARAMS: Readonly<Record<string, never>> = Object.freeze({});
-
-const FROZEN_EMPTY_SEGMENTS = Object.freeze({
-  deactivated: Object.freeze([]) as unknown as string[],
-  activated: Object.freeze([]) as unknown as string[],
-  intersection: "",
-});
-
-export const DEFAULT_TRANSITION = Object.freeze({
-  phase: "activating",
-  reason: "success",
-  segments: FROZEN_EMPTY_SEGMENTS,
-}) as TransitionMeta;

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,66 +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";
-
-// Route-tree mutation event payloads (observed via getRoutesApi().subscribeChanges)
-export type {
-  TreeChangedEvent,
-  TreeChangedAdd,
-  TreeChangedRemove,
-  TreeChangedUpdate,
-  TreeChangedReplace,
-  TreeChangedClear,
-  TreeStructuralPatch,
-} 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";
-
-// Re-exported so end users can `instanceof RecursionDepthError` at CRUD call
-// sites — the only error that escapes a `subscribeChanges` handler (depth-limit
-// overflow propagates, unlike ordinary listener errors which are isolated).
-export { RecursionDepthError } from "event-emitter";
-
-export { createRouter } from "./createRouter";
-
-export { getNavigator } from "./getNavigator";
-
-export { resolveForwardChain } from "./namespaces/RoutesNamespace/forwardChain";
-
-export type { RouteTree } from "route-tree";