@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-url/errors/classes/InvalidRoutePatternError.md

@@ -0,0 +1,203 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [errors](../README.md) / InvalidRoutePatternError
+
+# Class: InvalidRoutePatternError
+
+Defined in: [packages/play-url/src/errors.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L45)
+
+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);
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new InvalidRoutePatternError(pattern, options?): InvalidRoutePatternError;
+```
+
+Defined in: [packages/play-url/src/errors.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L55)
+
+#### Parameters
+
+| Parameter  | Type                      | Description                                                                                                                                                                                                                         |
+| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pattern`  | `string`                  | The route pattern that URLPattern could not compile.                                                                                                                                                                                |
+| `options?` | `ErrorOptions` & `object` | 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. |
+
+#### Returns
+
+`InvalidRoutePatternError`
+
+#### Overrides
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`constructor`](../../../play/errors/classes/PlayError.md#constructor)
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                         |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/PlayError.md#property-cause)                     | -                                                                                                                                  |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76)         |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                  |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/PlayError.md#property-name)                       | -                                                                                                                                  |
+| <a id="property-pattern"></a> `pattern`                 | `readonly` | `string`  | The string of the route pattern. URLPattern could not compile it.                                                                                                                                                                                                                                                                                                                                                                                 | -                                                                                                                                                | [packages/play-url/src/errors.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L47) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66)         |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/PlayError.md#property-stack)                     | -                                                                                                                                  |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                  |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: `@types/node`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`captureStackTrace`](../../../play/errors/classes/PlayError.md#capturestacktrace)
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Defined in: `typescript`
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`isError`](../../../play/errors/classes/PlayError.md#iserror)
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: `@types/node`
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`prepareStackTrace`](../../../play/errors/classes/PlayError.md#preparestacktrace)

package/api/@xmachines/play-url/errors/classes/MissingBasePathParamError.md

@@ -0,0 +1,199 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [errors](../README.md) / MissingBasePathParamError
+
+# Class: MissingBasePathParamError
+
+Defined in: [packages/play-url/src/errors.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L141)
+
+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}`);
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new MissingBasePathParamError(param, basePath): MissingBasePathParamError;
+```
+
+Defined in: [packages/play-url/src/errors.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L147)
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `param`    | `string` |
+| `basePath` | `string` |
+
+#### Returns
+
+`MissingBasePathParamError`
+
+#### Overrides
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`constructor`](../../../play/errors/classes/PlayError.md#constructor)
+
+## Properties
+
+| Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                           |
+| ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-basepath"></a> `basePath`               | `readonly` | `string`  | The `basePath` option that declares the param.                                                                                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                                                | [packages/play-url/src/errors.ts:145](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L145) |
+| <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/PlayError.md#property-cause)                     | -                                                                                                                                    |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76)           |
+| <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                    |
+| <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/PlayError.md#property-name)                       | -                                                                                                                                    |
+| <a id="property-param"></a> `param`                     | `readonly` | `string`  | The name of the `:param` segment without a value, and without its `:`.                                                                                                                                                                                                                                                                                                                                                                            | -                                                                                                                                                | [packages/play-url/src/errors.ts:143](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/errors.ts#L143) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66)           |
+| <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/PlayError.md#property-stack)                     | -                                                                                                                                    |
+| <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                    |
+
+## Methods
+
+### captureStackTrace()
+
+```ts
+static captureStackTrace(targetObject, constructorOpt?): void;
+```
+
+Defined in: `@types/node`
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack; // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+	b();
+}
+
+function b() {
+	c();
+}
+
+function c() {
+	// Create an error without stack trace to avoid calculating the stack trace twice.
+	const { stackTraceLimit } = Error;
+	Error.stackTraceLimit = 0;
+	const error = new Error();
+	Error.stackTraceLimit = stackTraceLimit;
+
+	// Capture the stack trace above function b
+	Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+	throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+| Parameter         | Type       |
+| ----------------- | ---------- |
+| `targetObject`    | `object`   |
+| `constructorOpt?` | `Function` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`captureStackTrace`](../../../play/errors/classes/PlayError.md#capturestacktrace)
+
+---
+
+### isError()
+
+```ts
+static isError(error): error is Error;
+```
+
+Defined in: `typescript`
+
+Indicates whether the argument provided is a built-in Error instance or not.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `error`   | `unknown` |
+
+#### Returns
+
+`error is Error`
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`isError`](../../../play/errors/classes/PlayError.md#iserror)
+
+---
+
+### prepareStackTrace()
+
+```ts
+static prepareStackTrace(err, stackTraces): any;
+```
+
+Defined in: `@types/node`
+
+#### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `err`         | `Error`      |
+| `stackTraces` | `CallSite`[] |
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`PlayError`](../../../play/errors/classes/PlayError.md).[`prepareStackTrace`](../../../play/errors/classes/PlayError.md#preparestacktrace)

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

@@ -0,0 +1,72 @@
+[API](../../../README.md) / [@xmachines/play-url](../README.md) / index
+
+# index
+
+@xmachines/play-url - the URL language of the Play Architecture
+
+`URLPattern` is the pattern language of XMachines, and this package reads it in ONE
+place: the parser, the compilation of a pattern against the native API or the polyfill,
+a base path with its `:param` substitution, and the normalization of the params that a
+framework router reports.
+
+It knows nothing of a state machine, of a route tree, or of a router bridge. Those live
+in `@xmachines/play-router`, which reads this package.
+
+The package exists because BOTH directions need the grammar. A URL becomes a state
+through the match of `@xmachines/play-router`, and a state becomes a URL through
+`buildPath` of this package, which the routing capability of `@xmachines/play-xstate`
+calls. `parsePattern` answers both directions, and one walk of its parts writes the
+path that another reads back.
+
+## See
+
+[Routing guide](../../../../guides/routing.md)
+
+## Interfaces
+
+- [BasePathOptions](interfaces/BasePathOptions.md)
+- [CompileOptions](interfaces/CompileOptions.md)
+- [FrameworkParamsSource](interfaces/FrameworkParamsSource.md)
+- [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)
+- [ResolvedBasePath](interfaces/ResolvedBasePath.md)
+- [SplitLocation](interfaces/SplitLocation.md)
+
+## Type Aliases
+
+- [PathBuildResult](type-aliases/PathBuildResult.md)
+- [PathParams](type-aliases/PathParams.md)
+- [PatternModifier](type-aliases/PatternModifier.md)
+- [PatternPart](type-aliases/PatternPart.md)
+- [URLPatternCtor](type-aliases/URLPatternCtor.md)
+- [URLPatternLike](type-aliases/URLPatternLike.md)
+
+## Variables
+
+- [NO\_BASE\_PATH](variables/NO_BASE_PATH.md)
+- [URLPattern](variables/URLPattern.md)
+
+## Functions
+
+- [buildPath](functions/buildPath.md)
+- [cleanFrameworkParams](functions/cleanFrameworkParams.md)
+- [createPatternCache](functions/createPatternCache.md)
+- [getCandidates](functions/getCandidates.md)
+- [getCompiledPattern](functions/getCompiledPattern.md)
+- [getIndexKey](functions/getIndexKey.md)
+- [holdsUnsubstitutedParam](functions/holdsUnsubstitutedParam.md)
+- [isDotSegment](functions/isDotSegment.md)
+- [joinBasePath](functions/joinBasePath.md)
+- [normalizeBasePath](functions/normalizeBasePath.md)
+- [parsePattern](functions/parsePattern.md)
+- [pickOwnParams](functions/pickOwnParams.md)
+- [resolveBasePath](functions/resolveBasePath.md)
+- [resolveFrameworkParams](functions/resolveFrameworkParams.md)
+- [sanitizePathname](functions/sanitizePathname.md)
+- [splitLocation](functions/splitLocation.md)
+- [stripBasePath](functions/stripBasePath.md)

package/api/@xmachines/play-url/index/functions/buildPath.md

@@ -0,0 +1,46 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / buildPath
+
+# Function: buildPath()
+
+```ts
+function buildPath(pattern, params?, options?): PathBuildResult;
+```
+
+Defined in: [packages/play-pattern/src/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-url/index/functions/cleanFrameworkParams.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / cleanFrameworkParams
+
+# Function: cleanFrameworkParams()
+
+```ts
+function cleanFrameworkParams(params): Record<string, string>;
+```
+
+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.
+
+Every framework reports a param that its own route DECLARES and that the location
+did not fill: Vue Router gives `undefined` or `""`, and SolidJS Router does the
+same. Such an entry is not an answer, and a pick that kept it would send an empty
+value to the actor as though the path carried one. Drop it here instead, one time,
+because the rule belongs to the decision of [resolveFrameworkParams](resolveFrameworkParams.md) and not
+to a bridge: `VueRouterBridge` and `SolidRouterBridge` held one copy each.
+
+A value of an array — the splat of a catch-all route of Vue Router — becomes its
+`String()` form, exactly as a single value does.
+
+The result has a null prototype, for the same reason [pickOwnParams](pickOwnParams.md) gives: a
+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, for a route the framework had answered already.
+
+## Parameters
+
+| Parameter | Type                            | Description                             |
+| --------- | ------------------------------- | --------------------------------------- |
+| `params`  | `Record`\<`string`, `unknown`\> | The raw params of the framework router. |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The params with no absent value, each one a string.

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

@@ -0,0 +1,47 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../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-url/index/functions/getCandidates.md

@@ -0,0 +1,29 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getCandidates
+
+# Function: getCandidates()
+
+```ts
+function getCandidates<T>(patternBuckets, indexKey): T[];
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:214](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/url-pattern-utils.ts#L214)
+
+Joins the bucket of the named segment and the wildcard bucket of one index key.
+The order of the insertion stays, through the `order` field.
+
+## Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `T` _extends_ `object` |
+
+## Parameters
+
+| Parameter        | Type                     | Description                                              |
+| ---------------- | ------------------------ | -------------------------------------------------------- |
+| `patternBuckets` | `Map`\<`string`, `T`[]\> | The map from a bucket key to its ordered pattern entries |
+| `indexKey`       | `string`                 | The key of the first segment, from `getIndexKey`         |
+
+## Returns
+
+`T`[]