Class: RouteMap

API / @xmachines/play-svelte-spa-router / RouteMap

Defined in: play-router/src/base-route-map.ts:105

The shared base class of the route map for both directions.

Every framework adapter uses this class as its route map. An adapter adds no logic of its own, and it inherits the complete public API from here.

The strategy of a lookup:

• A static path, without a :param → a Map lookup in O(1)
• A dynamic path → a scan of the bucket index in O(k), with URLPattern, where k is the number of the routes with the same first path segment
• The class keeps each result of a first match in an LRU cache. The default size is 500 entries, and the cacheSize constructor option changes it

The syntax of a pattern (:param, :param?, and *):

• :param — a necessary segment. It matches exactly one segment without a /
• :param? — an optional segment. It matches zero segments or one segment without a /
• * — a wildcard. It matches each number of segments, as URLPattern defines

The forms of a stateId: you can register a stateId, and you can look one up, in the form "#stateId" or in the form "stateId". RouteMap makes the canonical form itself. getStateIdByPath returns the stateId exactly as you registered it, and getPathByStateId accepts both forms. A registration of the same stateId in both forms gives one entry, and the later registration wins for the lookup in the other direction.

Example

import { RouteMap } from "@xmachines/play-router";

const map = new RouteMap([
  { stateId: "home", path: "/" },
  { stateId: "profile", path: "/profile/:userId" },
  { stateId: "settings", path: "/settings/:section?" },
]);

map.getStateIdByPath("/"); // "home"
map.getStateIdByPath("/profile/123"); // "profile"
map.getStateIdByPath("/settings"); // "settings"
map.getStateIdByPath("/unknown"); // null

map.getPathByStateId("profile"); // "/profile/:userId"
map.getPathByStateId("missing"); // null

Constructors

Constructor

new RouteMap(mappings, options?): RouteMap;

Defined in: play-router/src/base-route-map.ts:133

Builds a route map from an array of the mappings between a state ID and a path.

The constructor puts each static path, which holds no :param, into a Map for a lookup in O(1). It compiles each parameterized path to a URLPattern, and it groups the patterns into the buckets of the first segment. The selection of the candidates is therefore efficient.

Parameters

Parameter	Type	Description
mappings	RouteMapping[]	The array of the { stateId, path } entries. The order gives the priority when more than one pattern can match the same path.
options	{ cacheSize?: number; }	The optional configuration. options.cacheSize: the maximum number of the resolved parameterized path lookups in the cache. The default is 500. Raise it for an application with many different values in a parameterized URL, for example a page of a user profile with thousands of different IDs. After an eviction, the path goes to the bucket pattern scan in O(k) again, which is correct but slower. The smallest effective value is 1, because QuickLRU requires it.
options.cacheSize?	number	-

Returns

RouteMap

Methods

getPathByStateId()

getPathByStateId(stateId): string | null;

Defined in: play-router/src/base-route-map.ts:225

Returns the path pattern of a state ID.

The method accepts the stateId in the form "#stateId" and in the form "stateId", and the form of the registration has no effect. The method makes the canonical form itself. Therefore a consumer tries never both forms.

Parameters

Parameter	Type	Description
stateId	string	The state ID of the state machine, for example "profile" or "#settings"

Returns

string | null

The registered path pattern, or null when the state ID is unknown

Example

map.getPathByStateId("profile"); // "/profile/:userId"
map.getPathByStateId("#profile"); // "/profile/:userId" — the same entry
map.getPathByStateId("missing"); // null

---

getStateIdByPath()

getStateIdByPath(path): string | null;

Defined in: play-router/src/base-route-map.ts:185

Resolves a URL path to its state ID.

The method removes the query string and the hash fragment before the match. It tries an exact lookup in O(1) first, then it uses the pattern match on the bucket index. It keeps each result of a first pattern match in the cache.

Parameters

Parameter	Type	Description
path	string	The URL pathname. It can hold a query and a hash, for example "/profile/123?ref=nav"

Returns

string | null

The state ID of the path, or null when no route matches

Example

map.getStateIdByPath("/profile/123"); // "profile"
map.getStateIdByPath("/unknown"); // null