@xmachines/play-router 2.0.0 → 2.1.0

package/dist/base-route-map.js

@@ -1,51 +1,54 @@
 /**
- * RouteMap — Shared bidirectional route mapping base class
+ * RouteMap — the shared base class of the route map for both directions
  *
- * Provides bucket-based pattern matching shared across all framework adapters.
- * Adapters extend this class rather than duplicating the pattern-match logic.
+ * The class gives you the pattern match on buckets, and every framework adapter
+ * uses it. An adapter extends this class, and it therefore holds no copy of the
+ * pattern match logic.
  *
- * Algorithm: O(1) exact match via Map, then bucket-based O(k) pattern match
- * where k = routes in the first-segment bucket (typically << total routes).
- * Uses URLPattern for parameterized route matching.
+ * The algorithm: an exact match in O(1) through a Map, then a pattern match on the
+ * buckets in O(k), where k is the number of the routes in the bucket of the first
+ * segment, and that number is much smaller than the number of all the routes. The
+ * class matches a parameterized route with URLPattern.
  */
 import QuickLRU from "quick-lru";
 import { getURLPatternCtor, getCompiledPattern, getIndexKey, getCandidates, isParameterizedPattern, } from "./url-pattern-utils.js";
 import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
 /**
- * Canonical stateId key: the bare form with any leading `#` stripped.
+ * The canonical key of a stateId: the bare form, without a `#` at its start.
  *
- * `RouteMap` accepts stateIds in both `"#stateId"` and `"stateId"` form on insert
- * and on lookup. Internally every stateId is keyed on this canonical bare form so
- * consumers never need to re-implement dual-form handling. The *registered* form
- * is preserved and returned by `getStateIdByPath` so the map is transparent about
- * how routes were declared.
+ * `RouteMap` accepts a stateId in the form `"#stateId"` and in the form `"stateId"`,
+ * on an insert and on a lookup. Inside the class, the key of every stateId is this
+ * canonical bare form. Therefore a consumer writes no handler of the two forms. The
+ * class keeps the *registered* form, and `getStateIdByPath` returns it. The map is
+ * therefore honest about the declaration of each route.
  */
 function canonicalStateIdKey(stateId) {
     return stateId.startsWith("#") ? stateId.slice(1) : stateId;
 }
 /**
- * Shared bidirectional route map base class.
+ * The shared base class of the route map for both directions.
  *
- * 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.
+ * 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.
  *
- * **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)
+ * **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 size
+ *   is 500 entries, and the `cacheSize` constructor option changes it
  *
- * **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)
+ * **The syntax of a pattern** (`:param`, `:param?`, and `*`):
+ * - `: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
  *
- * **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).
+ * **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
  * ```typescript
@@ -67,26 +70,28 @@ function canonicalStateIdKey(stateId) {
  * ```
  */
 export class RouteMap {
-    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
+    /** The key is the canonical stateId form, which is bare and without a `#`. */
     stateIdToPath;
     pathToStateId;
     patternBuckets;
     pathMatchCache;
     /**
-     * Build a route map from an array of state ID ↔ path mappings.
+     * Builds a route map from an array of the mappings between a state ID and a path.
      *
-     * 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.
+     * 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.
      *
-     * @param mappings - Array of `{ stateId, path }` entries. Order determines
-     *   priority when multiple patterns could match the same path.
-     * @param options - 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).
+     * @param mappings - The array of the `{ stateId, path }` entries. The order gives the
+     *   priority when more than one pattern can match the same path.
+     * @param options - The optional configuration.
+     *   `options.cacheSize`: the maximum number of the resolved parameterized path
+     *   lookups in the cache. The default is `500`. Raise it for an application with
+     *   many different values in a parameterized URL, for example a page of a user
+     *   profile with thousands of different IDs. After an eviction, the path goes to the
+     *   bucket pattern scan in O(k) again, which is correct but slower. The smallest
+     *   effective value is `1`, because QuickLRU requires it.
      */
     constructor(mappings, { cacheSize = 500 } = {}) {
         this.stateIdToPath = new Map();
@@ -95,8 +100,9 @@ export class RouteMap {
         this.pathMatchCache = new QuickLRU({ maxSize: Math.max(1, cacheSize) });
         let patternOrder = 0;
         for (const { stateId, path } of mappings) {
-            // Key on the canonical (bare) form so getPathByStateId accepts both
-            // "#stateId" and "stateId". The registered form is kept for returns.
+            // The key is the canonical bare form. Therefore getPathByStateId accepts
+            // "#stateId" and also "stateId". The map keeps the registered form for its return
+            // values.
             this.stateIdToPath.set(canonicalStateIdKey(stateId), path);
             if (isParameterizedPattern(path)) {
                 const URLPatternCtorFn = getURLPatternCtor();
@@ -123,14 +129,14 @@ export class RouteMap {
         }
     }
     /**
-     * Resolve a URL path to its mapped state ID.
+     * Resolves a URL path to its 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.
+     * 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.
      *
-     * @param path - URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`)
-     * @returns The mapped state ID, or `null` if no route matches
+     * @param path - The URL pathname. It can hold a query and a hash, for example `"/profile/123?ref=nav"`
+     * @returns The state ID of the path, or `null` when no route matches
      *
      * @example
      * ```typescript
@@ -139,7 +145,7 @@ export class RouteMap {
      * ```
      */
     getStateIdByPath(path) {
-        // Strip query string and hash fragment for matching
+        // Remove the query string and the hash fragment before the match
         const cleanPath = path.split("?")[0].split("#")[0];
         const exactMatch = this.pathToStateId.get(cleanPath);
         if (exactMatch !== undefined)
@@ -159,19 +165,19 @@ export class RouteMap {
         return null;
     }
     /**
-     * Look up the path pattern registered for a state ID.
+     * Returns the path pattern of 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.
+     * 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.
      *
-     * @param stateId - State machine state ID (e.g., `"profile"`, `"#settings"`)
-     * @returns The registered path pattern, or `null` if the state ID is unknown
+     * @param stateId - The state ID of the state machine, for example `"profile"` or `"#settings"`
+     * @returns The registered path pattern, or `null` when the state ID is unknown
      *
      * @example
      * ```typescript
      * map.getPathByStateId("profile");   // "/profile/:userId"
-     * map.getPathByStateId("#profile");  // "/profile/:userId" (same entry)
+     * map.getPathByStateId("#profile");  // "/profile/:userId" — the same entry
      * map.getPathByStateId("missing");   // null
      * ```
      */

package/dist/base-route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-route-map.js","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-route-map.js","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"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"}

package/dist/build-tree.d.ts

@@ -1,20 +1,21 @@
 import type { RouteInfo, RouteTree } from "./types.js";
 /**
- * Build hierarchical route tree from flat route list
+ * Builds the hierarchical route tree from the flat list of the routes
  *
- * Constructs nested tree respecting parent-child state relationships.
- * Absolute routes become top-level, relative routes nest under parents.
- * Creates bidirectional maps for state ID ↔ path lookup.
+ * The function makes a nested tree, and it keeps the parent-child relation of the
+ * states. An absolute route becomes a route of the top level, and a relative route
+ * goes below its parent. The function also makes the maps of both directions, for
+ * the lookup between a state ID and a path.
  *
- * Duplicate detection runs here — after relative routes are resolved against
- * their parent's full path — so two relative routes with the same raw string
- * under different parents are valid, while distinct raw strings that resolve to
- * the same full path (which would silently overwrite each other in `byPath`)
- * are rejected.
+ * The detection of a duplicate runs here, after the function resolved each relative
+ * route against the complete path of its parent. Therefore two relative routes with
+ * the same raw string below two different parents are valid, and two different raw
+ * strings that resolve to the same complete path are not: those two overwrite each
+ * other in `byPath` in silence.
  *
- * @param routes - Flat list of RouteInfo from extraction
- * @returns RouteTree with root, byStateId map, and byPath map
- * @throws {DuplicateRoutePathError} If two states resolve to the same full path
+ * @param routes - The flat list of the RouteInfo objects, from the extraction
+ * @returns The RouteTree, with its root, its byStateId map, and its byPath map
+ * @throws {DuplicateRoutePathError} When two states resolve to the same complete path
  */
 export declare const buildRouteTree: (routes: RouteInfo[]) => RouteTree;
 //# sourceMappingURL=build-tree.d.ts.map

package/dist/build-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4B,SAAS,EAAE,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,KAAG,SAwEpD,CAAC"}
+{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4B,SAAS,EAAE,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,KAAG,SAyEpD,CAAC"}

package/dist/build-tree.js

@@ -1,45 +1,47 @@
 import { detectDuplicateRoutes } from "./validate-routes.js";
 /**
- * Build hierarchical route tree from flat route list
+ * Builds the hierarchical route tree from the flat list of the routes
  *
- * Constructs nested tree respecting parent-child state relationships.
- * Absolute routes become top-level, relative routes nest under parents.
- * Creates bidirectional maps for state ID ↔ path lookup.
+ * The function makes a nested tree, and it keeps the parent-child relation of the
+ * states. An absolute route becomes a route of the top level, and a relative route
+ * goes below its parent. The function also makes the maps of both directions, for
+ * the lookup between a state ID and a path.
  *
- * Duplicate detection runs here — after relative routes are resolved against
- * their parent's full path — so two relative routes with the same raw string
- * under different parents are valid, while distinct raw strings that resolve to
- * the same full path (which would silently overwrite each other in `byPath`)
- * are rejected.
+ * The detection of a duplicate runs here, after the function resolved each relative
+ * route against the complete path of its parent. Therefore two relative routes with
+ * the same raw string below two different parents are valid, and two different raw
+ * strings that resolve to the same complete path are not: those two overwrite each
+ * other in `byPath` in silence.
  *
- * @param routes - Flat list of RouteInfo from extraction
- * @returns RouteTree with root, byStateId map, and byPath map
- * @throws {DuplicateRoutePathError} If two states resolve to the same full path
+ * @param routes - The flat list of the RouteInfo objects, from the extraction
+ * @returns The RouteTree, with its root, its byStateId map, and its byPath map
+ * @throws {DuplicateRoutePathError} When two states resolve to the same complete path
  */
 export const buildRouteTree = (routes) => {
-    // 1. Create root node
+    // 1. Create the root node
     const root = {
         id: "__root__",
         path: "/",
         fullPath: "/",
         stateId: "__root__",
-        routable: false, // Root is not a routable state
+        routable: false, // The root is a state without a route
         children: [],
         parent: null,
-        metadata: "", // Synthetic non-routable root — no real route metadata
+        metadata: "", // The synthetic root has no route, and therefore no real route metadata
     };
-    // 2. Initialize maps
+    // 2. Initialize the maps
     const byStateId = new Map([[root.stateId, root]]);
     const byPath = new Map([[root.fullPath, root]]);
-    // 3. Sort routes by depth (shallowest first for proper parent linking)
+    // 3. Sort the routes by their depth. The shallowest route comes first, for the link to each parent
     // oxlint-disable-next-line unicorn/no-array-sort
     const sorted = routes.slice().sort((a, b) => a.statePath.length - b.statePath.length);
-    // 4. Build tree, collecting inserted nodes for resolved-path duplicate detection
+    // 4. Build the tree, and collect each node for the detection of a duplicate resolved path
     const insertedNodes = [];
     for (const route of sorted) {
-        // Find parent by walking up state path.
-        // Each entry in statePath is a full dotted stateId (e.g., "chain.app.section"),
-        // so we check each ancestor stateId directly from the end of the list.
+        // Find the parent, and walk up the state path.
+        // Each entry of statePath is a complete dotted stateId, for example
+        // "chain.app.section". Therefore the code tests each ancestor stateId directly,
+        // from the end of the list.
         let parentNode = root;
         for (let i = route.statePath.length - 2; i >= 0; i--) {
             const parentStateId = route.statePath[i]; // nosemgrep: gitlab.eslint.detect-object-injection
@@ -48,11 +50,11 @@ export const buildRouteTree = (routes) => {
                 break;
             }
         }
-        // Build full path
+        // Build the complete path
         const fullPath = route.isAbsolute
             ? route.routePath
             : `${parentNode.fullPath}/${route.routePath}`.replace(/\/+/g, "/");
-        // Create node
+        // Create the node
         const node = {
             id: route.stateId,
             path: route.routePath,
@@ -63,19 +65,19 @@ export const buildRouteTree = (routes) => {
             parent: parentNode,
             metadata: route.metadata,
         };
-        // Add pattern if it exists
+        // Add the pattern, when one is present
         if (route.pattern) {
             node.pattern = route.pattern;
         }
-        // Link to parent
+        // Link the node to its parent
         parentNode.children.push(node);
-        // Add to maps for bidirectional lookup
+        // Put the node in the maps, for the lookup in both directions
         byStateId.set(node.stateId, node);
         byPath.set(node.fullPath, node);
         insertedNodes.push(node);
     }
-    // 5. Reject resolved full-path collisions — a silent byPath overwrite would
-    // leave one state unreachable by URL.
+    // 5. Refuse a collision of two resolved complete paths. A silent overwrite in
+    // byPath leaves one state without a URL.
     detectDuplicateRoutes(insertedNodes);
     return { root, byStateId, byPath };
 };

package/dist/build-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"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"}

package/dist/create-route-map-from-tree.d.ts

@@ -2,31 +2,31 @@ import type { RouteTree } from "./types.js";
 import { RouteMap } from "./base-route-map.js";
 import type { RouteMapOptions } from "./create-route-map.js";
 /**
- * Create a `RouteMap` from a `RouteTree` node structure.
+ * Creates a `RouteMap` from the node structure of a `RouteTree`.
  *
- * Used by framework-router adapters that pass a
- * `RouteTree` produced by `extractMachineRoutes()` rather than calling
- * `createRouteMap()` directly.
+ * A framework router adapter uses this function when it gives a `RouteTree` from
+ * `extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
  *
- * Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
- * `node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
- * which is what `RouteMap` needs for browser URL matching. This matches the
- * behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
+ * The function walks every node, and it collects the pairs
+ * `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
+ * absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` needs
+ * that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
+ * same way, because it also uses `node.fullPath`.
  *
- * @param routeTree - A `RouteTree` as returned by `extractMachineRoutes()`.
- * @param options - Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size).
- * @returns A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+ * @param routeTree - A `RouteTree`, as `extractMachineRoutes()` returns it.
+ * @param options - The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache.
+ * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript
- * // Preferred — single call for XState machines:
+ * // The preferred form — one call for an XState machine:
  * import { createRouteMap } from '@xmachines/play-router';
- * const routeMap = createRouteMap(machine); // takes AnyStateMachine
+ * const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
  *
- * // Two-step form used by framework adapters that work with route trees:
+ * // The two-step form, for a framework adapter that works with a route tree:
  * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
  * const routeTree = extractMachineRoutes(machine);
- * const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+ * const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
  * ```
  */
 export declare function createRouteMapFromTree(routeTree: RouteTree, options?: RouteMapOptions): RouteMap;

package/dist/create-route-map-from-tree.js

@@ -1,30 +1,30 @@
 import { RouteMap } from "./base-route-map.js";
 /**
- * Create a `RouteMap` from a `RouteTree` node structure.
+ * Creates a `RouteMap` from the node structure of a `RouteTree`.
  *
- * Used by framework-router adapters that pass a
- * `RouteTree` produced by `extractMachineRoutes()` rather than calling
- * `createRouteMap()` directly.
+ * A framework router adapter uses this function when it gives a `RouteTree` from
+ * `extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
  *
- * Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
- * `node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
- * which is what `RouteMap` needs for browser URL matching. This matches the
- * behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
+ * The function walks every node, and it collects the pairs
+ * `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
+ * absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` needs
+ * that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
+ * same way, because it also uses `node.fullPath`.
  *
- * @param routeTree - A `RouteTree` as returned by `extractMachineRoutes()`.
- * @param options - Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size).
- * @returns A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+ * @param routeTree - A `RouteTree`, as `extractMachineRoutes()` returns it.
+ * @param options - The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache.
+ * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript
- * // Preferred — single call for XState machines:
+ * // The preferred form — one call for an XState machine:
  * import { createRouteMap } from '@xmachines/play-router';
- * const routeMap = createRouteMap(machine); // takes AnyStateMachine
+ * const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
  *
- * // Two-step form used by framework adapters that work with route trees:
+ * // The two-step form, for a framework adapter that works with a route tree:
  * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
  * const routeTree = extractMachineRoutes(machine);
- * const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+ * const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
  * ```
  */
 export function createRouteMapFromTree(routeTree, options) {

package/dist/create-route-map.d.ts

@@ -1,33 +1,35 @@
 import type { AnyStateMachine } from "xstate";
 import { RouteMap } from "./base-route-map.js";
 /**
- * Options for `createRouteMap` and `createRouteMapFromTree`.
+ * The options of `createRouteMap` and of `createRouteMapFromTree`.
  */
 export interface RouteMapOptions {
     /**
-     * Maximum number of resolved parameterized path lookups to cache.
+     * The maximum number of the resolved parameterized path lookups in the cache.
      *
-     * `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g.
-     * `/profile/:userId`) via URLPattern on every call. Frequently visited
-     * paths are cached in an LRU so subsequent lookups are O(1).
+     * `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example
+     * `/profile/:userId`, with URLPattern on each call. The map keeps each path of a
+     * frequent visit in an LRU cache, and a later lookup of that path is therefore
+     * O(1).
      *
-     * Increase this value for applications with large parameterized route sets
-     * or high navigation frequency. Default: `500`.
+     * Raise this value for an application with a large set of parameterized routes, or
+     * with a high frequency of the navigation. The default is `500`.
      */
     cacheSize?: number;
 }
 /**
- * Create a `RouteMap` from an XState state machine.
+ * Creates a `RouteMap` from an XState state machine.
  *
- * Extracts all routable states (those with `meta.route`) and builds a bidirectional
- * path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
- * subclasses to translate browser URL changes into `play.route` actor events and
- * vice-versa.
+ * The function reads every state with a route, which means each state with a
+ * `meta.route` field. It then builds the lookup structure between a path and a
+ * stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+ * converts each change of the browser URL into a `play.route` actor event, and each
+ * actor route into a URL.
  *
- * @param machine - XState v5 state machine with `meta.route` annotations on states.
- * @param options - Optional configuration. Pass `{ cacheSize }` to override the
- *   default LRU cache size for parameterized path lookups.
- * @returns A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+ * @param machine - The XState v5 state machine, with a `meta.route` annotation on each state with a route.
+ * @param options - The optional configuration. Give `{ cacheSize }` to change the
+ *   default size of the LRU cache of the parameterized path lookups.
+ * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript

package/dist/create-route-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAU5F"}
+{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAU5F"}

package/dist/create-route-map.js

@@ -2,17 +2,18 @@ import { extractMachineRoutes } from "./extract-routes.js";
 import { getRoutableRoutes } from "./query.js";
 import { RouteMap } from "./base-route-map.js";
 /**
- * Create a `RouteMap` from an XState state machine.
+ * Creates a `RouteMap` from an XState state machine.
  *
- * Extracts all routable states (those with `meta.route`) and builds a bidirectional
- * path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
- * subclasses to translate browser URL changes into `play.route` actor events and
- * vice-versa.
+ * The function reads every state with a route, which means each state with a
+ * `meta.route` field. It then builds the lookup structure between a path and a
+ * stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+ * converts each change of the browser URL into a `play.route` actor event, and each
+ * actor route into a URL.
  *
- * @param machine - XState v5 state machine with `meta.route` annotations on states.
- * @param options - Optional configuration. Pass `{ cacheSize }` to override the
- *   default LRU cache size for parameterized path lookups.
- * @returns A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+ * @param machine - The XState v5 state machine, with a `meta.route` annotation on each state with a route.
+ * @param options - The optional configuration. Give `{ cacheSize }` to change the
+ *   default size of the LRU cache of the parameterized path lookups.
+ * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript

package/dist/create-route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAmB/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB,EAAE,OAAyB;IACjF,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,IAAI,QAAQ,CAClB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACnB,CAAC,CAAC,EACH,OAAO,CACP,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAoB/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB,EAAE,OAAyB;IACjF,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,IAAI,QAAQ,CAClB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACnB,CAAC,CAAC,EACH,OAAO,CACP,CAAC;AACH,CAAC"}