@real-router/core 0.54.5 → 0.55.0

package/src/api/getRoutesApi.ts

@@ -6,16 +6,17 @@ import { createInterceptable, 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";
@@ -36,32 +37,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,20 +91,36 @@ 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;
 }
 
 /**
@@ -212,37 +203,19 @@ function addRoutes<
   routes: Route<Dependencies>[],
   parentName?: string,
 ): void {
-  if (parentName) {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const parentDef = findDefinition(store.definitions, parentName)!;
-
-    parentDef.children ??= [];
-
-    for (const route of routes) {
-      parentDef.children.push(sanitizeRoute(route));
-    }
-  } else {
-    for (const route of routes) {
-      store.definitions.push(sanitizeRoute(route));
-    }
-  }
-
-  registerAllRouteHandlers(
-    routes,
-    store.config,
-    store.routeCustomFields,
-    store.pendingCanActivate,
-    store.pendingCanDeactivate,
-    store.depsStore,
-    parentName ?? "",
-  );
-
-  store.treeOperations.commitTreeChanges(store);
+  // 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,
@@ -253,32 +226,19 @@ function replaceRoutes<
   currentPath: string | undefined,
   previousTransition: TransitionMeta | undefined,
 ): void {
-  // Step 2: Clear route data (WITHOUT tree rebuild)
-  clearRouteData(store);
-
-  // Step 3: Clear definition lifecycle handlers (preserve external guards)
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
-  store.lifecycleNamespace!.clearDefinitionGuards();
-
-  // Step 4: Register new routes
-  for (const route of routes) {
-    store.definitions.push(sanitizeRoute(route));
-  }
-
-  registerAllRouteHandlers(
+  // Build the whole new set BEFORE touching the store.
+  const artifacts = buildReplaceArtifacts(
     routes,
-    store.config,
-    store.routeCustomFields,
-    store.pendingCanActivate,
-    store.pendingCanDeactivate,
-    store.depsStore,
-    "",
+    store.rootPath,
+    store.matcherOptions,
   );
 
-  // Step 5: One tree rebuild
-  store.treeOperations.commitTreeChanges(store);
+  // 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 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 +301,6 @@ function updateRouteConfig<
       name,
       updates.forwardTo,
       store.config,
-      (config) => refreshForwardMap(config),
     );
   }
 

package/src/namespaces/EventBusNamespace/EventBusNamespace.ts

@@ -264,6 +264,19 @@ export class EventBusNamespace {
     return this.#currentToState;
   }
 
+  /**
+   * Plugin-author API for subscribing to internal router events.
+   *
+   * @remarks
+   *
+   * **Duplicate-registration semantics — strict (throws).** Passing the same
+   * callback reference twice for the same event throws
+   * `Error("Duplicate listener for ...")` from the underlying `EventEmitter`.
+   * This is loud-on-misuse by design: plugin code is expected to register
+   * each callback once. The contract differs from {@link subscribe} /
+   * {@link subscribeLeave}, which are end-user surfaces and silently accept
+   * duplicates.
+   */
   addEventListener<E extends EventName>(
     eventName: E,
     cb: Plugin[EventMethodMap[E]],
@@ -274,6 +287,22 @@ export class EventBusNamespace {
     );
   }
 
+  /**
+   * End-user / UI-binding API for subscribing to successful transitions.
+   *
+   * @remarks
+   *
+   * **Duplicate-registration semantics — independent.** Each call wraps
+   * `listener` in a fresh closure and registers it as a distinct internal
+   * slot. `router.subscribe(fn)` twice produces **two** active subscriptions;
+   * `fn` fires twice per `TRANSITION_SUCCESS`. The returned `Unsubscribe` is
+   * paired with its specific call — invoking it removes exactly that
+   * registration.
+   *
+   * This contract differs from {@link addEventListener} (plugin API, throws
+   * on duplicate). End-user code that wants idempotent registration must
+   * gate itself, e.g. `if (!unsub) unsub = router.subscribe(fn);`.
+   */
   subscribe(listener: SubscribeFn): Unsubscribe {
     return this.#emitter.on(
       events.TRANSITION_SUCCESS,
@@ -283,6 +312,31 @@ export class EventBusNamespace {
     );
   }
 
+  /**
+   * End-user / UI-binding API for subscribing to confirmed route departures
+   * (`LEAVE_APPROVED` phase). Async listeners block the activation phase.
+   *
+   * @remarks
+   *
+   * **Duplicate-registration semantics — independent (with internal quirk).**
+   * Each call pushes `listener` onto the internal array; `router.subscribeLeave(fn)`
+   * twice produces two array entries. `fn` fires **once** per leave when
+   * iteration snapshots the array (a snapshot is taken on entry to
+   * `awaitLeaveListeners`), but the function reference is invoked once per
+   * array slot — so in practice the wrapper fires twice through the same
+   * closure (no observable difference for stateless `fn`).
+   *
+   * The returned `Unsubscribe` removes the **first** array entry matching the
+   * function reference (`indexOf` semantic), not the most recently added one.
+   * Net effect of N subscribes + M unsubscribes is correct (N - M entries
+   * remain), but the specific physical entry that survives is reverse of the
+   * unsubscribe-call order. Irrelevant in practice — the function reference
+   * is the same; observable behaviour is identical regardless of which
+   * physical entry is removed.
+   *
+   * Contract differs from {@link addEventListener} (throws on duplicate).
+   * For idempotent registration, gate at the call site.
+   */
   subscribeLeave(listener: LeaveFn): Unsubscribe {
     this.#leaveListeners.push(listener);
 
@@ -308,16 +362,27 @@ export class EventBusNamespace {
       return undefined;
     }
 
-    const leaveState: LeaveState = {
+    // Freeze the payload wrapper so listeners cannot mutate it (`payload.route`
+    // is already deep-frozen via the State immutability invariant; this closes
+    // the wrapper-mutation gap surfaced by audit `probe-05-payload-frozen`).
+    const leaveState: LeaveState = Object.freeze({
       route: fromState,
       nextRoute: toState,
       signal,
-    };
+    });
 
     let promises: Promise<void>[] | undefined;
     let firstSyncError: unknown;
 
-    for (const listener of this.#leaveListeners) {
+    // Snapshot before iteration — a listener that reentrantly calls
+    // `subscribeLeave(newFn)` or its own `unsubscribe()` must not affect the
+    // current emit cycle. Symmetric with the EventEmitter snapshot invariant
+    // (PR #666 / #659). Use `Array.from` rather than `[...array]` to keep the
+    // intent explicit (some lint rules treat spread-of-own-array as
+    // redundant and silently revert it).
+    const snapshot = [...this.#leaveListeners];
+
+    for (const listener of snapshot) {
       try {
         const result = listener(leaveState);
 

package/src/namespaces/NavigationNamespace/types.ts

@@ -23,7 +23,7 @@ export interface NavigationContext {
  *
  * These are function references from other namespaces/facade,
  * avoiding the need to pass the entire Router object.
- **/
+ */
 export interface NavigationDependencies {
   /** Get router options */
   getOptions: () => Options;