@real-router/sources 0.2.3 → 0.2.4

package/README.md

@@ -1,22 +1,22 @@
 # @real-router/sources
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/npm/v/@real-router/sources.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/sources)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/sources.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/sources)
+[![bundle size](https://deno.bundlejs.com/?q=@real-router/sources&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/sources&treeshake=[*])
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
 
-Framework-agnostic subscription layer for Real-Router. Subscribe to router state slices with automatic filtering and deduplication. Provides minimal reactive primitives for building UI bindings.
+> Framework-agnostic subscription layer for [Real-Router](https://github.com/greydragon888/real-router). Reactive primitives compatible with `useSyncExternalStore` and vanilla JS.
+
+Used internally by [`@real-router/react`](https://www.npmjs.com/package/@real-router/react). Use this package directly when building integrations for other frameworks or vanilla JS applications.
 
 ## Installation
 
 ```bash
 npm install @real-router/sources
-# or
-pnpm add @real-router/sources
-# or
-yarn add @real-router/sources
-# or
-bun add @real-router/sources
 ```
 
+**Peer dependency:** `@real-router/core`
+
 ## Quick Start
 
 ```typescript
@@ -25,200 +25,115 @@ import { createRouteSource } from "@real-router/sources";
 
 const router = createRouter([
   { name: "home", path: "/" },
-  { name: "users", path: "/users" },
-  { name: "users.profile", path: "/:id" },
+  { name: "users", path: "/users/:id" },
 ]);
 
-router.start();
+await router.start("/");
 
 const source = createRouteSource(router);
-
-// Subscribe to route changes
 const unsubscribe = source.subscribe(() => {
   console.log("Route:", source.getSnapshot().route?.name);
 });
-
-// Clean up when done
-unsubscribe();
-```
-
----
-
-## API
-
-### `createRouteSource(router)`
-
-Creates a source for the full router state. Subscribes to the router on the first listener and unsubscribes when all listeners are removed (lazy-connection pattern).\
-`router: Router` — router instance\
-Returns: `RouterSource<RouteSnapshot>`
-
-```typescript
-const source = createRouteSource(router);
-```
-
----
-
-### `createRouteNodeSource(router, nodeName)`
-
-Creates a source scoped to a specific route node. Only updates when the node is in the transition path, avoiding unnecessary re-renders for unrelated navigations. Uses a lazy-connection pattern: subscribes to the router on the first listener and unsubscribes when all listeners are removed.\
-`router: Router` — router instance\
-`nodeName: string` — route node name to scope updates to\
-Returns: `RouterSource<RouteNodeSnapshot>`
-
-```typescript
-const source = createRouteNodeSource(router, "users");
-```
-
----
-
-### `createActiveRouteSource(router, routeName, params?, options?)`
-
-Creates a source that tracks whether a specific route is active. Returns a boolean snapshot.\
-`router: Router` — router instance\
-`routeName: string` — route name to check\
-`params?: Record<string, unknown>` — optional params to match\
-`options?: ActiveRouteSourceOptions` — matching options\
-Returns: `RouterSource<boolean>`
-
-```typescript
-const source = createActiveRouteSource(router, "users.profile", { id: "123" });
-const source = createActiveRouteSource(router, "users", undefined, {
-  strict: false,
-  ignoreQueryParams: true,
-});
-```
-
-Call `source.destroy()` when the source is no longer needed.
-
-**Options:**
-
-| Option              | Type      | Default | Description                                                |
-| ------------------- | --------- | ------- | ---------------------------------------------------------- |
-| `strict`            | `boolean` | `false` | When `true`, only matches the exact route, not descendants |
-| `ignoreQueryParams` | `boolean` | `true`  | When `true`, ignores query parameters when matching        |
-
----
-
-### `createTransitionSource(router)`
-
-Creates a source that tracks the router's transition lifecycle. Updates on `TRANSITION_START`, `TRANSITION_SUCCESS`, `TRANSITION_ERROR`, and `TRANSITION_CANCEL` events. Unlike other sources, this uses eager subscription (subscribes to events immediately, not lazily on first listener).\
-`router: Router` — router instance\
-Returns: `RouterSource<RouterTransitionSnapshot>`
-
-```typescript
-const source = createTransitionSource(router);
-
-source.subscribe(() => {
-  const { isTransitioning, toRoute, fromRoute } = source.getSnapshot();
-  if (isTransitioning) {
-    console.log(`Navigating: ${fromRoute?.name} → ${toRoute?.name}`);
-  }
-});
 ```
 
-Call `source.destroy()` when the source is no longer needed.
+## Source Factories
 
----
+| Factory | Snapshot | Updates when |
+|---------|----------|--------------|
+| `createRouteSource(router)` | `{ route, previousRoute }` | Every navigation |
+| `createRouteNodeSource(router, node)` | `{ route, previousRoute }` | Only when node activates/deactivates |
+| `createActiveRouteSource(router, name, params?, opts?)` | `boolean` | Route active status changes |
+| `createTransitionSource(router)` | `{ isTransitioning, toRoute, fromRoute }` | Transition start/end/cancel/error |
 
-### `RouterSource<T>` Interface
-
-All four factories return a `RouterSource<T>`:
+All factories return a `RouterSource<T>`:
 
 ```typescript
 interface RouterSource<T> {
-  subscribe(listener: () => void): () => void;
-  getSnapshot(): T;
-  destroy(): void;
+  subscribe(listener: () => void): () => void;  // useSyncExternalStore-compatible
+  getSnapshot(): T;                              // current value, synchronous
+  destroy(): void;                               // teardown, remove router subscription
 }
 ```
 
-`subscribe` — registers a listener and returns an unsubscribe function. Compatible with `useSyncExternalStore`.\
-`getSnapshot` — returns the current snapshot synchronously.\
-`destroy` — tears down the source and removes the router subscription.
+### Lazy vs Eager Subscription
 
----
+- `createRouteSource`, `createRouteNodeSource`, `createActiveRouteSource` — **lazy**: subscribe to the router on first listener, unsubscribe when all removed
+- `createTransitionSource` — **eager**: subscribes immediately (needs to track `TRANSITION_START`)
 
-## Types
+### `createActiveRouteSource` Options
 
 ```typescript
-import type {
-  RouterSource,
-  RouteSnapshot,
-  RouteNodeSnapshot,
-  RouterTransitionSnapshot,
-  ActiveRouteSourceOptions,
-} from "@real-router/sources";
+const source = createActiveRouteSource(router, "users", undefined, {
+  strict: false,          // default: false — match descendants too
+  ignoreQueryParams: true, // default: true
+});
 ```
 
-`RouteSnapshot` — full router state: `{ route: State | undefined, previousRoute: State | undefined }`\
-`RouteNodeSnapshot` — node-scoped state: `{ route: State | undefined, previousRoute: State | undefined }`\
-`RouterTransitionSnapshot` — transition state: `{ isTransitioning: boolean, toRoute: State | null, fromRoute: State | null }`\
-`ActiveRouteSourceOptions` — options for `createActiveRouteSource`: `{ strict?: boolean, ignoreQueryParams?: boolean }`\
-`RouterSource<T>` — the source interface returned by all four factories
-
----
-
 ## Usage Examples
 
 ### With React (`useSyncExternalStore`)
 
-```typescript
+```tsx
 import { useSyncExternalStore } from "react";
 import { createRouteSource } from "@real-router/sources";
 
 const source = createRouteSource(router);
 
 function CurrentRoute() {
-  const { route } = useSyncExternalStore(
-    source.subscribe,
-    source.getSnapshot,
-  );
-
-  return <p>Current route: {route.name}</p>;
+  const { route } = useSyncExternalStore(source.subscribe, source.getSnapshot);
+  return <p>Current route: {route?.name}</p>;
 }
 ```
 
 ### With Vanilla JS
 
 ```typescript
-import { createRouteSource } from "@real-router/sources";
+import { createRouteNodeSource } from "@real-router/sources";
 
-const source = createRouteSource(router);
+// Only fires when navigating within the "users" subtree
+const source = createRouteNodeSource(router, "users");
 
 const unsubscribe = source.subscribe(() => {
-  const { route, previousRoute } = source.getSnapshot();
-  console.log("Navigation:", previousRoute?.name, "->", route.name);
+  const { route } = source.getSnapshot();
+  console.log("Users section:", route?.name);
 });
 
-// Later, clean up
-unsubscribe();
+unsubscribe(); // automatically unsubscribes from router
 ```
 
-### Node-Scoped Updates
+### Transition Tracking
 
 ```typescript
-import { createRouteNodeSource } from "@real-router/sources";
+import { createTransitionSource } from "@real-router/sources";
 
-// Only re-renders when navigating within the "users" subtree
-const source = createRouteNodeSource(router, "users");
+const source = createTransitionSource(router);
 
-const unsubscribe = source.subscribe(() => {
-  const { route } = source.getSnapshot();
-  console.log("Users section route:", route?.name);
+source.subscribe(() => {
+  const { isTransitioning, toRoute, fromRoute } = source.getSnapshot();
+  if (isTransitioning) {
+    showSpinner();
+  } else {
+    hideSpinner();
+  }
 });
-
-// Later, clean up (automatically unsubscribes from router)
-unsubscribe();
 ```
 
----
+## Documentation
+
+Full documentation: [Wiki — sources](https://github.com/greydragon888/real-router/wiki/sources-package)
 
 ## Related Packages
 
-- [@real-router/core](https://www.npmjs.com/package/@real-router/core) — Core router
-- [@real-router/react](https://www.npmjs.com/package/@real-router/react) — React integration (uses sources internally)
-- [@real-router/rx](https://www.npmjs.com/package/@real-router/rx) — Reactive Observable API
+| Package | Description |
+|---------|-------------|
+| [@real-router/core](https://www.npmjs.com/package/@real-router/core) | Core router (required dependency) |
+| [@real-router/react](https://www.npmjs.com/package/@real-router/react) | React integration (uses sources internally) |
+| [@real-router/rx](https://www.npmjs.com/package/@real-router/rx) | Observable API (`state$`, `events$`) |
+
+## Contributing
+
+See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
 
 ## License
 
-MIT © [Oleg Ivanov](https://github.com/greydragon888)
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.js

@@ -1 +1 @@
-var e=require("@real-router/route-utils"),t=require("@real-router/core"),s=require("@real-router/core/api"),r=class{#e;#t=!1;#s=new Set;#r;#o;#n;constructor(e,t){this.#e=e,this.#r=t?.onFirstSubscribe,this.#o=t?.onLastUnsubscribe,this.#n=t?.onDestroy,this.subscribe=this.subscribe.bind(this),this.getSnapshot=this.getSnapshot.bind(this),this.destroy=this.destroy.bind(this)}subscribe(e){return this.#t?()=>{}:(0===this.#s.size&&this.#r&&this.#r(),this.#s.add(e),()=>{this.#s.delete(e),!this.#t&&0===this.#s.size&&this.#o&&this.#o()})}getSnapshot(){return this.#e}updateSnapshot(e){this.#t||(this.#e=e,this.#s.forEach(e=>{e()}))}destroy(){this.#t||(this.#t=!0,this.#n?.(),this.#s.clear())}};function o(e,t,s,r){const o=r?.route??t.getState(),n=r?.previousRoute,i=""===s||void 0!==o&&(o.name===s||o.name.startsWith(`${s}.`))?o:void 0;return i===e.route&&n===e.previousRoute?e:{route:i,previousRoute:n}}var n=new WeakMap,i={isTransitioning:!1,toRoute:null,fromRoute:null};exports.createActiveRouteSource=function(t,s,o,n){const i=n?.strict??!1,u=n?.ignoreQueryParams??!0,a=t.isActiveRoute(s,o,i,u),c=new r(a,{onDestroy:()=>{h()}}),h=t.subscribe(r=>{const n=e.areRoutesRelated(s,r.route.name),a=r.previousRoute&&e.areRoutesRelated(s,r.previousRoute.name);if(!n&&!a)return;const h=!!n&&t.isActiveRoute(s,o,i,u);Object.is(c.getSnapshot(),h)||c.updateSnapshot(h)});return c},exports.createRouteNodeSource=function(e,t){let s=null;const i=function(e,t){let s=n.get(e);s||(s=new Map,n.set(e,s));let r=s.get(t);return r||(r=e.shouldUpdateNode(t),s.set(t,r)),r}(e,t),u=()=>{const e=s;s=null,e?.()},a=new r(o({route:void 0,previousRoute:void 0},e,t),{onFirstSubscribe:()=>{a.updateSnapshot(o(a.getSnapshot(),e,t)),s=e.subscribe(s=>{if(!i(s.route,s.previousRoute))return;const r=o(a.getSnapshot(),e,t,s);Object.is(a.getSnapshot(),r)||a.updateSnapshot(r)})},onLastUnsubscribe:u,onDestroy:u});return a},exports.createRouteSource=function(e){let t=null;const s=()=>{const e=t;t=null,e?.()},o=new r({route:e.getState(),previousRoute:void 0},{onFirstSubscribe:()=>{t=e.subscribe(e=>{o.updateSnapshot({route:e.route,previousRoute:e.previousRoute})})},onLastUnsubscribe:s,onDestroy:s});return o},exports.createTransitionSource=function(e){const o=new r(i,{onDestroy:()=>{a.forEach(e=>{e()})}}),n=s.getPluginApi(e),u=()=>{o.updateSnapshot(i)},a=[n.addEventListener(t.events.TRANSITION_START,(e,t)=>{o.updateSnapshot({isTransitioning:!0,toRoute:e,fromRoute:t??null})}),n.addEventListener(t.events.TRANSITION_SUCCESS,u),n.addEventListener(t.events.TRANSITION_ERROR,u),n.addEventListener(t.events.TRANSITION_CANCEL,u)];return o};//# sourceMappingURL=index.js.map
+"use strict";var e=require("@real-router/route-utils"),t=require("@real-router/core"),s=require("@real-router/core/api"),r=class{#e;#t=!1;#s=new Set;#r;#o;#n;constructor(e,t){this.#e=e,this.#r=t?.onFirstSubscribe,this.#o=t?.onLastUnsubscribe,this.#n=t?.onDestroy,this.subscribe=this.subscribe.bind(this),this.getSnapshot=this.getSnapshot.bind(this),this.destroy=this.destroy.bind(this)}subscribe(e){return this.#t?()=>{}:(0===this.#s.size&&this.#r&&this.#r(),this.#s.add(e),()=>{this.#s.delete(e),!this.#t&&0===this.#s.size&&this.#o&&this.#o()})}getSnapshot(){return this.#e}updateSnapshot(e){this.#t||(this.#e=e,this.#s.forEach(e=>{e()}))}destroy(){this.#t||(this.#t=!0,this.#n?.(),this.#s.clear())}};function o(e,t,s,r){const o=r?.route??t.getState(),n=r?.previousRoute,i=""===s||void 0!==o&&(o.name===s||o.name.startsWith(`${s}.`))?o:void 0;return i===e.route&&n===e.previousRoute?e:{route:i,previousRoute:n}}var n=new WeakMap,i={isTransitioning:!1,toRoute:null,fromRoute:null};exports.createActiveRouteSource=function(t,s,o,n){const i=n?.strict??!1,u=n?.ignoreQueryParams??!0,a=t.isActiveRoute(s,o,i,u),c=new r(a,{onDestroy:()=>{h()}}),h=t.subscribe(r=>{const n=e.areRoutesRelated(s,r.route.name),a=r.previousRoute&&e.areRoutesRelated(s,r.previousRoute.name);if(!n&&!a)return;const h=!!n&&t.isActiveRoute(s,o,i,u);Object.is(c.getSnapshot(),h)||c.updateSnapshot(h)});return c},exports.createRouteNodeSource=function(e,t){let s=null;const i=function(e,t){let s=n.get(e);s||(s=new Map,n.set(e,s));let r=s.get(t);return r||(r=e.shouldUpdateNode(t),s.set(t,r)),r}(e,t),u=()=>{const e=s;s=null,e?.()},a=new r(o({route:void 0,previousRoute:void 0},e,t),{onFirstSubscribe:()=>{a.updateSnapshot(o(a.getSnapshot(),e,t)),s=e.subscribe(s=>{if(!i(s.route,s.previousRoute))return;const r=o(a.getSnapshot(),e,t,s);Object.is(a.getSnapshot(),r)||a.updateSnapshot(r)})},onLastUnsubscribe:u,onDestroy:u});return a},exports.createRouteSource=function(e){let t=null;const s=()=>{const e=t;t=null,e?.()},o=new r({route:e.getState(),previousRoute:void 0},{onFirstSubscribe:()=>{t=e.subscribe(e=>{o.updateSnapshot({route:e.route,previousRoute:e.previousRoute})})},onLastUnsubscribe:s,onDestroy:s});return o},exports.createTransitionSource=function(e){const o=new r(i,{onDestroy:()=>{a.forEach(e=>{e()})}}),n=s.getPluginApi(e),u=()=>{o.updateSnapshot(i)},a=[n.addEventListener(t.events.TRANSITION_START,(e,t)=>{o.updateSnapshot({isTransitioning:!0,toRoute:e,fromRoute:t??null})}),n.addEventListener(t.events.TRANSITION_SUCCESS,u),n.addEventListener(t.events.TRANSITION_ERROR,u),n.addEventListener(t.events.TRANSITION_CANCEL,u)];return o};//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/sources",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "commonjs",
   "description": "Framework-agnostic subscription layer for Real-Router state",
   "main": "./dist/cjs/index.js",
@@ -43,8 +43,8 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.36.0",
-    "@real-router/route-utils": "^0.1.4"
+    "@real-router/core": "^0.37.0",
+    "@real-router/route-utils": "^0.1.5"
   },
   "devDependencies": {
     "mitata": "1.0.34"