Abstract Class: RouterBridgeBase

API / @xmachines/play-router / index / RouterBridgeBase

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

A RouterBridge whose machine is mounted at a URL prefix that can MOVE while the bridge stays connected.

Every bridge on RouterBridgeBase satisfies this interface. The interface exists so that a provider component moves a live bridge instead of a teardown of it: a host route that renders again with a new prefix keeps the actor, the route map, and its LRU cache.

The mount that moves says WHERE an actor lives, and never WHICH actor lives there. An actor never changes identity, so a new identity is a new actor, and a new actor takes a new bridge.

Example

// The host moved this actor to another place in its URL space. `machineId` names
// WHICH document the actor runs, and it does not change: a new identity is a new
// actor, and therefore a new bridge, because one actor takes one bridge.
bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });

Extended by

Implements

MountableRouterBridge

Constructors

Constructor

new RouterBridgeBase(
   actor,
   routeMap,
   options?
): RouterBridgeBase;

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

Parameters

Parameter	Type	Description
`actor`	`RoutableActor`	A `RoutableActor`, with `currentRoute`, `initialRoute`, and `send`.
`routeMap`	{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; }	The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only.
`routeMap.getPathByStateId`	-
`routeMap.getStateIdByPath?`	-
`options?`	`RouterBridgeOptions`	-

Returns

RouterBridgeBase

Accessors

basePath

Get Signature

get basePath(): string;

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

The resolved URL prefix that the machine of this bridge is mounted under, or "" when the machine owns the complete router.

Returns

string

The resolved URL prefix of the mount, or "" when the machine owns the complete router.

Implementation of

MountableRouterBridge.basePath

basePathParams

Get Signature

get basePathParams(): Readonly<Record<string, string>>;

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

The resolved values of the :param segments of the mount, or {} for a prefix without a param.

These params belong to the HOST: the host wrote the prefix and resolved the values, and they describe the route of the host and not the route of the machine. They therefore travel in NO play.route event. The machine is authoritative over its own params, and event.params holds what the pattern of the machine declares, and nothing else.

They live here instead, because a value that reached the actor on a navigation ALONE would go stale: setBasePath() can move the mount while the machine stays on the same route, no event goes out, and event.params would then contradict basePath. A read of this accessor cannot go stale.

A machine that needs the identity of its host — a machineId, a tenant — takes it through the input of the actor, where it belongs: that identity decides WHICH machine runs, and it is not a param of a route inside the machine.

Example

bridge.basePath; // "/abc123/play"
bridge.basePathParams; // { machineId: "abc123" }

Returns

Readonly<Record<string, string>>

The resolved values of the :param segments of the mount, or {} for a prefix without a param.

These params belong to the HOST, so they travel in NO play.route event — the machine is authoritative over its own params. This accessor is therefore the one way a host reads them back, and it cannot go stale: setBasePath() can move the mount while the machine stays on the same route, and no event goes out.

Implementation of

MountableRouterBridge.basePathParams

Methods

connect()

connect(): void;

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

Connects the router bridge to the Actor.

The method installs the atom watcher of the direction from the actor to the router. It then starts the watch of the router changes, which each framework does in its own way.

The order of these steps is part of the contract of the bridge:

The constructor seeds lastActorRoute from actor.currentRoute, and it records no location
The method installs the actor watcher before the router subscriptions of the adapter
The first synchronization then separates a deep link from a restore, with actor.initialRoute

An adapter that needs a different behavior of the first synchronization overrides getInitialRouterPath(). It does not change the order of the steps of connect().

Returns

void

Implementation of

MountableRouterBridge.connect

disconnect()

disconnect(): void;

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

Disconnects the router bridge from the Actor.

The method stops the watch of the atom, and it removes the router listener of the framework.

Returns

void

Implementation of

MountableRouterBridge.disconnect

setBasePath()

setBasePath(basePath?, basePathParams?): void;

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

Moves the machine to a different mount point, while it stays connected.

This is the “load and unload” half of a shared router. It moves WHERE an actor is mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU cache all stay, and nothing goes away.

An actor never changes identity. A prefix that IDENTIFIES the actor — a machineId that names the document it runs — therefore never moves through this method: a new identity is a new actor, and a new actor takes a new bridge, because connect() permits one bridge for each actor. The segments that move here are the ones that LOCATE: a region, a locale, a tenant, a workspace slug.

The call then brings the location in step with the NEW prefix. A location inside the new mount runs the same first-synchronization decision as connect(): it drives the actor, and a restore keeps the route of the actor. A location OUTSIDE the new mount is the old mount in practice, so the bridge writes the new one itself, and it keeps the route of the actor while it does so — nothing else moves the address bar. A call that resolves to the current prefix changes no location, and it therefore reconciles nothing.

Parameters

Parameter	Type	Description
`basePath?`	`string`	The new prefix, as a pattern or as a concrete path. An absent value, `""`, and `"/"` all remove the prefix, and they give the machine the complete router again.
`basePathParams?`	`Record`<`string`, `string` \| `number`>	The values of the `:param` segments of `basePath`.

Returns

void

Throws

For a prefix that resolves to one concrete path never.

Throws

When a :param of the prefix has no value.

Example

// The host moved this actor to another place in its URL space. `machineId` names
// WHICH document the actor runs, and it does not change: a new identity is a new
// actor, and therefore a new bridge, because one actor takes one bridge.
bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });

Implementation of

MountableRouterBridge.setBasePath