@real-router/core 0.45.1 → 0.45.2

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -0,0 +1,535 @@
+// packages/core/src/namespaces/RoutesNamespace/RoutesNamespace.ts
+
+import { DEFAULT_ROUTE_NAME } from "./constants";
+import { paramsMatch, paramsMatchExcluding } from "./helpers";
+import {
+  createRoutesStore,
+  rebuildTreeInPlace,
+  resetStore,
+} from "./routesStore";
+import { constants } from "../../constants";
+import { getTransitionPath } from "../../transitionPath";
+
+import type { RoutesStore } from "./routesStore";
+import type { RoutesDependencies } from "./types";
+import type { Route } from "../../types";
+import type { RouteLifecycleNamespace } from "../RouteLifecycleNamespace";
+import type {
+  DefaultDependencies,
+  ForwardToCallback,
+  Options,
+  Params,
+  State,
+} from "@real-router/types";
+import type {
+  CreateMatcherOptions,
+  RouteParams,
+  RouteTree,
+  RouteTreeState,
+} from "route-tree";
+
+function collectUrlParamsArray(segments: readonly RouteTree[]): string[] {
+  const params: string[] = [];
+
+  for (const segment of segments) {
+    for (const param of segment.paramMeta.urlParams) {
+      params.push(param);
+    }
+  }
+
+  return params;
+}
+
+export function buildNameFromSegments(
+  segments: readonly { fullName: string }[],
+): string {
+  return segments.at(-1)?.fullName ?? "";
+}
+
+export function createRouteState<P extends RouteParams = RouteParams>(
+  matchResult: {
+    readonly segments: readonly { fullName: string }[];
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly meta: Readonly<Record<string, Record<string, "url" | "query">>>;
+  },
+  name?: string,
+): RouteTreeState<P> {
+  const resolvedName = name ?? buildNameFromSegments(matchResult.segments);
+
+  return {
+    name: resolvedName,
+    params: matchResult.params as P,
+    meta: matchResult.meta as Record<string, Record<string, "url" | "query">>,
+  };
+}
+
+interface CachedBuildPathOpts {
+  readonly trailingSlash?: "always" | "never" | undefined;
+  readonly queryParamsMode?: "default" | "strict" | "loose" | undefined;
+}
+
+/**
+ * Independent namespace for managing routes.
+ *
+ * Static methods handle validation (called by facade).
+ * Instance methods handle storage and business logic.
+ */
+export class RoutesNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly #store: RoutesStore<Dependencies>;
+  #cachedBuildPathOpts: CachedBuildPathOpts | undefined;
+
+  get #deps(): RoutesDependencies<Dependencies> {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return this.#store.depsStore!;
+  }
+
+  constructor(
+    routes: Route<Dependencies>[] = [],
+    matcherOptions?: CreateMatcherOptions,
+  ) {
+    this.#store = createRoutesStore(routes, matcherOptions);
+  }
+
+  /**
+   * Creates a predicate function to check if a route node should be updated.
+   * Note: Argument validation is done by facade (Router.ts) via validateShouldUpdateNodeArgs.
+   */
+  static shouldUpdateNode(
+    nodeName: string,
+  ): (toState: State, fromState?: State) => boolean {
+    return (toState: State, fromState?: State): boolean => {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (!(toState && typeof toState === "object" && "name" in toState)) {
+        throw new TypeError(
+          "[router.shouldUpdateNode] toState must be valid State object",
+        );
+      }
+
+      if (toState.transition?.reload) {
+        return true;
+      }
+
+      if (nodeName === DEFAULT_ROUTE_NAME && !fromState) {
+        return true;
+      }
+
+      const { intersection, toActivate, toDeactivate } = getTransitionPath(
+        toState,
+        fromState,
+      );
+
+      if (nodeName === intersection) {
+        return true;
+      }
+
+      if (toActivate.includes(nodeName)) {
+        return true;
+      }
+
+      return toDeactivate.includes(nodeName);
+    };
+  }
+
+  // =========================================================================
+  // Dependency injection
+  // =========================================================================
+
+  /**
+   * Sets dependencies and registers pending canActivate handlers.
+   * canActivate handlers from initial routes are deferred until deps are set.
+   */
+  setDependencies(deps: RoutesDependencies<Dependencies>): void {
+    this.#store.depsStore = deps;
+
+    for (const [routeName, handler] of this.#store.pendingCanActivate) {
+      deps.addActivateGuard(routeName, handler);
+    }
+
+    this.#store.pendingCanActivate.clear();
+
+    for (const [routeName, handler] of this.#store.pendingCanDeactivate) {
+      deps.addDeactivateGuard(routeName, handler);
+    }
+
+    this.#store.pendingCanDeactivate.clear();
+  }
+
+  /**
+   * Sets the lifecycle namespace reference.
+   */
+  setLifecycleNamespace(
+    namespace: RouteLifecycleNamespace<Dependencies> | undefined,
+  ): void {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    this.#store.lifecycleNamespace = namespace!;
+  }
+
+  // =========================================================================
+  // Route tree operations
+  // =========================================================================
+
+  setRootPath(newRootPath: string): void {
+    this.#store.rootPath = newRootPath;
+    rebuildTreeInPlace(this.#store);
+  }
+
+  hasRoute(name: string): boolean {
+    return this.#store.matcher.hasRoute(name);
+  }
+
+  clearRoutes(): void {
+    resetStore(this.#store);
+  }
+
+  // =========================================================================
+  // Path operations
+  // =========================================================================
+
+  /**
+   * Builds a URL path for a route.
+   * Note: Argument validation is done by facade (Router.ts) via validateBuildPathArgs.
+   *
+   * @param route - Route name
+   * @param params - Route parameters
+   * @param options - Router options
+   */
+  buildPath(route: string, params?: Params, options?: Options): string {
+    if (route === constants.UNKNOWN_ROUTE) {
+      return typeof params?.path === "string" ? params.path : "";
+    }
+
+    const paramsWithDefault = Object.hasOwn(
+      this.#store.config.defaultParams,
+      route,
+    )
+      ? { ...this.#store.config.defaultParams[route], ...params }
+      : /* v8 ignore next -- @preserve: V8 can't track ?? branch in ternary; covered by buildPath tests without params */ (params ??
+        {});
+
+    const encodedParams =
+      typeof this.#store.config.encoders[route] === "function"
+        ? this.#store.config.encoders[route]({ ...paramsWithDefault })
+        : paramsWithDefault;
+
+    return this.#store.matcher.buildPath(
+      route,
+      encodedParams,
+      this.#getBuildPathOptions(options),
+    );
+  }
+
+  /**
+   * Matches a URL path to a route in the tree.
+   * Note: Argument validation is done by facade (Router.ts) via validateMatchPathArgs.
+   */
+  matchPath<P extends Params = Params>(
+    path: string,
+    options?: Options,
+  ): State<P> | undefined {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Router.ts always passes options
+    const opts = options!;
+
+    const matchResult = this.#store.matcher.match(path);
+
+    if (!matchResult) {
+      return undefined;
+    }
+
+    const routeState = createRouteState(matchResult);
+    const { name, params, meta } = routeState;
+
+    const decodedParams =
+      typeof this.#store.config.decoders[name] === "function"
+        ? this.#store.config.decoders[name](params as Params)
+        : params;
+
+    const { name: routeName, params: routeParams } = this.#deps.forwardState<P>(
+      name,
+      decodedParams as P,
+    );
+
+    let builtPath = path;
+
+    if (opts.rewritePathOnMatch) {
+      const buildParams =
+        typeof this.#store.config.encoders[routeName] === "function"
+          ? this.#store.config.encoders[routeName]({
+              ...(routeParams as Params),
+            })
+          : (routeParams as Record<string, unknown>);
+
+      const ts = opts.trailingSlash;
+
+      builtPath = this.#store.matcher.buildPath(routeName, buildParams, {
+        trailingSlash: ts === "never" || ts === "always" ? ts : undefined,
+        queryParamsMode: opts.queryParamsMode,
+      });
+    }
+
+    return this.#deps.makeState<P>(routeName, routeParams, builtPath, meta);
+  }
+
+  /**
+   * Applies forwardTo and returns resolved state with merged defaultParams.
+   *
+   * Merges params in order:
+   * 1. Source route defaultParams
+   * 2. Provided params
+   * 3. Target route defaultParams (after resolving forwardTo)
+   */
+  forwardState<P extends Params = Params>(
+    name: string,
+    params: P,
+  ): { name: string; params: P } {
+    if (Object.hasOwn(this.#store.config.forwardFnMap, name)) {
+      const paramsWithSourceDefaults = this.#mergeDefaultParams(name, params);
+      const dynamicForward = this.#store.config.forwardFnMap[name];
+      const resolved = this.#resolveDynamicForward(
+        name,
+        dynamicForward,
+        params,
+      );
+
+      return {
+        name: resolved,
+        params: this.#mergeDefaultParams(resolved, paramsWithSourceDefaults),
+      };
+    }
+
+    const staticForward = this.#store.resolvedForwardMap[name] ?? name;
+
+    if (
+      staticForward !== name &&
+      Object.hasOwn(this.#store.config.forwardFnMap, staticForward)
+    ) {
+      const paramsWithSourceDefaults = this.#mergeDefaultParams(name, params);
+      const targetDynamicForward =
+        this.#store.config.forwardFnMap[staticForward];
+      const resolved = this.#resolveDynamicForward(
+        staticForward,
+        targetDynamicForward,
+        params,
+      );
+
+      return {
+        name: resolved,
+        params: this.#mergeDefaultParams(resolved, paramsWithSourceDefaults),
+      };
+    }
+
+    if (staticForward !== name) {
+      const paramsWithSourceDefaults = this.#mergeDefaultParams(name, params);
+
+      return {
+        name: staticForward,
+        params: this.#mergeDefaultParams(
+          staticForward,
+          paramsWithSourceDefaults,
+        ),
+      };
+    }
+
+    return { name, params: this.#mergeDefaultParams(name, params) };
+  }
+
+  /**
+   * Builds a RouteTreeState from already-resolved route name and params.
+   * Called by Router.buildState after forwardState is applied at facade level.
+   * This allows plugins to intercept forwardState.
+   */
+  buildStateResolved(
+    resolvedName: string,
+    resolvedParams: Params,
+  ): RouteTreeState | undefined {
+    const segments = this.#store.matcher.getSegmentsByName(resolvedName);
+
+    if (!segments) {
+      return undefined;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const meta = this.#store.matcher.getMetaByName(resolvedName)!;
+
+    return createRouteState(
+      { segments, params: resolvedParams, meta },
+      resolvedName,
+    );
+  }
+
+  // =========================================================================
+  // Query operations
+  // =========================================================================
+
+  /**
+   * Checks if a route is currently active.
+   */
+  isActiveRoute(
+    name: string,
+    params: Params = {},
+    strictEquality = false,
+    ignoreQueryParams = true,
+  ): boolean {
+    // Note: empty string check is handled by Router.ts facade
+    const activeState = this.#deps.getState();
+
+    if (!activeState) {
+      return false;
+    }
+
+    const activeName = activeState.name;
+
+    // Fast path: check if routes are related before expensive operations
+    if (
+      activeName !== name &&
+      !activeName.startsWith(`${name}.`) &&
+      !name.startsWith(`${activeName}.`)
+    ) {
+      return false;
+    }
+
+    const defaultParams = this.#store.config.defaultParams[name] as
+      | Params
+      | undefined;
+
+    // Exact match case
+    if (strictEquality || activeName === name) {
+      const effectiveParams = defaultParams
+        ? { ...defaultParams, ...params }
+        : params;
+
+      const targetState: State = {
+        name,
+        params: effectiveParams,
+        path: "",
+      };
+
+      return this.#deps.areStatesEqual(
+        targetState,
+        activeState,
+        ignoreQueryParams,
+      );
+    }
+
+    // Hierarchical check: activeState is a descendant of target (name)
+    const activeParams = activeState.params;
+
+    if (!paramsMatch(params, activeParams)) {
+      return false;
+    }
+
+    // Check defaultParams (skip keys already in params)
+    return (
+      !defaultParams ||
+      paramsMatchExcluding(defaultParams, activeParams, params)
+    );
+  }
+
+  getMetaForState(
+    name: string,
+  ): Record<string, Record<string, "url" | "query">> | undefined {
+    return this.#store.matcher.hasRoute(name)
+      ? this.#store.matcher.getMetaByName(name)
+      : undefined;
+  }
+
+  getUrlParams(name: string): string[] {
+    const segments = this.#store.matcher.getSegmentsByName(name);
+
+    if (!segments) {
+      return [];
+    }
+
+    return collectUrlParamsArray(segments as readonly RouteTree[]);
+  }
+
+  getStore(): RoutesStore<Dependencies> {
+    return this.#store;
+  }
+
+  #mergeDefaultParams<P extends Params = Params>(
+    routeName: string,
+    params: P,
+  ): P {
+    if (Object.hasOwn(this.#store.config.defaultParams, routeName)) {
+      return {
+        ...this.#store.config.defaultParams[routeName],
+        ...params,
+      } as P;
+    }
+
+    return params;
+  }
+
+  #getBuildPathOptions(options?: Options): CachedBuildPathOpts {
+    if (this.#cachedBuildPathOpts) {
+      return this.#cachedBuildPathOpts;
+    }
+
+    const ts = options?.trailingSlash;
+
+    this.#cachedBuildPathOpts = Object.freeze({
+      trailingSlash: ts === "never" || ts === "always" ? ts : undefined,
+      queryParamsMode: options?.queryParamsMode,
+    });
+
+    return this.#cachedBuildPathOpts;
+  }
+
+  #resolveDynamicForward(
+    startName: string,
+    startFn: ForwardToCallback<Dependencies>,
+    params: Params,
+  ): string {
+    const visited = new Set<string>([startName]);
+
+    let current = startFn(this.#deps.getDependency, params);
+    let depth = 0;
+    const MAX_DEPTH = 100;
+
+    if (typeof current !== "string") {
+      throw new TypeError(
+        `forwardTo callback must return a string, got ${typeof current}`,
+      );
+    }
+
+    while (depth < MAX_DEPTH) {
+      if (this.#store.matcher.getSegmentsByName(current) === undefined) {
+        throw new Error(`Route "${current}" does not exist`);
+      }
+
+      if (visited.has(current)) {
+        const chain = [...visited, current].join(" → ");
+
+        throw new Error(`Circular forwardTo detected: ${chain}`);
+      }
+
+      visited.add(current);
+
+      if (Object.hasOwn(this.#store.config.forwardFnMap, current)) {
+        const fn = this.#store.config.forwardFnMap[
+          current
+        ] as ForwardToCallback<Dependencies>;
+
+        current = fn(this.#deps.getDependency, params);
+
+        depth++;
+        continue;
+      }
+
+      const staticForward = this.#store.config.forwardMap[current];
+
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (staticForward !== undefined) {
+        current = staticForward;
+        depth++;
+        continue;
+      }
+
+      return current;
+    }
+
+    throw new Error(`forwardTo exceeds maximum depth of ${MAX_DEPTH}`);
+  }
+}

package/src/namespaces/RoutesNamespace/constants.ts

@@ -0,0 +1,6 @@
+// packages/core/src/namespaces/RoutesNamespace/constants.ts
+
+/**
+ * Default route name for the root node.
+ */
+export const DEFAULT_ROUTE_NAME = "";

package/src/namespaces/RoutesNamespace/forwardChain.ts

@@ -0,0 +1,34 @@
+// packages/core/src/namespaces/RoutesNamespace/forwardChain.ts
+
+export function resolveForwardChain(
+  startRoute: string,
+  forwardMap: Record<string, string>,
+  maxDepth = 100,
+): string {
+  const visited = new Set<string>();
+  const chain: string[] = [startRoute];
+  let current = startRoute;
+
+  while (forwardMap[current]) {
+    const next = forwardMap[current];
+
+    if (visited.has(next)) {
+      const cycleStart = chain.indexOf(next);
+      const cycle = [...chain.slice(cycleStart), next];
+
+      throw new Error(`Circular forwardTo: ${cycle.join(" → ")}`);
+    }
+
+    visited.add(current);
+    chain.push(next);
+    current = next;
+
+    if (chain.length > maxDepth) {
+      throw new Error(
+        `forwardTo chain exceeds maximum depth (${maxDepth}): ${chain.join(" → ")}`,
+      );
+    }
+  }
+
+  return current;
+}

package/src/namespaces/RoutesNamespace/helpers.ts

@@ -0,0 +1,126 @@
+// packages/core/src/namespaces/RoutesNamespace/helpers.ts
+
+import type { RouteConfig } from "./types";
+import type { Route } from "../../types";
+import type {
+  DefaultDependencies,
+  ForwardToCallback,
+  Params,
+} from "@real-router/types";
+import type { RouteDefinition } from "route-tree";
+
+/**
+ * Creates an empty RouteConfig.
+ */
+export function createEmptyConfig(): RouteConfig {
+  return {
+    decoders: Object.create(null) as Record<string, (params: Params) => Params>,
+    encoders: Object.create(null) as Record<string, (params: Params) => Params>,
+    defaultParams: Object.create(null) as Record<string, Params>,
+    forwardMap: Object.create(null) as Record<string, string>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    forwardFnMap: Object.create(null) as Record<string, ForwardToCallback<any>>,
+  };
+}
+
+// ============================================================================
+// Route Tree Helpers
+// ============================================================================
+
+/**
+ * Checks if all params from source exist with same values in target.
+ * Small function body allows V8 inlining.
+ */
+export function paramsMatch(source: Params, target: Params): boolean {
+  for (const key in source) {
+    if (source[key] !== target[key]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Checks params match, skipping keys present in skipKeys.
+ */
+export function paramsMatchExcluding(
+  source: Params,
+  target: Params,
+  skipKeys: Params,
+): boolean {
+  for (const key in source) {
+    if (key in skipKeys) {
+      continue;
+    }
+    if (source[key] !== target[key]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Sanitizes a route by keeping only essential properties.
+ */
+export function sanitizeRoute<Dependencies extends DefaultDependencies>(
+  route: Route<Dependencies>,
+): RouteDefinition {
+  const sanitized: RouteDefinition = {
+    name: route.name,
+    path: route.path,
+  };
+
+  if (route.children) {
+    sanitized.children = route.children.map((child) => sanitizeRoute(child));
+  }
+
+  return sanitized;
+}
+
+/**
+ * Recursively removes a route from definitions array.
+ */
+export function removeFromDefinitions(
+  definitions: RouteDefinition[],
+  routeName: string,
+  parentPrefix = "",
+): boolean {
+  for (let i = 0; i < definitions.length; i++) {
+    const route = definitions[i];
+    const fullName = parentPrefix
+      ? `${parentPrefix}.${route.name}`
+      : route.name;
+
+    if (fullName === routeName) {
+      definitions.splice(i, 1);
+
+      return true;
+    }
+
+    if (
+      route.children &&
+      routeName.startsWith(`${fullName}.`) &&
+      removeFromDefinitions(route.children, routeName, fullName)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Clears configuration entries that match the predicate.
+ */
+export function clearConfigEntries<T>(
+  config: Record<string, T>,
+  matcher: (key: string) => boolean,
+): void {
+  for (const key of Object.keys(config)) {
+    if (matcher(key)) {
+      delete config[key];
+    }
+  }
+}

package/src/namespaces/RoutesNamespace/index.ts

@@ -0,0 +1,11 @@
+// packages/core/src/namespaces/RoutesNamespace/index.ts
+
+export { RoutesNamespace } from "./RoutesNamespace";
+
+export { DEFAULT_ROUTE_NAME } from "./constants";
+
+export { createEmptyConfig } from "./helpers";
+
+export type { RouteConfig, RoutesDependencies } from "./types";
+
+export type { RoutesStore } from "./routesStore";