@xmachines/play-router 3.0.0 → 5.0.0

package/dist/base-route-map.js

@@ -10,9 +10,8 @@
  * 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";
+import { createPatternCache, getCandidates, getCompiledPattern, getIndexKey, parsePattern, splitLocation, } from "@xmachines/play-url";
+import { InvalidRoutePatternError } from "./errors.js";
 /**
  * The canonical key of a stateId: the bare form, without a `#` at its start.
  *
@@ -25,6 +24,65 @@ import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.j
 function canonicalStateIdKey(stateId) {
     return stateId.startsWith("#") ? stateId.slice(1) : stateId;
 }
+/**
+ * The bound of the path cache that a map builds for itself.
+ *
+ * `createPatternCache` keeps two generations, so the cache holds between this number and
+ * twice it. A caller that wants another bound passes a cache: `createPatternCache(5000)`
+ * builds one. A separate size option would configure THIS cache alone and say so nowhere,
+ * and it would do nothing at all beside a cache that the caller passed.
+ */
+const DEFAULT_PATH_CACHE_SIZE = 500;
+/**
+ * The id of one route table: a digest of its mappings, in order.
+ *
+ * It is the key space that each ROUTE TABLE owns inside a shared path cache. An entry of
+ * that cache says which state a path resolves to, and the answer is a pure function of
+ * the mappings and the path: two maps built from the SAME mappings resolve every path the
+ * same way, and two maps built from different mappings do not. A map with no route for
+ * `/settings/x` writes `null`, and a map that DOES hold `/settings/:s` then read that
+ * `null` and reported no state for a route of its own.
+ *
+ * The key therefore names the TABLE, and not the instance. An instance counter kept the
+ * two apart as well, and it also gave a server that rebuilds its map for each request a
+ * cache that answered nothing: every request opened a key space of its own, and the dead
+ * keys of the last one evicted the live entries of this one.
+ *
+ * Two maps built from the same mappings share the id, which is what a server that
+ * rebuilds its map for each request needs, and two maps built from different mappings do
+ * not — a map with no route for a path writes `null` for it, and a map that HOLDS one
+ * must not read that.
+ *
+ * A REGISTER of the serialized tables answered this before, and it kept every table
+ * string it had seen for the life of the process: a per-tenant table of fifty routes is a
+ * few kilobytes, and a bounded register of them still retained megabytes in exactly the
+ * per-request case that the cache exists for. A digest retains nothing.
+ *
+ * ## The collision
+ *
+ * Two DIFFERENT tables that share a digest share a key space, and the negative entries of
+ * one then answer for the other. The digest is 64 bits over the full signature, so a
+ * process that built ten thousand distinct route tables carries a chance of about 3 in
+ * 10^12 of one collision — far below the chance of the bit flip that would corrupt the
+ * cache anyway. This library already identifies by digest: an XMachines id is a Git OID.
+ */
+function routeTableId(mappings) {
+    // FNV-1a, in two 32-bit halves, because a bitwise operator of JavaScript truncates to
+    // 32 bits and `BigInt` costs an allocation for each character.
+    let hashLow = 0x811c9dc5;
+    let hashHigh = 0x811c9dc5;
+    for (const { stateId, path } of mappings) {
+        // The ORDER is significant: it gives the priority when more than one pattern matches,
+        // so the separators below keep `[{a, /x}, {b, /y}]` apart from `[{a, /x/b}, {/y}]`.
+        const entry = `${stateId}\u0000${path}\u0001`;
+        for (let index = 0; index < entry.length; index += 1) {
+            const code = entry.charCodeAt(index);
+            hashLow = Math.imul(hashLow ^ code, 0x01000193) >>> 0;
+            hashHigh = Math.imul(hashHigh ^ (code + index), 0x01000193) >>> 0;
+        }
+    }
+    return `${hashLow.toString(36)}.${hashHigh.toString(36)}`;
+}
 /**
  * The shared base class of the route map for both directions.
  *
@@ -35,14 +93,21 @@ function canonicalStateIdKey(stateId) {
  * - 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
+ * - 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** (`:param`, `:param?`, and `*`):
+ * **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](../../docs/guides/routing.md) 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
@@ -75,6 +140,16 @@ export class RouteMap {
     pathToStateId;
     patternBuckets;
     pathMatchCache;
+    /** The key space of this ROUTE TABLE inside {@link pathMatchCache}, which a caller may share. */
+    pathCacheKey;
+    /**
+     * The caches that every parse and every compilation of this map reads.
+     *
+     * Each default stays SHARED on purpose. A map that built one of its own would keep its
+     * patterns out of the cache that `find-route.ts` and `router-sync.ts` read, so the same
+     * pattern would parse two times. A caller that wants the isolation passes a cache.
+     */
+    compileOptions;
     /**
      * Builds a route map from an array of the mappings between a state ID and a path.
      *
@@ -85,35 +160,44 @@ export class RouteMap {
      *
      * @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.
+     * @param options - See {@link RouteMapOptions}. A map holds TWO caches, so no option is
+     *   named `cache`: each one names the cache that it carries.
      */
