@real-router/core 0.55.0 → 0.56.0

package/src/api/getRoutesApi.ts

@@ -2,7 +2,7 @@ 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,
@@ -30,6 +30,8 @@ import type {
   Params,
   Router,
   TransitionMeta,
+  TreeChangedEvent,
+  TreeStructuralPatch,
 } from "@real-router/types";
 import type { RouteDefinition, RouteTree } from "route-tree";
 
@@ -124,30 +126,25 @@ function updateForwardTo<
 }
 
 /**
- * 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) {
@@ -157,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),
@@ -188,6 +213,199 @@ function enrichRoute<
   return route;
 }
 
+// ============================================================================
+// TREE_CHANGED payload helpers
+// ============================================================================
+
+/**
+ * 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 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>,
+  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;
+
+      if (include(fullName)) {
+        result.set(
+          fullName,
+          buildFlatRoute(fullName, def.path, store.config, factories),
+        );
+      }
+
+      if (def.children) {
+        walk(def.children, fullName);
+      }
+    }
+  };
+
+  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);
+    }
+  }
+
+  for (const [fullName, route] of after) {
+    if (!before.has(fullName)) {
+      added.push(route);
+    }
+  }
+
+  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
 // ============================================================================
@@ -225,6 +443,7 @@ function replaceRoutes<
   ctx: RouterInternals<Dependencies>,
   currentPath: string | undefined,
   previousTransition: TransitionMeta | undefined,
+  onCommitted?: () => void,
 ): void {
   // Build the whole new set BEFORE touching the store.
   const artifacts = buildReplaceArtifacts(
@@ -238,6 +457,10 @@ function replaceRoutes<
   store.lifecycleNamespace!.clearDefinitionGuards();
   adoptRouteArtifacts(store, artifacts);
 
+  // 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?.();
+
   // Revalidate state (preserve transition from previous state)
   if (currentPath !== undefined) {
     const revalidated = ctx.matchPath(currentPath, ctx.getOptions());
@@ -372,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) => {
@@ -397,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) => {
@@ -419,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) {
@@ -426,6 +661,12 @@ export function getRoutesApi<
           "router.removeRoute",
           `Route "${name}" not found. No changes made.`,
         );
+
+        return;
+      }
+
+      if (removedSubtree !== undefined) {
+        emitChange({ op: "remove", name, removedSubtree });
       }
     },
 
@@ -482,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: () => {
@@ -494,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) => {
@@ -534,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";

package/src/internals.ts

@@ -15,6 +15,7 @@ import type {
   RouteTreeState,
   SimpleState,
   State,
+  TreeChangedEvent,
   Unsubscribe,
 } from "@real-router/types";
 import type { RouteTree } from "route-tree";
@@ -51,6 +52,21 @@ export interface RouterInternals<
     cb: Plugin[EventMethodMap[E]],
   ) => Unsubscribe;
 
+  /**
+   * Route-tree mutation channel — internal access for the `getRoutesApi`
+   * wrapper. A dedicated bridge is required because the public
+   * `addEventListener<E extends EventName>` structurally rejects
+   * `"TREE_CHANGED"` (it is not in the public `EventName` union), is strict on
+   * duplicates, and exposes neither `emit` nor `listenerCount`.
+   */
+  readonly treeChanged: {
+    readonly emit: (event: TreeChangedEvent) => void;
+    readonly subscribe: (
+      handler: (event: TreeChangedEvent) => void,
+    ) => Unsubscribe;
+    readonly listenerCount: () => number;
+  };
+
   readonly buildPath: (route: string, params?: Params) => string;
 
   readonly emitTransitionError: (error: Error) => void;
@@ -160,6 +176,12 @@ function executeInterceptorChain<T>(
   return chain(...args) as T;
 }
 
+/**
+ * Variadic interceptor wrapper — wraps a function of any arity, returning the
+ * same callable type `T`. Use {@link createBinaryInterceptable} instead when the
+ * wrapped method takes exactly two args and the caller needs the precise
+ * `(a, b) => r` signature preserved (the variadic form widens args to `any[]`).
+ */
 export function createInterceptable<T extends (...args: any[]) => any>(
   name: string,
   original: T,
@@ -179,7 +201,13 @@ export function createInterceptable<T extends (...args: any[]) => any>(
   }) as T;
 }
 
