@real-router/core 0.56.0 → 0.57.0

package/src/namespaces/RouterLifecycleNamespace/types.ts

@@ -1,30 +0,0 @@
-// packages/core/src/namespaces/RouterLifecycleNamespace/types.ts
-
-import type {
-  NavigationOptions,
-  Options,
-  Params,
-  State,
-} from "@real-router/types";
-
-export interface RouterLifecycleDependencies {
-  getOptions: () => Options;
-  /**
-   * Commit a fully-resolved State without re-running `forwardState`/`buildPath`.
-   * `start(path)` uses this to commit `matchPath(path)` directly — the same
-   * primitive URL plugins use on popstate / navigate-event (#525). Keeps
-   * `state.path` identical to the source URL (preserves trailing slash in
-   * `trailingSlash:"preserve"` mode) and avoids the redundant
-   * forwardState+buildPath round-trip in `buildNavigateState`.
-   */
-  navigateToState: (state: State, opts: NavigationOptions) => Promise<State>;
-  navigateToNotFound: (path: string) => State;
-  clearState: () => void;
-  matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
-  completeStart: () => void;
-  emitTransitionError: (
-    toState: State | undefined,
-    fromState: State | undefined,
-    error: Error,
-  ) => void;
-}

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -1,582 +0,0 @@
-// packages/core/src/namespaces/RoutesNamespace/RoutesNamespace.ts
-
-import { DEFAULT_ROUTE_NAME } from "./constants";
-import {
-  matchSourceTrailingSlash,
-  paramsMatch,
-  paramsMatchExcluding,
-  stripQueryDefaults,
-} from "./helpers";
-import {
-  createRoutesStore,
-  rebuildTreeInPlace,
-  resetStore,
-} from "./routesStore";
-import { constants, DEFAULT_TRANSITION } 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,
-  };
-}
-
-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;
-      }
-
-      // Root node (DEFAULT_ROUTE_NAME === "") has no route-level identity — it
-      // represents "any route". It must update on every transition so that
-      // consumers subscribed via useRouteNode("") (including RouteView at
-      // the top of the tree) see every change. This matches the documented
-      // contract in adapter docs: `useRouteNode("")` — Root — ALL route
-      // changes. See #519 for the missed transitions it was suffering from
-      // (users → users.user had intersection="users", leaving the root node
-      // un-updated under a flat <Match segment="users.user" exact> pattern).
-      if (nodeName === DEFAULT_ROUTE_NAME) {
-        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)
-        : 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,
-      });
-
-      if (ts === "preserve") {
-        builtPath = matchSourceTrailingSlash(path, builtPath);
-      }
-    }
-
-    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: "",
-        transition: DEFAULT_TRANSITION,
-        context: {},
-      };
-
-      return this.#deps.areStatesEqual(
-        targetState,
-        activeState,
-        ignoreQueryParams,
-      );
-    }
-
-    // The fast path above lets through three relations: exact (handled in
-    // the previous block), `activeName` descendant of `name`, and `name`
-    // descendant of `activeName`. Only the first two count as "active" —
-    // a link pointing DEEPER than the current state is a navigation option,
-    // not an active state. Reject the descendant-of-active case explicitly.
-    if (!activeName.startsWith(`${name}.`)) {
-      return false;
-    }
-
-    // Hierarchical check: activeState is a descendant of target (name)
-    const activeParams = activeState.params;
-
-    if (!paramsMatch(params, activeParams)) {
-      return false;
-    }
-
-    if (!defaultParams) {
-      return true;
-    }
-
-    // Honor `ignoreQueryParams` symmetrically with the exact-match branch
-    // above: query-only param differences (e.g. parent has
-    // `defaultParams: { sort: "asc" }` while the active descendant is
-    // `products.detail` with `params: { id: "6" }` and no sort) must not
-    // disqualify an ancestor link from being active. Strip query-typed
-    // keys of `name` from the defaults before comparison; URL-typed keys
-    // (`:id`, `:role`, etc.) are still enforced.
-    // `name` reaches this point only after the fast-path established a valid
-    // hierarchical relation AND `defaultParams` is non-null — both imply the
-    // matcher has registered the route, so `getMetaByName(name)![name]` is
-    // always defined here. Non-null assertions trade a defensive guard for
-    // honest 100% coverage.
-    const defaultsToCheck = ignoreQueryParams
-      ? stripQueryDefaults(
-          defaultParams,
-          this.#store.matcher.getMetaByName(name)?.[name],
-        )
-      : defaultParams;
-
-    return paramsMatchExcluding(defaultsToCheck, 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,
-      };
-    }
-
-    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

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

@@ -1,34 +0,0 @@
-// 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;
-}