Class: RouteMap

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

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

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

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

Build a route map from an array of state ID ↔ path mappings.

Static paths (no :param) are indexed in an O(1) Map. Parameterized paths are compiled to URLPattern and grouped into first-segment buckets for efficient candidate selection.

Parameters

Parameter	Type	Description
`mappings`	`RouteMapping`[]	Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.
`options`	{ `cacheSize?`: `number`; }	Optional configuration. `options.cacheSize`: Maximum number of resolved parameterized path lookups to cache. Defaults to `500`. Increase for applications with many unique parameterized URL values (e.g. user profile pages with thousands of distinct IDs). After eviction the path falls back to the O(k) bucket pattern scan — correct but slower. Minimum effective value is `1` (QuickLRU constraint).
`options.cacheSize?`	`number`	-

Returns

RouteMap

Methods

getPathByStateId()

getPathByStateId(stateId): string | null;

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

Look up the path pattern registered for a state ID.

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("missing"); // null

getStateIdByPath()

getStateIdByPath(path): string | null;

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

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