@real-router/rx

Reactive Observable API for Real-Router. Zero-cost opt-in for reactive programming patterns.

Installation

npm install @real-router/rx
# or
pnpm add @real-router/rx
# or
yarn add @real-router/rx
# or
bun add @real-router/rx

Quick Start

import { createRouter } from "@real-router/core";
import { state$ } from "@real-router/rx";

const router = createRouter([
  { name: "home", path: "/" },
  { name: "users", path: "/users" },
  { name: "users.profile", path: "/:id" },
]);

router.start();

// Subscribe to state changes
state$(router).subscribe(({ route, previousRoute }) => {
  console.log("Navigation:", previousRoute?.name, "→", route.name);
});

API

Streams

state$(router, options?)

Creates a reactive stream of router state changes.
router: Router — router instance
options.signal?: AbortSignal — for automatic unsubscription
Returns: RxObservable<{ route: State, previousRoute?: State }>
Wiki

events$(router)

Creates a reactive stream of all router events.
router: Router — router instance
Returns: RxObservable<RouterEvent>
Wiki

observable(router)

Creates a TC39 Observable-compliant wrapper for RxJS interop.
router: Router — router instance
Returns: RxObservable<SubscribeState>
Wiki

Operators

map(project)

Transforms emitted values.
Wiki

filter(predicate)

Filters values based on a predicate.
Wiki

debounceTime(duration)

Delays emissions, emitting only the last value.
Wiki

distinctUntilChanged(comparator?)

Filters consecutive duplicate values.
Wiki

takeUntil(notifier)

Completes stream when notifier emits.
Wiki

Usage Examples

Operator Pipeline

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);
  });

Event Filtering

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

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

RxJS Interop

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 available on the Wiki:

• API Reference
• Operators
• Async Iteration
• Migration Guide

Related Packages

• @real-router/core — Core router
• @real-router/react — React integration
• @real-router/browser-plugin — Browser history

License

MIT © Oleg Ivanov