-export function createInterceptable2<A, B, R>(
+/**
+ * Two-argument interceptor wrapper — preserves the exact `(a: A, b: B) => R`
+ * signature, which the variadic {@link createInterceptable} cannot express
+ * (it widens args to `any[]`). Used for the binary interceptable methods
+ * `forwardState(routeName, routeParams)` and `buildPath(route, params)`.
+ */
+export function createBinaryInterceptable<A, B, R>(
   name: string,
   original: (a: A, b: B) => R,
   interceptors: Map<

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -16,10 +16,19 @@ import type {
   Plugin,
   State,
   SubscribeFn,
+  TreeChangedEvent,
   Unsubscribe,
 } from "@real-router/types";
 import type { EventEmitter } from "event-emitter";
 
+/**
+ * Internal-only event key for route-tree mutations. Lives on the same
+ * `EventEmitter` as the 7 transition events but never enters the public
+ * `EventName` union — reachable only through
+ * `getRoutesApi(router).subscribeChanges()`.
+ */
+const TREE_CHANGED = "TREE_CHANGED";
+
 function ensureError(value: unknown): Error {
   /* v8 ignore next -- @preserve: defensive guard — listeners should always throw Error objects */
   return value instanceof Error ? value : new Error(String(value));
@@ -141,6 +150,34 @@ export class EventBusNamespace {
     this.#emitter.emit(events.TRANSITION_LEAVE_APPROVE, toState, fromState);
   }
 
+  /**
+   * Emits the internal `TREE_CHANGED` event after a structural route-tree
+   * mutation. Reuses the shared `EventEmitter` — so depth tracking
+   * (`maxEventDepth`) and per-listener error isolation (`onListenerError`)
+   * apply automatically.
+   */
+  emitTreeChanged(event: TreeChangedEvent): void {
+    this.#emitter.emit(TREE_CHANGED, event);
+  }
+
+  /**
+   * Subscribes to `TREE_CHANGED`. **Lenient** duplicate semantics (mirrors
+   * {@link subscribe}): each call wraps the handler in a fresh closure, so N
+   * registrations of the same reference produce N independent subscriptions.
+   */
+  subscribeTreeChanged(
+    handler: (event: TreeChangedEvent) => void,
+  ): Unsubscribe {
+    return this.#emitter.on(TREE_CHANGED, (event: TreeChangedEvent) => {
+      handler(event);
+    });
+  }
+
+  /** Number of active `TREE_CHANGED` listeners (drives conditional emit). */
+  treeChangedListenerCount(): number {
+    return this.#emitter.listenerCount(TREE_CHANGED);
+  }
+
   sendStart(): void {
     this.#fsm.send(routerEvents.START);
   }

package/src/transitionPath.ts

@@ -86,10 +86,14 @@ function nameToIDsGeneral(name: string): string[] {
   return ids;
 }
 
-function isPrimitive(value: unknown): value is PrimitiveParam {
-  const type = typeof value;
+const PRIMITIVE_TYPES: ReadonlySet<string> = new Set([
+  "string",
+  "number",
+  "boolean",
+]);
 
-  return type === "string" || type === "number" || type === "boolean";
+function isPrimitive(value: unknown): value is PrimitiveParam {
+  return PRIMITIVE_TYPES.has(typeof value);
 }
 
 /**

package/src/types.ts

@@ -15,6 +15,7 @@ import type {
   RouterError as RouterErrorType,
   RouteTreeState,
   State,
+  TreeChangedEvent,
 } from "@real-router/types";
 
 // Re-export from @real-router/types (canonical source)
@@ -27,10 +28,16 @@ export type {
 } from "@real-router/types";
 
 /**
- * Event argument tuples for the router's 7 events.
+ * Event argument tuples for the router's 7 transition events plus the internal
+ * `TREE_CHANGED` channel.
  *
  * Uses explicit `| undefined` unions (not optional `?`) to satisfy
  * `exactOptionalPropertyTypes` when passing undefined args from FSM payloads.
+ *
+ * `TREE_CHANGED` is an **internal-only** key: it is deliberately absent from the
+ * public `EventName` union / `events.*` registry / `Plugin` interface. It
+ * reuses the same `EventEmitter` (depth tracking, error isolation) but is only
+ * reachable via `getRoutesApi(router).subscribeChanges()`.
  */
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- must be `type` for Record<string, unknown[]> constraint
 export type RouterEventMap = {
@@ -49,6 +56,7 @@ export type RouterEventMap = {
     error: RouterErrorType | undefined,
   ];
   $$cancel: [toState: State, fromState: State | undefined];
+  TREE_CHANGED: [event: TreeChangedEvent];
 };
 
 /**