Class: BaseRouteMap

Documentation / @xmachines/play-router / BaseRouteMap

Shared bidirectional route map base class.

All framework adapter RouteMap classes extend this — 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 RegExp, where k is the number of routes sharing the same first path segment
Results are cached after the first match

Pattern syntax (:param / :param?):

:param — required segment, matches exactly one non-/ segment
:param? — optional segment, matches zero or one non-/ segment

Example

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

const map = new BaseRouteMap([
  { 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

Extended by

Constructors

Constructor

new BaseRouteMap(mappings): BaseRouteMap;

Defined in: base-route-map.ts:86

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 RegExp and grouped into first-segment buckets for efficient candidate selection.

Parameters

Parameter	Type	Description
`mappings`	`BaseRouteMapping`[]	Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.

Returns

BaseRouteMap

Methods

getPathByStateId()

getPathByStateId(stateId): string | null;

Defined in: base-route-map.ts:164

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: base-route-map.ts:130

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