Class: ReactRouterBridge

API / @xmachines/play-react-router / ReactRouterBridge

Defined in: play-react-router/src/react-router-bridge.ts:27

Abstract base class for all @xmachines router adapter bridges.

Implements RouterBridge protocol and contains all common bridge logic. Subclasses only need to implement the 3 abstract methods that differ between frameworks.

Extends

RouterBridgeBase

Constructors

Constructor

new ReactRouterBridge(
   router,
   actor,
   routeMap): ReactRouterBridge;

Defined in: play-react-router/src/react-router-bridge.ts:30

Parameters

Parameter	Type
`router`	`Router`
`actor`	`RoutableActor`
`routeMap`	`RouteMap`

Returns

ReactRouterBridge

Overrides

RouterBridgeBase.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
`actor`	`readonly`	`RoutableActor`	`undefined`	A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.	`RouterBridgeBase`.`actor`	play-router/src/router-bridge-base.ts:125
`hasConnectedOnce`	`protected`	`boolean`	`false`	-	`RouterBridgeBase`.`hasConnectedOnce`	play-router/src/router-bridge-base.ts:103
`isConnected`	`protected`	`boolean`	`false`	-	`RouterBridgeBase`.`isConnected`	play-router/src/router-bridge-base.ts:102
`isProcessingNavigation`	`protected`	`boolean`	`false`	Guards `syncActorFromRouter` against re-entrant calls triggered by the actor’s own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`.	`RouterBridgeBase`.`isProcessingNavigation`	play-router/src/router-bridge-base.ts:115
`lastSyncedPath`	`protected`	`string` \| `null`	`null`	-	`RouterBridgeBase`.`lastSyncedPath`	play-router/src/router-bridge-base.ts:104
`routeMap`	`readonly`	`object`	`undefined`	Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent.	`RouterBridgeBase`.`routeMap`	play-router/src/router-bridge-base.ts:126
`routeMap.getPathByStateId`	`public`	`string` \| `null` \| `undefined`	`undefined`	-	-	play-router/src/router-bridge-base.ts:128
`routeMap.getStateIdByPath`	`public`	`string` \| `null` \| `undefined`	`undefined`	-	-	play-router/src/router-bridge-base.ts:127
`routeWatcher`	`protected`	\| `RouteWatcherHandle` \| `null`	`null`	-	`RouterBridgeBase`.`routeWatcher`	play-router/src/router-bridge-base.ts:116

Methods

connect()

connect(): void;

Defined in: play-router/src/router-bridge-base.ts:152

Connect the router bridge to the Actor.

Sets up the TC39 Signal watcher for actor → router direction and starts watching router changes (framework-specific).

Ordering here is part of the bridge contract:

lastSyncedPath is seeded in the constructor from actor.currentRoute
the actor watcher is installed before adapter router subscriptions
initial sync then resolves deep-link vs restore using actor.initialRoute

Adapters that need custom initial-sync behavior should override getInitialRouterPath() rather than reordering connect() steps.

Returns

void

Inherited from

RouterBridgeBase.connect

disconnect()

disconnect(): void;

Defined in: play-router/src/router-bridge-base.ts:248

Disconnect the router bridge from the Actor.

Stops signal watching and unregisters framework-specific router listener.

Returns

void

Inherited from

RouterBridgeBase.disconnect

extractParams()

protected extractParams(pathname, stateId): Record<string, string>;

Defined in: play-router/src/router-bridge-base.ts:402

Extract path parameters from URL using the URLPattern API.

Accesses globalThis.URLPattern at runtime — no polyfill is imported by this library. If URLPattern is unavailable and the matched route has parameterized segments, a URLPatternUnavailableError is thrown — callers must provide a polyfill for environments without native URLPattern support (Node.js < 24, older browsers).

Parameters

Parameter	Type	Description
`pathname`	`string`	The actual URL path (e.g., ‘/profile/john’)
`stateId`	`string`	The matched state ID for looking up the route pattern

Returns

Record<string, string>

Extracted path parameters, or empty object if no match

Throws

When URLPattern is absent and the route is parameterized

Inherited from

RouterBridgeBase.extractParams

extractQuery()

protected extractQuery(search): Record<string, string>;

Defined in: play-router/src/router-bridge-base.ts:439

Extract query parameters from URL search string.

Parameters

Parameter	Type	Description
`search`	`string`	URL search string (e.g., ‘?tab=security&page=1’)

Returns

Record<string, string>

Extracted query parameters or empty object

Inherited from

RouterBridgeBase.extractQuery

getInitialRouterPath()

protected getInitialRouterPath(): string | null;

Defined in: play-react-router/src/react-router-bridge.ts:48

Return the router’s current pathname so connect() can sync the actor to the URL on initial load. router.subscribe() only fires on future navigations — it does not replay the already-loaded location — so without this, loading the page on /about would leave the actor in its default “home” state.

Returns

string | null

Overrides

RouterBridgeBase.getInitialRouterPath

getInitialRouterSearch()

protected getInitialRouterSearch(): string | undefined;

Defined in: play-react-router/src/react-router-bridge.ts:59

Return the initial URL search string for query-param forwarding on connect().

Reads from router.state.location.search — the same source used by getInitialRouterPath(). An empty string (no query params) returns undefined so syncActorFromRouter produces query: {} rather than parsing an empty string.

Returns

string | undefined

Overrides

RouterBridgeBase.getInitialRouterSearch

navigateRouter()

protected navigateRouter(path): void;

Defined in: play-react-router/src/react-router-bridge.ts:38

Must trigger the framework router’s navigation (e.g., router.navigate(path)).

Parameters

Parameter	Type
`path`	`string`

Returns

void

Overrides

RouterBridgeBase.navigateRouter

resolveNavigationPath()

protected resolveNavigationPath(route): string | null;

Defined in: play-router/src/router-bridge-base.ts:424

Resolve an actor route value to a concrete URL path for navigation.

Bridges that receive raw actor.currentRoute values in navigateRouter can call this to normalize stateIds (with or without # prefix) to paths. Returns null when navigation is not possible:

unknown stateId with no route map entry
parameterized pattern (e.g. /profile/:id) — no concrete values available
non-path string that isn’t a known stateId

Route maps may store stateIds with or without the # prefix; both forms are tried automatically.

Parameters

Parameter	Type	Description
`route`	`string`	Raw actor route value (stateId, `#`-stateId, or concrete path)

