@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-router/index/README.md

@@ -0,0 +1,83 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / index
+
+# index
+
+## Classes
+
+- [RouteMap](classes/RouteMap.md)
+- [RouterBridgeBase](classes/RouterBridgeBase.md)
+
+## Interfaces
+
+- [BasePathOptions](interfaces/BasePathOptions.md)
+- [BuildPlayRouteEventOptions](interfaces/BuildPlayRouteEventOptions.md)
+- [CompileOptions](interfaces/CompileOptions.md)
+- [FrameworkParamsSource](interfaces/FrameworkParamsSource.md)
+- [LocationLike](interfaces/LocationLike.md)
+- [MountableRouterBridge](interfaces/MountableRouterBridge.md)
+- [OpenProviderBridgeArgs](interfaces/OpenProviderBridgeArgs.md)
+- [ParsedPattern](interfaces/ParsedPattern.md)
+- [ParseOptions](interfaces/ParseOptions.md)
+- [PatternCache](interfaces/PatternCache.md)
+- [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
+- [ResolvedBasePath](interfaces/ResolvedBasePath.md)
+- [ResolvedRoutePath](interfaces/ResolvedRoutePath.md)
+- [Routable](interfaces/Routable.md)
+- [RoutableActor](interfaces/RoutableActor.md)
+- [RouteInfo](interfaces/RouteInfo.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
+- [RouteMapping](interfaces/RouteMapping.md)
+- [RouteMatch](interfaces/RouteMatch.md)
+- [RouteNode](interfaces/RouteNode.md)
+- [RouteObject](interfaces/RouteObject.md)
+- [RouterBridge](interfaces/RouterBridge.md)
+- [RouterBridgeOptions](interfaces/RouterBridgeOptions.md)
+- [RouterConnection](interfaces/RouterConnection.md)
+- [RouteTree](interfaces/RouteTree.md)
+- [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
+- [SplitLocation](interfaces/SplitLocation.md)
+- [WindowLike](interfaces/WindowLike.md)
+
+## Type Aliases
+
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
+- [RouteData](type-aliases/RouteData.md)
+- [RouteDataResolver](type-aliases/RouteDataResolver.md)
+- [RouteMetadata](type-aliases/RouteMetadata.md)
+- [URLPatternLike](type-aliases/URLPatternLike.md)
+
+## Variables
+
+- [DISPOSE](variables/DISPOSE.md)
+- [NO\_BASE\_PATH](variables/NO_BASE_PATH.md)
+- [ROOT\_NODE\_ID](variables/ROOT_NODE_ID.md)
+
+## Functions
+
+- [buildPlayRouteEvent](functions/buildPlayRouteEvent.md)
+- [buildRouteTree](functions/buildRouteTree.md)
+- [cleanFrameworkParams](functions/cleanFrameworkParams.md)
+- [createPatternCache](functions/createPatternCache.md)
+- [createRouteMapFromTree](functions/createRouteMapFromTree.md)
+- [createRouterConnection](functions/createRouterConnection.md)
+- [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
+- [extractQuery](functions/extractQuery.md)
+- [extractRouteParams](functions/extractRouteParams.md)
+- [findRouteById](functions/findRouteById.md)
+- [findRouteByPath](functions/findRouteByPath.md)
+- [isMountableBridge](functions/isMountableBridge.md)
+- [joinBasePath](functions/joinBasePath.md)
+- [mountKey](functions/mountKey.md)
+- [normalizeBasePath](functions/normalizeBasePath.md)
+- [openProviderBridge](functions/openProviderBridge.md)
+- [parsePattern](functions/parsePattern.md)
+- [pickOwnParams](functions/pickOwnParams.md)
+- [repointProviderBridge](functions/repointProviderBridge.md)
+- [resolveBasePath](functions/resolveBasePath.md)
+- [resolveFrameworkParams](functions/resolveFrameworkParams.md)
+- [sanitizePathname](functions/sanitizePathname.md)
+- [splitLocation](functions/splitLocation.md)
+- [stripBasePath](functions/stripBasePath.md)
+- [validateRouteFormat](functions/validateRouteFormat.md)
+- [validateStateExists](functions/validateStateExists.md)

package/api/@xmachines/play-router/{classes → index/classes}/RouteMap.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMap
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / RouteMap
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [packages/play-router/src/base-route-map.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L177)
 
 The shared base class of the route map for both directions.
 
@@ -14,15 +14,22 @@ of its own, and it inherits the complete public API from here.
 - 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](../../../../../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
@@ -58,7 +65,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [packages/play-router/src/base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L210)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -69,11 +76,10 @@ candidates is therefore efficient.
 
 #### Parameters
 
-| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                                                                                                                                                                                                                                                                                                                                                     |
-| `options`            | \{ `cacheSize?`: `number`; \}                     | 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. |
-| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Parameter  | Type                                                  | Description                                                                                                                                               |
+| ---------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`RouteMapping`](../interfaces/RouteMapping.md)[]     | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                            |
+| `options`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | See [RouteMapOptions](../interfaces/RouteMapOptions.md). A map holds TWO caches, so no option is named `cache`: each one names the cache that it carries. |
 
 #### Returns
 
@@ -87,7 +93,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [packages/play-router/src/base-route-map.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L324)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [packages/play-router/src/base-route-map.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L279)
 
 Resolves a URL path to its state ID.
 

package/api/@xmachines/play-router/{classes → index/classes}/RouterBridgeBase.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouterBridgeBase
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / RouterBridgeBase
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [play-router/src/router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L112)
+Defined in: [packages/play-router/src/router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L124)
 
 A `RouterBridge` whose machine is mounted at a URL prefix that can MOVE while the
 bridge stays connected.
@@ -27,14 +27,15 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 ## Extended by
 
-- [`DomRouterBridge`](../../play-dom-router/classes/DomRouterBridge.md)
-- [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
-- [`TanStackRouterBridgeBase`](../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
-- [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
-- [`SvelteKitRouterBridge`](../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
-- [`SvelteSpaRouterBridge`](../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
-- [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
-- [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
+- [`DomRouterBridge`](../../../play-dom-router/classes/DomRouterBridge.md)
+- [`ReactRouterBridge`](../../../play-react-router/classes/ReactRouterBridge.md)
+- [`TanStackRouterBridgeBase`](../../../play-tanstack-router/classes/TanStackRouterBridgeBase.md)
+- [`SolidRouterBridge`](../../../play-solid-router/classes/SolidRouterBridge.md)
+- [`SvelteKitRouterBridge`](../../../play-sveltekit-router/classes/SvelteKitRouterBridge.md)
+- [`SvelteSpaRouterBridge`](../../../play-svelte-spa-router/classes/SvelteSpaRouterBridge.md)
+- [`TanStackReactRouterBridge`](../../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
+- [`TanStackSolidRouterBridge`](../../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+- [`VueRouterBridge`](../../../play-vue-router/index/classes/VueRouterBridge.md)
 
 ## Implements
 
@@ -48,10 +49,11 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 new RouterBridgeBase(
    actor,
    routeMap,
-   options?): RouterBridgeBase;
+   options?
+): RouterBridgeBase;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L230)
+Defined in: [packages/play-router/src/router-bridge-base.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L249)
 
 #### Parameters
 
@@ -61,7 +63,7 @@ Defined in: [play-router/src/router-bridge-base.ts:230](https://gitlab.com/xmach
 | `routeMap`                   | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | The route map of both directions, for the resolution between a `stateId` and a `path`. Give `getStateIdByPath` and `getPathByStateId`. A framework adapter usually wraps the result of `createRouteMap(machine)`, or an equivalent value. The key of `getPathByStateId` is the form `"#stateId"` or the bare form `"stateId"`. The bridge tries both forms. Therefore an implementation of your own, for example a plain test object, handles one form only. |
 | `routeMap.getPathByStateId`  | -                                                                                                                   |
 | `routeMap.getStateIdByPath?` | -                                                                                                                   |
-| `options?`                   | [`BasePathOptions`](../interfaces/BasePathOptions.md)                                                               | -                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `options?`                   | [`RouterBridgeOptions`](../interfaces/RouterBridgeOptions.md)                                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
@@ -77,7 +79,7 @@ Defined in: [play-router/src/router-bridge-base.ts:230](https://gitlab.com/xmach
 get basePath(): string;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L255)
+Defined in: [packages/play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L282)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -102,7 +104,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 get basePathParams(): Readonly<Record<string, string>>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+Defined in: [packages/play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L311)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -153,11 +155,11 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
+Defined in: [packages/play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
-The method installs the TC39 Signal watcher of the direction from the actor to the
+The method installs the atom watcher of the direction from the actor to the
 router. It then starts the watch of the router changes, which each framework does
 in its own way.
 
@@ -187,11 +189,11 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
+Defined in: [packages/play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L791)
 
 Disconnects the router bridge from the Actor.
 
-The method stops the watch of the signal, and it removes the router listener of the
+The method stops the watch of the atom, and it removes the router listener of the
 framework.
 
 #### Returns
@@ -210,7 +212,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [packages/play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 

package/api/@xmachines/play-router/{functions → index/functions}/buildPlayRouteEvent.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildPlayRouteEvent
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / buildPlayRouteEvent
 
 # Function: buildPlayRouteEvent()
 
@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [play-router/src/router-sync.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L175)
+Defined in: [packages/play-router/src/router-sync.ts:161](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-sync.ts#L161)
 
 Builds a normalized `play.route` event from the raw input of a router or of a
 browser.

package/api/@xmachines/play-router/{functions → index/functions}/buildRouteTree.md

@@ -1,12 +1,12 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / buildRouteTree
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / buildRouteTree
 
 # Function: buildRouteTree()
 
 ```ts
-function buildRouteTree(routes): RouteTree;
+function buildRouteTree<TGraph>(routes): RouteTree<TGraph>;
 ```
 
-Defined in: [play-router/src/build-tree.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/build-tree.ts#L22)
+Defined in: [packages/play-router/src/build-tree.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/build-tree.ts#L38)
 
 Builds the hierarchical route tree from the flat list of the routes
 
@@ -21,6 +21,16 @@ 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.
 
+`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`.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `TGraph`       | `unknown`    |
+
 ## Parameters
 
 | Parameter | Type                                        | Description                                                 |
@@ -29,7 +39,7 @@ other in `byPath` in silence.
 
 ## Returns
 
-[`RouteTree`](../interfaces/RouteTree.md)
+[`RouteTree`](../interfaces/RouteTree.md)\<`TGraph`\>
 
 The RouteTree, with its root, its byStateId map, and its byPath map
 

package/api/@xmachines/play-router/{functions → index/functions}/cleanFrameworkParams.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / cleanFrameworkParams
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / cleanFrameworkParams
 
 # Function: cleanFrameworkParams()
 
@@ -6,7 +6,7 @@
 function cleanFrameworkParams(params): Record<string, string>;
 ```
 
-Defined in: [play-router/src/framework-params.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/framework-params.ts#L182)
+Defined in: [packages/play-url/src/framework-params.ts:107](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/framework-params.ts#L107)
 
 The params of a framework router, in the shape that [pickOwnParams](pickOwnParams.md) reads.
 
@@ -24,8 +24,7 @@ The result has a null prototype, for the same reason [pickOwnParams](pickOwnPara
 plain `{}` accumulator turns `cleaned["__proto__"] = value` into a write of the
 PROTOTYPE setter, which drops a string value in silence. `pickOwnParams` then read
 `Object.hasOwn(params, "__proto__")` as `false`, called the pick incomplete, and fell
-back to the URLPattern extraction — which THROWS on a runtime with no URLPattern, for
-a route the framework had answered already.
+back to the URLPattern extraction, for a route the framework had answered already.
 
 ## Parameters
 

package/api/@xmachines/play-router/index/functions/createPatternCache.md

@@ -0,0 +1,47 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / createPatternCache
+
+# Function: createPatternCache()
+
+```ts
+function createPatternCache<V>(maxSize?): PatternCache<V>;
+```
+
+Defined in: [packages/play-pattern/src/cache.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L85)
+
+Builds a cache that forgets its least recently used entries.
+
+## The algorithm
+
+Two maps, and no list. `recent` takes every write. When a write fills `recent`, it
+becomes `old` and a new `recent` opens, which drops the previous `old` whole. A read of
+a key of `old` moves the entry into `recent`, and THAT is what makes the eviction an
+LRU one rather than a FIFO one: an entry that every lookup reads moves forward, and an
+entry that nothing reads falls out with the map that holds it.
+
+The cache therefore holds between `maxSize` and `2 * maxSize` entries, and it does no
+bookkeeping for a read that hits `recent`.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `V`            |
+
+## Parameters
+
+| Parameter | Type     | Default value | Description                                                                                                                                                                                                          |
+| --------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxSize` | `number` | `500`         | The number of entries that `recent` holds. It is `1` at the least, and the default is `500`. A value that is not a finite number reads as the default, so a cache with no eviction at all cannot happen by accident. |
+
+## Returns
+
+[`PatternCache`](../interfaces/PatternCache.md)\<`V`\>
+
+A cache. It is not shared: each call builds one.
+
+## Example
+
+```typescript
+const cache = createPatternCache<ParsedPattern>(50);
+parsePattern("/profile/:userId", { patternCache: cache });
+```

package/api/@xmachines/play-router/{functions → index/functions}/createRouteMapFromTree.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromTree
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / createRouteMapFromTree
 
 # Function: createRouteMapFromTree()
 
@@ -6,12 +6,13 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [packages/play-router/src/create-route-map-from-tree.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/create-route-map-from-tree.ts#L40)
 
 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
@@ -19,12 +20,17 @@ absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` need
 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.
+
 ## Parameters
 
-| Parameter   | Type                                                  | Description                                                                                  |
-| ----------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md)             | A `RouteTree`, as `extractMachineRoutes()` returns it.                                       |
-| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache. |
+| Parameter   | Type                                                  | Description                                                                                             |
+| ----------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `routeTree` | [`RouteTree`](../interfaces/RouteTree.md)             | A `RouteTree`, as `extractMachineRoutes()` returns it.                                                  |
+| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | The optional configuration, for example `{ pathCache }` to replace the LRU cache of the resolved paths. |
 
 ## Returns
 
@@ -36,11 +42,12 @@ A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ```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/api/@xmachines/play-router/{functions → index/functions}/createRouterConnection.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / createRouterConnection
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / createRouterConnection
 
 # Function: createRouterConnection()
 
@@ -6,7 +6,7 @@
 function createRouterConnection(bridge): RouterConnection;
 ```
 
-Defined in: [play-router/src/provider-lifecycle.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L303)
+Defined in: [packages/play-router/src/provider-lifecycle.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/provider-lifecycle.ts#L330)
 
 Wraps a live bridge in the [RouterConnection](../interfaces/RouterConnection.md) that `connectRouter` returns.
 

package/api/@xmachines/play-router/{functions → index/functions}/detectDuplicateRoutes.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / detectDuplicateRoutes
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / detectDuplicateRoutes
 
 # Function: detectDuplicateRoutes()
 
@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [play-router/src/validate-routes.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/validate-routes.ts#L70)
+Defined in: [packages/play-router/src/validate-routes.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/validate-routes.ts#L70)
 
 Finds each duplicate route path
 

package/api/@xmachines/play-router/{functions → index/functions}/extractQuery.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / extractQuery
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / extractQuery
 
 # Function: extractQuery()
 
@@ -6,7 +6,7 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-sync.ts:155](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L155)
+Defined in: [packages/play-router/src/router-sync.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-sync.ts#L135)
 
 Parses a URL search string into the plain object that a `play.route` event
 needs.

package/api/@xmachines/play-router/{functions → index/functions}/extractRouteParams.md

@@ -1,12 +1,12 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / extractRouteParams
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / extractRouteParams
 
 # Function: extractRouteParams()
 
 ```ts
-function extractRouteParams(pathname, pattern): Record<string, string>;
+function extractRouteParams(pathname, pattern, options?): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-sync.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-sync.ts#L117)
+Defined in: [packages/play-router/src/router-sync.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-sync.ts#L84)
 
 Reads the named path parameters of a URL, with the URLPattern API.
 
@@ -29,10 +29,11 @@ raw.
 
 ## Parameters
 
-| Parameter  | Type     | Description                                                       |
-| ---------- | -------- | ----------------------------------------------------------------- |
-| `pathname` | `string` | The concrete URL pathname, for example `/profile/alice`           |
-| `pattern`  | `string` | The template of the URL pattern, for example `/profile/:username` |
+| Parameter  | Type                                                | Description                                                       |
+| ---------- | --------------------------------------------------- | ----------------------------------------------------------------- |
+| `pathname` | `string`                                            | The concrete URL pathname, for example `/profile/alice`           |
+| `pattern`  | `string`                                            | The template of the URL pattern, for example `/profile/:username` |
+| `options?` | [`CompileOptions`](../interfaces/CompileOptions.md) | -                                                                 |
 
 ## Returns
 
@@ -42,7 +43,7 @@ The record of the parameter values of the read, or `{}` for a static pattern.
 
 ## Throws
 
-When `URLPattern` is absent and the pattern holds a parameter.
+When URLPattern cannot compile the pattern.
 
 ## Example
 

package/api/@xmachines/play-router/{functions → index/functions}/findRouteById.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / findRouteById
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / findRouteById
 
 # Function: findRouteById()
 
@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [play-router/src/find-route.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/find-route.ts#L59)
+Defined in: [packages/play-router/src/find-route.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/find-route.ts#L58)
 
 Finds a route node by its state ID
 

package/api/@xmachines/play-router/index/functions/findRouteByPath.md

@@ -0,0 +1,48 @@
+[API](../../../../README.md) / [@xmachines/play-router](../../README.md) / [index](../README.md) / findRouteByPath
+
+# Function: findRouteByPath()
+
+```ts
+function findRouteByPath(tree, path, options?): RouteNode | undefined;
+```
+
+Defined in: [packages/play-router/src/find-route.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/find-route.ts#L96)
+
+Finds a route node by its URL path
+
+The function looks the route node up by the URL path. It gives you the state ID of
+a browser URL, for the `play.route` event of a navigation.
+
+When more than one state holds the same path, for example the root and a second
+state both at "/", the function prefers a node with a route, which means a node
+with a `meta.route` field, over a node without one.
+
+The function also matches a pattern of a dynamic route, for example
+'/settings/:section?'.
+
+## Parameters
+
+| Parameter  | Type                                                | Description                                                                                                                                                                                                                                                                                                                                                        |
+| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tree`     | [`RouteTree`](../interfaces/RouteTree.md)           | The route tree, from extractMachineRoutes                                                                                                                                                                                                                                                                                                                          |
+| `path`     | `string`                                            | The URL path, for example '/dashboard' or '/settings/profile'                                                                                                                                                                                                                                                                                                      |
+| `options?` | [`CompileOptions`](../interfaces/CompileOptions.md) | The caches that the pattern match reads. The default is the pair that `@xmachines/play-url` shares with every caller of the process. A server that serves many tenants passes a cache that the tenant owns, exactly as `RouteMap` and a bridge take one. A cache changes how often the work runs, and it changes no answer, so this argument is safe to leave out. |
+
+## Returns
+
+[`RouteNode`](../interfaces/RouteNode.md) \| `undefined`
+
+The route node, or undefined when the function finds none
+
+## Example
+
+```typescript
+const tree = extractMachineRoutes(machine);
+const node = findRouteByPath(tree, "/dashboard");
+
+// With a cache that one request owns and drops
+const node = findRouteByPath(tree, "/dashboard", {
+	patternCache: createPatternCache(),
+	compiledCache: createPatternCache(),
+});
+```