@real-router/sources 0.4.2 → 0.4.4

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/createRouteSource.ts","../../src/createRouteNodeSource.ts","../../src/createActiveRouteSource.ts","../../src/createTransitionSource.ts","../../src/createErrorSource.ts"],"mappings":";;;UAEiB,aAAA;EACf,KAAA,EAAO,KAAA;EACP,aAAA,EAAe,KAAA;AAAA;AAAA,UAGA,iBAAA;EACf,KAAA,EAAO,KAAA;EACP,aAAA,EAAe,KAAA;AAAA;AAAA,UAGA,YAAA;EACf,SAAA,GAAY,QAAA;EACZ,WAAA,QAAmB,CAAA;EACnB,OAAA;AAAA;AAAA,UAGe,wBAAA;EACf,MAAA;EACA,iBAAA;AAAA;AAAA,UAGe,wBAAA;EACf,eAAA;EACA,eAAA;EACA,OAAA,EAAS,KAAA;EACT,SAAA,EAAW,KAAA;AAAA;AAAA,UAGI,mBAAA;EACf,KAAA,EAAO,WAAA;EACP,OAAA,EAAS,KAAA;EACT,SAAA,EAAW,KAAA;EACX,OAAA;AAAA;;;;AAhCF;;;;;;iBCWgB,iBAAA,CAAkB,MAAA,EAAQ,MAAA,GAAS,YAAA,CAAa,aAAA;;;;ADXhE;;;;;;iBEYgB,qBAAA,CACd,MAAA,EAAQ,MAAA,EACR,QAAA,WACC,YAAA,CAAa,iBAAA;;;iBCVA,uBAAA,CACd,MAAA,EAAQ,MAAA,EACR,SAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA,GAAU,wBAAA,GACT,YAAA;;;iBCIa,sBAAA,CACd,MAAA,EAAQ,MAAA,GACP,YAAA,CAAa,wBAAA;;;iBCHA,iBAAA,CACd,MAAA,EAAQ,MAAA,GACP,YAAA,CAAa,mBAAA"}

package/dist/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/createRouteSource.ts","../../src/createRouteNodeSource.ts","../../src/createActiveRouteSource.ts","../../src/createTransitionSource.ts","../../src/createErrorSource.ts"],"mappings":";;;UAEiB,aAAA;EACf,KAAA,EAAO,KAAA;EACP,aAAA,EAAe,KAAA;AAAA;AAAA,UAGA,iBAAA;EACf,KAAA,EAAO,KAAA;EACP,aAAA,EAAe,KAAA;AAAA;AAAA,UAGA,YAAA;EACf,SAAA,GAAY,QAAA;EACZ,WAAA,QAAmB,CAAA;EACnB,OAAA;AAAA;AAAA,UAGe,wBAAA;EACf,MAAA;EACA,iBAAA;AAAA;AAAA,UAGe,wBAAA;EACf,eAAA;EACA,eAAA;EACA,OAAA,EAAS,KAAA;EACT,SAAA,EAAW,KAAA;AAAA;AAAA,UAGI,mBAAA;EACf,KAAA,EAAO,WAAA;EACP,OAAA,EAAS,KAAA;EACT,SAAA,EAAW,KAAA;EACX,OAAA;AAAA;;;;AAhCF;;;;;;iBCWgB,iBAAA,CAAkB,MAAA,EAAQ,MAAA,GAAS,YAAA,CAAa,aAAA;;;;ADXhE;;;;;;iBEYgB,qBAAA,CACd,MAAA,EAAQ,MAAA,EACR,QAAA,WACC,YAAA,CAAa,iBAAA;;;iBCVA,uBAAA,CACd,MAAA,EAAQ,MAAA,EACR,SAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA,GAAU,wBAAA,GACT,YAAA;;;iBCIa,sBAAA,CACd,MAAA,EAAQ,MAAA,GACP,YAAA,CAAa,wBAAA;;;iBCHA,iBAAA,CACd,MAAA,EAAQ,MAAA,GACP,YAAA,CAAa,mBAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/sources",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "commonjs",
   "description": "Framework-agnostic subscription layer for Real-Router state",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -42,8 +42,8 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1",
