@real-router/rx

Reactive Observable API for Real-Router. State streams, event streams, built-in operators, TC39 Observable and RxJS interop. Zero-cost opt-in — only bundled when imported.

Installation

npm install @real-router/rx

Peer dependency: @real-router/core

Quick Start

import { state$, map, filter, distinctUntilChanged } from "@real-router/rx";

state$(router)
  .pipe(
    map(({ route }) => route.params.categoryId),
    filter((id) => id !== undefined),
    distinctUntilChanged(),
  )
  .subscribe((categoryId) => {
    loadCategory(categoryId);
  });

Streams

| Factory | Returns | Description | |---------|---------|-------------| | state$(router, options?) | RxObservable<{ route, previousRoute }> | Router state changes | | events$(router) | RxObservable<RouterEvent> | All router events (start, stop, transition, error, cancel) | | observable(router) | RxObservable<SubscribeState> | TC39 Observable-compliant wrapper for RxJS interop |

state$ accepts { signal: AbortSignal } for automatic unsubscription.

Operators

| Operator | Description | |----------|-------------| | map(project) | Transform emitted values | | filter(predicate) | Filter values by predicate | | debounceTime(ms) | Emit only the last value after a delay | | distinctUntilChanged(cmp?) | Skip consecutive duplicates | | takeUntil(notifier) | Complete when notifier emits |

All operators are composable via .pipe():

state$(router).pipe(
  filter(({ route }) => route.name.startsWith("admin")),
  debounceTime(100),
).subscribe(({ route }) => {
  analytics.trackPage(route.name);
});

Event Filtering

import { events$, filter } from "@real-router/rx";

events$(router)
  .pipe(filter((e) => e.type === "TRANSITION_ERROR"))
  .subscribe(({ error }) => {
    errorTracker.capture(error);
  });

RxJS Interop

observable() returns a TC39-compliant Observable — pass it to RxJS from():

import { from } from "rxjs";
import { debounceTime } from "rxjs/operators";
import { observable } from "@real-router/rx";

from(observable(router))
  .pipe(debounceTime(100))
  .subscribe(({ route }) => {
    console.log("Route:", route.name);
  });

Documentation

Full documentation: Wiki — rx

• API Reference
• Operators
• Async Iteration
• Migration Guide

Related Packages

| Package | Description | |---------|-------------| | @real-router/core | Core router (required peer dependency) | | @real-router/sources | useSyncExternalStore-based alternative | | @real-router/react | React integration |

Contributing

See contributing guidelines for development setup and PR process.

License

MIT © Oleg Ivanov