Interface: RouterBridge

Documentation / @xmachines/play-router / RouterBridge

RouterBridge interface for runtime infrastructure adapters

Defines the lifecycle connection between Infrastructure (e.g., TanStack Router) and the Actor. Infrastructure “bridges” to the Actor by observing its signals and managing its own lifecycle accordingly.

Architectural Context: Implements Passive Infrastructure (INV-04) by establishing a unidirectional observation pattern. Infrastructure connects to observe Actor signals (currentRoute, currentView, state) and reflects changes without making state decisions.

Example

TanStack Router bridge implementation

import type { RouterBridge } from "@xmachines/play-router";
import { Signal } from "@xmachines/play-signals";

class TanStackRouterBridge implements RouterBridge {
  private watcher: Signal.Watcher | null = null;

  async connect(): Promise<void> {
    // Start observing actor.currentRoute signal
    this.watcher = new Signal.subtle.Watcher(() => {
      const route = actor.currentRoute.get();
      if (route) router.navigate(route);
    });
    this.watcher.watch(actor.currentRoute);
  }

  async disconnect(): Promise<void> {
    // Stop observing, cleanup watchers
    this.watcher?.unwatch(actor.currentRoute);
    this.watcher = null;
  }
}

See

RFC Play v1 - Invariant INV-04

Methods

connect()

connect(): void | Promise<void>;

Defined in: types.ts:254

Connect the router bridge to the Actor

Called when Infrastructure should begin observing Actor signals and synchronizing its state (e.g., browser URL) with Actor state.

Returns

void | Promise<void>

Promise that resolves when connection is established, or void for synchronous connection

Example

const bridge: RouterBridge = createBridge(actor, router);
await bridge.connect();
// Bridge now observing actor.currentRoute signal

disconnect()

disconnect(): void | Promise<void>;

Defined in: types.ts:270

Disconnect the router bridge from the Actor

Called when Infrastructure should stop observing and clean up resources (e.g., signal watchers, event listeners).

Returns

void | Promise<void>

Promise that resolves when disconnection is complete, or void for synchronous disconnection

Example

await bridge.disconnect();
// Bridge stopped observing, resources cleaned up