@real-router/sources 0.8.4 → 0.8.6

package/src/createDismissableError.ts

@@ -1,108 +0,0 @@
-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";
-
-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;
-  // 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 buildDismissableSnapshot = (): 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>(
-    buildDismissableSnapshot(),
-    {
-      onFirstSubscribe: () => {
-        unsubFromError = errorSource.subscribe(() => {
-          source.updateSnapshot(buildDismissableSnapshot());
-        });
-      },
-      onLastUnsubscribe: () => {
-        disconnect();
-      },
-    },
-  );
-
-  function resetError(): void {
-    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 {
-    const unsub = unsubFromError;
-
-    unsubFromError = null;
-    unsub?.();
-  }
-
-  const wrapper: RouterSource<DismissableErrorSnapshot> = {
-    subscribe: source.subscribe,
-    getSnapshot: source.getSnapshot,
-    destroy: noopDestroy,
-  };
-
-  dismissableCache.set(router, wrapper);
-
-  return wrapper;
-}

package/src/createErrorSource.ts

@@ -1,111 +0,0 @@
-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";
-
-const INITIAL_SNAPSHOT: RouterErrorSnapshot = {
-  error: null,
-  toRoute: null,
-  fromRoute: null,
-  version: 0,
-};
-
-const errorSourceCache = new WeakMap<
-  Router,
-  RouterSource<RouterErrorSnapshot>
->();
-
-export function createErrorSource(
-  router: Router,
-): RouterSource<RouterErrorSnapshot> {
-  let errorVersion = 0;
-  let hasError = false;
-
-  const source = new BaseSource(INITIAL_SNAPSHOT, {
-    onDestroy: () => {
-      for (const unsub of unsubs) {
-        unsub();
-      }
-    },
-  });
-
-  const api = getPluginApi(router);
-
-  // Eager connection: subscribe to router events immediately
-  const unsubs = [
-    api.addEventListener(
-      events.TRANSITION_ERROR,
-      (
-        toState: State | undefined,
-        fromState: State | undefined,
-        err: RouterError,
-      ) => {
-        errorVersion++;
-        hasError = true;
-        source.updateSnapshot({
-          error: err,
-          toRoute: toState ?? null,
-          /* v8 ignore next -- @preserve: fromState undefined only during start() error; unreachable via navigate() */
-          fromRoute: fromState ?? null,
-          version: errorVersion,
-        });
-      },
-    ),
-    api.addEventListener(events.TRANSITION_SUCCESS, () => {
-      // Skip if no error — avoids unnecessary re-renders.
-      // BaseSource.updateSnapshot() always notifies listeners (new object = new ref),
-      // and useSyncExternalStore compares via Object.is().
-      if (hasError) {
-        hasError = false;
-        source.updateSnapshot({
-          error: null,
-          toRoute: null,
-          fromRoute: null,
-          version: errorVersion,
-        });
-      }
-    }),
-  ];
-
-  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;
-}

package/src/createRouteNodeSource.ts

@@ -1,130 +0,0 @@
-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";
-
-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;
-
-  // 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,
-    previousRoute: undefined,
-  };
-
-  const disconnect = (): void => {
-    const unsub = routerUnsubscribe;
-
-    routerUnsubscribe = null;
-    unsub?.();
-  };
-
-  const source = new BaseSource<RouteNodeSnapshot>(
-    computeSnapshot(initialSnapshot, router, nodeName),
-    {
-      onFirstSubscribe: () => {
-        // Reconcile snapshot with current router state before connecting.
-        // Covers reconnection after Activity hide/show cycles where the
-        // source was disconnected and missed navigation events.
-        const reconciled = computeSnapshot(
-          source.getSnapshot(),
-          router,
-          nodeName,
-        );
-
-        if (!Object.is(reconciled, source.getSnapshot())) {
-          source.updateSnapshot(reconciled);
-        }
-
-        // Connect to router on first subscription
-        routerUnsubscribe = router.subscribe((next) => {
-          if (!shouldUpdate(next.route, next.previousRoute)) {
-            return;
-          }
-
-          const newSnapshot = computeSnapshot(
-            source.getSnapshot(),
-            router,
-            nodeName,
-            next,
-          );
-
-          // 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,
-    },
-  );
-
-  return source;
-}

package/src/createRouteSource.ts

@@ -1,56 +0,0 @@
-import { BaseSource } from "./BaseSource";
-import { stabilizeState } from "./stabilizeState.js";
-
-import type { RouteSnapshot, RouterSource } from "./types.js";
-import type { Router } from "@real-router/core";
-
-/**
- * Creates a source for the full route state.
- *
- * 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.
- */
-export function createRouteSource(router: Router): RouterSource<RouteSnapshot> {
-  let routerUnsubscribe: (() => void) | null = null;
-
-  const disconnect = (): void => {
-    const unsub = routerUnsubscribe;
-
-    routerUnsubscribe = null;
-    unsub?.();
-  };
-
-  const source = new BaseSource<RouteSnapshot>(
-    {
-      route: router.getState(),
-      previousRoute: undefined,
-    },
-    {
-      onFirstSubscribe: () => {
-        routerUnsubscribe = router.subscribe((next) => {
-          const prev = source.getSnapshot();
-          const newRoute = stabilizeState(prev.route, next.route);
-          const newPreviousRoute = stabilizeState(
-            prev.previousRoute,
-            next.previousRoute,
-          );
-
-          if (
-            newRoute !== prev.route ||
-            newPreviousRoute !== prev.previousRoute
-          ) {
-            source.updateSnapshot({
-              route: newRoute,
-              previousRoute: newPreviousRoute,
-            });
-          }
-        });
-      },
-      onLastUnsubscribe: disconnect,
-      onDestroy: disconnect,
-    },
-  );
-
-  return source;
-}

package/src/createTransitionSource.ts

@@ -1,192 +0,0 @@
-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";
-
-// 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: () => {
-      for (const unsub of unsubs) {
-        unsub();
-      }
-    },
-  });
-
-  const api = getPluginApi(router);
-
-  const resetToIdle = (): void => {
-    source.updateSnapshot(IDLE_SNAPSHOT);
-  };
-
-  // Eager connection: subscribe to router events immediately
-  const unsubs = [
-    api.addEventListener(
-      events.TRANSITION_START,
-      (toState: State, fromState?: State) => {
-        // 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 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),
-    api.addEventListener(events.TRANSITION_ERROR, resetToIdle),
-    api.addEventListener(events.TRANSITION_CANCEL, resetToIdle),
-  ];
-
-  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;
-}

package/src/index.ts

@@ -1,35 +0,0 @@
-export type {
-  RouterSource,
-  RouteSnapshot,
-  RouteNodeSnapshot,
-  ActiveRouteSourceOptions,
-  RouterTransitionSnapshot,
-  RouterErrorSnapshot,
-  DismissableErrorSnapshot,
-} from "./types.js";
-
-export { createRouteSource } from "./createRouteSource";
-
-export { createRouteNodeSource } from "./createRouteNodeSource";
-
-export { createActiveRouteSource } from "./createActiveRouteSource";
-
-export {
-  createTransitionSource,
-  getTransitionSource,
-} from "./createTransitionSource";
-
-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/internal/noopDestroy.ts

@@ -1,19 +0,0 @@
-/**
- * @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

@@ -1,32 +0,0 @@
-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;
-}