@real-router/core 0.25.4 → 0.26.0

package/src/namespaces/RoutesNamespace/routesStore.ts

@@ -0,0 +1,388 @@
+// 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 "./forwardToValidation";
+import { createEmptyConfig, sanitizeRoute } from "./helpers";
+import { validateRoutes } from "./validators";
+
+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>,
+      noValidate: boolean,
+    ) => void;
+    readonly resetStore: (store: RoutesStore<Dependencies>) => void;
+    readonly nodeToDefinition: (node: RouteTree) => RouteDefinition;
+    readonly validateRoutes: (
+      routes: Route<Dependencies>[],
+      tree?: RouteTree,
+      forwardMap?: Record<string, string>,
+      parentName?: string,
+    ) => void;
+  };
+}
+
+// =============================================================================
+// 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 commitTreeChanges<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(store: RoutesStore<Dependencies>, noValidate: boolean): void {
+  const result = rebuildTree(
+    store.definitions,
+    store.rootPath,
+    store.matcherOptions,
+  );
+
+  store.tree = result.tree;
+  store.matcher = result.matcher;
+  store.resolvedForwardMap = refreshForwardMap(store.config, noValidate);
+}
+
+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;
+}
+
+// =============================================================================
+// 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 {
+  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>
+  >;
+
+  rebuildTreeInPlace(store);
+}
+
+// =============================================================================
+// Forward map
+// =============================================================================
+
+export function refreshForwardMap(
+  config: RouteConfig,
+  noValidate: boolean,
+): Record<string, string> {
+  if (noValidate) {
+    return cacheForwardMap(config);
+  }
+
+  return validateAndCacheForwardMap(config);
+}
+
+function validateAndCacheForwardMap(
+  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;
+}
+
+function cacheForwardMap(config: RouteConfig): Record<string, string> {
+  const map = Object.create(null) as Record<string, string>;
+
+  for (const fromRoute of Object.keys(config.forwardMap)) {
+    let current = fromRoute;
+
+    while (config.forwardMap[current]) {
+      current = config.forwardMap[current];
+    }
+
+    map[fromRoute] = current;
+  }
+
+  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}".`,
+    );
+  }
+
+  // Async validation ALWAYS runs (even with noValidate=true)
+  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(([k]) => !standardKeys.has(k)),
+  );
+
+  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>[],
+  noValidate: boolean,
+  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: Record<string, string> = noValidate
+    ? cacheForwardMap(config)
+    : validateAndCacheForwardMap(config);
+
+  return {
+    definitions,
+    config,
+    tree,
+    matcher,
+    resolvedForwardMap,
+    routeCustomFields,
+    rootPath: "",
+    matcherOptions,
+    depsStore: undefined,
+    lifecycleNamespace: undefined,
+    pendingCanActivate,
+    pendingCanDeactivate,
+    treeOperations: {
+      commitTreeChanges,
+      resetStore,
+      nodeToDefinition,
+      validateRoutes,
+    },
+  };
+}

package/src/namespaces/RoutesNamespace/validators.ts

@@ -7,6 +7,7 @@
  * Extracted from RoutesNamespace class for better separation of concerns.
  */
 
