@real-router/sources 0.8.5 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/sources",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "type": "commonjs",
   "description": "Framework-agnostic subscription layer for Real-Router state",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -43,7 +42,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.56.0",
+    "@real-router/core": "^0.58.0",
     "@real-router/route-utils": "^0.2.3"
   },
   "devDependencies": {

package/src/BaseSource.ts

@@ -1,95 +0,0 @@
-export interface BaseSourceOptions {
-  onFirstSubscribe?: () => void;
-  onLastUnsubscribe?: () => void;
-  onDestroy?: () => void;
-}
-
-export class BaseSource<T> {
-  #currentSnapshot: T;
-  #destroyed = false;
-
-  readonly #listeners = new Set<() => void>();
-  readonly #onFirstSubscribe: (() => void) | undefined;
-  readonly #onLastUnsubscribe: (() => void) | undefined;
-  readonly #onDestroy: (() => void) | undefined;
-
-  constructor(initialSnapshot: T, options?: BaseSourceOptions) {
-    this.#currentSnapshot = initialSnapshot;
-    this.#onFirstSubscribe = options?.onFirstSubscribe;
-    this.#onLastUnsubscribe = options?.onLastUnsubscribe;
-    this.#onDestroy = options?.onDestroy;
-
-    this.subscribe = this.subscribe.bind(this);
-    this.getSnapshot = this.getSnapshot.bind(this);
-    this.destroy = this.destroy.bind(this);
-  }
-
-  subscribe(listener: () => void): () => void {
-    if (this.#destroyed) {
-      return () => {};
-    }
-
-    const wasFirst = this.#listeners.size === 0;
-
-    // Add listener BEFORE onFirstSubscribe so that if the reconciliation in
-    // onFirstSubscribe calls updateSnapshot(), this listener receives the
-    // notification. Critical for useSyncExternalStore in adapters — without
-    // this the post-reconnection snapshot is missed and consumers render
-    // stale data. (See Preact RouteView nested remount test.)
-    this.#listeners.add(listener);
-
-    if (wasFirst && this.#onFirstSubscribe) {
-      this.#onFirstSubscribe();
-    }
-
-    return () => {
-      this.#listeners.delete(listener);
-
-      if (
-        !this.#destroyed &&
-        this.#listeners.size === 0 &&
-        this.#onLastUnsubscribe
-      ) {
-        this.#onLastUnsubscribe();
-      }
-    };
-  }
-
-  getSnapshot(): T {
-    return this.#currentSnapshot;
-  }
-
-  updateSnapshot(snapshot: T): void {
-    /* v8 ignore next 2 -- @preserve: defensive guard unreachable via public API (destroy() removes router subscription first) */
-    if (this.#destroyed) {
-      return;
-    }
-
-    this.#currentSnapshot = snapshot;
-    // Isolate listener exceptions so a single throwing subscriber (e.g. React
-    // error-boundary fallback throwing inside `onStoreChange`) does not block
-    // the remaining subscribers — the invariant "after updateSnapshot all
-    // listeners see the new snapshot" must hold. Re-throw asynchronously via
-    // queueMicrotask so global error handlers / test harnesses still surface
-    // the bug without breaking the synchronous notification fan-out.
-    for (const listener of this.#listeners) {
-      try {
-        listener();
-      } catch (error) {
-        queueMicrotask(() => {
-          throw error;
-        });
-      }
-    }
-  }
-
-  destroy(): void {
-    if (this.#destroyed) {
-      return;
-    }
-
-    this.#destroyed = true;
-    this.#onDestroy?.();
-    this.#listeners.clear();
-  }
-}

package/src/canonicalJson.ts

@@ -1,110 +0,0 @@
-/**
- * Serializes a value into a stable JSON string — object keys are sorted at
- * every level so that `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same
- * output.
- *
- * Used as a cache key for `createActiveRouteSource` so that equivalent params
- * objects share the same cached source regardless of key order.
- *
- * **Divergence from `shared/dom-utils/scroll-restore.canonicalJson` — by
- * design.** That sibling implementation is the cheap navigation-hot-path
- * variant (uses `localeCompare`, plain-object accumulator, native cycle
- * detector) and pairs with `safeKeyOf` for crash-tolerance. This one is the
- * strict cache-key variant: byte-order compare, prototype-less accumulator,
- * bespoke cycle detection — eagerly throws on inputs that would cause
- * collisions or pollution, so callers can fall back to non-cached sources.
- * They are NOT interchangeable; cross-package equivalence is explicitly not
- * a goal (audit-2 / audit-2026-05-17 §2).
- *
- * Edge cases:
- * - Arrays preserve order (canonical: index-ordered already).
- * - `undefined` values are dropped (standard JSON behaviour).
- * - `Date` is serialized via its `toJSON` method (ISO string).
- * - `Symbol` becomes `undefined` (standard JSON behaviour).
- * - `BigInt` throws via `JSON.stringify` defaults.
- * - `Map`, `Set`, `RegExp`, `WeakMap`, `WeakSet` would silently collapse to
- *   `"{}"` (no enumerable own keys), which would cause **different inputs to
- *   share the same cache key**. We detect these explicitly and throw — callers
- *   then take the non-cached fallback path (same behaviour as `BigInt`).
- * - Circular references throw `TypeError` (parity with native `JSON.stringify`).
- *   The replacer copies each object level into a fresh prototype-less record,
- *   so we must run our own cycle detection — the native detector never sees
- *   the original object graph.
- * - `__proto__` keys are preserved as own properties (no prototype pollution
- *   and no silent collision between `{ __proto__: x, b: 1 }` and `{ b: 1 }`).
- *
- * In practice, route params carry primitives (`string | number | boolean`);
- * the cache-key-collision edge cases above are defensive bugs caught loudly.
- */
-export function canonicalJson(value: unknown): string {
-  return JSON.stringify(canonicalize(value, new Set<object>()));
-}
-
-// Key comparison uses byte-order (`<` / `>`) instead of `localeCompare()` so
-// the output is independent of the Node.js ICU build / system locale. Same
-// canonical form on every machine — required for cache-key stability.
-function compareKeys(left: string, right: string): number {
-  return left < right ? -1 : 1;
-}
-
-/**
- * Returns a structural clone with object keys sorted at every level. Path-based
- * cycle detection (`path` set) matches the semantics of native `JSON.stringify`
- * — a `TypeError` is thrown on a true cycle, but the same object reachable via
- * two independent branches (DAG) serialises fine.
- *
- * `Date` instances pass through unchanged so `JSON.stringify` can invoke their
- * `toJSON` hook. Other built-ins (`Map`, `Set`, `WeakMap`, `WeakSet`, `RegExp`)
- * throw eagerly to avoid silent cache-key collisions.
- */
-function canonicalize(value: unknown, path: Set<object>): unknown {
-  if (value === null || typeof value !== "object") {
-    return value;
-  }
-
-  if (value instanceof Date) {
-    return value;
-  }
-
-  if (
-    value instanceof Map ||
-    value instanceof Set ||
-    value instanceof WeakMap ||
-    value instanceof WeakSet ||
-    value instanceof RegExp
-  ) {
-    throw new TypeError(
-      `canonicalJson: cannot serialize ${(value as { constructor: { name: string } }).constructor.name} — non-enumerable own keys collapse to "{}" and would cause cache-key collisions. Pass primitive params (string | number | boolean) instead.`,
-    );
-  }
-
-  if (path.has(value)) {
-    throw new TypeError(
-      "canonicalJson: cannot serialize circular structure (cycle detected during traversal).",
-    );
-  }
-
-  path.add(value);
-  try {
-    if (Array.isArray(value)) {
-      return value.map((item) => canonicalize(item, path));
-    }
-
-    // Use a null-prototype record so `__proto__` is treated as a regular
-    // own property — assigning to a plain `{}` would set the prototype
-    // chain instead and silently collide with inputs that omit the key.
-    const sorted: Record<string, unknown> = Object.create(null) as Record<
-      string,
-      unknown
-    >;
-    const keys = Object.keys(value).toSorted(compareKeys);
-
-    for (const key of keys) {
-      sorted[key] = canonicalize((value as Record<string, unknown>)[key], path);
-    }
-
-    return sorted;
-  } finally {
-    path.delete(value);
-  }
-}

package/src/computeSnapshot.ts

@@ -1,44 +0,0 @@
-import { stabilizeState } from "./stabilizeState.js";
-
-import type { RouteNodeSnapshot } from "./types.js";
-import type { Router, SubscribeState } from "@real-router/core";
-
-export function computeSnapshot(
-  currentSnapshot: RouteNodeSnapshot,
-  router: Router,
-  nodeName: string,
-  next?: SubscribeState,
-): RouteNodeSnapshot {
-  const currentRoute = next?.route ?? router.getState();
-  const previousRoute = next?.previousRoute;
-
-  const isNodeActive =
-    nodeName === "" ||
-    (currentRoute !== undefined &&
-      (currentRoute.name === nodeName ||
-        currentRoute.name.startsWith(`${nodeName}.`)));
-
-  const route = isNodeActive ? currentRoute : undefined;
-
-  if (
-    route === currentSnapshot.route &&
-    previousRoute === currentSnapshot.previousRoute
-  ) {
-    return currentSnapshot;
-  }
-
-  const newRoute = stabilizeState(currentSnapshot.route, route);
-  const newPreviousRoute = stabilizeState(
-    currentSnapshot.previousRoute,
-    previousRoute,
-  );
-
-  if (
-    newRoute === currentSnapshot.route &&
-    newPreviousRoute === currentSnapshot.previousRoute
-  ) {
-    return currentSnapshot;
-  }
-
-  return { route: newRoute, previousRoute: newPreviousRoute };
-}

package/src/createActiveNameSelector.ts

@@ -1,182 +0,0 @@
-import { areRoutesRelated } from "@real-router/route-utils";
-
-import { noopDestroy } from "./internal/noopDestroy.js";
-
-import type { Router } from "@real-router/core";
-
-export interface ActiveNameSelector {
-  /**
-   * Subscribes to active-state changes of a specific route name.
-   * Listener is called only when `isActive(routeName)` for this name transitions.
-   * Returns an unsubscribe function.
-   */
-  subscribe: (routeName: string, listener: () => void) => () => void;
-  /**
-   * O(1) active check for the given route name (non-strict by default —
-   * matches descendants). Uses the shared underlying router subscription.
-   */
-  isActive: (routeName: string) => boolean;
-  /** No-op on the cached wrapper. */
-  destroy: () => void;
-}
-
-const selectorCache = new WeakMap<Router, ActiveNameSelector>();
-
-/**
- * Per-router cached selector providing O(1) active-route checks with one
- * shared router subscription for any number of distinct `routeName`
- * consumers.
- *
- * **When to use:** framework `Link` components that need an active boolean
- * without custom `params` / `activeStrict` / `ignoreQueryParams` — e.g. the
- * common navigation-link case. Multiple `<Link>` components with different
- * `routeName` share ONE `router.subscribe` handle instead of creating one
- * per Link (which is what `createActiveRouteSource(router, name)` does — it
- * caches per-name, so N names = N subscriptions).
- *
- * **When NOT to use:** Link needs `activeStrict: true`, custom `routeParams`,
- * or `ignoreQueryParams: false`. Fall back to `createActiveRouteSource` —
- * its cache handles the full argument surface.
- *
- * Based on the `routeSelector` pattern pioneered by `@real-router/solid`'s
- * `RouterProvider` (`createSelector` + `areRoutesRelated`). This helper
- * ports it to framework-agnostic API so Vue / React / Preact / Svelte /
- * Angular Link components can adopt the same fast path.
- *
- * @see Solid reference implementation — `packages/solid/src/RouterProvider.tsx`
- */
-export function createActiveNameSelector(router: Router): ActiveNameSelector {
-  const cached = selectorCache.get(router);
-
-  if (cached) {
-    return cached;
-  }
-
-  // listeners per-name — re-evaluated on every router transition
-  const listenersByName = new Map<string, Set<() => void>>();
-  // cached active state per-name — used to diff before notifying
-  const activeByName = new Map<string, boolean>();
-
-  let routerUnsubscribe: (() => void) | null = null;
-
-  const isActiveNonStrict = (routeName: string): boolean => {
-    const current = router.getState();
-
-    if (!current) {
-      return false;
-    }
-
-    // Empty string represents the root of the name hierarchy — every named
-    // route is its descendant. Without this short-circuit, `current.name`
-    // would have to equal `""` or start with `"."` (both impossible for
-    // valid route names), breaking symmetry with `createRouteNodeSource("")`
-    // which is always-active when a route is current.
-    if (routeName === "") {
-      return true;
-    }
-
-    return (
-      current.name === routeName || current.name.startsWith(`${routeName}.`)
-    );
-  };
-
-  const connect = (): void => {
-    routerUnsubscribe = router.subscribe((next) => {
-      for (const [routeName, listeners] of listenersByName) {
-        // Cheap pre-filter: if neither new nor previous route is related
-        // to this name, its active state cannot have changed. Empty
-        // routeName is the implicit root — every route is its descendant,
-        // so the filter would falsely exclude it (`areRoutesRelated`
-        // doesn't treat `""` specially). Skip the filter for the root.
-        if (routeName !== "") {
-          const isNewRelated = areRoutesRelated(routeName, next.route.name);
-          const isPrevRelated =
-            next.previousRoute &&
-            areRoutesRelated(routeName, next.previousRoute.name);
-
-          if (!isNewRelated && !isPrevRelated) {
-            continue;
-          }
-        }
-
-        // activeByName always has an entry for names present in listenersByName —
-        // subscribe() seeds it, and we only iterate over listenersByName.
-        const prevActive = activeByName.get(routeName) === true;
-        const nextActive = isActiveNonStrict(routeName);
-
-        if (prevActive === nextActive) {
-          continue;
-        }
-
-        activeByName.set(routeName, nextActive);
-        for (const listener of listeners) {
-          listener();
-        }
-      }
-    });
-  };
-
-  const disconnect = (): void => {
-    const unsub = routerUnsubscribe;
-
-    routerUnsubscribe = null;
-    unsub?.();
-  };
-
-  const subscribe = (routeName: string, listener: () => void): (() => void) => {
-    let listeners = listenersByName.get(routeName);
-
-    if (!listeners) {
-      listeners = new Set();
-      listenersByName.set(routeName, listeners);
-      activeByName.set(routeName, isActiveNonStrict(routeName));
-    }
-
-    listeners.add(listener);
-
-    if (!routerUnsubscribe) {
-      connect();
-    }
-
-    let unsubscribed = false;
-
-    return () => {
-      if (unsubscribed) {
-        return;
-      }
-
-      unsubscribed = true;
-      listeners.delete(listener);
-
-      if (listeners.size === 0) {
-        listenersByName.delete(routeName);
-        activeByName.delete(routeName);
-      }
-
-      if (listenersByName.size === 0) {
-        disconnect();
-      }
-    };
-  };
-
-  const isActive = (routeName: string): boolean => {
-    const cachedActive = activeByName.get(routeName);
-
-    if (cachedActive !== undefined) {
-      return cachedActive;
-    }
-
-    // Not subscribed — compute on demand.
-    return isActiveNonStrict(routeName);
-  };
-
-  const selector: ActiveNameSelector = {
-    subscribe,
-    isActive,
-    destroy: noopDestroy,
-  };
-
-  selectorCache.set(router, selector);
-
-  return selector;
-}

package/src/createActiveRouteSource.ts

@@ -1,223 +0,0 @@
-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";
-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`).
- *
- * For cached entries `destroy()` is a no-op — shared sources live with the
- * router and release automatically on router GC (WeakMap entry).
- *
- * `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,
-  routeName: string,
-  params?: Params,
-  options?: ActiveRouteSourceOptions,
-): RouterSource<boolean> {
-  const { strict, ignoreQueryParams, hash } = 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 {
-    // `hash === undefined` produces "" via String(undefined) → "undefined";
-    // we encode it as the empty string sentinel to keep the key short and
-    // distinct from the literal "undefined" hash value (which is a valid,
-    // if unusual, fragment).
-    const hashKey = hash === undefined ? "" : `#${hash}`;
-
-    // `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) {
-    // 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,
-      strict,
-      ignoreQueryParams,
-      hash,
-    );
-  }
-
-  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,
-      hash,
-    );
-
-    cached = {
-      subscribe: source.subscribe,
-      getSnapshot: source.getSnapshot,
-      destroy: noopDestroy,
-    };
-    perRouter.set(key, cached);
-  }
-
-  return cached;
-}
-
-/**
- * Combines route-name match with optional hash match (#532).
- *
- * - Route-name match: `router.isActiveRoute(name, params, strict, ignoreQueryParams)`.
- * - Hash match (only when `hash !== undefined`): `state.context.url.hash` must
- *   equal the requested fragment exactly. With hash-plugin (no `url`
- *   namespace), this returns `false` — the documented limitation.
- */
-function computeActive(
-  router: Router,
-  routeName: string,
-  params: Params | undefined,
-  strict: boolean,
-  ignoreQueryParams: boolean,
-  hash: string | undefined,
-): boolean {
-  const routeActive = router.isActiveRoute(
-    routeName,
-    params,
-    strict,
-    ignoreQueryParams,
-  );
-
-  if (!routeActive) {
-    return false;
-  }
-  if (hash === undefined) {
-    return true;
-  }
-
-  // `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(
-  router: Router,
-  routeName: string,
-  params: Params | undefined,
-  strict: boolean,
-  ignoreQueryParams: boolean,
-  hash: string | undefined,
-): RouterSource<boolean> {
-  const initialValue = computeActive(
-    router,
-    routeName,
-    params,
-    strict,
-    ignoreQueryParams,
-    hash,
-  );
-
-  let routerUnsubscribe: (() => void) | undefined;
-
-  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 &&
-      areRoutesRelated(routeName, next.previousRoute.name);
-
-    // Hash-aware sources also flip on same-path-different-hash transitions.
-    // The route comparison alone misses these (route is identical), but the
-    // hash claim updated, so we must re-evaluate. Detect via the `hashChanged`
-    // flag published by URL plugins.
-    const hashFlip =
-      hash !== undefined &&
-      ((next.route.context as { url?: { hashChanged?: boolean } } | undefined)
-        ?.url?.hashChanged ??
-        false);
-
-    if (!isNewRelated && !isPrevRelated && !hashFlip) {
-      return;
-    }
-
-    // If new route is not related, we know the route is inactive —
-    // avoid calling isActiveRoute for the optimization. (Hash check would
-    // also fail without route-match, so this short-circuit holds for
-    // hash-aware sources too.)
-    const newValue = isNewRelated
-      ? computeActive(
-          router,
-          routeName,
-          params,
-          strict,
-          ignoreQueryParams,
-          hash,
-        )
-      : false;
-
-    if (!Object.is(source.getSnapshot(), newValue)) {
-      source.updateSnapshot(newValue);
-    }
-  });
-
-  return source;
-}