-    constructor(mappings, { cacheSize = 500 } = {}) {
+    constructor(mappings, options = {}) {
+        const { pathCache, ...compileOptions } = options;
+        this.compileOptions = compileOptions;
         this.stateIdToPath = new Map();
         this.pathToStateId = new Map();
         this.patternBuckets = new Map();
-        this.pathMatchCache = new QuickLRU({ maxSize: Math.max(1, cacheSize) });
+        this.pathMatchCache =
+            pathCache ?? createPatternCache(DEFAULT_PATH_CACHE_SIZE);
+        // A map that BUILDS its own cache owns every key in it, and a prefix would only make
+        // each key longer. A map that RECEIVES one shares it, so its keys carry the prefix.
+        if (pathCache === undefined) {
+            this.pathCacheKey = (path) => path;
+        }
+        else {
+            const prefix = `${routeTableId(mappings)}\u0002`;
+            this.pathCacheKey = (path) => prefix + path;
+        }
         let patternOrder = 0;
         for (const { stateId, path } of mappings) {
             // 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();
-                if (!URLPatternCtorFn) {
-                    throw new URLPatternUnavailableError();
-                }
-                const bucketKey = getIndexKey(path);
+            // ONE parse answers both questions: is the path a pattern, and which bucket does
+            // it belong to. The key comes from that parse, and not from a split of the raw
+            // string. A pattern such as `/books{/:id}?` keeps the literal first segment
+            // `books`, and a split on `/` read the key `books{` and put the route in a bucket
+            // that the path `/books/1` reaches never.
+            const parsed = parsePattern(path, this.compileOptions);
+            if (parsed.parameterized) {
+                const bucketKey = parsed.indexKey;
                 const bucket = this.patternBuckets.get(bucketKey) ?? [];
                 try {
                     bucket.push({
-                        pattern: getCompiledPattern(path, URLPatternCtorFn),
+                        pattern: getCompiledPattern(path, this.compileOptions),
                         stateId,
                         order: patternOrder++,
                     });
@@ -150,23 +234,28 @@ export class RouteMap {
      * ```
      */
     getStateIdByPath(path) {
-        // Remove the query string and the hash fragment before the match
-        const cleanPath = path.split("?")[0].split("#")[0];
+        // Remove the query string and the hash fragment before the match. `splitLocation` is
+        // the ONE answer to "where does a pathname end", and `RouterBridgeBase`,
+        // `framework-params.ts` and `sanitizePathname` read it too, so the four cannot
+        // disagree. Two splits allocated two arrays of every part on the hottest lookup of
+        // the library, and this function then read one element of each.
+        const cleanPath = splitLocation(path).pathname;
         const exactMatch = this.pathToStateId.get(cleanPath);
         if (exactMatch !== undefined)
             return exactMatch;
-        const cachedMatch = this.pathMatchCache.get(cleanPath);
+        const cacheKey = this.pathCacheKey(cleanPath);
+        const cachedMatch = this.pathMatchCache.get(cacheKey);
         if (cachedMatch !== undefined)
             return cachedMatch;
         const candidates = getCandidates(this.patternBuckets, getIndexKey(cleanPath));
         for (const { pattern, stateId } of candidates) {
             const match = pattern.exec({ pathname: cleanPath });
             if (match) {
-                this.pathMatchCache.set(cleanPath, stateId);
+                this.pathMatchCache.set(cacheKey, stateId);
                 return stateId;
             }
         }
-        this.pathMatchCache.set(cleanPath, null);
+        this.pathMatchCache.set(cacheKey, null);
         return 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,4 +1,15 @@
 import type { RouteInfo, RouteTree } from "./types.js";
+/**
+ * The ID and the state ID of the synthetic root node of every `RouteTree`.
+ *
+ * `buildRouteTree` always makes this node, and no state of a machine declares it. It
+ * gives the tree one parent for each absolute route, and it holds `routable: false`.
+ *
+ * A consumer that walks a tree must SKIP this node. `createRouteMapFromTree` skips it,
+ * and `getRoutableRoutes` of `@xmachines/play-router/xstate` skips it. A walk that keeps
+ * it maps the path `/` to a state that the machine does not hold.
+ */
+export declare const ROOT_NODE_ID = "__root__";
 /**
  * Builds the hierarchical route tree from the flat list of the routes
  *
@@ -13,9 +24,13 @@ import type { RouteInfo, RouteTree } from "./types.js";
  * strings that resolve to the same complete path are not: those two overwrite each
  * other in `byPath` in silence.
  *
+ * `TGraph` names the type of the graph that a CALLER attaches afterwards. The builder
+ * attaches none: it reads a list of routes and writes the maps of the tree.
+ * `extractMachineRoutes` of `@xmachines/play-router/xstate` binds it to `MachineGraph`.
+ *
  * @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;
+export declare const buildRouteTree: <TGraph = unknown>(routes: RouteInfo[]) => RouteTree<TGraph>;
 //# 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;;;;;;;;;;;;;;;;;GAiBG;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,EAAa,SAAS,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,GAAG,OAAO,EAAE,QAAQ,SAAS,EAAE,KAAG,SAAS,CAAC,MAAM,CA0EtF,CAAC"}

package/dist/build-tree.js

@@ -1,4 +1,15 @@
 import { detectDuplicateRoutes } from "./validate-routes.js";
+/**
+ * The ID and the state ID of the synthetic root node of every `RouteTree`.
+ *
+ * `buildRouteTree` always makes this node, and no state of a machine declares it. It
+ * gives the tree one parent for each absolute route, and it holds `routable: false`.
+ *
+ * A consumer that walks a tree must SKIP this node. `createRouteMapFromTree` skips it,
+ * and `getRoutableRoutes` of `@xmachines/play-router/xstate` skips it. A walk that keeps
+ * it maps the path `/` to a state that the machine does not hold.
+ */
+export const ROOT_NODE_ID = "__root__";
 /**
  * Builds the hierarchical route tree from the flat list of the routes
  *
@@ -13,6 +24,10 @@ import { detectDuplicateRoutes } from "./validate-routes.js";
  * strings that resolve to the same complete path are not: those two overwrite each
  * other in `byPath` in silence.
  *
+ * `TGraph` names the type of the graph that a CALLER attaches afterwards. The builder
+ * attaches none: it reads a list of routes and writes the maps of the tree.
+ * `extractMachineRoutes` of `@xmachines/play-router/xstate` binds it to `MachineGraph`.
+ *
  * @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
@@ -20,10 +35,10 @@ import { detectDuplicateRoutes } from "./validate-routes.js";
 export const buildRouteTree = (routes) => {
     // 1. Create the root node
     const root = {
-        id: "__root__",
+        id: ROOT_NODE_ID,
         path: "/",
         fullPath: "/",
-        stateId: "__root__",
+        stateId: ROOT_NODE_ID,
         routable: false, // The root is a state without a route
         children: [],
         parent: null,
@@ -44,8 +59,11 @@ export const buildRouteTree = (routes) => {
         let parentNode = root;
         for (let i = route.statePath.length - 2; i >= 0; i--) {
             const parentStateId = route.statePath[i]; // nosemgrep: gitlab.eslint.detect-object-injection
-            if (byStateId.has(parentStateId)) {
-                parentNode = byStateId.get(parentStateId);
+            if (parentStateId === undefined)
+                continue;
+            const candidate = byStateId.get(parentStateId);
+            if (candidate !== undefined) {
+                parentNode = candidate;
                 break;
             }
         }

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":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAmB,MAAmB,EAAqB,EAAE;IAC1F,0BAA0B;IAC1B,MAAM,IAAI,GAAc;QACvB,EAAE,EAAE,YAAY;QAChB,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,GAAG;QACb,OAAO,EAAE,YAAY;QACrB,QAAQ,EAAE,KAAK,EAAE,sCAAsC;QACvD,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,EAAE,EAAE,wEAAwE;KACtF,CAAC;IAEF,yBAAyB;IACzB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAoB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAoB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEnE,mGAAmG;IACnG,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAElF,0FAA0F;IAC1F,MAAM,aAAa,GAAgB,EAAE,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,+CAA+C;QAC/C,oEAAoE;QACpE,gFAAgF;QAChF,4BAA4B;QAC5B,IAAI,UAAU,GAAG,IAAI,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtD,MAAM,aAAa,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,mDAAmD;YAC7F,IAAI,aAAa,KAAK,SAAS;gBAAE,SAAS;YAC1C,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC/C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC7B,UAAU,GAAG,SAAS,CAAC;gBACvB,MAAM;YACP,CAAC;QACF,CAAC;QAED,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU;YAChC,CAAC,CAAC,KAAK,CAAC,SAAS;YACjB,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAEpE,kBAAkB;QAClB,MAAM,IAAI,GAAc;YACvB,EAAE,EAAE,KAAK,CAAC,OAAO;YACjB,IAAI,EAAE,KAAK,CAAC,SAAS;YACrB,QAAQ;YACR,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,EAAE;YACZ,MAAM,EAAE,UAAU;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACxB,CAAC;QAEF,uCAAuC;QACvC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,CAAC;QAED,8BAA8B;QAC9B,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,8DAA8D;QAC9D,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAChC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,8EAA8E;IAC9E,yCAAyC;IACzC,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAErC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC,CAAC"}

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

@@ -1,11 +1,11 @@
-import type { RouteTree } from "./types.js";
+import type { RouteTree, RouteMapOptions } from "./types.js";
 import { RouteMap } from "./base-route-map.js";
-import type { RouteMapOptions } from "./create-route-map.js";
 /**
  * Creates a `RouteMap` from the node structure of a `RouteTree`.
  *
- * A framework router adapter uses this function when it gives a `RouteTree` from
- * `extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
+ * A framework router adapter uses this function when it holds a `RouteTree`, for example
+ * from `extractMachineRoutes()` of `@xmachines/play-router/xstate`, and not when it calls
+ * `createRouteMap()` of that package directly.
  *
  * The function walks every node, and it collects the pairs
  * `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
@@ -13,18 +13,24 @@ import type { RouteMapOptions } from "./create-route-map.js";
  * that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
  * same way, because it also uses `node.fullPath`.
  *
+ * The walk SKIPS the synthetic root node. `buildRouteTree` makes that node to hold each
+ * absolute route, and no state of a machine declares it. `createRouteMap` skips it as
+ * well, through `getRoutableRoutes`, and the two functions therefore answer the same map
+ * for the same tree.
+ *
  * @param routeTree - A `RouteTree`, as `extractMachineRoutes()` returns it.
- * @param options - The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache.
+ * @param options - The optional configuration, for example `{ pathCache }` to replace the LRU cache of the resolved paths.
  * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript
  * // The preferred form — one call for an XState machine:
- * import { createRouteMap } from '@xmachines/play-router';
+ * import { createRouteMap } from '@xmachines/play-router/xstate';
  * const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
  *
  * // The two-step form, for a framework adapter that works with a route tree:
- * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
+ * import { createRouteMapFromTree } from '@xmachines/play-router';
+ * import { extractMachineRoutes } from '@xmachines/play-router/xstate';
  * const routeTree = extractMachineRoutes(machine);
  * const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
  * ```

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

@@ -1 +1 @@
-{"version":3,"file":"create-route-map-from-tree.d.ts","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAchG"}
+{"version":3,"file":"create-route-map-from-tree.d.ts","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,eAAe,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAchG"}

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

@@ -1,9 +1,11 @@
 import { RouteMap } from "./base-route-map.js";
+import { ROOT_NODE_ID } from "./build-tree.js";
 /**
  * Creates a `RouteMap` from the node structure of a `RouteTree`.
  *
- * A framework router adapter uses this function when it gives a `RouteTree` from
- * `extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
+ * A framework router adapter uses this function when it holds a `RouteTree`, for example
+ * from `extractMachineRoutes()` of `@xmachines/play-router/xstate`, and not when it calls
+ * `createRouteMap()` of that package directly.
  *
  * The function walks every node, and it collects the pairs
  * `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
@@ -11,18 +13,24 @@ import { RouteMap } from "./base-route-map.js";
  * that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
  * same way, because it also uses `node.fullPath`.
  *
+ * The walk SKIPS the synthetic root node. `buildRouteTree` makes that node to hold each
+ * absolute route, and no state of a machine declares it. `createRouteMap` skips it as
+ * well, through `getRoutableRoutes`, and the two functions therefore answer the same map
+ * for the same tree.
+ *
  * @param routeTree - A `RouteTree`, as `extractMachineRoutes()` returns it.
- * @param options - The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache.
+ * @param options - The optional configuration, for example `{ pathCache }` to replace the LRU cache of the resolved paths.
  * @returns A `RouteMap` for each adapter on `RouterBridgeBase`.
  *
  * @example
  * ```typescript
  * // The preferred form — one call for an XState machine:
- * import { createRouteMap } from '@xmachines/play-router';
+ * import { createRouteMap } from '@xmachines/play-router/xstate';
  * const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
  *
  * // The two-step form, for a framework adapter that works with a route tree:
- * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
+ * import { createRouteMapFromTree } from '@xmachines/play-router';
+ * import { extractMachineRoutes } from '@xmachines/play-router/xstate';
  * const routeTree = extractMachineRoutes(machine);
  * const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
  * ```
@@ -30,7 +38,7 @@ import { RouteMap } from "./base-route-map.js";
 export function createRouteMapFromTree(routeTree, options) {
     const routes = [];
     function traverse(node) {
-        if (node.id && node.fullPath) {
+        if (node.id && node.fullPath && node.id !== ROOT_NODE_ID) {
             routes.push({ stateId: node.id, path: node.fullPath });
         }
         if (node.children) {

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

@@ -1 +1 @@
-{"version":3,"file":"create-route-map-from-tree.js","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,OAAyB;IACrF,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"create-route-map-from-tree.js","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,OAAyB;IACrF,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,EAAE,KAAK,YAAY,EAAE,CAAC;YAC1D,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
+export { InvalidRoutePatternError, InvalidBasePathError, MissingBasePathParamError, } from "@xmachines/play-url/errors";
 /**
  * The bridge throws this error when `RouterBridgeBase.syncActorFromRouter()`
  * cannot process a location change of the router and send the `play.route` event to
@@ -55,27 +56,6 @@ export declare class RouterSyncError extends PlayError {
 export declare class DuplicateBridgeError extends PlayError {
     constructor();
 }
-/**
- * The `RouteMap` constructor throws this error when the caller registers a
- * parameterized route, the current runtime has no `URLPattern` API, and no polyfill
- * is loaded.
- *
- * **The remedy:** load `urlpattern-polyfill` at the entry point of your application,
- * before each import of `@xmachines/play-router`:
- *
- * ```typescript
- * // the entry point of the application — it must run first
- * import "urlpattern-polyfill";
- * ```
- *
- * URLPattern is native in Node.js ≥ 24 and in a modern browser (Chrome 95+,
- * Firefox 117+, Safari 16.4+). Use the polyfill for an older target.
- *
- * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
- */
-export declare class URLPatternUnavailableError extends PlayError {
-    constructor();
-}
 /**
  * `validateRouteFormat()` throws this error when a state declares a `meta.route`
  * field with an empty string as its path.
@@ -122,116 +102,4 @@ export declare class UnknownStateTypeError extends PlayError {
     readonly nodeId: string;
     constructor(stateType: string, nodeId: string, validTypes: string[]);
 }
-/**
- * The library throws this error when `URLPattern` cannot compile the string of a route
- * pattern. The `pattern` field holds the string in question, and `cause` holds the
- * original error of the `URLPattern` constructor.
- *
- * Every compilation reports through this error, so `extractRouteParams` raises it for a
- * pattern that no `RouteMap` ever held, and not a bare `TypeError`.
- *
- * The common causes:
- * - A parenthesis or a bracket without its pair in the string of the pattern
- * - A character that a URL pathname pattern does not permit
- * - Two params of one pattern that land on the same URLPattern group. A name with a
- *   hyphen compiles with an underscore, so `:cat-id` and `:cat_id` are one group. The
- *   message names the two params and the group, and `cause` is absent: the library
- *   refuses the pattern before URLPattern sees it.
- *
- * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
- *
- * @example
- * ```typescript
- * import { InvalidRoutePatternError } from "@xmachines/play-router/errors";
- *
- * try {
- *   const routeMap = createRouteMap(machine);
- * } catch (err) {
- *   if (err instanceof InvalidRoutePatternError) {
- *     console.error(`Bad route pattern: "${err.pattern}"`, err.cause);
- *   }
- * }
- * ```
- */
-export declare class InvalidRoutePatternError extends PlayError {
-    /** The string of the route pattern. URLPattern could not compile it. */
-    readonly pattern: string;
-    /**
-     * @param pattern - The route pattern that URLPattern could not compile.
-     * @param options - The standard `cause`, and an optional `reason` that says WHY. Give
-     *   a reason whenever the library knows it: the pattern alone shows a caller nothing
-     *   when the fault is a rewrite that the library made, and not the text they wrote.
-     */
-    constructor(pattern: string, options?: ErrorOptions & {
-        reason?: string;
-    });
-}
-/**
- * Thrown when a `basePath` option resolves to one concrete URL prefix never.
- *
- * A bridge writes a real browser URL from its prefix, so every segment must hold
- * exactly one value. A wildcard segment (`*`), an optional segment (`:section?`), a
- * nameless `:` segment, a query string, and a hash fragment each describe a SET of
- * prefixes instead, or no prefix at all. A `$param` segment is the route-param
- * syntax of TanStack Router: a base path writes a param as `:param`, and it takes
- * the value of that param from `basePathParams`.
- *
- * **How to fix it:** mount on the prefix itself, and let the machine own the rest.
- * For the splat route `/$machineId/play/$` of TanStack, the base path is
- * `"/:machineId/play"` with `basePathParams: { machineId }`.
- *
- * **Error code:** `PLAY_ROUTER_INVALID_BASE_PATH`
- *
- * @example
- * ```typescript
- * import { InvalidBasePathError } from "@xmachines/play-router/errors";
- *
- * try {
- *   bridge.setBasePath("/:machineId/play/*");
- * } catch (err) {
- *   if (err instanceof InvalidBasePathError) {
- *     console.error(`Bad base path: "${err.basePath}"`, err.message);
- *   }
- * }
- * ```
- */
-export declare class InvalidBasePathError extends PlayError {
-    /** The `basePath` option of the refusal, exactly as the caller gave it. */
-    readonly basePath: string;
-    constructor(basePath: string, reason: string);
-}
-/**
- * Thrown when a `:param` segment of a `basePath` has no value in `basePathParams`.
- *
- * A base path can be a pattern, so a host keeps one string that mirrors its own
- * route config. The bridge must still resolve that pattern to a concrete prefix,
- * because it writes a real browser URL, and it removes a literal prefix from every
- * inbound location. Every `:param` therefore needs a value.
- *
- * **How to fix it:** give the value that the host resolved already — a loader of
- * TanStack, or a `useParams()` call, holds it — as `basePathParams: { machineId }`.
- * An empty string counts as an absent value, because it would collapse the segment.
- *
- * **Error code:** `PLAY_ROUTER_MISSING_BASE_PATH_PARAM`
- *
- * @example
- * ```typescript
- * import { MissingBasePathParamError } from "@xmachines/play-router/errors";
- *
- * try {
- *   connectRouter({ actor, router, routeMap, basePath: "/:machineId/play" });
- * } catch (err) {
- *   if (err instanceof MissingBasePathParamError) {
- *     console.error(`basePath needs a value for :${err.param}`);
- *   }
- * }
- * ```
- */
-export declare class MissingBasePathParamError extends PlayError {
-    /** The name of the `:param` segment without a value, and without its `:`. */
-    readonly param: string;
-    /** The `basePath` option that declares the param. */
-    readonly basePath: string;
-    constructor(param: string, basePath: string);
-}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAazE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAWnD,OAAO,EACN,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GACzB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE"}