Abstract Class: RouterBridgeBase
Documentation / @xmachines/play-router / RouterBridgeBase
Defined in: router-bridge-base.ts:56
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.
Extended by
Implements
Constructors
Constructor
new RouterBridgeBase(actor, routeMap): RouterBridgeBase;Defined in: router-bridge-base.ts:70
Constructor receives the 3 things all bridges need.
Parameters
| Parameter | Type | Description |
|---|---|---|
actor | AbstractActor<AnyActorLogic> & Routable | Actor with currentRoute signal and send method |
routeMap | { getPathByStateId: string | null | undefined; getStateIdByPath: string | null | undefined; } | Bidirectional route map for stateId ↔ path resolution |
routeMap.getPathByStateId | - | |
routeMap.getStateIdByPath | - |
Returns
RouterBridgeBase
Properties
| Property | Modifier | Type | Default value | Description | Defined in |
|---|---|---|---|---|---|
actor | readonly | AbstractActor<AnyActorLogic> & Routable | undefined | Actor with currentRoute signal and send method | router-bridge-base.ts:71 |
hasConnectedOnce | protected | boolean | false | - | router-bridge-base.ts:59 |
isConnected | protected | boolean | false | - | router-bridge-base.ts:58 |
isProcessingNavigation | protected | boolean | false | - | router-bridge-base.ts:61 |
lastSyncedPath | protected | string | "" | - | router-bridge-base.ts:60 |
routeMap | readonly | object | undefined | Bidirectional route map for stateId ↔ path resolution | router-bridge-base.ts:72 |
routeMap.getPathByStateId | public | string | null | undefined | undefined | - | router-bridge-base.ts:74 |
routeMap.getStateIdByPath | public | string | null | undefined | undefined | - | router-bridge-base.ts:73 |
routeWatcher | protected | | Watcher | null | null | - | router-bridge-base.ts:62 |
Methods
connect()
connect(): void;Defined in: router-bridge-base.ts:90
Connect the router bridge to the Actor.
Sets up the TC39 Signal watcher for actor → router direction and starts watching router changes (framework-specific).
Returns
void
Implementation of
disconnect()
disconnect(): void;Defined in: router-bridge-base.ts:140
Disconnect the router bridge from the Actor.
Stops signal watching and unregisters framework-specific router listener.
Returns
void
Implementation of
extractParams()
protected extractParams(pathname, stateId): Record<string, string>;Defined in: router-bridge-base.ts:276
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 (Node.js < 24, older browsers without a
polyfill), this method returns {} silently (graceful degradation — routing still
works, params will be empty).
Parameters
| Parameter | Type | Description |
|---|---|---|
pathname | string | The actual URL path (e.g., ‘/profile/john’) |
stateId | string | The matched state ID for looking up route pattern |
Returns
Record<string, string>
Extracted path parameters, or empty object if URLPattern is unavailable or no match
extractQuery()
protected extractQuery(search): Record<string, string>;Defined in: router-bridge-base.ts:303
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
getInitialRouterPath()
protected getInitialRouterPath(): string | null;Defined in: router-bridge-base.ts:353
Return the router’s current pathname at connect() time, or null if unavailable.
Called once during connect() to perform the initial URL → actor sync.
router.subscribe() only fires on future navigation events; it does not
replay the already-loaded location. Subclasses that can read the router’s
current location synchronously (e.g. router.state.location.pathname)
should override this method so that deep-link / direct-URL loads drive the
actor to the correct state instead of leaving it at its machine default.
The default returns null (no initial router → actor sync), preserving the previous behaviour for bridges that have not yet implemented this hook.
Returns
string | null
navigateRouter()
abstract protected navigateRouter(path): void;Defined in: router-bridge-base.ts:323
Navigate the framework router to the given path.
Called when actor’s currentRoute signal changes to a new path. Must trigger the framework router’s navigation (e.g., router.navigate(path)).
Parameters
| Parameter | Type |
|---|---|
path | string |
Returns
void
syncActorFromRouter()
protected syncActorFromRouter(pathname, search?): void;Defined in: router-bridge-base.ts:187
Sync actor state when router location changes.
Sends play.route event to actor with resolved stateId, params, and query. Prevents circular updates via isProcessingNavigation flag.
Parameters
| Parameter | Type |
|---|---|
pathname | string |
search? | string |
Returns
void
syncRouterFromActor()
protected syncRouterFromActor(route): void;Defined in: router-bridge-base.ts:167
Sync router location when actor route signal changes.
Calls navigateRouter() for framework-specific navigation. Prevents circular updates via isProcessingNavigation flag.
Parameters
| Parameter | Type |
|---|---|
route | unknown |
Returns
void
unwatchRouterChanges()
abstract protected unwatchRouterChanges(): void;Defined in: router-bridge-base.ts:338
Stop watching for router location changes.
Called by disconnect(). Should clean up the framework-specific subscription.
Returns
void
watchRouterChanges()
abstract protected watchRouterChanges(): void;Defined in: router-bridge-base.ts:331
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.
Returns
void