@real-router/core 0.45.0 → 0.45.1

package/src/namespaces/RoutesNamespace/routeGuards.ts

@@ -1,62 +0,0 @@
-import { logger } from "@real-router/logger";
-
-/**
- * Validates removeRoute constraints.
- * Returns false if removal should be blocked (route is active).
- * Logs warnings for edge cases.
- *
- * @param name - Route name to remove
- * @param currentStateName - Current active route name (or undefined)
- * @param isNavigating - Whether navigation is in progress
- * @returns true if removal can proceed, false if blocked
- */
-export function validateRemoveRoute(
-  name: string,
-  currentStateName: string | undefined,
-  isNavigating: boolean,
-): boolean {
-  if (currentStateName) {
-    const isExactMatch = currentStateName === name;
-    const isParentOfCurrent = currentStateName.startsWith(`${name}.`);
-
-    if (isExactMatch || isParentOfCurrent) {
-      const suffix = isExactMatch ? "" : ` (current: "${currentStateName}")`;
-
-      logger.warn(
-        "router.removeRoute",
-        `Cannot remove route "${name}" — it is currently active${suffix}. Navigate away first.`,
-      );
-
-      return false;
-    }
-  }
-
-  if (isNavigating) {
-    logger.warn(
-      "router.removeRoute",
-      `Route "${name}" removed while navigation is in progress. This may cause unexpected behavior.`,
-    );
-  }
-
-  return true;
-}
-
-/**
- * Validates clearRoutes operation.
- * Returns false if operation should be blocked (navigation in progress).
- *
- * @param isNavigating - Whether navigation is in progress
- * @returns true if clearRoutes can proceed, false if blocked
- */
-export function validateClearRoutes(isNavigating: boolean): boolean {
-  if (isNavigating) {
-    logger.error(
-      "router.clearRoutes",
-      "Cannot clear routes while navigation is in progress. Wait for navigation to complete.",
-    );
-
-    return false;
-  }
-
-  return true;
-}

package/src/namespaces/RoutesNamespace/routesStore.ts