-    "@real-router/route-utils": "^0.1.12"
+    "@real-router/core": "^0.46.0",
+    "@real-router/route-utils": "^0.1.14"
   },
   "devDependencies": {
     "mitata": "1.0.34"
@@ -53,7 +53,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0 --no-error-on-unmatched-pattern",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "test:properties": "vitest --config vitest.config.properties.mts --run",
     "test:stress": "vitest run --config vitest.config.stress.mts",

package/src/BaseSource.ts

@@ -0,0 +1,76 @@
+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 () => {};
+    }
+
+    if (this.#listeners.size === 0 && this.#onFirstSubscribe) {
+      this.#onFirstSubscribe();
+    }
+
+    this.#listeners.add(listener);
+
+    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;
+    this.#listeners.forEach((listener) => {
+      listener();
+    });
+  }
+
+  destroy(): void {
+    if (this.#destroyed) {
+      return;
+    }
+
+    this.#destroyed = true;
+    this.#onDestroy?.();
+    this.#listeners.clear();
+  }
+}

package/src/computeSnapshot.ts

@@ -0,0 +1,44 @@
+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/createActiveRouteSource.ts

@@ -0,0 +1,53 @@
+import { areRoutesRelated } from "@real-router/route-utils";
+
+import { BaseSource } from "./BaseSource";
+
+import type { ActiveRouteSourceOptions, RouterSource } from "./types.js";
+import type { Params, Router } from "@real-router/core";
+
+export function createActiveRouteSource(
+  router: Router,
+  routeName: string,
+  params?: Params,
+  options?: ActiveRouteSourceOptions,
+): RouterSource<boolean> {
+  const strict = options?.strict ?? false;
+  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
+
+  const initialValue = router.isActiveRoute(
+    routeName,
+    params,
+    strict,
+    ignoreQueryParams,
+  );
+
+  const source = new BaseSource(initialValue, {
+    onDestroy: () => {
+      unsubscribe();
+    },
+  });
+
+  // Eager connection: subscribe to router immediately
+  const unsubscribe = router.subscribe((next) => {
+    const isNewRelated = areRoutesRelated(routeName, next.route.name);
+    const isPrevRelated =
+      next.previousRoute &&
+      areRoutesRelated(routeName, next.previousRoute.name);
+
+    if (!isNewRelated && !isPrevRelated) {
+      return;
+    }
+
+    // If new route is not related, we know the route is inactive —
+    // avoid calling isActiveRoute for the optimization
+    const newValue = isNewRelated
+      ? router.isActiveRoute(routeName, params, strict, ignoreQueryParams)
+      : false;
+
+    if (!Object.is(source.getSnapshot(), newValue)) {
+      source.updateSnapshot(newValue);
+    }
+  });
+
+  return source;
+}

package/src/createErrorSource.ts