+import { logger } from "@real-router/logger";
 import { validateRoute } from "route-tree";
 import {
   isString,
@@ -15,11 +16,19 @@ import {
   getTypeDescription,
 } from "type-guards";
 
-import { validateRouteProperties, validateForwardToTargets } from "./helpers";
+import {
+  resolveForwardChain,
+  validateForwardToTargets,
+  validateRouteProperties,
+} from "./forwardToValidation";
 
+import type { RouteConfig } from "./types";
 import type { Route, RouteConfigUpdate } from "../../types";
-import type { DefaultDependencies } from "@real-router/types";
-import type { RouteTree } from "route-tree";
+import type {
+  DefaultDependencies,
+  ForwardToCallback,
+} from "@real-router/types";
+import type { Matcher, RouteTree } from "route-tree";
 
 /**
  * Validates removeRoute arguments.
@@ -329,3 +338,200 @@ export function validateRoutes<Dependencies extends DefaultDependencies>(
     validateForwardToTargets(routes, forwardMap, tree);
   }
 }
+
+// ============================================================================
+// Instance-level validators (moved from routesCrud.ts)
+// ============================================================================
+
+/**
+ * Collects URL params from segments into a Set.
+ */
+function collectUrlParams(segments: readonly RouteTree[]): Set<string> {
+  const params = new Set<string>();
+
+  for (const segment of segments) {
+    for (const param of segment.paramMeta.urlParams) {
+      params.add(param);
+    }
+  }
+
+  return params;
+}
+
+/**
+ * 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 {
+  // Check if trying to remove currently active route (or its parent)
+  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;
+    }
+  }
+
+  // Warn if navigation is in progress (but allow removal)
+  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;
+}
+
+/**
+ * Validates that forwardTo target doesn't require params that source doesn't have.
+ *
+ * @param sourceName - Source route name
+ * @param targetName - Target route name
+ * @param matcher - Current route matcher
+ */
+export function validateForwardToParamCompatibility(
+  sourceName: string,
+  targetName: string,
+  matcher: Matcher,
+): void {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const sourceSegments = matcher.getSegmentsByName(
+    sourceName,
+  )! as readonly RouteTree[];
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const targetSegments = matcher.getSegmentsByName(
+    targetName,
+  )! as readonly RouteTree[];
+
+  // Get source URL params as a Set for O(1) lookup
+  const sourceParams = collectUrlParams(sourceSegments);
+
+  // Build target URL params array (inline — no separate helper needed)
+  const targetParams: string[] = [];
+
+  for (const segment of targetSegments) {
+    for (const param of segment.paramMeta.urlParams) {
+      targetParams.push(param);
+    }
+  }
+
+  // Check if target requires params that source doesn't have
+  const missingParams = targetParams.filter(
+    (param) => !sourceParams.has(param),
+  );
+
+  if (missingParams.length > 0) {
+    throw new Error(
+      `[real-router] forwardTo target "${targetName}" requires params ` +
+        `[${missingParams.join(", ")}] that are not available in source route "${sourceName}"`,
+    );
+  }
+}
+
+/**
+ * Validates that adding forwardTo doesn't create a cycle.
+ * Creates a test map with the new entry and uses resolveForwardChain
+ * to detect cycles before any mutation happens.
+ *
+ * @param sourceName - Source route name
+ * @param targetName - Target route name
+ * @param config - Current route config (forwardMap read-only in this call)
+ */
+export function validateForwardToCycle(
+  sourceName: string,
+  targetName: string,
+  config: RouteConfig,
+): void {
+  // Create a test map with the new entry to validate BEFORE mutation
+  const testMap = {
+    ...config.forwardMap,
+    [sourceName]: targetName,
+  };
+
+  // resolveForwardChain will throw if cycle is detected or max depth exceeded
+  resolveForwardChain(sourceName, testMap);
+}
+
+/**
+ * Validates updateRoute instance-level constraints (route existence, forwardTo).
+ *
+ * @param name - Route name (already validated by static method)
+ * @param forwardTo - Cached forwardTo value
+ * @param hasRoute - Function to check route existence
+ * @param matcher - Current route matcher
+ * @param config - Current route config
+ */
+export function validateUpdateRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  name: string,
+  forwardTo: string | ForwardToCallback<Dependencies> | null | undefined,
+  hasRoute: (n: string) => boolean,
+  matcher: Matcher,
+  config: RouteConfig,
+): void {
+  // Validate route exists
+  if (!hasRoute(name)) {
+    throw new ReferenceError(
+      `[real-router] updateRoute: route "${name}" does not exist`,
+    );
+  }
+
+  // Validate forwardTo target exists and is valid (only for string forwardTo)
+  if (
+    forwardTo !== undefined &&
+    forwardTo !== null &&
+    typeof forwardTo === "string"
+  ) {
+    if (!hasRoute(forwardTo)) {
+      throw new Error(
+        `[real-router] updateRoute: forwardTo target "${forwardTo}" does not exist`,
+      );
+    }
+
+    // Check forwardTo param compatibility
+    validateForwardToParamCompatibility(name, forwardTo, matcher);
+
+    // Check for cycle detection
+    validateForwardToCycle(name, forwardTo, config);
+  }
+}

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -1,11 +1,6 @@
 // packages/core/src/namespaces/StateNamespace/StateNamespace.ts
 
-import {
-  getTypeDescription,
-  isParams,
-  isString,
-  validateState,
-} from "type-guards";
+import { getTypeDescription, validateState } from "type-guards";
 
 import { areParamValuesEqual, getUrlParamsFromMeta } from "./helpers";
 import { constants } from "../../constants";
@@ -56,44 +51,6 @@ export class StateNamespace {
   // Static validation methods (called by facade before instance methods)
   // =========================================================================
 
-  /**
-   * Validates makeState arguments.
-   */
-  static validateMakeStateArgs(
-    name: unknown,
-    params: unknown,
-    path: unknown,
-    forceId: unknown,
-  ): void {
-    // Validate name is a string
-    if (!isString(name)) {
-      throw new TypeError(
-        `[router.makeState] Invalid name: ${getTypeDescription(name)}. Expected string.`,
-      );
-    }
-
-    // Validate params if provided
-    if (params !== undefined && !isParams(params)) {
-      throw new TypeError(
-        `[router.makeState] Invalid params: ${getTypeDescription(params)}. Expected plain object.`,
-      );
-    }
-
-    // Validate path if provided
-    if (path !== undefined && !isString(path)) {
-      throw new TypeError(
-        `[router.makeState] Invalid path: ${getTypeDescription(path)}. Expected string.`,
-      );
-    }
-
-    // Validate forceId if provided
-    if (forceId !== undefined && typeof forceId !== "number") {
-      throw new TypeError(
-        `[router.makeState] Invalid forceId: ${getTypeDescription(forceId)}. Expected number.`,
-      );
-    }
-  }
-
   /**
    * Validates areStatesEqual arguments.
    */