Skip to content
XMachines

Function: createRouteMatcher()

API / @xmachines/play-router / createRouteMatcher

function createRouteMatcher(routeTree): RouteMatcher;

Defined in: create-route-matcher.ts:74

Create a URL pattern matcher from a RouteTree for efficient path lookups.

Architecture:

  • Pure function - no side effects
  • O(1) lookups for exact matches via Map
  • O(k) bucket-indexed pattern matching with URLPattern, where k = routes in the first-segment bucket (typically << total routes)
  • Returns formatted state IDs (with # prefix)
  • Extracts params from matched patterns

URLPattern requirement: Dynamic route pattern matching requires URLPattern to be available on globalThis. On Node.js < 24 and older browsers, load a polyfill before calling this function:

import "urlpattern-polyfill"; // before importing @xmachines/play-router

If URLPattern is unavailable, a URLPatternUnavailableError is thrown. Static (exact) routes are unaffected by URLPattern availability.

Usage:

const routeTree = extractMachineRoutes(machine);
const routeMatcher = createRouteMatcher(routeTree);


const { to, params } = routeMatcher.match("/settings/account");
if (to) {
  actor.send({ type: "play.route", to, params });
}

Parameters

ParameterType
routeTreeRouteTree

Returns

RouteMatcher