Interface: RouteMap

API / @xmachines/play-dom-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

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