@real-router/core 0.54.6 → 0.56.0

package/src/api/getRoutesApi.ts

@@ -2,20 +2,21 @@ import { logger } from "@real-router/logger";
 
 import { throwIfDisposed } from "./helpers";
 import { guardRouteStructure } from "../guards";
-import { createInterceptable, getInternals } from "../internals";
+import { getInternals } from "../internals";
 import {
   clearConfigEntries,
   removeFromDefinitions,
-  sanitizeRoute,
 } from "../namespaces/RoutesNamespace/helpers";
 import {
   validateClearRoutes,
   validateRemoveRoute,
 } from "../namespaces/RoutesNamespace/routeGuards";
 import {
-  clearRouteData,
+  adoptRouteArtifacts,
+  assertAddable,
+  buildAddArtifacts,
+  buildReplaceArtifacts,
   refreshForwardMap,
-  registerAllRouteHandlers,
 } from "../namespaces/RoutesNamespace/routesStore";
 
 import type { RoutesApi } from "./types";
@@ -29,6 +30,8 @@ import type {
   Params,
   Router,
   TransitionMeta,
+  TreeChangedEvent,
+  TreeStructuralPatch,
 } from "@real-router/types";
 import type { RouteDefinition, RouteTree } from "route-tree";
 
@@ -36,32 +39,6 @@ import type { RouteDefinition, RouteTree } from "route-tree";
 // Helpers
 // ============================================================================
 
-/**
- * Recursively finds a route definition by its full dotted name.
- */
-function findDefinition(
-  definitions: RouteDefinition[],
-  fullName: string,
-  parentPrefix = "",
-): RouteDefinition | undefined {
-  for (const def of definitions) {
-    const currentFullName = parentPrefix
-      ? `${parentPrefix}.${def.name}`
-      : def.name;
-
-    if (currentFullName === fullName) {
-      return def;
-    }
-
-    if (def.children && fullName.startsWith(`${currentFullName}.`)) {
-      return findDefinition(def.children, fullName, currentFullName);
-    }
-  }
-
-  /* v8 ignore next -- @preserve: defensive return, callers validate route exists before calling */
-  return undefined;
-}
-
 /**
  * Clears all config entries and lifecycle handlers for a removed route
  * (and all its descendants).
@@ -116,47 +93,58 @@ function updateForwardTo<
   name: string,
   forwardTo: string | ForwardToCallback<Dependencies> | null,
   config: RouteConfig,
-  refreshForwardMapFn: (config: RouteConfig) => Record<string, string>,
 ): Record<string, string> {
+  // Prepare-then-commit (issue #698): apply the change to CLONES of the forward
+  // maps, resolve the chain (a cycle throws here), and only then swap the clones
+  // in — so a rejected update never leaves config.forwardMap poisoned.
+  const forwardMap = Object.assign(
+    Object.create(null) as RouteConfig["forwardMap"],
+    config.forwardMap,
+  );
+  const forwardFnMap = Object.assign(
+    Object.create(null) as RouteConfig["forwardFnMap"],
+    config.forwardFnMap,
+  );
+
   if (forwardTo === null) {
-    delete config.forwardMap[name];
-    delete config.forwardFnMap[name];
+    delete forwardMap[name];
+    delete forwardFnMap[name];
   } else if (typeof forwardTo === "string") {
-    delete config.forwardFnMap[name];
-    config.forwardMap[name] = forwardTo;
+    delete forwardFnMap[name];
+    forwardMap[name] = forwardTo;
   } else {
-    delete config.forwardMap[name];
-    config.forwardFnMap[name] = forwardTo;
+    delete forwardMap[name];
+    forwardFnMap[name] = forwardTo;
   }
 
-  return refreshForwardMapFn(config);
+  const resolved = refreshForwardMap({ ...config, forwardMap });
+
+  config.forwardMap = forwardMap;
+  config.forwardFnMap = forwardFnMap;
+
+  return resolved;
 }
 
 /**
- * Builds a full Route object from a bare RouteDefinition by re-attaching
- * config entries and lifecycle factories.
- *
- * RECURSIVE — call with the factories tuple obtained ONCE from
- * `lifecycleNamespace.getFactories()` and pass it through to children.
+ * Re-attaches the stored config (forwardTo / defaultParams / encode-decode) and
+ * lifecycle guards for `lookupName` onto `route`, then returns it (mutates in
+ * place). Shared by {@link enrichRoute} (nested, bare `name`) and
+ * {@link buildFlatRoute} (flat, full dotted `name`) — one source of truth for
+ * the route-config field set.
  */
