@real-router/sources 0.5.0 → 0.6.0

package/src/createActiveRouteSource.ts

@@ -1,19 +1,105 @@
 import { areRoutesRelated } from "@real-router/route-utils";
 
 import { BaseSource } from "./BaseSource";
+import { canonicalJson } from "./canonicalJson.js";
+import { normalizeActiveOptions } from "./normalizeActiveOptions.js";
 
 import type { ActiveRouteSourceOptions, RouterSource } from "./types.js";
 import type { Params, Router } from "@real-router/core";
 
+const activeSourceCache = new WeakMap<
+  Router,
+  Map<string, RouterSource<boolean>>
+>();
+
+/**
+ * Creates a source tracking whether a route (with given params/options) is active.
+ *
+ * **Per-router + canonical-args cache:** repeated calls with equivalent
+ * arguments return the same shared instance. Param key order doesn't matter
+ * (`{ 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.
+ *
+ * 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.
+ */
 export function createActiveRouteSource(
   router: Router,
   routeName: string,
   params?: Params,
   options?: ActiveRouteSourceOptions,
 ): RouterSource<boolean> {
-  const strict = options?.strict ?? false;
-  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
+  const { strict, ignoreQueryParams } = normalizeActiveOptions(options);
+
+  // BigInt/Symbol/circular refs cannot be serialized — fall back to creating
+  // a fresh (non-cached) source. Callers pass these edge-case params rarely;
+  // the extra allocation is acceptable.
+  let key: string | undefined;
+
+  try {
+    key = `${routeName}|${canonicalJson(params)}|${String(strict)}|${String(ignoreQueryParams)}`;
+  } catch {
+    key = undefined;
+  }
+
+  if (key === undefined) {
+    const source = buildActiveRouteSource(
+      router,
+      routeName,
+      params,
+      strict,
+      ignoreQueryParams,
+    );
+
+    return {
+      subscribe: source.subscribe,
+      getSnapshot: source.getSnapshot,
+      destroy: noopDestroy,
+    };
+  }
+
+  let perRouter = activeSourceCache.get(router);
+
+  if (!perRouter) {
+    perRouter = new Map();
+    activeSourceCache.set(router, perRouter);
+  }
+
+  let cached = perRouter.get(key);
+
+  if (!cached) {
+    const source = buildActiveRouteSource(
+      router,
+      routeName,
+      params,
+      strict,
+      ignoreQueryParams,
+    );
 
+    cached = {
+      subscribe: source.subscribe,
+      getSnapshot: source.getSnapshot,
+      destroy: noopDestroy,
+    };
+    perRouter.set(key, cached);
+  }
+
+  return cached;
+}
+
+function buildActiveRouteSource(
+  router: Router,
+  routeName: string,
+  params: Params | undefined,
+  strict: boolean,
+  ignoreQueryParams: boolean,
+): RouterSource<boolean> {
   const initialValue = router.isActiveRoute(
     routeName,
     params,
@@ -21,14 +107,13 @@ export function createActiveRouteSource(
     ignoreQueryParams,
   );
 
-  const source = new BaseSource(initialValue, {
-    onDestroy: () => {
-      unsubscribe();
-    },
-  });
+  const source = new BaseSource(initialValue);
 
-  // Eager connection: subscribe to router immediately
-  const unsubscribe = router.subscribe((next) => {
+  // 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 isNewRelated = areRoutesRelated(routeName, next.route.name);
     const isPrevRelated =
       next.previousRoute &&
@@ -51,3 +136,7 @@ export function createActiveRouteSource(
 
   return source;
 }
+
+function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/createDismissableError.ts

@@ -0,0 +1,95 @@
+import { BaseSource } from "./BaseSource";
+import { getErrorSource } from "./createErrorSource";
+
+import type { DismissableErrorSnapshot, RouterSource } from "./types.js";
+import type { Router } from "@real-router/core";
+
+const dismissableCache = new WeakMap<
+  Router,
+  RouterSource<DismissableErrorSnapshot>
+>();
+
+/**
+ * Returns a per-router cached source that wraps `getErrorSource(router)` with
+ * an integrated "dismissed" version counter, exposing a single reactive
+ * snapshot `{ error, toRoute, fromRoute, version, resetError }`.
+ *
+ * Each `RouterErrorBoundary` in a framework adapter subscribes to this one
+ * source instead of re-implementing the `dismissedVersion` state pattern
+ * locally. The 6-copy duplicate across adapters collapses to this helper.
+ *
+ * **Semantics:**
+ * - `error` is non-null only when `underlying.version > dismissedVersion`.
+ * - `resetError()` sets `dismissedVersion = current underlying version`,
+ *   immediately clearing `error` to `null` and notifying all listeners.
+ * - A subsequent `TRANSITION_ERROR` advances `version` beyond `dismissedVersion`,
+ *   so `error` becomes non-null again — no additional plumbing needed.
+ *
+ * **Cached:** one instance per router. `destroy()` on the returned source is
+ * a no-op. Shared across all `RouterErrorBoundary` consumers.
+ */
+export function createDismissableError(
+  router: Router,
+): RouterSource<DismissableErrorSnapshot> {
+  const cached = dismissableCache.get(router);
+
+  if (cached) {
+    return cached;
+  }
+
+  const errorSource = getErrorSource(router);
+
+  let dismissedVersion = -1;
+
+  const computeSnapshot = (): DismissableErrorSnapshot => {
+    const snap = errorSource.getSnapshot();
+    const isDismissed = snap.version <= dismissedVersion;
+
+    return {
+      error: isDismissed ? null : snap.error,
+      toRoute: isDismissed ? null : snap.toRoute,
+      fromRoute: isDismissed ? null : snap.fromRoute,
+      version: snap.version,
+      resetError,
+    };
+  };
+
+  const source = new BaseSource<DismissableErrorSnapshot>(computeSnapshot(), {
+    onFirstSubscribe: () => {
+      unsubFromError = errorSource.subscribe(() => {
+        source.updateSnapshot(computeSnapshot());
+      });
+    },
+    onLastUnsubscribe: () => {
+      disconnect();
+    },
+  });
+
+  let unsubFromError: (() => void) | null = null;
+
+  function resetError(): void {
+    dismissedVersion = errorSource.getSnapshot().version;
+    source.updateSnapshot(computeSnapshot());
+  }
+
+  function disconnect(): void {
+    const unsub = unsubFromError;
+
+    unsubFromError = null;
+    unsub?.();
+  }
+
+  const wrapper: RouterSource<DismissableErrorSnapshot> = {
+    subscribe: source.subscribe,
+    getSnapshot: source.getSnapshot,
+    destroy: noopDestroy,
+  };
+
+  dismissableCache.set(router, wrapper);
+
+  return wrapper;
+}
+
+function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/createErrorSource.ts

@@ -13,6 +13,11 @@ const INITIAL_SNAPSHOT: RouterErrorSnapshot = {
   version: 0,
 };
 
+const errorSourceCache = new WeakMap<
+  Router,
+  RouterSource<RouterErrorSnapshot>
+>();
+
 export function createErrorSource(
   router: Router,
 ): RouterSource<RouterErrorSnapshot> {
@@ -64,3 +69,43 @@ export function createErrorSource(
 
   return source;
 }
+
+/**
+ * Returns a per-router cached error source shared across all consumers.
+ *
+ * Safe to call destroy() — the cached source ignores external destroy() calls
+ * and lives until the router itself is garbage-collected (the WeakMap entry
+ * releases automatically).
+ *
+ * Use this in framework adapters (React/Preact/Solid/Vue/Svelte/Angular) to
+ * share a single ErrorSource instance across all mount/unmount cycles.
+ *
+ * For isolated/advanced use (ad-hoc, short-lived, per-owner teardown), call
+ * `createErrorSource(router)` directly — it returns a fresh instance with a
+ * working `destroy()`.
+ */
+export function getErrorSource(
+  router: Router,
+): RouterSource<RouterErrorSnapshot> {
+  let cached = errorSourceCache.get(router);
+
+  if (!cached) {
+    const source = createErrorSource(router);
+
+    // Wrap with no-op destroy. The underlying source is shared across all
+    // consumers; letting any one consumer call destroy() would tear it down
+    // for the rest. The source lives as long as the router (WeakMap key).
+    cached = {
+      subscribe: source.subscribe,
+      getSnapshot: source.getSnapshot,
+      destroy: noopDestroy,
+    };
+    errorSourceCache.set(router, cached);
+  }
+
+  return cached;
+}
+
+function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/createRouteNodeSource.ts

@@ -1,24 +1,68 @@
 import { BaseSource } from "./BaseSource";
 import { computeSnapshot } from "./computeSnapshot.js";
-import { getCachedShouldUpdate } from "./shouldUpdateCache.js";
 
 import type { RouteNodeSnapshot, RouterSource } from "./types.js";
 import type { Router } from "@real-router/core";
 
+const nodeSourceCache = new WeakMap<
+  Router,
+  Map<string, RouterSource<RouteNodeSnapshot>>
+>();
+
 /**
  * Creates a source scoped to a specific route node.
  *
+ * **Per-router + per-nodeName cache:** repeated calls with the same
+ * `(router, nodeName)` return the same shared instance. `N` consumers
+ * calling `createRouteNodeSource(r, "users")` produce one router subscription
+ * shared across all of them.
+ *
  * Uses a lazy-connection pattern: the router subscription is created when the
  * first listener subscribes and removed when the last listener unsubscribes.
  * This is compatible with React's useSyncExternalStore and Strict Mode.
+ *
+ * `destroy()` on the returned source is a no-op — the shared instance lives
+ * as long as the router itself (the WeakMap entry releases automatically on
+ * router GC). Callers that need an isolated instance with working teardown
+ * can use `buildRouteNodeSource` internally (not exported).
  */
 export function createRouteNodeSource(
   router: Router,
   nodeName: string,
+): RouterSource<RouteNodeSnapshot> {
+  let perRouter = nodeSourceCache.get(router);
+
+  if (!perRouter) {
+    perRouter = new Map();
+    nodeSourceCache.set(router, perRouter);
+  }
+
+  let cached = perRouter.get(nodeName);
+
+  if (!cached) {
+    const source = buildRouteNodeSource(router, nodeName);
+
+    // Wrap with no-op destroy. The shared source lives with the router.
+    cached = {
+      subscribe: source.subscribe,
+      getSnapshot: source.getSnapshot,
+      destroy: noopDestroy,
+    };
+    perRouter.set(nodeName, cached);
+  }
+
+  return cached;
+}
+
+function buildRouteNodeSource(
+  router: Router,
+  nodeName: string,
 ): RouterSource<RouteNodeSnapshot> {
   let routerUnsubscribe: (() => void) | null = null;
 
-  const shouldUpdate = getCachedShouldUpdate(router, nodeName);
+  // Built once per cached source instance; safe — createRouteNodeSource is
+  // itself per-(router, nodeName) cached, so shouldUpdate is called once.
+  const shouldUpdate = router.shouldUpdateNode(nodeName);
 
   const initialSnapshot: RouteNodeSnapshot = {
     route: undefined,
@@ -68,9 +112,12 @@ export function createRouteNodeSource(
         });
       },
       onLastUnsubscribe: disconnect,
-      onDestroy: disconnect,
     },
   );
 
   return source;
 }
+
+function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/createTransitionSource.ts

@@ -14,6 +14,11 @@ const IDLE_SNAPSHOT: RouterTransitionSnapshot = {
   fromRoute: null,
 };
 
+const transitionSourceCache = new WeakMap<
+  Router,
+  RouterSource<RouterTransitionSnapshot>
+>();
+
 export function createTransitionSource(
   router: Router,
 ): RouterSource<RouterTransitionSnapshot> {
@@ -74,3 +79,43 @@ export function createTransitionSource(
 
   return source;
 }
+
+/**
+ * Returns a per-router cached transition source shared across all consumers.
+ *
+ * Safe to call destroy() — the cached source ignores external destroy() calls
+ * and lives until the router itself is garbage-collected (the WeakMap entry
+ * releases automatically).
+ *
+ * Use this in framework adapters (React/Preact/Solid/Vue/Svelte/Angular) to
+ * share a single TransitionSource instance across all mount/unmount cycles.
+ *
+ * For isolated/advanced use (ad-hoc, short-lived, per-owner teardown), call
+ * `createTransitionSource(router)` directly — it returns a fresh instance with
+ * a working `destroy()`.
+ */
+export function getTransitionSource(
+  router: Router,
+): RouterSource<RouterTransitionSnapshot> {
+  let cached = transitionSourceCache.get(router);
+
+  if (!cached) {
+    const source = createTransitionSource(router);
+
+    // Wrap with no-op destroy. The underlying source is shared across all
+    // consumers; letting any one consumer call destroy() would tear it down
+    // for the rest. The source lives as long as the router (WeakMap key).
+    cached = {
+      subscribe: source.subscribe,
+      getSnapshot: source.getSnapshot,
+      destroy: noopDestroy,
+    };
+    transitionSourceCache.set(router, cached);
+  }
+
+  return cached;
+}
+
+function noopDestroy(): void {
+  // Shared cached source — external destroy() is a no-op.
+}

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
   ActiveRouteSourceOptions,
   RouterTransitionSnapshot,
   RouterErrorSnapshot,
+  DismissableErrorSnapshot,
 } from "./types.js";
 
 export { createRouteSource } from "./createRouteSource";
@@ -13,6 +14,22 @@ export { createRouteNodeSource } from "./createRouteNodeSource";
 
 export { createActiveRouteSource } from "./createActiveRouteSource";
 
-export { createTransitionSource } from "./createTransitionSource";
+export {
+  createTransitionSource,
+  getTransitionSource,
+} from "./createTransitionSource";
 
-export { createErrorSource } from "./createErrorSource";
+export { createErrorSource, getErrorSource } from "./createErrorSource";
+
+export { createDismissableError } from "./createDismissableError";
+
+export { createActiveNameSelector } from "./createActiveNameSelector";
+
+export type { ActiveNameSelector } from "./createActiveNameSelector";
+
+export {
+  DEFAULT_ACTIVE_OPTIONS,
+  normalizeActiveOptions,
+} from "./normalizeActiveOptions";
+
+export { canonicalJson } from "./canonicalJson";

package/src/normalizeActiveOptions.ts

@@ -0,0 +1,29 @@
+import type { ActiveRouteSourceOptions } from "./types.js";
+
+/**
+ * Default options for `createActiveRouteSource` and adapter-level helpers.
+ *
+ * Frozen to prevent accidental mutation by consumers.
+ */
+export const DEFAULT_ACTIVE_OPTIONS: Readonly<
+  Required<ActiveRouteSourceOptions>
+> = Object.freeze({
+  strict: false,
+  ignoreQueryParams: true,
+});
+
+/**
+ * Normalizes partial `ActiveRouteSourceOptions` into a fully-defaulted object.
+ *
+ * Use this to produce a stable options record for comparison, caching, or
+ * downstream consumers that require all fields present.
+ */
+export function normalizeActiveOptions(
+  options?: ActiveRouteSourceOptions,
+): Required<ActiveRouteSourceOptions> {
+  return {
+    strict: options?.strict ?? DEFAULT_ACTIVE_OPTIONS.strict,
+    ignoreQueryParams:
+      options?.ignoreQueryParams ?? DEFAULT_ACTIVE_OPTIONS.ignoreQueryParams,
+  };
+}

package/src/types.ts

@@ -34,3 +34,16 @@ export interface RouterErrorSnapshot {
   fromRoute: State | null;
   version: number;
 }
+
+export interface DismissableErrorSnapshot {
+  /** Currently visible error, or `null` if none (never seen or dismissed). */
+  error: RouterError | null;
+  /** Target route of the failed navigation. */
+  toRoute: State | null;
+  /** Source route at the time of failure. */
+  fromRoute: State | null;
+  /** Monotonic version counter from the underlying error source. */
+  version: number;
+  /** Dismisses the current error. Next error (new version) becomes visible again. */
+  resetError: () => void;
+}

package/src/shouldUpdateCache.ts

@@ -1,27 +0,0 @@
-import type { Router, State } from "@real-router/core";
-
-const shouldUpdateCache = new WeakMap<
-  Router,
-  Map<string, (toState: State, fromState?: State) => boolean>
->();
-
-export function getCachedShouldUpdate(
-  router: Router,
-  nodeName: string,
-): (toState: State, fromState?: State) => boolean {
-  let routerCache = shouldUpdateCache.get(router);
-
-  if (!routerCache) {
-    routerCache = new Map();
-    shouldUpdateCache.set(router, routerCache);
-  }
-
-  let fn = routerCache.get(nodeName);
-
-  if (!fn) {
-    fn = router.shouldUpdateNode(nodeName);
-    routerCache.set(nodeName, fn);
-  }
-
-  return fn;
-}