Class: SvelteKitRouterBridge

API / @xmachines/play-sveltekit-router / SvelteKitRouterBridge

Defined in: play-sveltekit-router/src/sveltekit-router-bridge.ts:89

The SvelteKit router bridge — it connects the SvelteKit navigation to RouterBridgeBase.

It implements the three abstract methods:

navigateRouter → goto(path, { reset: false }) on SvelteKit 3, and goto(path, { noScroll: true, keepFocus: true }) on SvelteKit 2
watchRouterChanges → an afterNavigate() subscription through an indirection cell, which ignores a shallow navigation. With shallow: "sync", a watch of page of $app/state instead, which sees each shallow change too
unwatchRouterChanges → it sets the cell to null. This releases the bridge reference of the registered closure before the component unmounts. With shallow: "sync", it ends the watch

It overrides two optional hooks:

getInitialRouterPath → loc.pathname
getInitialRouterSearch → loc.search

The bridge inherits the restore-or-deeplink detection and the lastSyncedPath echo suppression from RouterBridgeBase.

Param

actor

A Routable actor.

Param

routeMap

The bidirectional route map.

Param

loc

The location-like object for the initial URL reads, and for each read of shallow: "sync". The default is globalThis.location. Give a mock in a test, or a stub in an SSR environment.

Param

options

The options of the base class, and shallow.

Extends

RouterBridgeBase

Constructors

Constructor

new SvelteKitRouterBridge(
   actor,
   routeMap,
   loc?,
   options?
): SvelteKitRouterBridge;

Defined in: play-sveltekit-router/src/sveltekit-router-bridge.ts:111

Parameters

Parameter	Type
`actor`	`RoutableActor`
`routeMap`	`RouteMap`
`loc`	`LocationLike` \| `null`
`options?`	`SvelteKitRouterBridgeOptions`

Returns

SvelteKitRouterBridge

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