-function enrichRoute<
+function assignRouteConfig<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
-  routeDef: RouteDefinition,
-  routeName: string,
+  route: Route<Dependencies>,
+  lookupName: string,
   config: RouteConfig,
   factories: [
     Record<string, GuardFnFactory<Dependencies>>,
     Record<string, GuardFnFactory<Dependencies>>,
   ],
 ): Route<Dependencies> {
-  const route: Route<Dependencies> = {
-    name: routeDef.name,
-    path: routeDef.path,
-  };
-
-  const forwardToFn = config.forwardFnMap[routeName];
-  const forwardToStr = config.forwardMap[routeName];
+  const forwardToFn = config.forwardFnMap[lookupName];
+  const forwardToStr = config.forwardMap[lookupName];
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   if (forwardToFn !== undefined) {
@@ -166,28 +154,56 @@ function enrichRoute<
     route.forwardTo = forwardToStr;
   }
 
-  if (routeName in config.defaultParams) {
-    route.defaultParams = config.defaultParams[routeName];
+  if (lookupName in config.defaultParams) {
+    route.defaultParams = config.defaultParams[lookupName];
   }
 
-  if (routeName in config.decoders) {
-    route.decodeParams = config.decoders[routeName];
+  if (lookupName in config.decoders) {
+    route.decodeParams = config.decoders[lookupName];
   }
 
-  if (routeName in config.encoders) {
-    route.encodeParams = config.encoders[routeName];
+  if (lookupName in config.encoders) {
+    route.encodeParams = config.encoders[lookupName];
   }
 
   const [canDeactivateFactories, canActivateFactories] = factories;
 
-  if (routeName in canActivateFactories) {
-    route.canActivate = canActivateFactories[routeName];
+  if (lookupName in canActivateFactories) {
+    route.canActivate = canActivateFactories[lookupName];
   }
 
-  if (routeName in canDeactivateFactories) {
-    route.canDeactivate = canDeactivateFactories[routeName];
+  if (lookupName in canDeactivateFactories) {
+    route.canDeactivate = canDeactivateFactories[lookupName];
   }
 
+  return route;
+}
+
+/**
+ * Builds a full Route object from a bare RouteDefinition by re-attaching
+ * config entries and lifecycle factories.
+ *
+ * RECURSIVE — call with the factories tuple obtained ONCE from
+ * `lifecycleNamespace.getFactories()` and pass it through to children.
+ */
+function enrichRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routeDef: RouteDefinition,
+  routeName: string,
+  config: RouteConfig,
+  factories: [
+    Record<string, GuardFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
+  ],
+): Route<Dependencies> {
+  const route: Route<Dependencies> = {
+    name: routeDef.name,
+    path: routeDef.path,
+  };
+
+  assignRouteConfig(route, routeName, config, factories);
+
   if (routeDef.children) {
     route.children = routeDef.children.map((child) =>
       enrichRoute(child, `${routeName}.${child.name}`, config, factories),
@@ -198,51 +214,226 @@ function enrichRoute<
 }
 
 // ============================================================================
-// CRUD operations
+// TREE_CHANGED payload helpers
 // ============================================================================
 
 /**
- * Adds one or more routes to the router.
- * Input already validated by facade.
+ * Builds a single FLAT `Route` for `fullName` from the store config + lifecycle
+ * factories — `name` is the FULL dotted name and there is no `children` array
+ * (consumers want a flat, by-name list). Frozen on construction.
  */
-function addRoutes<
+function buildFlatRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  fullName: string,
+  path: string,
+  config: RouteConfig,
+  factories: [
+    Record<string, GuardFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
+  ],
+): Route<Dependencies> {
+  const route: Route<Dependencies> = { name: fullName, path };
+
+  assignRouteConfig(route, fullName, config, factories);
+
+  return Object.freeze(route);
+}
+
+/**
+ * Walks the store's definitions depth-first, building a FLAT
+ * `Map<fullName, Route>` for every node whose full dotted name satisfies
+ * `include`. Reads the live store, so call it at the right moment relative to
+ * the mutation (before for removed, after for added).
+ */
+function collectFlatRoutes<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(
   store: RoutesStore<Dependencies>,
-  routes: Route<Dependencies>[],
-  parentName?: string,
-): void {
-  if (parentName) {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const parentDef = findDefinition(store.definitions, parentName)!;
+  include: (fullName: string) => boolean,
+): Map<string, Route<Dependencies>> {
+  const result = new Map<string, Route<Dependencies>>();
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+  const factories = store.lifecycleNamespace!.getFactories();
+
+  const walk = (defs: readonly RouteDefinition[], parentName: string): void => {
+    for (const def of defs) {
+      const fullName = parentName ? `${parentName}.${def.name}` : def.name;
 
-    parentDef.children ??= [];
+      if (include(fullName)) {
+        result.set(
+          fullName,
+          buildFlatRoute(fullName, def.path, store.config, factories),
+        );
+      }
 
-    for (const route of routes) {
-      parentDef.children.push(sanitizeRoute(route));
+      if (def.children) {
+        walk(def.children, fullName);
+      }
     }
-  } else {
-    for (const route of routes) {
-      store.definitions.push(sanitizeRoute(route));
+  };
+
+  walk(store.definitions, "");
+
+  return result;
+}
+
+/**
+ * Collects the route `name` and all of its descendants as a FLAT, frozen array.
+ * MUST be called BEFORE the removal mutation — the nodes are gone afterwards.
+ */
+function collectSubtree<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  name: string,
+): readonly Route<Dependencies>[] {
+  const prefix = `${name}.`;
+  const subtree = collectFlatRoutes(
+    store,
+    (fullName) => fullName === name || fullName.startsWith(prefix),
+  );
+
+  return Object.freeze([...subtree.values()]);
+}
+
+/**
+ * Builds the FLAT, frozen payload array for an `add`, walking only the input
+ * routes — O(added), not O(tree). `path` is taken from the input verbatim
+ * (`sanitizeRoute` never rewrites it); config fields are read from the
+ * post-commit store by full name. `add` never removes, so the input subtree is
+ * exactly what changed.
+ */
+function collectAddedRoutes<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routes: readonly Route<Dependencies>[],
+  parentName: string | undefined,
+  store: RoutesStore<Dependencies>,
+): readonly Route<Dependencies>[] {
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+  const factories = store.lifecycleNamespace!.getFactories();
+  const result: Route<Dependencies>[] = [];
+
+  const walk = (
+    input: readonly Route<Dependencies>[],
+    parent: string,
+  ): void => {
+    for (const route of input) {
+      const fullName = parent ? `${parent}.${route.name}` : route.name;
+
+      result.push(
+        buildFlatRoute(fullName, route.path, store.config, factories),
+      );
+
+      if (route.children) {
+        walk(route.children, fullName);
+      }
+    }
+  };
+
+  walk(routes, parentName ?? "");
+
+  return Object.freeze(result);
+}
+
+/** Diffs two flat route maps by full name into frozen removed/added arrays. */
+function diffFlatRoutes<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  before: ReadonlyMap<string, Route<Dependencies>>,
+  after: ReadonlyMap<string, Route<Dependencies>>,
+): {
+  removed: readonly Route<Dependencies>[];
+  added: readonly Route<Dependencies>[];
+} {
+  const removed: Route<Dependencies>[] = [];
+  const added: Route<Dependencies>[] = [];
+
+  for (const [fullName, route] of before) {
+    if (!after.has(fullName)) {
+      removed.push(route);
     }
   }
 
-  registerAllRouteHandlers(
-    routes,
-    store.config,
-    store.routeCustomFields,
-    store.pendingCanActivate,
-    store.pendingCanDeactivate,
-    store.depsStore,
-    parentName ?? "",
-  );
+  for (const [fullName, route] of after) {
+    if (!before.has(fullName)) {
+      added.push(route);
+    }
+  }
 
-  store.treeOperations.commitTreeChanges(store);
+  return { removed: Object.freeze(removed), added: Object.freeze(added) };
+}
+
+/**
+ * Builds the structural subset of an `update()` patch (forwardTo /
+ * defaultParams / encodeParams / decodeParams) from the already-destructured
+ * update fields — so user getters are not re-invoked. A guard-only patch yields
+ * an empty object → the caller emits no TREE_CHANGED (О-7: guards are
+ * invoked-on-demand, not cached, so they need no observation channel).
+ *
+ * The returned envelope is a fresh object (caller's patch untouched) and is
+ * frozen on construction. Nested values (e.g. `defaultParams`) are kept by
+ * reference — the same objects the router stored — so exotic inputs (circular
+ * refs, class instances) are tolerated, matching `update()`'s existing contract.
+ */
+function buildStructuralPatch<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(fields: {
+  forwardTo?: string | ForwardToCallback<Dependencies> | null | undefined;
+  defaultParams?: Params | null | undefined;
+  decodeParams?: ((params: Params) => Params) | null | undefined;
+  encodeParams?: ((params: Params) => Params) | null | undefined;
+}): Readonly<TreeStructuralPatch<Dependencies>> {
+  const patch: TreeStructuralPatch<Dependencies> = {};
+
+  if (fields.forwardTo !== undefined) {
+    patch.forwardTo = fields.forwardTo;
+  }
+
+  if (fields.defaultParams !== undefined) {
+    patch.defaultParams = fields.defaultParams;
+  }
+
+  if (fields.encodeParams !== undefined) {
+    patch.encodeParams = fields.encodeParams;
+  }
+
+  if (fields.decodeParams !== undefined) {
+    patch.decodeParams = fields.decodeParams;
+  }
+
+  return Object.freeze(patch);
+}
+
+// ============================================================================
+// CRUD operations
+// ============================================================================
+
+/**
+ * Adds one or more routes to the router.
+ * Input already validated by facade.
+ */
+function addRoutes<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  routes: Route<Dependencies>[],
+  parentName?: string,
+): void {
+  // Prepare-then-commit (issue #698): reject the silent-corruption cases
+  // up front (dup name vs existing, missing parent), build the merged tree /
+  // config into locals (async/circular forwardTo + invalid constraint throw
+  // here), then swap atomically. A rejected add leaves the store untouched.
+  assertAddable(store, routes, parentName);
+  adoptRouteArtifacts(store, buildAddArtifacts(store, routes, parentName));
 }
 
 /**
- * Atomically replaces all routes with a new set.
- * Follows RFC 6-step semantics for HMR support.
+ * Atomically replaces all routes with a new set (HMR / code-splitting).
+ * Prepare-then-commit (issue #698): the new set is fully built into locals
+ * first — a circular/async forwardTo or invalid path throws here, leaving the
+ * existing tree intact — then committed.
  */
 function replaceRoutes<
   Dependencies extends DefaultDependencies = DefaultDependencies,
@@ -252,33 +443,25 @@ function replaceRoutes<
   ctx: RouterInternals<Dependencies>,
   currentPath: string | undefined,
   previousTransition: TransitionMeta | undefined,
+  onCommitted?: () => void,
 ): void {
-  // Step 2: Clear route data (WITHOUT tree rebuild)
-  clearRouteData(store);
+  // Build the whole new set BEFORE touching the store.
+  const artifacts = buildReplaceArtifacts(
+    routes,
+    store.rootPath,
+    store.matcherOptions,
+  );
 
-  // Step 3: Clear definition lifecycle handlers (preserve external guards)
+  // Clear definition lifecycle handlers (preserve external guards), then swap.
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
   store.lifecycleNamespace!.clearDefinitionGuards();
+  adoptRouteArtifacts(store, artifacts);
 
-  // Step 4: Register new routes
-  for (const route of routes) {
-    store.definitions.push(sanitizeRoute(route));
-  }
-
-  registerAllRouteHandlers(
-    routes,
-    store.config,
-    store.routeCustomFields,
-    store.pendingCanActivate,
-    store.pendingCanDeactivate,
-    store.depsStore,
-    "",
-  );
+  // TREE_CHANGED fires here (О-5): the new tree is committed but state is not
+  // yet revalidated, so the handler sees the new tree and the still-old state.
+  onCommitted?.();
 
-  // Step 5: One tree rebuild
-  store.treeOperations.commitTreeChanges(store);
-
-  // Step 6: Revalidate state (preserve transition from previous state)
+  // Revalidate state (preserve transition from previous state)
   if (currentPath !== undefined) {
     const revalidated = ctx.matchPath(currentPath, ctx.getOptions());
 
@@ -341,7 +524,6 @@ function updateRouteConfig<
       name,
       updates.forwardTo,
       store.config,
-      (config) => refreshForwardMap(config),
     );
   }
 
@@ -413,13 +595,12 @@ export function getRoutesApi<
 
   const store = ctx.routeGetStore();
 
-  const interceptableAdd = createInterceptable(
-    "add",
-    (routeArray: Route<Dependencies>[], options?: { parent?: string }) => {
-      addRoutes(store, routeArray, options?.parent);
-    },
-    ctx.interceptors,
-  );
+  // Single cast site: the channel is typed with default Dependencies on
+  // RouterInternals (RouterEventMap is non-generic), but payloads are built
+  // with this api's Dependencies. The runtime shape is identical.
+  const emitChange = (event: TreeChangedEvent<Dependencies>): void => {
+    ctx.treeChanged.emit(event as TreeChangedEvent);
+  };
 
   return {
     add: (routes, options) => {
@@ -438,10 +619,18 @@ export function getRoutesApi<
       ctx.validator?.routes.validateAddRouteArgs(routeArray);
       ctx.validator?.routes.validateRoutes(routeArray, store);
 
-      interceptableAdd(
-        routeArray,
-        parentName === undefined ? undefined : { parent: parentName },
-      );
+      addRoutes(store, routeArray, parentName);
+
+      // Built from the post-commit store (О-1), only when someone is listening.
+      if (ctx.treeChanged.listenerCount() > 0) {
+        const added = collectAddedRoutes(routeArray, parentName, store);
+
+        emitChange(
+          parentName === undefined
+            ? { op: "add", added }
+            : { op: "add", added, parent: parentName },
+        );
+      }
     },
 
     remove: (name) => {
@@ -460,6 +649,11 @@ export function getRoutesApi<
         return;
       }
 
+      // Snapshot the subtree BEFORE the mutation — the nodes are gone after.
+      const removedSubtree =
+        ctx.treeChanged.listenerCount() > 0
+          ? collectSubtree(store, name)
+          : undefined;
       const wasRemoved = removeRoute(store, name);
 
       if (!wasRemoved) {
@@ -467,6 +661,12 @@ export function getRoutesApi<
           "router.removeRoute",
           `Route "${name}" not found. No changes made.`,
         );
+
+        return;
+      }
+
+      if (removedSubtree !== undefined) {
+        emitChange({ op: "remove", name, removedSubtree });
       }
     },
 
@@ -523,6 +723,22 @@ export function getRoutesApi<
           store.lifecycleNamespace!.addCanDeactivate(name, canDeactivate, true);
         }
       }