@@ -1,346 +0,0 @@
-// packages/core/src/namespaces/RoutesNamespace/routesStore.ts
-
-import { logger } from "@real-router/logger";
-import { createMatcher, createRouteTree, nodeToDefinition } from "route-tree";
-
-import { DEFAULT_ROUTE_NAME } from "./constants";
-import { resolveForwardChain } from "./forwardChain";
-import { createEmptyConfig, sanitizeRoute } from "./helpers";
-
-import type { RouteConfig, RoutesDependencies } from "./types";
-import type { GuardFnFactory, Route } from "../../types";
-import type { RouteLifecycleNamespace } from "../RouteLifecycleNamespace";
-import type { DefaultDependencies, Params } from "@real-router/types";
-import type {
-  CreateMatcherOptions,
-  Matcher,
-  RouteDefinition,
-  RouteTree,
-} from "route-tree";
-
-// =============================================================================
-// Interfaces
-// =============================================================================
-
-export interface RoutesStore<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  readonly definitions: RouteDefinition[];
-  readonly config: RouteConfig;
-  tree: RouteTree;
-  matcher: Matcher;
-  resolvedForwardMap: Record<string, string>;
-  routeCustomFields: Record<string, Record<string, unknown>>;
-  rootPath: string;
-  readonly matcherOptions: CreateMatcherOptions | undefined;
-  depsStore: RoutesDependencies<Dependencies> | undefined;
-  lifecycleNamespace: RouteLifecycleNamespace<Dependencies> | undefined;
-  readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
-  readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
-  readonly treeOperations: {
-    readonly commitTreeChanges: (store: RoutesStore<Dependencies>) => void;
-    readonly resetStore: (store: RoutesStore<Dependencies>) => void;
-    readonly nodeToDefinition: (node: RouteTree) => RouteDefinition;
-  };
-}
-
-// =============================================================================
-// Tree operations
-// =============================================================================
-
-function rebuildTree(
-  definitions: RouteDefinition[],
-  rootPath: string,
-  matcherOptions: CreateMatcherOptions | undefined,
-): { tree: RouteTree; matcher: Matcher } {
-  const tree = createRouteTree(DEFAULT_ROUTE_NAME, rootPath, definitions);
-  const matcher = createMatcher(matcherOptions);
-
-  matcher.registerTree(tree);
-
-  return { tree, matcher };
-}
-
-export function rebuildTreeInPlace<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(store: RoutesStore<Dependencies>): void {
-  const result = rebuildTree(
-    store.definitions,
-    store.rootPath,
-    store.matcherOptions,
-  );
-
-  store.tree = result.tree;
-  store.matcher = result.matcher;
-}
-
-export function commitTreeChanges<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(store: RoutesStore<Dependencies>): void {
-  rebuildTreeInPlace(store);
-  store.resolvedForwardMap = refreshForwardMap(store.config);
-}
-
-// =============================================================================
-// Store reset
-// =============================================================================
-
-/**
- * Clears all routes and resets config.
- * Does NOT clear lifecycle handlers or state — caller handles that.
- */
-export function resetStore<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(store: RoutesStore<Dependencies>): void {
-  clearRouteData(store);
-  rebuildTreeInPlace(store);
-}
-
-/**
- * Clears route data without rebuilding the tree.
- * Used by replace() to avoid double rebuild (clearRouteData + commitTreeChanges).
- */
-export function clearRouteData<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(store: RoutesStore<Dependencies>): void {
-  store.definitions.length = 0;
-
-  Object.assign(store.config, createEmptyConfig());
-
-  store.resolvedForwardMap = Object.create(null) as Record<string, string>;
-  store.routeCustomFields = Object.create(null) as Record<
-    string,
-    Record<string, unknown>
-  >;
-}
-
-// =============================================================================
-// Forward map
-// =============================================================================
-
-export function refreshForwardMap(config: RouteConfig): Record<string, string> {
-  const map = Object.create(null) as Record<string, string>;
-
-  for (const fromRoute of Object.keys(config.forwardMap)) {
-    map[fromRoute] = resolveForwardChain(fromRoute, config.forwardMap);
-  }
-
-  return map;
-}
-
-// =============================================================================
-// Route handler registration
-// =============================================================================
-
-function registerForwardTo<Dependencies extends DefaultDependencies>(
-  route: Route<Dependencies>,
-  fullName: string,
-  config: RouteConfig,
-): void {
-  if (route.canActivate) {
-    /* v8 ignore next -- @preserve: edge case, both string and function tested separately */
-    const forwardTarget =
-      typeof route.forwardTo === "string" ? route.forwardTo : "[dynamic]";
-
-    logger.warn(
-      "real-router",
-      `Route "${fullName}" has both forwardTo and canActivate. ` +
-        `canActivate will be ignored because forwardTo creates a redirect (industry standard). ` +
-        `Move canActivate to the target route "${forwardTarget}".`,
-    );
-  }
-
-  if (route.canDeactivate) {
-    /* v8 ignore next -- @preserve: edge case, both string and function tested separately */
-    const forwardTarget =
-      typeof route.forwardTo === "string" ? route.forwardTo : "[dynamic]";
-
-    logger.warn(
-      "real-router",
-      `Route "${fullName}" has both forwardTo and canDeactivate. ` +
-        `canDeactivate will be ignored because forwardTo creates a redirect (industry standard). ` +
-        `Move canDeactivate to the target route "${forwardTarget}".`,
-    );
-  }
-
-  if (typeof route.forwardTo === "function") {
-    const isNativeAsync =
-      (route.forwardTo as { constructor: { name: string } }).constructor
-        .name === "AsyncFunction";
-    const isTranspiledAsync = route.forwardTo.toString().includes("__awaiter");
-
-    if (isNativeAsync || isTranspiledAsync) {
-      throw new TypeError(
-        `forwardTo callback cannot be async for route "${fullName}". ` +
-          `Async functions break matchPath/buildPath.`,
-      );
-    }
-  }
-
-  // forwardTo is guaranteed to exist at this point
-  if (typeof route.forwardTo === "string") {
-    config.forwardMap[fullName] = route.forwardTo;
-  } else {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    config.forwardFnMap[fullName] = route.forwardTo!;
-  }
-}
-
-function registerSingleRouteHandlers<Dependencies extends DefaultDependencies>(
-  route: Route<Dependencies>,
-  fullName: string,
-  config: RouteConfig,
-  routeCustomFields: Record<string, Record<string, unknown>>,
-  pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>,
-  pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>,
-  depsStore: RoutesDependencies<Dependencies> | undefined,
-): void {
-  const standardKeys = new Set([
-    "name",
-    "path",
-    "children",
-    "canActivate",
-    "canDeactivate",
-    "forwardTo",
-    "encodeParams",
-    "decodeParams",
-    "defaultParams",
-  ]);
-  const customFields = Object.fromEntries(
-    Object.entries(route).filter(([key]) => !standardKeys.has(key)),
-  );
-
-  if (Object.keys(customFields).length > 0) {
-    routeCustomFields[fullName] = customFields;
-  }
-
-  if (route.canActivate) {
-    if (depsStore) {
-      depsStore.addActivateGuard(fullName, route.canActivate);
-    } else {
-      pendingCanActivate.set(fullName, route.canActivate);
-    }
-  }
-
-  if (route.canDeactivate) {
-    if (depsStore) {
-      depsStore.addDeactivateGuard(fullName, route.canDeactivate);
-    } else {
-      pendingCanDeactivate.set(fullName, route.canDeactivate);
-    }
-  }
-
-  if (route.forwardTo) {
-    registerForwardTo(route, fullName, config);
-  }
-
-  if (route.decodeParams) {
-    config.decoders[fullName] = (params: Params): Params =>
-      route.decodeParams?.(params) ?? params;
-  }
-
-  if (route.encodeParams) {
-    config.encoders[fullName] = (params: Params): Params =>
-      route.encodeParams?.(params) ?? params;
-  }
-
-  if (route.defaultParams) {
-    config.defaultParams[fullName] = route.defaultParams;
-  }
-}
-
-export function registerAllRouteHandlers<
-  Dependencies extends DefaultDependencies,
->(
-  routes: readonly Route<Dependencies>[],
-  config: RouteConfig,
-  routeCustomFields: Record<string, Record<string, unknown>>,
-  pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>,
-  pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>,
-  depsStore: RoutesDependencies<Dependencies> | undefined,
-  parentName = "",
-): void {
-  for (const route of routes) {
-    const fullName = parentName ? `${parentName}.${route.name}` : route.name;
-
-    registerSingleRouteHandlers(
-      route,
-      fullName,
-      config,
-      routeCustomFields,
-      pendingCanActivate,
-      pendingCanDeactivate,
-      depsStore,
-    );
-
-    if (route.children) {
-      registerAllRouteHandlers(
-        route.children,
-        config,
-        routeCustomFields,
-        pendingCanActivate,
-        pendingCanDeactivate,
-        depsStore,
-        fullName,
-      );
-    }
-  }
-}
-
-// =============================================================================
-// Factory
-// =============================================================================
-
-export function createRoutesStore<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(
-  routes: Route<Dependencies>[],
-  matcherOptions?: CreateMatcherOptions,
-): RoutesStore<Dependencies> {
-  const definitions: RouteDefinition[] = [];
-  const config: RouteConfig = createEmptyConfig();
-  const routeCustomFields: Record<
-    string,
-    Record<string, unknown>
-  > = Object.create(null) as Record<string, Record<string, unknown>>;
-  const pendingCanActivate = new Map<string, GuardFnFactory<Dependencies>>();
-  const pendingCanDeactivate = new Map<string, GuardFnFactory<Dependencies>>();
-
-  for (const route of routes) {
-    definitions.push(sanitizeRoute(route));
-  }
-
-  const { tree, matcher } = rebuildTree(definitions, "", matcherOptions);
-
-  registerAllRouteHandlers(
-    routes,
-    config,
-    routeCustomFields,
-    pendingCanActivate,
-    pendingCanDeactivate,
-    undefined,
-    "",
-  );
-
-  const resolvedForwardMap = refreshForwardMap(config);
-
-  return {
-    definitions,
-    config,
-    tree,
-    matcher,
-    resolvedForwardMap,
-    routeCustomFields,
-    rootPath: "",
-    matcherOptions,
-    depsStore: undefined,
-    lifecycleNamespace: undefined,
-    pendingCanActivate,
-    pendingCanDeactivate,
-    treeOperations: {
-      commitTreeChanges,
-      resetStore,
-      nodeToDefinition,
-    },
-  };
-}

