Class: RouteMap

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

Constructors

Constructor

new RouteMap(mappings, options?): RouteMap;

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

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