+
+      // Conditional emit: structural fields only, built from the destructured
+      // locals (so user getters are not re-invoked). A guard-only or empty
+      // patch produces no event (О-7 + empty-patch rule).
+      if (ctx.treeChanged.listenerCount() > 0) {
+        const patch = buildStructuralPatch<Dependencies>({
+          forwardTo,
+          defaultParams,
+          encodeParams,
+          decodeParams,
+        });
+
+        if (Object.keys(patch).length > 0) {
+          emitChange({ op: "update", name, patch });
+        }
+      }
     },
 
     clear: () => {
@@ -535,10 +751,21 @@ export function getRoutesApi<
         return;
       }
 
+      // Snapshot the routes BEFORE the reset empties them. Emitted whenever
+      // there is a listener — even for an empty clear (О-4).
+      const removed =
+        ctx.treeChanged.listenerCount() > 0
+          ? Object.freeze([...collectFlatRoutes(store, () => true).values()])
+          : undefined;
+
       store.treeOperations.resetStore(store);
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
       store.lifecycleNamespace!.clearAll();
       ctx.clearState();
+
+      if (removed !== undefined) {
+        emitChange({ op: "clear", removed });
+      }
     },
 
     has: (name) => {
@@ -575,13 +802,30 @@ export function getRoutesApi<
 
       const currentState = router.getState();
 
+      // The flat removed/added diff is O(N) — compute it only when someone is
+      // listening (Решение 3.B). Snapshot the old tree BEFORE the swap.
+      const before =
+        ctx.treeChanged.listenerCount() > 0
+          ? collectFlatRoutes(store, () => true)
+          : undefined;
+
       replaceRoutes(
         store,
         routeArray,
         ctx,
         currentState?.path,
         currentState?.transition,
+        before === undefined
+          ? undefined
+          : () => {
+              const after = collectFlatRoutes(store, () => true);
+              const { removed, added } = diffFlatRoutes(before, after);
+
+              emitChange({ op: "replace", removed, added });
+            },
       );
     },
