@real-router/sources 0.8.0 → 0.8.2

package/src/createActiveRouteSource.ts

@@ -2,6 +2,8 @@ import { areRoutesRelated } from "@real-router/route-utils";
 
 import { BaseSource } from "./BaseSource";
 import { canonicalJson } from "./canonicalJson.js";
+import { noopDestroy } from "./internal/noopDestroy.js";
+import { readContextHash } from "./internal/readContextHash.js";
 import { normalizeActiveOptions } from "./normalizeActiveOptions.js";
 
 import type { ActiveRouteSourceOptions, RouterSource } from "./types.js";
@@ -20,14 +22,12 @@ const activeSourceCache = new WeakMap<
  * (`{ a:1, b:2 }` and `{ b:2, a:1 }` hit the same cache entry via
  * `canonicalJson`).
  *
- * `destroy()` is a no-op — shared sources live with the router. The router
- * subscription stays active while any consumer subscribes; when the router
- * is garbage-collected, the WeakMap entry releases automatically.
+ * For cached entries `destroy()` is a no-op — shared sources live with the
+ * router and release automatically on router GC (WeakMap entry).
  *
- * Edge cases: `Symbol`/`BigInt` in params bypass `canonicalJson` and produce
- * an unstable cache key — these will simply miss the cache and create a new
- * source on each call. Practical params are primitives, so this is not a
- * concern in real usage.
+ * `BigInt`/circular params can't be serialized → the source bypasses the cache
+ * and `destroy()` becomes a real teardown that detaches the underlying
+ * `router.subscribe` handle.
  */
 export function createActiveRouteSource(
   router: Router,
@@ -49,13 +49,30 @@ export function createActiveRouteSource(
     // if unusual, fragment).
     const hashKey = hash === undefined ? "" : `#${hash}`;
 
-    key = `${routeName}|${canonicalJson(params)}|${String(strict)}|${String(ignoreQueryParams)}|${hashKey}`;
+    // `params === undefined` is the common Link case (`<Link to="users">`
+    // with no params). Skip canonicalJson(undefined) — it returns the literal
+    // string "undefined" and template interpolation would just embed it. An
+    // explicit empty sentinel avoids the call and shaves the cache-key by 9
+    // characters per Link.
+    const paramsKey = params === undefined ? "" : canonicalJson(params);
+
+    // Delimiter `|` is safe because route names use `.` as the segment
+    // separator (`users.list`, not `users|list`) and canonicalJson-encoded
+    // params escape `"` (so any literal `|` inside params lives inside a
+    // quoted JSON string and can't be confused with our delimiter). If route
+    // names ever grow a `|` character, this composite key would become
+    // ambiguous — change the separator to a control char or hash-encode each
+    // field.
+    key = `${routeName}|${paramsKey}|${String(strict)}|${String(ignoreQueryParams)}|${hashKey}`;
   } catch {
     key = undefined;
   }
 
   if (key === undefined) {
-    const source = buildActiveRouteSource(
+    // Non-cached fallback (canonicalJson threw on BigInt / circular / etc.).
+    // Return the real source — `destroy()` must unwind the router subscription;
+    // otherwise the wrapper leaks for the lifetime of the router.
+    return buildActiveRouteSource(
       router,
       routeName,
       params,
@@ -63,12 +80,6 @@ export function createActiveRouteSource(
       ignoreQueryParams,
       hash,
     );
-
-    return {
-      subscribe: source.subscribe,
-      getSnapshot: source.getSnapshot,
-      destroy: noopDestroy,
-    };
   }
 
   let perRouter = activeSourceCache.get(router);
@@ -101,20 +112,6 @@ export function createActiveRouteSource(
   return cached;
 }
 
-/**
- * Reads the URL fragment published by browser/navigation plugins on the given
- * router state. Returns `""` when no plugin claims the `"url"` namespace
- * (hash-plugin runtime, memory-plugin, SSR) — `undefined` is reserved for
- * "no published fragment yet" and not visible at the source layer.
- */
-function readContextHash(router: Router): string {
-  const ctx = router.getState()?.context as
-    | { url?: { hash?: string } }
-    | undefined;
-
-  return ctx?.url?.hash ?? "";
-}
-
 /**
  * Combines route-name match with optional hash match (#532).
  *
@@ -145,7 +142,11 @@ function computeActive(
     return true;
   }
 
-  return readContextHash(router) === hash;
+  // `readContextHash` returns `undefined` when no URL plugin claimed the
+  // namespace (hash-plugin runtime, memory-plugin, SSR). For hash-equality
+  // matching we collapse that to `""` — a hash-aware Link with no URL plugin
+  // can only match when the consumer also asked for `hash: ""`.
+  return (readContextHash(router.getState()) ?? "") === hash;
 }
 
 function buildActiveRouteSource(
@@ -165,13 +166,20 @@ function buildActiveRouteSource(
     hash,
   );
 
-  const source = new BaseSource(initialValue);
+  let routerUnsubscribe: (() => void) | undefined;
 
-  // Eager connection: subscribe to router immediately. This source is only
-  // ever reached through the cached public `createActiveRouteSource`, whose
-  // returned wrapper has a no-op destroy. The source lives with the router;
-  // the router.subscribe handle is released on router GC.
-  router.subscribe((next) => {
+  const source = new BaseSource(initialValue, {
+    onDestroy: () => {
+      routerUnsubscribe?.();
+      routerUnsubscribe = undefined;
+    },
+  });
+
+  // Eager connection: subscribe to router immediately. For the cached path,
+  // the returned wrapper has a no-op destroy and the handle lives with the
+  // router (released on router GC). For the non-cached fallback (BigInt /
+  // circular params), the handle is unwound through `onDestroy` above.
+  routerUnsubscribe = router.subscribe((next) => {
     const isNewRelated = areRoutesRelated(routeName, next.route.name);
     const isPrevRelated =
       next.previousRoute &&
@@ -213,7 +221,3 @@ function buildActiveRouteSource(
 
   return source;
 }
-
-function noopDestroy(): void {
-  // Shared cached source — external destroy() is a no-op.
-}

package/src/createDismissableError.ts

@@ -1,5 +1,6 @@
 import { BaseSource } from "./BaseSource";
 import { getErrorSource } from "./createErrorSource";
+import { noopDestroy } from "./internal/noopDestroy.js";
 
 import type { DismissableErrorSnapshot, RouterSource } from "./types.js";
 import type { Router } from "@real-router/core";
@@ -40,8 +41,12 @@ export function createDismissableError(
   const errorSource = getErrorSource(router);
 
   let dismissedVersion = -1;
+  // Hoisted up here so the `onFirstSubscribe` closure below can read/write
+  // it before `disconnect()`'s declaration. JS hoisting makes the original
+  // post-declaration order legal, but reading top-to-bottom is clearer.
+  let unsubFromError: (() => void) | null = null;
 
-  const computeSnapshot = (): DismissableErrorSnapshot => {
+  const buildDismissableSnapshot = (): DismissableErrorSnapshot => {
     const snap = errorSource.getSnapshot();
     const isDismissed = snap.version <= dismissedVersion;
 
@@ -54,22 +59,34 @@ export function createDismissableError(
     };
   };
 
-  const source = new BaseSource<DismissableErrorSnapshot>(computeSnapshot(), {
-    onFirstSubscribe: () => {
-      unsubFromError = errorSource.subscribe(() => {
-        source.updateSnapshot(computeSnapshot());
-      });
-    },
-    onLastUnsubscribe: () => {
-      disconnect();
+  const source = new BaseSource<DismissableErrorSnapshot>(
+    buildDismissableSnapshot(),
+    {
+      onFirstSubscribe: () => {
+        unsubFromError = errorSource.subscribe(() => {
+          source.updateSnapshot(buildDismissableSnapshot());
+        });
+      },
+      onLastUnsubscribe: () => {
+        disconnect();
+      },
     },
-  });
-
-  let unsubFromError: (() => void) | null = null;
+  );
 
   function resetError(): void {
-    dismissedVersion = errorSource.getSnapshot().version;
-    source.updateSnapshot(computeSnapshot());
+    const currentVersion = errorSource.getSnapshot().version;
+
+    // No-op guard: if we already dismissed at this version (or are even ahead
+    // of the live error stream), there's nothing to clear. Skipping prevents
+    // a redundant snapshot allocation + listener notification under tight
+    // resetError(); resetError() patterns — common when a RouterErrorBoundary
+    // user clicks "dismiss" while another dismiss is already in flight.
+    if (currentVersion <= dismissedVersion) {
+      return;
+    }
+
+    dismissedVersion = currentVersion;
+    source.updateSnapshot(buildDismissableSnapshot());
   }
 
   function disconnect(): void {
@@ -89,7 +106,3 @@ export function createDismissableError(
 
   return wrapper;
 }
-
-function noopDestroy(): void {
-  // Shared cached source — external destroy() is a no-op.
-}

package/src/createErrorSource.ts

@@ -2,6 +2,7 @@ import { events } from "@real-router/core";
 import { getPluginApi } from "@real-router/core/api";
 
 import { BaseSource } from "./BaseSource";
+import { noopDestroy } from "./internal/noopDestroy.js";
 
 import type { RouterErrorSnapshot, RouterSource } from "./types.js";
 import type { Router, State, RouterError } from "@real-router/core";
@@ -22,12 +23,13 @@ export function createErrorSource(
   router: Router,
 ): RouterSource<RouterErrorSnapshot> {
   let errorVersion = 0;
+  let hasError = false;
 
   const source = new BaseSource(INITIAL_SNAPSHOT, {
     onDestroy: () => {
-      unsubs.forEach((unsub) => {
+      for (const unsub of unsubs) {
         unsub();
-      });
+      }
     },
   });
 
@@ -43,6 +45,7 @@ export function createErrorSource(
         err: RouterError,
       ) => {
         errorVersion++;
+        hasError = true;
         source.updateSnapshot({
           error: err,
           toRoute: toState ?? null,
@@ -56,7 +59,8 @@ export function createErrorSource(
       // Skip if no error — avoids unnecessary re-renders.
       // BaseSource.updateSnapshot() always notifies listeners (new object = new ref),
       // and useSyncExternalStore compares via Object.is().
-      if (source.getSnapshot().error !== null) {
+      if (hasError) {
+        hasError = false;
         source.updateSnapshot({
           error: null,
           toRoute: null,
@@ -105,7 +109,3 @@ export function getErrorSource(
 
   return cached;
 }
-
-function noopDestroy(): void {
-  // Shared cached source — external destroy() is a no-op.
-}

package/src/createRouteNodeSource.ts

@@ -1,5 +1,6 @@
 import { BaseSource } from "./BaseSource";
 import { computeSnapshot } from "./computeSnapshot.js";
+import { noopDestroy } from "./internal/noopDestroy.js";
 
 import type { RouteNodeSnapshot, RouterSource } from "./types.js";
 import type { Router } from "@real-router/core";
@@ -106,9 +107,19 @@ function buildRouteNodeSource(
             next,
           );
 
-          if (!Object.is(source.getSnapshot(), newSnapshot)) {
-            source.updateSnapshot(newSnapshot);
+          // computeSnapshot returns the SAME currentSnapshot reference when
+          // both route and previousRoute stabilize to prev — guard against
+          // emitting redundant updates to listeners (matters for signal-
+          // based adapters that re-run effects on every set).
+          /* v8 ignore next 3 -- @preserve: structurally unreachable after #605
+             — reload navs always return fresh refs via stabilizeState, and
+             within-node non-reload navs short-circuit at shouldUpdate. Guard
+             kept for defensive correctness against future stabilizer changes. */
+          if (Object.is(source.getSnapshot(), newSnapshot)) {
+            return;
           }
+
+          source.updateSnapshot(newSnapshot);
         });
       },
       onLastUnsubscribe: disconnect,
