@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-dom-router/interfaces/VanillaRouter.md

@@ -1,46 +1,59 @@
 [API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / VanillaRouter
 
-# Interface: VanillaRouter\<History\>
+# Interface: VanillaRouter
 
-Defined in: [play-dom-router/src/create-router.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-router.ts#L17)
+Defined in: [play-dom-router/src/create-router.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L24)
 
-The router that [createRouter](../functions/createRouter.md) builds.
+The router that [createRouter](../functions/createRouter.md) builds and returns.
 
-The type parameter carries the history of the CALLER. `createBrowserHistory` gives a
-`DisposableBrowserHistory` back, and a bare `VanillaRouter` would widen it to
-`BrowserHistory` — so `using stop = router.history.subscribe(fn)` would refuse to
-compile through the very path the README documents. A test double that hands a plain
-function back stays a plain `BrowserHistory`, because the parameter says what it says.
+The router wraps a [BrowserHistory](BrowserHistory.md) and a `RouteTree`, and it does nothing more.
+It OWNS the history, and the history patches `window.history.pushState`, so a scope
+that drops the router without releasing it leaves the global patched. The dispose key
+lets a scope do that work:
 
-The default keeps `VanillaRouter` usable with no argument, which is what
-`connect-router.ts` writes.
-
-## Extended by
-
-- [`DisposableVanillaRouter`](DisposableVanillaRouter.md)
+```ts
+using router = createRouter({ routeTree, history });
+```
 
-## Type Parameters
+The release covers the HISTORY alone, exactly as `destroy()` always did.
+`connectRouter` hands back its own `RouterConnection`, and a scope that ends releases
+no connection for the caller: release the connection first, then the router.
 
-| Type Parameter                                            | Default type                          |
-| --------------------------------------------------------- | ------------------------------------- |
-| `History` _extends_ [`BrowserHistory`](BrowserHistory.md) | [`BrowserHistory`](BrowserHistory.md) |
+A caller that keeps `destroy()` keeps it: the two release the same work, and the
+release is idempotent because [BrowserHistory.destroy](BrowserHistory.md#destroy) is.
 
 ## Properties
 
-| Property                                    | Modifier   | Type                                                     | Description                                     | Defined in                                                                                                                                            |
-| ------------------------------------------- | ---------- | -------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-history"></a> `history`     | `readonly` | `History`                                                | The history instance                            | [play-dom-router/src/create-router.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-router.ts#L21) |
-| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | The route tree, as a reference to the structure | [play-dom-router/src/create-router.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-router.ts#L26) |
+| Property                                    | Modifier   | Type                                                           | Description                                     | Defined in                                                                                                                                            |
+| ------------------------------------------- | ---------- | -------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-history"></a> `history`     | `readonly` | [`BrowserHistory`](BrowserHistory.md)                          | The history instance                            | [play-dom-router/src/create-router.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L28) |
+| <a id="property-routetree"></a> `routeTree` | `readonly` | [`RouteTree`](../../play-router/index/interfaces/RouteTree.md) | The route tree, as a reference to the structure | [play-dom-router/src/create-router.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L33) |
 
 ## Methods
 
+### \[dispose\]()
+
+```ts
+dispose: void;
+```
+
+Defined in: [play-dom-router/src/create-router.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L41)
+
+Releases the history with [VanillaRouter.destroy](#destroy). It is idempotent.
+
+#### Returns
+
+`void`
+
+---
+
 ### destroy()
 
 ```ts
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-router.ts#L31)
+Defined in: [play-dom-router/src/create-router.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L38)
 
 Cleans up
 

package/api/@xmachines/play-dom-router/type-aliases/Cleanup.md

@@ -6,7 +6,7 @@
 type Cleanup = () => void & { [Key in DisposeKey]: () => void };
 ```
 
-Defined in: [play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L66)
+Defined in: [play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/disposable.ts#L66)
 
 The release of a subscription. A caller runs it, or a scope releases it.
 
@@ -16,12 +16,12 @@ caller inside one scope writes `using` and writes no teardown at all:
 
 ```ts
 // The explicit form. It stays correct.
-const stop = watchSignal(count, render);
+const stop = watchAtom(count, render);
 stop();
 
 // The scoped form. The scope releases it, and an exception releases it too.
 {
-	using stop = watchSignal(count, render);
+	using stop = watchAtom(count, render);
 	render(count.get());
 }
 ```
@@ -31,7 +31,7 @@ stop();
 `target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
 how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
 still calls it as a function, and a consumer that declares a lower `lib` still reads
-the type. See [DisposeKey](../../play/type-aliases/DisposeKey.md) for the second half of that.
+the type. See [DisposeKey](../../play/index/type-aliases/DisposeKey.md) for the second half of that.
 
 ## See
 

package/api/@xmachines/play-dom-router/variables/DISPOSE.md

@@ -6,7 +6,7 @@
 const DISPOSE: DisposeKey;
 ```
 
-Defined in: [play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L94)
+Defined in: [play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/disposable.ts#L94)
 
 The key that a release is stored under.
 
@@ -25,7 +25,7 @@ The type assertion states what the fallback IS. `Symbol.for` returns a plain `sy
 TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
 a `unique symbol` other than the declaration itself.
 
-This binding resolves ONE time, when the module evaluates. [asCleanup](../../play/functions/asCleanup.md) therefore
+This binding resolves ONE time, when the module evaluates. [asCleanup](../functions/asCleanup.md) therefore
 reads `Symbol.dispose` again at each call and stores the release under both keys, so a
 polyfill that installs the well-known symbol after this module evaluates still finds
 the release. A class or an object literal that writes `[DISPOSE]()` has no such second

package/api/@xmachines/play-pattern/README.md

@@ -0,0 +1,115 @@
+[API](../../README.md) / @xmachines/play-pattern
+
+# @xmachines/play-pattern
+
+The route pattern language of the XMachines Play Architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-pattern)
+
+One parse of the URLPattern pathname grammar, and the path that it builds back.
+
+## What this package is
+
+`URLPattern` is the pattern language of XMachines. This package reads a route pattern ONE time and answers every question that a router asks about it, and it writes a path back from the same parse.
+
+- **`parsePattern(pattern)`** — the parts, the params, which of them a path must fill, whether the pattern needs a match, the bucket key, the bare form, and the literal path.
+- **`buildPath(pattern, params)`** — the path that the pattern describes, with each param filled. It reports a fault through its return value, and it throws never: `reason: "missing"` for a param that needs a value and has none, and `reason: "unresolvable"` for a param that carries a value no path can hold, such as a dot segment.
+- **`getIndexKey(path)`** — the bucket key of a concrete path.
+- **`isDotSegment(segment)`** — whether a URL resolves the segment away. `buildPath` reads it, and [`@xmachines/play-url`](../play-url/README.md) reads it for a base path, so ONE definition answers for both.
+
+Both directions read the same parts, so a route that the match reads derives a URL that the match reads back.
+
+## What this package is NOT
+
+It holds no `URLPattern` API. A parse is string work and it needs no constructor, so this package carries no polyfill. [`@xmachines/play-url`](../play-url/README.md) holds the API, the base path and the params of a framework router, and it reads this package for the language.
+
+That line is why the package exists. [`@xmachines/play-xstate`](../play-xstate/README.md) BUILDS a URL and matches none, so it reads the grammar and installs no matching machinery for it.
+
+## Install
+
+```bash
+pnpm add @xmachines/play-pattern
+```
+
+Most applications install it through [`@xmachines/play-url`](../play-url/README.md), which re-exports the language whole. [`@xmachines/play-router`](../play-router/README.md) re-exports the part that a router needs: `parsePattern` and `createPatternCache`.
+
+## Usage
+
+```typescript
+import { buildPath, parsePattern } from "@xmachines/play-pattern";
+
+parsePattern("/settings/:section?").requiredNames; // []
+parsePattern("/docs/:cat-id").names; // ["cat-id"]
+
+buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
+buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
+buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
+buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", param: "name", value: ".." }
+buildPath("/files/v:version", { version: ".." }); // { ok: true, path: "/files/v.." } — the value shares the segment
+```
+
+## The grammar
+
+| form         | meaning                                                   |
+| ------------ | --------------------------------------------------------- |
+| `/users`     | a literal                                                 |
+| `:name`      | a named param, one path segment                           |
+| `:name(\d+)` | a named param with a regular expression constraint        |
+| `(\d+)`      | an anonymous param, numbered from `0`                     |
+| `*`          | an anonymous param that matches every remaining character |
+| `{…}`        | a group, which carries its own literals and params        |
+| `?` `+` `*`  | the modifier of the part before it                        |
+| `\:`         | an escape, which makes the next character a literal       |
+
+A param name of this library holds a hyphen, which URLPattern does not: `/docs/:cat-id` is ONE param named `cat-id`, and `ParsedPattern.normalized` carries the form that URLPattern compiles. The [routing guide](../../../guides/routing.md) states the divergence and which forms each direction reads.
+
+## License
+
+MIT
+
+The route pattern language of XMachines.
+
+`URLPattern` is that language, and this package reads it ONE time for each pattern.
+`parsePattern` answers every question that a router asks about a route — which params
+the pattern declares, which of them a path must fill, whether the pattern needs a match
+at all, which bucket it belongs to, and which path it matches when every optional part
+is absent. `buildPath` walks the SAME parts back into a path, so a route that the match
+reads derives a URL that the match reads back.
+
+## What this package does NOT hold
+
+The URLPattern API. A parse is string work, and it needs no constructor: this package
+therefore carries no polyfill. `@xmachines/play-url` holds the API, the base path and
+the params of a framework router, and it reads this package for the language.
+
+That line is the reason the package exists. `@xmachines/play-xstate` BUILDS a URL and
+it matches none, so it reads the grammar and it installs no matching machinery for it.
+
+## See
+
+[Routing guide](../../../guides/routing.md)
+
+## Interfaces
+
+- [GroupPart](interfaces/GroupPart.md)
+- [LiteralPart](interfaces/LiteralPart.md)
+- [ParamPart](interfaces/ParamPart.md)
+- [ParsedPattern](interfaces/ParsedPattern.md)
+- [ParseOptions](interfaces/ParseOptions.md)
+- [PatternCache](interfaces/PatternCache.md)
+- [PatternParam](interfaces/PatternParam.md)
+
+## Type Aliases
+
+- [PathBuildResult](type-aliases/PathBuildResult.md)
+- [PathParams](type-aliases/PathParams.md)
+- [PatternModifier](type-aliases/PatternModifier.md)
+- [PatternPart](type-aliases/PatternPart.md)
+
+## Functions
+
+- [buildPath](functions/buildPath.md)
+- [createPatternCache](functions/createPatternCache.md)
+- [getIndexKey](functions/getIndexKey.md)
+- [isDotSegment](functions/isDotSegment.md)
+- [parsePattern](functions/parsePattern.md)

package/api/@xmachines/play-pattern/functions/buildPath.md

@@ -0,0 +1,46 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / buildPath
+
+# Function: buildPath()
+
+```ts
+function buildPath(pattern, params?, options?): PathBuildResult;
+```
+
+Defined in: [pattern-grammar.ts:713](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L713)
+
+Builds the path that a pattern describes, with each param filled from `params`.
+
+This is the OUTBOUND half of the language, and it reads the same parse as the match.
+The walk drops an optional part that has no value TOGETHER with the `/` that the part
+absorbed, which is the prefix rule of the module comment: `/settings/:section?` builds
+`/settings`, and not `/settings/`.
+
+The function reports a fault through its return value, and it throws never. The
+`reason` field names the fault: `missing` for a param that needs a value and has none,
+and `unresolvable` for a param that carries a value no path can hold. A caller raises
+the error of its own layer — `@xmachines/play-xstate` raises `MissingRouteParamError`
+for the first one and `InvalidRouteParamError` for the second.
+
+## Parameters
+
+| Parameter  | Type                                            | Description                                                           |
+| ---------- | ----------------------------------------------- | --------------------------------------------------------------------- |
+| `pattern`  | `string`                                        | The route pattern, for example `/profile/:userId`.                    |
+| `params`   | [`PathParams`](../type-aliases/PathParams.md)   | The value of each param, keyed by the name that the pattern declares. |
+| `options?` | [`ParseOptions`](../interfaces/ParseOptions.md) | -                                                                     |
+
+## Returns
+
+[`PathBuildResult`](../type-aliases/PathBuildResult.md)
+
+The path, or the reason that stopped the walk with the param that carries it.
+
+## Example
+
+```typescript
+buildPath("/profile/:userId", { userId: "alice" }); // { ok: true, path: "/profile/alice" }
+buildPath("/settings/:section?", {}); // { ok: true, path: "/settings" }
+buildPath("/tags/c\\+\\+", {}); // { ok: true, path: "/tags/c++" }
+buildPath("/profile/:userId", {}); // { ok: false, reason: "missing", missing: "userId" }
+buildPath("/files/:name", { name: ".." }); // { ok: false, reason: "unresolvable", … }
+```

package/api/@xmachines/play-pattern/functions/createPatternCache.md

@@ -0,0 +1,47 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / createPatternCache
+
+# Function: createPatternCache()
+
+```ts
+function createPatternCache<V>(maxSize?): PatternCache<V>;
+```
+
+Defined in: [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-pattern/functions/getIndexKey.md

@@ -0,0 +1,30 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / getIndexKey
+
+# Function: getIndexKey()
+
+```ts
+function getIndexKey(path): string;
+```
+
+Defined in: [pattern-grammar.ts:201](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L201)
+
+Computes the key of the bucket index of a concrete PATH.
+
+The key is the first path segment, for example `"settings"` of `"/settings/billing"`.
+The root path `"/"` gives the key `"/"`, and a path whose first segment is EMPTY —
+`"//docs"` — gives the key `""`. The two are different keys, so a pattern that matches
+both asks [ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) for the wildcard key instead.
+
+[ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) computes the key of a PATTERN, and it calls this
+function for every pattern whose first segment is a literal. One function therefore
+answers both sides, and a pattern in the wrong bucket cannot happen.
+
+## Parameters
+
+| Parameter | Type     | Description               |
+| --------- | -------- | ------------------------- |
+| `path`    | `string` | The string of a URL path. |
+
+## Returns
+
+`string`

package/api/@xmachines/play-pattern/functions/isDotSegment.md

@@ -0,0 +1,40 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / isDotSegment
+
+# Function: isDotSegment()
+
+```ts
+function isDotSegment(segment): boolean;
+```
+
+Defined in: [pattern-grammar.ts:872](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L872)
+
+Answers whether one segment resolves away in a URL, rather than naming itself.
+
+A URL parser reads the dot segments BEFORE it decodes the percent escapes, and it counts
+`%2e` as the dot. The WHATWG URL standard names six forms, and a browser resolves every
+one of them out of a location: `.` and `%2e` for the single dot, and `..`, `.%2e`, `%2e.`
+and `%2e%2e` for the double dot. Each percent test is case-insensitive.
+
+NO encoding of `.` or `..` therefore survives. A param that carries one describes a path
+that its own pattern matches back never, so [buildPath](buildPath.md) refuses it, and
+`normalizeBasePath` of `@xmachines/play-url` refuses the same value in a base path.
+
+Give the segment in the form that the URL carries, and encode nothing here. The two
+callers reach that form by two roads, and both are correct. [buildPath](buildPath.md) encodes a
+param value first, so a value that HOLDS a percent sign arrives with that sign escaped:
+the string `"%2e"` encodes to `"%252e"`, which names itself and stays. `normalizeBasePath`
+of `@xmachines/play-url` reads a path that an author wrote, which is encoded already, so
+it passes the segment RAW and `"%2e"` there is the dot. A caller that encodes an
+already-encoded segment a second time hides every `%2e` from this test.
+
+## Parameters
+
+| Parameter | Type     | Description                                                                         |
+| --------- | -------- | ----------------------------------------------------------------------------------- |
+| `segment` | `string` | ONE path segment, with no separator around it, in the form that the URL carries it. |
+
+## Returns
+
+`boolean`
+
+`true` when a URL resolves the segment away.

package/api/@xmachines/play-pattern/functions/parsePattern.md

@@ -0,0 +1,28 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / parsePattern
+
+# Function: parsePattern()
+
+```ts
+function parsePattern(pattern, options?): ParsedPattern;
+```
+
+Defined in: [pattern-grammar.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L264)
+
+Reads a route pattern, one time for each distinct pattern.
+
+The parser reports a fault never. A pattern that it cannot read reports
+`parameterized: true` and `bareForm: null`, which sends it to the URLPattern
+constructor and keeps every derived answer on the safe side.
+
+## Parameters
+
+| Parameter  | Type                                            | Description                                        |
+| ---------- | ----------------------------------------------- | -------------------------------------------------- |
+| `pattern`  | `string`                                        | The route pattern, for example `/profile/:userId`. |
+| `options?` | [`ParseOptions`](../interfaces/ParseOptions.md) | -                                                  |
+
+## Returns
+
+[`ParsedPattern`](../interfaces/ParsedPattern.md)
+
+The parse. The caller treats it as read-only: the cache holds this object.

package/api/@xmachines/play-pattern/interfaces/GroupPart.md

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / GroupPart
+
+# Interface: GroupPart
+
+Defined in: [pattern-grammar.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L92)
+
+A `{…}` group, which carries its own parts and its own modifier.
+
+## Properties
+
+| Property                                  | Modifier   | Type                                                       | Defined in                                                                                                                         |
+| ----------------------------------------- | ---------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-kind"></a> `kind`         | `readonly` | `"group"`                                                  | [pattern-grammar.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L93) |
+| <a id="property-modifier"></a> `modifier` | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md)    | [pattern-grammar.ts:95](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L95) |
+| <a id="property-parts"></a> `parts`       | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | [pattern-grammar.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L94) |

package/api/@xmachines/play-pattern/interfaces/LiteralPart.md

@@ -0,0 +1,14 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / LiteralPart
+
+# Interface: LiteralPart
+
+Defined in: [pattern-grammar.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L59)
+
+A run of literal characters, with every escape already resolved.
+
+## Properties
+
+| Property                          | Modifier   | Type        | Description                                                     | Defined in                                                                                                                         |
+| --------------------------------- | ---------- | ----------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-kind"></a> `kind` | `readonly` | `"literal"` | -                                                               | [pattern-grammar.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L60) |
+| <a id="property-text"></a> `text` | `readonly` | `string`    | The characters that a path must carry, for example `/settings`. | [pattern-grammar.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L62) |

package/api/@xmachines/play-pattern/interfaces/ParamPart.md

@@ -0,0 +1,21 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / ParamPart
+
+# Interface: ParamPart
+
+Defined in: [pattern-grammar.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L71)
+
+A param: `:name`, `(\d+)`, or `*`.
+
+An anonymous param carries no `name`. URLPattern numbers such a group from `0`, and
+this library reports it to no machine — see [ParsedPattern.params](ParsedPattern.md#property-params).
+
+## Properties
+
+| Property                                    | Modifier   | Type                                                    | Description                                                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                                         |
+| ------------------------------------------- | ---------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-groupname"></a> `groupName` | `readonly` | `string` \| `null`                                      | The name that URLPattern compiles, with each hyphen rewritten to an underscore, or `null` for an anonymous param. The rewrite happens ONE time, here, and [ParsedPattern.normalized](ParsedPattern.md#property-normalized) carries the same characters. A caller that needs the group name of a param reads this field, and it rewrites nothing of its own. | [pattern-grammar.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L83) |
+| <a id="property-kind"></a> `kind`           | `readonly` | `"param"`                                               | -                                                                                                                                                                                                                                                                                                                                                           | [pattern-grammar.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L72) |
+| <a id="property-modifier"></a> `modifier`   | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md) | -                                                                                                                                                                                                                                                                                                                                                           | [pattern-grammar.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L88) |
+| <a id="property-name"></a> `name`           | `readonly` | `string` \| `null`                                      | The declared name, with each hyphen kept, or `null` for an anonymous param.                                                                                                                                                                                                                                                                                 | [pattern-grammar.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L74) |
+| <a id="property-prefix"></a> `prefix`       | `readonly` | `string`                                                | The `/` that the param absorbed from the literal before it, or `""`.                                                                                                                                                                                                                                                                                        | [pattern-grammar.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L87) |
+| <a id="property-regexp"></a> `regexp`       | `readonly` | `string` \| `null`                                      | The source of the constraint of `:id(\d+)`, or `null` when the param declares none.                                                                                                                                                                                                                                                                         | [pattern-grammar.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L85) |

package/api/@xmachines/play-pattern/interfaces/ParseOptions.md

@@ -0,0 +1,19 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / ParseOptions
+
+# Interface: ParseOptions
+
+Defined in: [cache.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L34)
+
+The options that every read of the pattern language takes.
+
+It is ONE field today, and it is an object rather than a positional argument so that a
+caller holds one object and hands it to every call — `parsePattern`, `buildPath`,
+`getCompiledPattern`, `findRouteByPath`, a route map and a bridge all take it, and
+`CompileOptions` and `RouteMapOptions` extend it with the caches of their own layer. A
+positional argument gave each layer a different position to remember.
+
+## Properties
+
+| Property                                           | Modifier   | Type                                                                     | Description                                                                                                              | Defined in                                                                                                     |
+| -------------------------------------------------- | ---------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| <a id="property-patterncache"></a> `patternCache?` | `readonly` | [`PatternCache`](PatternCache.md)\<[`ParsedPattern`](ParsedPattern.md)\> | The cache of the PARSE of a pattern. The default is the cache that this package shares with every caller of the process. | [cache.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/cache.ts#L40) |

package/api/@xmachines/play-pattern/interfaces/ParsedPattern.md

@@ -0,0 +1,23 @@
+[API](../../../README.md) / [@xmachines/play-pattern](../README.md) / ParsedPattern
+
+# Interface: ParsedPattern
+
+Defined in: [pattern-grammar.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L117)
+
+Everything that this library reads from one route pattern.
+
+## Properties
+
+| Property                                            | Modifier   | Type                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                           |
+| --------------------------------------------------- | ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bareform"></a> `bareForm`           | `readonly` | `string` \| `null`                                         | The path that the pattern matches when every optional part is absent, or `null` when the pattern holds a part that a path must fill. `/settings/:section?` gives `/settings`, `/a/{b}?/c` gives `/a//c`, and `/profile/:userId` gives `null`.                                                                                                                                                                                                                                           | [pattern-grammar.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L154) |
+| <a id="property-declarednames"></a> `declaredNames` | `readonly` | `ReadonlyMap`\<`string`, `string`\>                        | The map from each rewritten group name back to the name that the pattern declares, for example `cat_id` to `cat-id`. The map holds an entry only for a name that the rewrite changed. It is empty for most patterns, and a caller that reads a group name falls back to the name itself.                                                                                                                                                                                                | [pattern-grammar.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L184) |
+| <a id="property-indexkey"></a> `indexKey`           | `readonly` | `string`                                                   | The key of the bucket index: the first path segment, or `"*"` when a param can stand in the first segment.                                                                                                                                                                                                                                                                                                                                                                              | [pattern-grammar.ts:171](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L171) |
+| <a id="property-literalpath"></a> `literalPath`     | `readonly` | `string` \| `null`                                         | The ONE path that the pattern matches, with each escape resolved, or `null` when the pattern describes a SET of paths. `/users` gives `/users`, `/tags/c\+\+` gives `/tags/c++`, `/x{y}z` gives `/xyz`, and `/profile/:userId` gives `null`. A bridge writes a real browser URL from this field. The SOURCE of the pattern is no substitute for it: `/tags/c\+\+` carries two backslashes that the address bar must not hold, and a location that carries them matches the route never. | [pattern-grammar.ts:166](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L166) |
+| <a id="property-names"></a> `names`                 | `readonly` | readonly `string`[]                                        | The name of every param of [params](#property-params), in the same order. `resolveFrameworkParams` runs on EVERY navigation and it needs this list each time. The parse holds it, so a navigation allocates none. A caller that hands the array to somebody else copies it: the cache holds this one.                                                                                                                                                                                   | [pattern-grammar.ts:131](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L131) |
+| <a id="property-normalized"></a> `normalized`       | `readonly` | `string`                                                   | The pattern in the form that URLPattern compiles: each param name that holds a hyphen carries an underscore instead.                                                                                                                                                                                                                                                                                                                                                                    | [pattern-grammar.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L176) |
+| <a id="property-parameterized"></a> `parameterized` | `readonly` | `boolean`                                                  | True when the pattern needs a URLPattern match, and false when it is a literal path. A malformed pattern reports `true`, so that it reaches the URLPattern constructor and fails there with the error of the API. A parser that called it static would send it to the exact-match map instead, where it matches nothing and reports no fault.                                                                                                                                           | [pattern-grammar.ts:146](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L146) |
+| <a id="property-params"></a> `params`               | `readonly` | readonly [`PatternParam`](PatternParam.md)[]               | The NAMED params, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                          | [pattern-grammar.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L123) |
+| <a id="property-parts"></a> `parts`                 | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | The parts, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [pattern-grammar.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L121) |
+| <a id="property-requirednames"></a> `requiredNames` | `readonly` | readonly `string`[]                                        | The name of every param that a path must fill, in the order of [params](#property-params). The same rule as [names](#property-names): the parse holds the array, and a navigation reads it.                                                                                                                                                                                                                                                                                             | [pattern-grammar.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L137) |
+| <a id="property-source"></a> `source`               | `readonly` | `string`                                                   | The pattern as the caller wrote it.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [pattern-grammar.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-pattern/src/pattern-grammar.ts#L119) |