+
+    subscribeChanges: (handler) => ctx.treeChanged.subscribe(handler),
   };
 }

package/src/index.ts

@@ -34,6 +34,17 @@ export type {
   Unsubscribe,
 } from "@real-router/types";
 
+// Route-tree mutation event payloads (observed via getRoutesApi().subscribeChanges)
+export type {
+  TreeChangedEvent,
+  TreeChangedAdd,
+  TreeChangedRemove,
+  TreeChangedUpdate,
+  TreeChangedReplace,
+  TreeChangedClear,
+  TreeStructuralPatch,
+} from "@real-router/types";
+
 export type { ErrorCodes, Constants } from "./constants";
 
 export { events, constants, errorCodes, UNKNOWN_ROUTE } from "./constants";
@@ -41,6 +52,11 @@ export { events, constants, errorCodes, UNKNOWN_ROUTE } from "./constants";
 // RouterError class (migrated from router-error package)
 export { RouterError } from "./RouterError";
 
+// Re-exported so end users can `instanceof RecursionDepthError` at CRUD call
+// sites — the only error that escapes a `subscribeChanges` handler (depth-limit
+// overflow propagates, unlike ordinary listener errors which are isolated).
+export { RecursionDepthError } from "event-emitter";
+
 export { createRouter } from "./createRouter";
 
 export { getNavigator } from "./getNavigator";