@@ -117,7 +128,3 @@ function buildRouteNodeSource(
 
   return source;
 }
-
-function noopDestroy(): void {
-  // Shared cached source — external destroy() is a no-op.
-}

package/src/createTransitionSource.ts

@@ -2,31 +2,97 @@ import { events } from "@real-router/core";
 import { getPluginApi } from "@real-router/core/api";
 
 import { BaseSource } from "./BaseSource";
+import { noopDestroy } from "./internal/noopDestroy.js";
 import { stabilizeState } from "./stabilizeState.js";
 
 import type { RouterTransitionSnapshot, RouterSource } from "./types.js";
 import type { Router, State } from "@real-router/core";
 
-const IDLE_SNAPSHOT: RouterTransitionSnapshot = {
+// Frozen so accidental consumer mutation (`source.getSnapshot().toRoute = X`)
+// throws in strict mode. The singleton ref is shared across every IDLE state
+// for the lifetime of the process — mutating it would corrupt the contract
+// "all IDLE snapshots are the same object reference" relied on by every
+// adapter's useSyncExternalStore equivalent.
+const IDLE_SNAPSHOT: RouterTransitionSnapshot = Object.freeze({
   isTransitioning: false,
   isLeaveApproved: false,
   toRoute: null,
   fromRoute: null,
-};
+});
 
 const transitionSourceCache = new WeakMap<
   Router,
   RouterSource<RouterTransitionSnapshot>
 >();
 
