@real-router/core 0.56.0 → 0.57.1

package/src/namespaces/RoutesNamespace/routesStore.ts

@@ -1,566 +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
-// =============================================================================
-
-/**
- * Throws if `forwardTo` is an async function (native or transpiled). Async
- * forwardTo callbacks break the synchronous matchPath/buildPath contract.
- * Runs inside `registerForwardTo`, which the prepare-phase build invokes via
- * `registerAllRouteHandlers` — so the check fires before any store mutation.
- */
-function assertForwardToNotAsync(forwardTo: unknown, fullName: string): void {
-  if (typeof forwardTo !== "function") {
-    return;
-  }
-
-  const isNativeAsync =
-    (forwardTo as { constructor: { name: string } }).constructor.name ===
-    "AsyncFunction";
-  const isTranspiledAsync = (forwardTo as { toString: () => string })
-    .toString()
-    .includes("__awaiter");
-
-  if (isNativeAsync || isTranspiledAsync) {
-    throw new TypeError(
-      `forwardTo callback cannot be async for route "${fullName}". ` +
-        `Async functions break matchPath/buildPath.`,
-    );
-  }
-}
-
-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}".`,
-    );
-  }
-
-  assertForwardToNotAsync(route.forwardTo, fullName);
-
-  // 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>>,
-): 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;
-  }
-
-  // Guards are collected here and registered into the lifecycle later — by
-  // `adoptRouteArtifacts` (add/replace) or `setDependencies` (initial routes) —
-  // so the build stays a pure, side-effect-free preparation step.
-  if (route.canActivate) {
-    pendingCanActivate.set(fullName, route.canActivate);
-  }
-
-  if (route.canDeactivate) {
-    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;
-  }
-}
-
-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>>,
-  parentName = "",
-): void {
-  for (const route of routes) {
-    const fullName = parentName ? `${parentName}.${route.name}` : route.name;
-
-    registerSingleRouteHandlers(
-      route,
-      fullName,
-      config,
-      routeCustomFields,
-      pendingCanActivate,
-      pendingCanDeactivate,
-    );
-
-    if (route.children) {
-      registerAllRouteHandlers(
-        route.children,
-        config,
-        routeCustomFields,
-        pendingCanActivate,
-        pendingCanDeactivate,
-        fullName,
-      );
-    }
-  }
-}
-
-// =============================================================================
-// Prepare-then-commit (issue #698)
-//
-// add()/replace() build the complete new store state into LOCAL structures, and
-// only swap it into the store once every core-level error has surfaced from the
-// build itself (async/circular forwardTo throw in registerAllRouteHandlers /
-// refreshForwardMap; invalid path constraint throws in rebuildTree). The store
-// is mutated only by `adoptRouteArtifacts`, which cannot throw — so a rejected
-// build leaves the existing routes untouched. The two silent-corruption cases
-// route-tree never throws on (duplicate name vs an existing route, missing
-// parent) are caught up front by `assertAddable`.
-// =============================================================================
-
-/**
- * The fully-built, ready-to-swap result of preparing a route mutation. Holds
- * everything `adoptRouteArtifacts` assigns into the store.
- */
-interface RouteArtifacts<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  readonly definitions: RouteDefinition[];
-  readonly config: RouteConfig;
-  readonly routeCustomFields: Record<string, Record<string, unknown>>;
-  readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
-  readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
-  readonly tree: RouteTree;
-  readonly matcher: Matcher;
-  readonly resolvedForwardMap: Record<string, string>;
-}
-
-/** Null-proto shallow clone of a RouteConfig (preserves the 5 maps' contents). */
-function cloneConfig(config: RouteConfig): RouteConfig {
-  const clone = createEmptyConfig();
-
-  Object.assign(clone.decoders, config.decoders);
-  Object.assign(clone.encoders, config.encoders);
-  Object.assign(clone.defaultParams, config.defaultParams);
-  Object.assign(clone.forwardMap, config.forwardMap);
-  Object.assign(clone.forwardFnMap, config.forwardFnMap);
-
-  return clone;
-}
-
-/**
- * Returns a new definitions array with `added` inserted, without mutating the
- * input. For a top-level add the existing definitions are shallow-copied and
- * `added` appended. For a parented add the spine down to the parent is cloned
- * (siblings/other branches are shared by reference) and `added` appended to the
- * parent's children. Caller guarantees the parent path exists (see assertAddable).
- */
-function insertAddedDefinitions(
-  definitions: readonly RouteDefinition[],
-  added: RouteDefinition[],
-  parentSegments: readonly string[],
-): RouteDefinition[] {
-  if (parentSegments.length === 0) {
-    return [...definitions, ...added];
-  }
-
-  const [head, ...rest] = parentSegments;
-
-  return definitions.map((def) => {
-    if (def.name !== head) {
-      return def;
-    }
-
-    const children = def.children ?? [];
-
-    return {
-      ...def,
-      children:
-        rest.length === 0
-          ? [...children, ...added]
-          : insertAddedDefinitions(children, added, rest),
-    };
-  });
-}
-
-/** Depth-first walk yielding each route's full dotted name (no side effects). */
-function walkRouteNames<Dependencies extends DefaultDependencies>(
-  routes: readonly Route<Dependencies>[],
-  parentName: string,
-  onName: (fullName: string) => void,
-): void {
-  for (const route of routes) {
-    const fullName = parentName ? `${parentName}.${route.name}` : route.name;
-
-    onName(fullName);
-
-    if (route.children) {
-      walkRouteNames(route.children, fullName, onName);
-    }
-  }
-}
-
-/**
- * Up-front guard for `add` against the two corruptions route-tree stays silent
- * on: a missing `parent`, and a name that collides with an EXISTING route
- * (which would otherwise be silently overwritten). Throws before any build.
- */
-export function assertAddable<Dependencies extends DefaultDependencies>(
-  store: RoutesStore<Dependencies>,
-  routes: readonly Route<Dependencies>[],
-  parentName: string | undefined,
-): void {
-  if (parentName !== undefined && !store.matcher.hasRoute(parentName)) {
-    throw new Error(
-      `[router.addRoute] Parent route "${parentName}" does not exist`,
-    );
-  }
-
-  walkRouteNames(routes, parentName ?? "", (fullName) => {
-    if (store.matcher.hasRoute(fullName)) {
-      throw new Error(`[router.addRoute] Route "${fullName}" already exists`);
-    }
-  });
-}
-
-/**
- * Builds RouteArtifacts from a final definitions array and the routes whose
- * handlers (config + guards) populate `config`/`routeCustomFields`. Guards are
- * collected into the returned pending maps (depsStore is intentionally omitted
- * so nothing compiles or touches the lifecycle here). THROWS on async/circular
- * forwardTo and invalid path constraint — before the caller mutates the store.
- */
-function buildArtifacts<Dependencies extends DefaultDependencies>(
-  definitions: RouteDefinition[],
-  routesForHandlers: readonly Route<Dependencies>[],
-  config: RouteConfig,
-  routeCustomFields: Record<string, Record<string, unknown>>,
-  handlerParentName: string,
-  rootPath: string,
-  matcherOptions: CreateMatcherOptions | undefined,
-): RouteArtifacts<Dependencies> {
-  const pendingCanActivate = new Map<string, GuardFnFactory<Dependencies>>();
-  const pendingCanDeactivate = new Map<string, GuardFnFactory<Dependencies>>();
-
-  registerAllRouteHandlers(
-    routesForHandlers,
-    config,
-    routeCustomFields,
-    pendingCanActivate,
-    pendingCanDeactivate,
-    handlerParentName,
-  );
-
-  const resolvedForwardMap = refreshForwardMap(config);
-  const { tree, matcher } = rebuildTree(definitions, rootPath, matcherOptions);
-
-  return {
-    definitions,
-    config,
-    routeCustomFields,
-    pendingCanActivate,
-    pendingCanDeactivate,
-    tree,
-    matcher,
-    resolvedForwardMap,
-  };
-}
-
-/** Builds the merged artifacts for an incremental `add` (existing ∪ new). */
-export function buildAddArtifacts<Dependencies extends DefaultDependencies>(
-  store: RoutesStore<Dependencies>,
-  routes: readonly Route<Dependencies>[],
-  parentName: string | undefined,
-): RouteArtifacts<Dependencies> {
-  const definitions = insertAddedDefinitions(
-    store.definitions,
-    routes.map((route) => sanitizeRoute(route)),
-    parentName === undefined ? [] : parentName.split("."),
-  );
-
-  return buildArtifacts(
-    definitions,
-    routes,
-    cloneConfig(store.config),
-    Object.assign(
-      Object.create(null) as Record<string, Record<string, unknown>>,
-      store.routeCustomFields,
-    ),
-    parentName ?? "",
-    store.rootPath,
-    store.matcherOptions,
-  );
-}
-
-/** Builds the fresh artifacts for a full `replace` (standalone new set). */
-export function buildReplaceArtifacts<Dependencies extends DefaultDependencies>(
-  routes: readonly Route<Dependencies>[],
-  rootPath: string,
-  matcherOptions: CreateMatcherOptions | undefined,
-): RouteArtifacts<Dependencies> {
-  return buildArtifacts(
-    routes.map((route) => sanitizeRoute(route)),
-    routes,
-    createEmptyConfig(),
-    Object.create(null) as Record<string, Record<string, unknown>>,
-    "",
-    rootPath,
-    matcherOptions,
-  );
-}
-
-/**
- * Commits prepared artifacts into the store in place. Pure assignment — never
- * throws — so it is the single atomic swap point of the prepare-then-commit
- * pipeline. Guard registration is deferred to here (the build collected guards
- * without compiling); `depsStore` is always set on a wired router, which is the
- * only path that reaches `add`/`replace`.
- */
-export function adoptRouteArtifacts<Dependencies extends DefaultDependencies>(
-  store: RoutesStore<Dependencies>,
-  artifacts: RouteArtifacts<Dependencies>,
-): void {
-  store.definitions.length = 0;
-
-  for (const def of artifacts.definitions) {
-    store.definitions.push(def);
-  }
-
-  Object.assign(store.config, artifacts.config);
-  store.routeCustomFields = artifacts.routeCustomFields;
-  store.tree = artifacts.tree;
-  store.matcher = artifacts.matcher;
-  store.resolvedForwardMap = artifacts.resolvedForwardMap;
-
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- depsStore is set once the router is wired; add/replace only run on a wired router (constructor-time registration uses createRoutesStore)
-  const deps = store.depsStore!;
-
-  for (const [name, handler] of artifacts.pendingCanActivate) {
-    deps.addActivateGuard(name, handler);
-  }
-
-  for (const [name, handler] of artifacts.pendingCanDeactivate) {
-    deps.addDeactivateGuard(name, handler);
-  }
-}
-
-// =============================================================================
-// Factory
-// =============================================================================
-
-export function createRoutesStore<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(
-  routes: Route<Dependencies>[],
-  matcherOptions?: CreateMatcherOptions,
-): RoutesStore<Dependencies> {
-  // Initial routes are a standalone set at rootPath "" — same build the
-  // prepare-then-commit `replace` path uses. Guards land in the pending maps
-  // (depsStore is wired later via setDependencies, which flushes them).
-  const artifacts = buildReplaceArtifacts(routes, "", matcherOptions);
-
-  return {
-    definitions: artifacts.definitions,
-    config: artifacts.config,
-    tree: artifacts.tree,
-    matcher: artifacts.matcher,
-    resolvedForwardMap: artifacts.resolvedForwardMap,
-    routeCustomFields: artifacts.routeCustomFields,
-    rootPath: "",
-    matcherOptions,
-    depsStore: undefined,
-    lifecycleNamespace: undefined,
-    pendingCanActivate: artifacts.pendingCanActivate,
-    pendingCanDeactivate: artifacts.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>>;
-}