@@ -0,0 +1,66 @@
+import { events } from "@real-router/core";
+import { getPluginApi } from "@real-router/core/api";
+
+import { BaseSource } from "./BaseSource";
+
+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,
+};
+
+export function createErrorSource(
+  router: Router,
+): RouterSource<RouterErrorSnapshot> {
+  let errorVersion = 0;
+
+  const source = new BaseSource(INITIAL_SNAPSHOT, {
+    onDestroy: () => {
+      unsubs.forEach((unsub) => {
+        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++;
+        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 (source.getSnapshot().error !== null) {
+        source.updateSnapshot({
+          error: null,
+          toRoute: null,
+          fromRoute: null,
+          version: errorVersion,
+        });
+      }
+    }),
+  ];
+
+  return source;
+}

package/src/createRouteNodeSource.ts

@@ -0,0 +1,76 @@
+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";
+
+/**
+ * Creates a source scoped to a specific route node.
+ *
+ * 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 createRouteNodeSource(
+  router: Router,
+  nodeName: string,
+): RouterSource<RouteNodeSnapshot> {
+  let routerUnsubscribe: (() => void) | null = null;
+
+  const shouldUpdate = getCachedShouldUpdate(router, 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,
+          );
+
+          if (!Object.is(source.getSnapshot(), newSnapshot)) {
+            source.updateSnapshot(newSnapshot);
+          }
+        });
+      },
+      onLastUnsubscribe: disconnect,
+      onDestroy: disconnect,
+    },
+  );
+
+  return source;
+}

package/src/createRouteSource.ts

@@ -0,0 +1,56 @@
+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

@@ -0,0 +1,76 @@
+import { events } from "@real-router/core";
+import { getPluginApi } from "@real-router/core/api";
+
+import { BaseSource } from "./BaseSource";
+import { stabilizeState } from "./stabilizeState.js";
+
+import type { RouterTransitionSnapshot, RouterSource } from "./types.js";
+import type { Router, State } from "@real-router/core";
+
+const IDLE_SNAPSHOT: RouterTransitionSnapshot = {
+  isTransitioning: false,
+  isLeaveApproved: false,
+  toRoute: null,
+  fromRoute: null,
+};
+
+export function createTransitionSource(
+  router: Router,
+): RouterSource<RouterTransitionSnapshot> {
+  const source = new BaseSource(IDLE_SNAPSHOT, {
+    onDestroy: () => {
+      unsubs.forEach((unsub) => {
+        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) => {
+        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,
+          });
+        }
+      },
+    ),
+    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),
+        });
+      },
+    ),
+    api.addEventListener(events.TRANSITION_SUCCESS, resetToIdle),
+    api.addEventListener(events.TRANSITION_ERROR, resetToIdle),
+    api.addEventListener(events.TRANSITION_CANCEL, resetToIdle),
+  ];
+
+  return source;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export type {
+  RouterSource,
+  RouteSnapshot,
+  RouteNodeSnapshot,
+  ActiveRouteSourceOptions,
+  RouterTransitionSnapshot,
+  RouterErrorSnapshot,
+} from "./types.js";
+
+export { createRouteSource } from "./createRouteSource";
+
+export { createRouteNodeSource } from "./createRouteNodeSource";
+
+export { createActiveRouteSource } from "./createActiveRouteSource";
+
+export { createTransitionSource } from "./createTransitionSource";
+
+export { createErrorSource } from "./createErrorSource";

package/src/shouldUpdateCache.ts

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

package/src/stabilizeState.ts

@@ -0,0 +1,31 @@
+import type { State } from "@real-router/core";
+
+/**
+ * State-aware stabilization for route snapshots.
+ *
+ * Compares `path` — the canonical representation of rendering-relevant
+ * State fields (name + params). When path matches, returns `prev`
+ * (preserving reference), enabling frameworks to skip re-renders.
+ *
+ * Ignores `meta` (internal: auto-increment id) and `transition`
+ * (reference data: from, segments, reload) — they don't affect
+ * what is rendered.
+ *
+ * Accepts `null` for compatibility with `RouterTransitionSnapshot`
+ * (toRoute/fromRoute are `State | null`).
+ *
+ * @internal Not exported from package public API.
+ */
+export function stabilizeState<T extends State | null | undefined>(
+  prev: T,
+  next: T,
+): T {
+  if (prev === next) {
+    return prev;
+  }
+  if (prev?.path !== next?.path) {
+    return next;
+  }
+
+  return prev;
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+import type { RouterError, State } from "@real-router/core";
+
+export interface RouteSnapshot {
+  route: State | undefined;
+  previousRoute: State | undefined;
+}
+
+export interface RouteNodeSnapshot {
+  route: State | undefined;
+  previousRoute: State | undefined;
+}
+
+export interface RouterSource<T> {
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => T;
+  destroy: () => void;
+}
+
+export interface ActiveRouteSourceOptions {
+  strict?: boolean;
+  ignoreQueryParams?: boolean;
+}
+
+export interface RouterTransitionSnapshot {
+  isTransitioning: boolean;
+  isLeaveApproved: boolean;
+  toRoute: State | null;
+  fromRoute: State | null;
+}
+
+export interface RouterErrorSnapshot {
+  error: RouterError | null;
+  toRoute: State | null;
+  fromRoute: State | null;
+  version: number;
+}