package/src/namespaces/RoutesNamespace/types.ts

@@ -1,81 +0,0 @@
-// packages/core/src/namespaces/RoutesNamespace/types.ts
-
-import type { GuardFnFactory } from "../../types";
-import type {
-  DefaultDependencies,
-  ForwardToCallback,
-  Params,
-  SimpleState,
-  State,
-} from "@real-router/types";
-
-/**
- * Dependencies injected into RoutesNamespace.
- *
- * These are function references from the Router facade,
- * avoiding the need to pass the entire Router object.
- */
-export interface RoutesDependencies<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  /** Register canActivate handler for a route */
-  addActivateGuard: (
-    name: string,
-    handler: GuardFnFactory<Dependencies>,
-  ) => void;
-
-  /** Register canDeactivate handler for a route */
-  addDeactivateGuard: (
-    name: string,
-    handler: GuardFnFactory<Dependencies>,
-  ) => void;
-
-  /** Create state object */
-  makeState: <P extends Params = Params>(
-    name: string,
-    params?: P,
-    path?: string,
-    meta?: Record<string, Record<string, "url" | "query">>,
-  ) => State<P>;
-
-  /** Get current router state */
-  getState: () => State | undefined;
-
-  /** Compare two states for equality */
-  areStatesEqual: (
-    state1: State | undefined,
-    state2: State | undefined,
-    ignoreQueryParams?: boolean,
-  ) => boolean;
-
-  /** Get a dependency by name */
-  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K];
-
-  /** Forward state through facade (allows plugin interception) */
-  forwardState: <P extends Params = Params>(
-    name: string,
-    params: P,
-  ) => SimpleState<P>;
-}
-
-/**
- * Configuration storage for routes.
- * Stores decoders, encoders, default params, and forward mappings.
- */
-export interface RouteConfig {
-  /** Custom param decoders per route */
-  decoders: Record<string, (params: Params) => Params>;
-
-  /** Custom param encoders per route */
-  encoders: Record<string, (params: Params) => Params>;
-
-  /** Default params per route */
-  defaultParams: Record<string, Params>;
-
-  /** Forward mappings (source -> target) */
-  forwardMap: Record<string, string>;
-
-  /** Dynamic forward callbacks (source -> callback) */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  forwardFnMap: Record<string, ForwardToCallback<any>>;
-}

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -1,211 +0,0 @@
-// packages/core/src/namespaces/StateNamespace/StateNamespace.ts
-
-import { areParamValuesEqual } from "./helpers";
-import { EMPTY_PARAMS } from "../../constants";
-import { freezeStateInPlace } from "../../helpers";
-import { setStateMetaParams } from "../../stateMetaStore";
-
-import type { StateNamespaceDependencies } from "./types";
-import type { Params, State } from "@real-router/types";
-import type { RouteTreeStateMeta } from "route-tree";
-
-/**
- * Independent namespace for managing router state storage and creation.
- *
- * Static methods handle validation (called by facade).
- * Instance methods handle state storage, freezing, and creation.
- */
-export class StateNamespace {
-  /**
-   * Cached frozen state - avoids structuredClone on every getState() call.
-   */
-  #frozenState: State | undefined = undefined;
-
-  /**
-   * Previous state before the last setState call.
-   */
-  #previousState: State | undefined = undefined;
-
-  /**
-   * Dependencies injected from Router.
-   */
-  #deps!: StateNamespaceDependencies;
-
-  /**
-   * Cache for URL params by route name.
-   */
-  readonly #urlParamsCache = new Map<string, string[]>();
-
-  // =========================================================================
-  // Instance methods (trust input - already validated by facade)
-  // =========================================================================
-
-  /**
-   * Returns the current router state.
-   *
-   * The returned state is deeply frozen (immutable) for safety.
-   * Returns `undefined` if the router has not been started or has been stopped.
-   */
-  get<P extends Params = Params>(): State<P> | undefined {
-    return this.#frozenState as State<P> | undefined; // NOSONAR -- generic narrowing needed for public API
-  }
-
-  /**
-   * Sets the current router state.
-   *
-   * The state is deeply frozen before storage to ensure immutability.
-   * The previous state is preserved and accessible via `getPrevious()`.
-   *
-   * @param state - Already validated by facade, or undefined to clear
-   */
-  set(state: State | undefined): void {
-    // Preserve current state as previous before updating
-    this.#previousState = this.#frozenState;
-
-    // If state is already frozen (from makeState()), use it directly.
-    // For external states, freeze in place without cloning.
-    this.#frozenState = state ? freezeStateInPlace(state) : undefined;
-  }
-
-  /**
-   * Returns the previous router state (before the last navigation).
-   */
-  getPrevious(): State | undefined {
-    return this.#previousState;
-  }
-
-  reset(): void {
-    this.#frozenState = undefined;
-    this.#previousState = undefined;
-    this.#urlParamsCache.clear();
-  }
-
-  // =========================================================================
-  // Dependency Injection
-  // =========================================================================
-
-  /**
-   * Sets dependencies for state creation methods.
-   * Must be called before using makeState, areStatesEqual, etc.
-   */
-  setDependencies(deps: StateNamespaceDependencies): void {
-    this.#deps = deps;
-  }
-
-  // =========================================================================
-  // State Creation Methods
-  // =========================================================================
-
-  /**
-   * Creates a frozen state object for a route.
-   */
-  makeState<P extends Params = Params>(
-    name: string,
-    params?: P,
-    path?: string,
-    meta?: RouteTreeStateMeta,
-    skipFreeze?: boolean,
-  ): State<P> {
-    // Optimization: O(1) lookup instead of O(depth) ancestor iteration
-    const defaultParamsConfig = this.#deps.getDefaultParams();
-    const hasDefaultParams = Object.hasOwn(defaultParamsConfig, name);
-
-    // Conditional allocation: avoid spreading when no defaultParams exist
-    let mergedParams: P;
-
-    if (hasDefaultParams) {
-      mergedParams = { ...defaultParamsConfig[name], ...params } as P;
-    } else if (!params || params === EMPTY_PARAMS) {
-      mergedParams = EMPTY_PARAMS as P;
-    } else {
-      mergedParams = { ...params };
-    }
-
-    const state: State<P> = {
-      name,
-      params: mergedParams,
-      path: path ?? this.#deps.buildPath(name, params),
-    };
-
-    if (meta) {
-      setStateMetaParams(state, meta as unknown as Params);
-    }
-
-    return skipFreeze ? state : freezeStateInPlace(state);
-  }
-
-  // =========================================================================
-  // State Comparison Methods
-  // =========================================================================
-
-  /**
-   * Compares two states for equality.
-   * By default, ignores query params (only compares URL params).
-   */
-  areStatesEqual(
-    state1: State | undefined,
-    state2: State | undefined,
-    ignoreQueryParams = true,
-  ): boolean {
-    if (!state1 || !state2) {
-      return !!state1 === !!state2;
-    }
-
-    if (state1.name !== state2.name) {
-      return false;
-    }
-
-    if (ignoreQueryParams) {
-      const urlParams = this.#getUrlParams(state1.name);
-
-      for (const urlParam of urlParams) {
-        if (
-          !areParamValuesEqual(state1.params[urlParam], state2.params[urlParam])
-        ) {
-          return false;
-        }
-      }
-
-      return true;
-    }
-
-    const state1Keys = Object.keys(state1.params);
-    const state2Keys = Object.keys(state2.params);
-
-    if (state1Keys.length !== state2Keys.length) {
-      return false;
-    }
-
-    for (const param of state1Keys) {
-      if (
-        !(param in state2.params) ||
-        !areParamValuesEqual(state1.params[param], state2.params[param])
-      ) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-
-  // =========================================================================
-  // Private Helpers
-  // =========================================================================
-
-  /**
-   * Gets URL params for a route name, using cache for performance.
-   */
-  #getUrlParams(name: string): string[] {
-    const cached = this.#urlParamsCache.get(name);
-
-    if (cached !== undefined) {
-      return cached;
-    }
-
-    const result = this.#deps.getUrlParams(name);
-
-    this.#urlParamsCache.set(name, result);
-
-    return result;
-  }
-}