Returns

string | null

Concrete URL path, or null if navigation should be skipped

Inherited from

RouterBridgeBase.resolveNavigationPath

sanitizePath()

protected sanitizePath(pathname): string | null;

Defined in: play-router/src/router-bridge-base.ts:466

Sanitize and validate a raw URL pathname received from the router.

Applies the path-length cap (2048 chars), strips query strings and fragments that may have been included in the pathname segment, and normalises consecutive slashes.

Implementations that bypass syncActorFromRouter() (e.g. when using framework-native reactive watchers that receive pre-parsed route objects) MUST call this method before passing the path to any route-map lookup. syncActorFromRouter() calls this internally, so bridges that delegate to it do not need to call sanitizePath themselves.

Parameters

Parameter	Type	Description
`pathname`	`string`	Raw URL pathname from the framework router.

Returns

string | null

Sanitized pathname, or null if the path is invalid / too long.

Inherited from

RouterBridgeBase.sanitizePath

syncActorFromRouter()

protected syncActorFromRouter(pathname, search?): void;

Defined in: play-router/src/router-bridge-base.ts:324

Sync actor state when router location changes.

Known path: sends a play.route event to the actor with the matched stateId, params, and query. Prevents circular updates via the isProcessingNavigation flag.

Unknown/unmapped path: does NOT send a play.route event (actor state is unchanged). Instead, actively corrects the browser URL by calling navigateRouter(actor.currentRoute.get()) — keeping the URL in sync with actor state even when the user types an invalid path into the address bar or pushes one programmatically mid-session. lastSyncedPath is set to the resolved concrete path before calling navigateRouter so the router’s own callback for that navigation short-circuits the echo-suppression guard and sends no spurious event.

Parameters

Parameter	Type
`pathname`	`string`
`search?`	`string`

Returns

void

Inherited from

RouterBridgeBase.syncActorFromRouter

syncRouterFromActor()

protected syncRouterFromActor(route): void;

Defined in: play-router/src/router-bridge-base.ts:289

Sync router location when actor route signal changes.

Calls navigateRouter() for framework-specific navigation.

Echo suppression — preventing the router’s own callback from re-driving the actor — is handled entirely by lastSyncedPath: it is set to route before navigateRouter() is called, so any syncActorFromRouter invocation for the same path short-circuits at the sanitized === lastSyncedPath check and sends no event regardless of whether the callback fires synchronously or asynchronously.

isProcessingNavigation is NOT set here — it is only used inside syncActorFromRouter to guard against re-entrant guard-redirect loops.

Parameters

Parameter	Type
`route`	`unknown`

Returns

void

Inherited from

RouterBridgeBase.syncRouterFromActor

unwatchRouterChanges()

protected unwatchRouterChanges(): void;

Defined in: play-react-router/src/react-router-bridge.ts:69

Stop watching for router location changes.

Called by disconnect(). Should clean up the framework-specific subscription.

Returns

void

Overrides

RouterBridgeBase.unwatchRouterChanges

watchRouterChanges()

protected watchRouterChanges(): void;

Defined in: play-react-router/src/react-router-bridge.ts:63

Start watching for router location changes.

Called by connect(). Should set up the framework-specific subscription for location changes and call syncActorFromRouter() on each change.

Implementations that call syncActorFromRouter get path sanitization applied automatically — no extra work needed.

Implementations that bypass syncActorFromRouter (e.g. VueRouterBridge, which builds the play.route event directly from framework-native route params) MUST call this.sanitizePath(path) and return early when it returns null. Skipping this allows oversized or malformed paths through without the length and content guards that protect the route-map lookup.

Returns

void

Overrides

RouterBridgeBase.watchRouterChanges