+/**
+ * @internal test-only export — returns the next snapshot for a TRANSITION_START
+ * payload, or `null` when the same-paths dedup guard should suppress the
+ * update. Exported so the (structurally-unreachable after #605) guard can be
+ * exercised by unit tests without resorting to private-API hacks.
+ */
+export function nextTransitionStartSnapshot(
+  prev: RouterTransitionSnapshot,
+  toState: State,
+  fromState: State | undefined,
+): RouterTransitionSnapshot | null {
+  const newToRoute = stabilizeState(prev.toRoute, toState);
+  const newFromRoute = stabilizeState(prev.fromRoute, fromState ?? null);
+
+  if (
+    prev.isTransitioning &&
+    newToRoute === prev.toRoute &&
+    newFromRoute === prev.fromRoute
+  ) {
+    return null;
+  }
+
+  return {
+    isTransitioning: true,
+    isLeaveApproved: false,
+    toRoute: newToRoute,
+    fromRoute: newFromRoute,
+  };
+}
+
+/**
+ * @internal test-only export — analogous to {@link nextTransitionStartSnapshot}
+ * for the LEAVE_APPROVE payload. The guard is structurally unreachable in
+ * practice (router emits LEAVE_APPROVE exactly once per pipeline) but stays
+ * for plugin-driven re-entrant flows.
+ */
+export function nextLeaveApproveSnapshot(
+  prev: RouterTransitionSnapshot,
+  toState: State,
+  fromState: State | undefined,
+): RouterTransitionSnapshot | null {
+  const newToRoute = stabilizeState(prev.toRoute, toState);
+  const newFromRoute = stabilizeState(prev.fromRoute, fromState ?? null);
+
+  if (
+    prev.isLeaveApproved &&
+    newToRoute === prev.toRoute &&
+    newFromRoute === prev.fromRoute
+  ) {
+    return null;
+  }
+
+  return {
+    isTransitioning: true,
+    isLeaveApproved: true,
+    toRoute: newToRoute,
+    fromRoute: newFromRoute,
+  };
+}
+
 export function createTransitionSource(
   router: Router,
 ): RouterSource<RouterTransitionSnapshot> {
   const source = new BaseSource(IDLE_SNAPSHOT, {
     onDestroy: () => {
-      unsubs.forEach((unsub) => {
+      for (const unsub of unsubs) {
         unsub();
-      });
+      }
     },
   });
 
@@ -41,35 +107,44 @@ export function createTransitionSource(
     api.addEventListener(
       events.TRANSITION_START,
       (toState: State, fromState?: State) => {
-        const prev = source.getSnapshot();
-        const newToRoute = stabilizeState(prev.toRoute, toState);
-        const newFromRoute = stabilizeState(prev.fromRoute, fromState ?? null);
-
-        if (
-          !prev.isTransitioning ||
-          newToRoute !== prev.toRoute ||
-          newFromRoute !== prev.fromRoute
-        ) {
-          source.updateSnapshot({
-            isTransitioning: true,
-            isLeaveApproved: false,
-            toRoute: newToRoute,
-            fromRoute: newFromRoute,
-          });
+        // The same-paths dedup branch inside nextTransitionStartSnapshot is
+        // structurally unreachable after #605 (every router-emitted
+        // TRANSITION_START carries a fresh State per navigate()), but the
+        // helper is kept testable for future stabilizer changes — see the
+        // direct unit test in createTransitionSource.test.ts.
+        const next = nextTransitionStartSnapshot(
+          source.getSnapshot(),
+          toState,
+          fromState,
+        );
+
+        /* v8 ignore next 3 -- @preserve: dedup-skip branch unreachable through
+           normal router flow; covered directly via nextTransitionStartSnapshot
+           unit test. */
+        if (next === null) {
+          return;
         }
+
+        source.updateSnapshot(next);
       },
     ),
     api.addEventListener(
       events.TRANSITION_LEAVE_APPROVE,
       (toState: State, fromState?: State) => {
-        const prev = source.getSnapshot();
-
-        source.updateSnapshot({
-          isTransitioning: true,
-          isLeaveApproved: true,
-          toRoute: stabilizeState(prev.toRoute, toState),
-          fromRoute: stabilizeState(prev.fromRoute, fromState ?? null),
-        });
+        const next = nextLeaveApproveSnapshot(
+          source.getSnapshot(),
+          toState,
+          fromState,
+        );
+
+        /* v8 ignore next 3 -- @preserve: dedup-skip branch unreachable through
+           normal router flow (LEAVE_APPROVE fires once per pipeline); covered
+           directly via nextLeaveApproveSnapshot unit test. */
+        if (next === null) {
+          return;
+        }
+
+        source.updateSnapshot(next);
       },
     ),
     api.addEventListener(events.TRANSITION_SUCCESS, resetToIdle),
@@ -115,7 +190,3 @@ export function getTransitionSource(
 
   return cached;
 }
-
-function noopDestroy(): void {
-  // Shared cached source — external destroy() is a no-op.
-}

package/src/internal/noopDestroy.ts

@@ -0,0 +1,19 @@
+/**
+ * @internal
+ *
+ * Shared no-op `destroy()` for cached `RouterSource` wrappers.
+ *
+ * Cached factories (`getTransitionSource`, `getErrorSource`, `createDismissableError`,
+ * `createActiveNameSelector`, cache hit in `createRouteNodeSource`,
+ * `createActiveRouteSource`) return a wrapper whose `destroy()` is a no-op —
+ * the underlying source is shared across all consumers and lives as long as
+ * the router (WeakMap entry releases on router GC).
+ *
+ * One module-level function shared by every cached factory keeps the wrapper
+ * shape (`{ subscribe, getSnapshot, destroy: noopDestroy }`) byte-stable and
+ * eliminates the previous six copies. (Bundlers inline a stand-alone arrow
+ * just as readily, so the cost is purely on the maintenance side.)
+ */
+export function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/internal/readContextHash.ts

@@ -0,0 +1,32 @@
+import type { State } from "@real-router/core";
+
+/**
+ * @internal
+ *
+ * Reads the URL fragment published by `browser-plugin` / `navigation-plugin`
+ * on a router state. The plugins claim the `"url"` namespace via
+ * `state.context.url` and the `hash` field carries the **decoded** fragment.
+ *
+ * Returns:
+ * - `undefined` — no plugin claimed the `"url"` namespace (hash-plugin runtime,
+ *   memory-plugin, SSR before hydration) OR the state itself is nullish;
+ * - `""` — the URL namespace exists but the fragment is empty
+ *   (browser-plugin on a hash-less URL).
+ *
+ * Callers that need the "no namespace at all" branch (e.g. `stabilizeState`
+ * comparing cross-plugin transitions) read the raw `undefined`. Callers that
+ * collapse "no namespace" to "no hash" (e.g. `createActiveRouteSource`'s
+ * hash-equality check) coalesce with `?? ""` themselves.
+ *
+ * Centralising the context cast removes the previous duplicate definitions in
+ * `stabilizeState.ts` and `createActiveRouteSource.ts` that drifted in
+ * signature (state vs router) and default-value (undefined vs "") — both
+ * variants are reconstructible from this single helper at the callsite.
+ */
+export function readContextHash(
+  state: State | null | undefined,
+): string | undefined {
+  const ctx = state?.context as { url?: { hash?: string } } | undefined;
+
+  return ctx?.url?.hash;
+}

package/src/stabilizeState.ts

@@ -1,20 +1,28 @@
+import { readContextHash } from "./internal/readContextHash.js";
+
 import type { State } from "@real-router/core";
 
 /**
  * State-aware stabilization for route snapshots.
  *
- * Compares `path` (canonical name+params) AND `state.context.url.hash`
- * (URL fragment, #532). When both match, returns `prev` (preserving
- * reference) so frameworks can skip re-renders. When hash flips on a
- * same-path navigation (tab-style UI), returns `next` so consumers
- * subscribing through `useRoute()` see the new state.
+ * Compares `path` (canonical name+params), `state.context.url.hash`
+ * (URL fragment, #532), and `state.transition.reload` (#605). When all
+ * three match (idempotent navigation), returns `prev` (preserving
+ * reference) so frameworks can skip re-renders. When any of them flips,
+ * returns `next` so consumers subscribing through `useRoute()` see the
+ * new state.
+ *
+ * `transition.reload === true` is the user's explicit signal for a
+ * non-idempotent navigation — `router.navigate(name, params, { reload:
+ * true })` is the canonical pairing for `invalidate(router, namespace)`
+ * and any cache-bust pattern. Bypassing stabilization for reloads makes
+ * `useRoute()` consumers see fresh `state.context.<namespace>` values
+ * written by the SSR loader plugin's `subscribeLeave` handler.
  *
- * Ignores `meta` (internal: auto-increment id), `transition` (reference
- * data: from, segments, reload), and `state.context.navigation` /
+ * Ignores `meta` (internal: auto-increment id), other `transition` fields
+ * (`from`, `segments`, `redirected`), and `state.context.navigation` /
  * `state.context.browser` (transient transition metadata) — they don't
- * affect what is rendered. `state.context.url.hash` is the only context
- * field that participates in render identity, because tab-style UIs
- * subscribe to it directly.
+ * affect render identity for idempotent navigations.
  *
  * Accepts `null` for compatibility with `RouterTransitionSnapshot`
  * (toRoute/fromRoute are `State | null`).
@@ -41,11 +49,27 @@ export function stabilizeState<T extends State | null | undefined>(
     return next;
   }
 
+  // Explicit reload navigation (#605) — caller asked to bypass dedupe so
+  // observers see fresh `state.context` written by `invalidate()`-driven
+  // loader re-runs. The path equality above guarantees both prev and next
+  // are either non-null with matching paths or both nullish; only the
+  // non-null branch can carry a meaningful `transition.reload`.
+  if (readReloadFlag(next)) {
+    return next;
+  }
+
   return prev;
 }
 
-function readContextHash(state: State | null | undefined): string | undefined {
-  const ctx = state?.context as { url?: { hash?: string } } | undefined;
+function readReloadFlag(state: State | null | undefined): boolean {
+  // Defensive read: `transition` is mandatory in the public State type, but a
+  // plugin returning a malformed state (or a future fork) shouldn't crash the
+  // stabilizer with a TypeError. We cast to a structurally-loose shape so the
+  // optional chain is permitted; the runtime guard preserves dedup (false =
+  // not-a-reload) for malformed inputs.
+  const transition = (
+    state as { transition?: { reload?: boolean } } | null | undefined
+  )?.transition;
 
-  return ctx?.url?.hash;
+  return transition?.reload === true;
 }