@xmachines/docs 3.0.0 → 5.0.0

package/api/@xmachines/play-xstate/errors/classes/MissingRouteParamError.md

@@ -0,0 +1,199 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [errors](../README.md) / MissingRouteParamError
+
+# Class: MissingRouteParamError
+
+Defined in: [packages/play-xstate/src/errors.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L52)
+
+`buildRouteUrl()` throws this error when the context of the actor does not hold a
+necessary route parameter.
+
+Read the `param` field and the `template` field to identify the parameter that is
+absent. Your code therefore parses no `.message` string.
+
+**Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
+
+Note: `actor.currentRoute.get()` shows this error never. The route derivation
+catches it, and it returns `null` for the temporary case during a transition. The
+error leaves a direct `buildRouteUrl()` call only.
+
+## Example
+
+```typescript
+import { buildRouteUrl } from "@xmachines/play-xstate/routing";
+import { MissingRouteParamError } from "@xmachines/play-xstate/errors";
+
+try {
+	buildRouteUrl("/profile/:userId", { params: {}, query: {} });
+} catch (err) {
+	if (err instanceof MissingRouteParamError) {
+		console.error(`Missing "${err.param}" for template "${err.template}"`);
+	}
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new MissingRouteParamError(param, template): MissingRouteParamError;
+```
+
+Defined in: [packages/play-xstate/src/errors.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L59)
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `param`    | `string` |
+| `template` | `string` |
+
+#### Returns
+
+`MissingRouteParamError`
+
+#### 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-param"></a> `param`                     | `readonly` | `string`  | The name of the route parameter that was absent, for example `"userId"`.                                                                                                                                                                                                                                                                                                                                                                          | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L54) |
+| <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-template"></a> `template`               | `readonly` | `string`  | The route template that needs the absent parameter, for example `"/profile/:userId"`.                                                                                                                                                                                                                                                                                                                                                             | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L57) |
+| <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-xstate/errors/classes/MissingStateIdError.md

@@ -0,0 +1,203 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [errors](../README.md) / MissingStateIdError
+
+# Class: MissingStateIdError
+
+Defined in: [packages/play-xstate/src/errors.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L154)
+
+`formatPlayRouteTransitions()` throws this error when a state node declares a
+`meta.route` field but no explicit `id` field.
+
+Without an `id`, the function can generate no `play.route` guard that targets the
+state: the guard compares `event.to` with `#<id>`. An absent `id` therefore makes
+the state unreachable through the routing, and nothing says so. This error shows
+the fault of the configuration at the moment of the machine definition, and the
+function skips no state in silence.
+
+**Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
+
+## Example
+
+```typescript
+// Bad — a meta.route field without an id field:
+states: {
+  profile: {
+    meta: { route: "/profile/:username" },
+    // ← the id: "profile" field is absent
+  }
+}
+
+// Good:
+states: {
+  profile: {
+    id: "profile",
+    meta: { route: "/profile/:username" },
+  }
+}
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new MissingStateIdError(stateKey, route): MissingStateIdError;
+```
+
+Defined in: [packages/play-xstate/src/errors.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L160)
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `stateKey` | `string` |
+| `route`    | `string` |
+
+#### Returns
+
+`MissingStateIdError`
+
+#### 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-route"></a> `route`                     | `readonly` | `string`  | The route template of the state, for example `"/profile/:username"`.                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L158) |
+| <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-statekey"></a> `stateKey`               | `readonly` | `string`  | The state key, which is the position in the tree of the states, without an explicit `id` field.                                                                                                                                                                                                                                                                                                                                                   | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:156](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L156) |
+| <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-xstate/index/README.md

@@ -0,0 +1,38 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / index
+
+# index
+
+@xmachines/play-xstate - the XState v5 adapter of the Play Architecture
+
+This package gives you the definePlayer() API. That function binds an XState state
+machine to the actor base, with the atom lifecycle and the DevTools
+integration.
+
+The Play RFC gives this package as the adapter of the logic layer. It converts a
+declarative machine definition into a live actor with an atom-driven
+reactivity.
+
+## Classes
+
+- [PlayerActor](classes/PlayerActor.md)
+
+## Interfaces
+
+- [PlayerConfig](interfaces/PlayerConfig.md)
+- [PlayerFactoryResumeOptions](interfaces/PlayerFactoryResumeOptions.md)
+- [PlayerOptions](interfaces/PlayerOptions.md)
+
+## Type Aliases
+
+- [Capability](type-aliases/Capability.md)
+- [PlayerConstructor](type-aliases/PlayerConstructor.md)
+- [PlayerFactory](type-aliases/PlayerFactory.md)
+
+## Variables
+
+- [DISPOSE](variables/DISPOSE.md)
+
+## Functions
+
+- [compose](functions/compose.md)
+- [definePlayer](functions/definePlayer.md)