Class: SolidRouterBridge

API / @xmachines/play-solid-router / SolidRouterBridge

Defined in: play-solid-router/src/solid-router-bridge.ts:73

The SolidJS Router integration bridge. It extends RouterBridgeBase

The class implements the RouterBridge protocol for SolidJS Router with the reactive primitives of Solid. The actor-to-router direction uses the atom watcher of the base class. The router-to-actor direction uses the Solid createEffect function for a native reactivity.

The bridge prefers the values of the reactive useParams() proxy of Solid, so a parameterized route reaches URLPattern for its params never while Solid answers for it. Two cases still reach it: a bridge under a basePath, where Solid matched a route of the HOST and its params describe the route of the machine never, and a location that fills a segment of the pattern while Solid reports none of its names.

This is about the CALLS that a navigation makes, and not about the availability of the API. @xmachines/play-url carries urlpattern-polyfill as an ordinary dependency and it uses the native URLPattern when the runtime has one, so the API is present whatever this bridge does. A BAD pattern is a question of the route map: RouteMap compiles each parameterized route in its constructor and throws an InvalidRoutePatternError there. See the extractParams override of this class.

Extends

RouterBridgeBase

Constructors

Constructor

new SolidRouterBridge(
   solidNavigate,
   location,
   params,
   actor,
   routeMap,
   options?
): SolidRouterBridge;

Defined in: play-solid-router/src/solid-router-bridge.ts:96

Creates a SolidJS Router bridge

CRITICAL: call connect() inside a Solid component, where the hooks are available.

Parameters

Parameter	Type	Description
`solidNavigate`	`Navigator`	The result of the useNavigate() hook
`location`	`LocationLike`	The result of the useLocation() hook
`params`	`Params`	The result of the useParams() hook. The bridge reads each path parameter directly from it. A parameterized route therefore runs no URLPattern match of its own
`actor`	`RoutableActor`	The XMachines actor instance
`routeMap`	`RouteMap`	The bidirectional map between the state IDs and the paths
`options?`	`RouterBridgeOptions`	-

Returns

SolidRouterBridge

Overrides

RouterBridgeBase.constructor

Accessors

basePath

Get Signature

get basePath(): string;

Defined in: 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.

Inherited from

RouterBridgeBase.basePath

basePathParams

Get Signature

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

Defined in: 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.

Inherited from

RouterBridgeBase.basePathParams

Methods

connect()

connect(): void;

Defined in: 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

Inherited from

RouterBridgeBase.connect

disconnect()

disconnect(): void;

Defined in: 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

Inherited from

RouterBridgeBase.disconnect

setBasePath()

setBasePath(basePath?, basePathParams?): void;

Defined in: 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 });

Inherited from

RouterBridgeBase.setBasePath