Class: RouteMap

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

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

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 cache holds between 500 and 1000 entries, and the pathCache constructor option replaces it

The syntax of a pattern: the whole URLPattern pathname grammar. The forms used most often are:

: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

A {…} group, a :param(\d+) constraint, a + modifier and a \: escape are read too. The routing guide states every form, the prefix rule, and the one divergence from the standard: a param name of this library can hold a hyphen.

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

Constructors

Constructor

new RouteMap(mappings, options?): RouteMap;

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

Builds a route map from an array of the mappings between a state ID and a path.

The constructor puts each static path, which holds no :param, into a Map for a lookup in O(1). It compiles each parameterized path to a URLPattern, and it groups the patterns into the buckets of the first segment. The selection of the candidates is therefore efficient.

Parameters

Parameter	Type	Description
`mappings`	`RouteMapping`[]	The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.
`options`	`RouteMapOptions`	See RouteMapOptions. A map holds TWO caches, so no option is named `cache`: each one names the cache that it carries.

Returns

RouteMap

Methods

getPathByStateId()

getPathByStateId(stateId): string | null;

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

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

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