Interface: RouteMap

API / @xmachines/play-dom-router / RouteMap

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

Shared bidirectional route map base class.

All framework adapters use this class as their route map — they add no logic of their own and inherit the full public API from here.

Lookup strategy:

• Static paths (no :param) → O(1) Map lookup
• Dynamic paths → O(k) bucket-indexed scan using URLPattern, where k is the number of routes sharing the same first path segment
• Results are cached after the first match in an LRU cache (default 500 entries, configurable via the cacheSize constructor option)

Pattern syntax (:param / :param? / *):

• :param — required segment, matches exactly one non-/ segment
• :param? — optional segment, matches zero or one non-/ segment
• * — wildcard, matches any number of segments (URLPattern semantics)

StateId forms: stateIds may be registered and looked up in either "#stateId" or "stateId" form — RouteMap canonicalizes internally. getStateIdByPath returns the stateId exactly as registered; getPathByStateId accepts both forms. Registering the same stateId in both forms refers to one entry (the later registration wins for reverse lookup).

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:218

Look up the path pattern registered for a state ID.

Accepts the stateId in either "#stateId" or "stateId" form regardless of which form was used at registration — lookups are canonicalized internally, so consumers never need to try both forms.

Parameters

Parameter	Type	Description
stateId	string	State machine state ID (e.g., "profile", "#settings")

Returns

string | null

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

Example

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

---

getStateIdByPath()

getStateIdByPath(path): string | null;

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

Resolve a URL path to its mapped state ID.

Strips query strings and hash fragments before matching. Tries an O(1) exact lookup first, then falls back to bucket-indexed pattern matching. Results are cached after the first pattern match.

Parameters

Parameter	Type	Description
path	string	URL pathname, optionally including query/hash (e.g., "/profile/123?ref=nav")

Returns

string | null

The mapped state ID, or null if no route matches

Example

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