@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/play-vue-router/{variables → index/variables}/PlayRouterProvider.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / PlayRouterProvider
+[API](../../../../README.md) / [@xmachines/play-vue-router](../../README.md) / [index](../README.md) / PlayRouterProvider
 
 # Variable: PlayRouterProvider
 
@@ -7,7 +7,7 @@ const PlayRouterProvider: DefineComponent<
 	ExtractPropTypes<{
 		actor: {
 			required: true;
-			type: PropType<PlayActor>;
+			type: PropType<RoutableActor>;
 		};
 		basePath: {
 			default: undefined;
@@ -45,7 +45,7 @@ const PlayRouterProvider: DefineComponent<
 		ExtractPropTypes<{
 			actor: {
 				required: true;
-				type: PropType<PlayActor>;
+				type: PropType<RoutableActor>;
 			};
 			basePath: {
 				default: undefined;
@@ -87,7 +87,7 @@ const PlayRouterProvider: DefineComponent<
 >;
 ```
 
-Defined in: [play-vue-router/src/play-router-provider.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-vue-router/src/play-router-provider.ts#L20)
+Defined in: [packages/play-vue-router/src/play-router-provider.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-vue-router/src/play-router-provider.ts#L17)
 
 PlayRouterProvider — the Vue wrapper of VueRouterBridge.
 

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

@@ -4,17 +4,21 @@
 
 > XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with signal-driven reactivity and a router integration.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
+> **Browser floor: Chrome 110, Firefox 115, Safari 16.4.** This package calls the ES2023
+> change-by-copy array methods, so a browser below that floor throws
+> `TypeError: ... is not a function`. The root README carries the table.
+
 ## Installation
 
 ```bash
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency. Install it with this package.
+`xstate ^5.33.0` is a peer dependency. Install it with this package.
 
 ---
 
@@ -22,7 +26,8 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 
 // 1. Define your XState v5 machine
 const machine = setup({}).createMachine({
@@ -34,7 +39,7 @@ const machine = setup({}).createMachine({
 });
 
 // 2. Create a player factory
-const createPlayer = definePlayer({ machine });
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
 
 // 3. Instantiate and start an actor
 const actor = createPlayer();
@@ -129,16 +134,75 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-This concrete actor class is an XState v5 actor that also exposes reactive TC39 Signals. It implements both the `Routable` interface and the `Viewable` interface from `@xmachines/play-actor`.
+This concrete actor class is an XState v5 actor that exposes reactive TC39 Signals. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
 
 #### Signals
 
-| Signal         | Type                                   | Description                                                                                                                             |
-| -------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition                                                            |
-| `currentRoute` | `Signal.Computed<string \| null>`      | The URL that comes from the `meta.route` template of the active state and from the context                                              |
-| `currentView`  | `Signal.State<PlaySpec \| null>`       | The view spec from the `meta.view` metadata of the active state, with the context params added                                          |
-| `initialRoute` | `readonly string \| null`              | The route of the initial state of the machine. The constructor fixes it, and a router bridge uses it to detect a deep link or a restore |
+| Signal  | Type                                   | Description                                                                  |
+| ------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| `state` | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+
+### The capabilities
+
+Routing and the view are OPTIONAL, and each one is a mixin behind its own entry point. An application that declares no route loads no routing code, and an application that renders no view loads no view code and installs no json-render.
+
+Each capability package is an OPTIONAL peer dependency. Install the one that you compose:
+
+```bash
+pnpm add @xmachines/play-router   # for @xmachines/play-xstate/routing
+pnpm add @xmachines/play-view     # for @xmachines/play-xstate/view
+```
+
+The main entry point of this package names neither. `@xmachines/play-xstate/routing` also
+carries the route utilities — `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
+`formatPlayRouteTransitions` and the route types — because each one names
+`@xmachines/play-router` in its own types.
+
+| Capability | Entry point                      | Adds                           | Interface                              |
+| ---------- | -------------------------------- | ------------------------------ | -------------------------------------- |
+| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of `@xmachines/play-router` |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of `@xmachines/play-view`   |
+
+`compose` applies each capability from left to right:
+
+```typescript
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+
+// Both capabilities
+const createPlayer = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
+
+// Routing alone: `currentView` is a compile error on this actor
+const createRouted = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+
+// Neither: `state` and `send`
+const createBare = definePlayer({ machine });
+```
+
+**Compose `withView` after `withRouting`.** An override calls `super.onSnapshot()` first, so the composition order decides the derivation order: the route holds its new value before the view derives from the same transition. A router bridge therefore sees a guard redirect before a renderer sees the view of the state that the guard refused.
+
+**A lifecycle hook receives the bare actor.** `PlayerOptions` is typed before the class is composed, so it cannot name the capabilities, and a narrower hook parameter is refused under `strictFunctionTypes`. A hook that reads `currentRoute` or `currentView` reads them through a binding of the composed type:
+
+```typescript
+let composed: PlayerActor<typeof machine> & Routable & Viewable;
+
+const actor = definePlayer({
+	machine,
+	options: { onStateChange: () => console.log(composed.currentRoute.get()) },
+	actor: compose(PlayerActor, withRouting, withView),
+})();
+composed = actor;
+```
+
+| Signal         | Type                              | Capability | Description                                                                                                                              |
+| -------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentRoute` | `Signal.Computed<string \| null>` | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
+| `initialRoute` | `readonly string \| null`         | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
+| `currentView`  | `Signal.State<PlaySpec \| null>`  | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
 
 #### Methods
 
@@ -149,7 +213,7 @@ This concrete actor class is an XState v5 actor that also exposes reactive TC39
 | `send(event)`   | Sends a typed event to the machine and calls the `onTransition` hook      |
 | `can(event)`    | Returns `true` when the current state accepts the given event             |
 | `getSnapshot()` | Returns the current XState snapshot                                       |
-| `dispose()`     | The alias of `stop()`                                                     |
+| `[DISPOSE]()`   | Stops the actor at the end of a `using` scope. The release is `stop()`    |
 
 #### Signal usage example
 
@@ -168,39 +232,26 @@ actor.start();
 
 ---
 
-### Guard utilities
-
-> **Deprecated:** these guard helpers wrap the `and()`, `or()`, and `not()`
-> combinators of XState, but they do not compose with a guard slot that
-> `setup()` types. Use the combinators of XState directly. The next major
-> version removes this module.
+### Guards
 
-These composable guard helpers wrap the `and()`, `or()`, and `not()` functions of XState. Use them in a machine `setup({ guards })` definition.
+This package gives no guard utility. Compose a guard with the `and()`, `or()` and `not()` combinators of XState:
 
 ```typescript
-import { setup } from "xstate";
-import {
-	composeGuards, // AND logic: all guards must pass
-	composeGuardsOr, // OR logic:  at least one guard must pass
-	negateGuard, // NOT logic: inverts a guard
-	hasContext, // guard: context field is present and non-null
-	eventMatches, // guard: event type matches a string
-	contextFieldMatches, // guard: context field equals a value
-} from "@xmachines/play-xstate";
+import { and, not, setup } from "xstate";
 
 const machine = setup({
 	guards: {
-		isLoggedIn: ({ context }) => !!context.userId,
+		isLoggedIn: ({ context }) => context.userId !== "",
 		hasAdminRole: ({ context }) => context.role === "admin",
 	},
 }).createMachine({
 	on: {
 		accessAdmin: {
-			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
+			guard: and(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
 		accessLogin: {
-			guard: negateGuard("isLoggedIn"),
+			guard: not("isLoggedIn"),
 			target: "login",
 		},
 	},
@@ -208,6 +259,10 @@ const machine = setup({
 });
 ```
 
+A combinator resolves each name against the `guards` of `setup()`. A name that the map does not hold therefore fails to compile, and it names the fault: `Type '"typoGuardName"' is not assignable to type '"isLoggedIn"'`.
+
+`composeGuards`, `composeGuardsOr`, `negateGuard`, `hasContext`, `eventMatches` and `contextFieldMatches` stood here before. They closed two gaps of the types of XState 5.28. The peer floor of this package is `^5.33.0`, and 5.33 holds neither gap. The helpers also fitted a guard slot that `setup()` types never: the example of this package reached them through an `as never` cast. Write the combinator instead, and write a plain predicate in place of each helper.
+
 ---
 
 ### Routing utilities
@@ -220,7 +275,7 @@ This function reads each machine state that has a `meta.route` field. It then ge
 
 ```typescript
 import { setup } from "xstate";
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
@@ -251,6 +306,12 @@ const machine = setup({}).createMachine(config);
 | `isAbsoluteRoute(route)`           | Returns `true` when the route string is an absolute URL path                |
 | `buildRouteUrl(template, context)` | Replaces each `:param` placeholder of a route template with a context value |
 
+#### The release protocol
+
+`DISPOSE` comes from [`@xmachines/play`](../play/README.md), and this package re-exports
+it, because `PlayerActor` carries `[DISPOSE]`: a scope releases an actor with `using` and
+writes no teardown.
+
 ---
 
 ## Inspection
@@ -298,17 +359,75 @@ import type {
 	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // deprecated with the guard utilities — removed in the next major
-	GuardArray, // deprecated with the guard utilities — removed in the next major
-	ComposedGuard, // deprecated with the guard utilities — removed in the next major
+} from "@xmachines/play-xstate";
+
+import type {
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
-	RouteObject, // Route metadata object shape: { path: string }
+	RouteObject, // Route metadata object shape: { path, reenter?, handler?, data? }
 	RouteMetadata, // Union: string | RouteObject
-} from "@xmachines/play-xstate";
+	RouteData, // The resolved extra data of a route: Record<string, unknown>
+	RouteDataResolver, // The function form of RouteObject.data
+} from "@xmachines/play-xstate/routing";
+```
+
+`RouteObject`, `RouteMetadata`, `RouteData`, and `RouteDataResolver` have one
+definition, and it lives in `@xmachines/play-router`. `@xmachines/play-xstate/routing`
+re-exports them, so either import path gives you the same type. The MAIN entry point of
+this package re-exports them no longer: it would name an optional peer in the types of
+every consumer, including one that composes no routing.
+
+### The object form of `meta.route`
+
+The string form declares the path only. The object form declares the path and the
+behaviour of the generated `play.route` transition:
+
+```typescript
+meta: {
+	route: {
+		path: "/doc/:docId",
+		// Where the generated transition sits. The default is "root", which is what
+		// XState does: every route transition sits on the root of the machine.
+		//   "root"  — one transition on the root. A route from any state arrives.
+		//   "local" — one transition on the PARENT. The parent keeps its entry action,
+		//             and a route from outside the parent arrives NOWHERE.
+		//   "both"  — one in each place. The parent keeps its entry action, and a route
+		//             from outside the parent still arrives.
+		handler: "both",
+		// Whether the transition re-enters its OWN DOMAIN. The default is false, which
+		// is the default of XState. Under `handler: "root"` the domain is the root of
+		// the machine, so `false` spares the root alone: each ancestor between the root
+		// and the target still runs its exit and its entry actions. `handler` is the
+		// field that spares those intermediate ancestors.
+		reenter: false,
+		// The extra data of the route. The generated transition assigns it to
+		// `context.data`. A literal value, or a function of { context, event }.
+		data: { titleKey: "doc.view" },
+	},
+}
 ```
 
+An unknown `handler` value throws `InvalidRouteHandlerError` at the format time.
+
+> **Upgrading from 3.x: the `reenter` default changed, and a machine that relies on it
+> goes quiet.** An earlier release wrote `reenter: true` on EVERY generated transition,
+> so every routed state re-entered its own domain on each navigation and ran its `entry`
+> actions again. The flag is now what `meta.route` declares, and the default is `false` —
+> which is the default of XState. A state whose `entry` action must run on each
+> navigation has to declare `reenter: true` for itself. Nothing throws, and the action
+> simply stops running.
+
+The `data` field follows the `WithDynamicParams` shape of XState, so the function form
+reads the context and the event:
+
+```typescript
+data: ({ context, event }) => ({ title: `Document ${event.params?.docId}` });
+```
+
+A function does not survive `JSON.stringify`. Use the literal form for a machine that
+Stately Studio reads, or that a process sends over a wire.
+
 ---
 
 ## Error Classes
@@ -318,31 +437,16 @@ The `@xmachines/play-xstate/errors` subpath exports the error classes. The main
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // deprecated: no longer thrown
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
 	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
-	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
+	InvalidRouteHandlerError, // meta.route.handler is not "root", "local", or "both"
 } from "@xmachines/play-xstate/errors";
 ```
 
-Every error class extends `PlayError` from `@xmachines/play`. Each class also carries typed detail fields, such as `param`, `template`, and `combinator`. Your code therefore reads the details of an error, and it does not parse the message.
-
----
-
-## Testing
-
-```bash
-# Run tests for this package in isolation
-pnpm --filter @xmachines/play-xstate test
-
-# Watch mode
-pnpm --filter @xmachines/play-xstate run test:watch
-```
-
-The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/test/`.
+Every error class extends `PlayError` from `@xmachines/play/errors`. Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
 
 ---
 
@@ -350,48 +454,9 @@ The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/t
 
 MIT — see [LICENSE](LICENSE) for details.
 
-@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 signal 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 a signal-driven
-reactivity.
-
-## Classes
-
-- [PlayerActor](classes/PlayerActor.md)
-
-## Interfaces
-
-- [PlayerConfig](interfaces/PlayerConfig.md)
-- [PlayerFactoryResumeOptions](interfaces/PlayerFactoryResumeOptions.md)
-- [PlayerOptions](interfaces/PlayerOptions.md)
-- [RouteContext](interfaces/RouteContext.md)
-- [RouteObject](interfaces/RouteObject.md)
-
-## Type Aliases
-
-- [~~ComposedGuard~~](type-aliases/ComposedGuard.md)
-- [~~Guard~~](type-aliases/Guard.md)
-- [~~GuardArray~~](type-aliases/GuardArray.md)
-- [PlayerFactory](type-aliases/PlayerFactory.md)
-- [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
-- [RouteMetadata](type-aliases/RouteMetadata.md)
-- [RouteStateNode](type-aliases/RouteStateNode.md)
-
-## Functions
+## Modules
 
-- [buildRouteUrl](functions/buildRouteUrl.md)
-- [~~composeGuards~~](functions/composeGuards.md)
-- [~~composeGuardsOr~~](functions/composeGuardsOr.md)
-- [~~contextFieldMatches~~](functions/contextFieldMatches.md)
-- [definePlayer](functions/definePlayer.md)
-- [deriveRoute](functions/deriveRoute.md)
-- [~~eventMatches~~](functions/eventMatches.md)
-- [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
-- [~~hasContext~~](functions/hasContext.md)
-- [isAbsoluteRoute](functions/isAbsoluteRoute.md)
-- [~~negateGuard~~](functions/negateGuard.md)
+- [errors](errors/README.md)
+- [index](index/README.md)
+- [with-routing](with-routing/README.md)
+- [with-view](with-view/README.md)

package/api/@xmachines/play-xstate/errors/README.md

@@ -0,0 +1,13 @@
+[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / errors
+
+# errors
+
+## Classes
+
+- [ActorThrewNonErrorError](classes/ActorThrewNonErrorError.md)
+- [InvalidEventError](classes/InvalidEventError.md)
+- [InvalidMachineError](classes/InvalidMachineError.md)
+- [InvalidRouteHandlerError](classes/InvalidRouteHandlerError.md)
+- [InvalidRouteMetadataError](classes/InvalidRouteMetadataError.md)
+- [MissingRouteParamError](classes/MissingRouteParamError.md)
+- [MissingStateIdError](classes/MissingStateIdError.md)

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

@@ -0,0 +1,199 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [errors](../README.md) / ActorThrewNonErrorError
+
+# Class: ActorThrewNonErrorError
+
+Defined in: [packages/play-xstate/src/errors.ts:295](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L295)
+
+The actor gives this error to `PlayerOptions.onError` when it failed with a value
+that is not an `Error`, for example after a machine action ran
+`throw { code: 42 }`.
+
+An actor error that _is_ an `Error` reaches `onError` without a change, and it
+keeps the identity of the machine. This case alone builds a new error. The new
+error therefore carries a code that your code can match, and not a
+`String(value)` message such as `"[object Object]"`. The `cause` field holds the
+value from the throw.
+
+**Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
+
+## Example
+
+```typescript
+import { ActorThrewNonErrorError } from "@xmachines/play-xstate/errors";
+
+definePlayer({
+	machine,
+	options: {
+		onError: (actor, err) => {
+			if (err instanceof ActorThrewNonErrorError) {
+				// err.cause is the value that the machine threw
+				console.error("Machine threw a non-Error:", err.cause);
+			}
+		},
+	},
+});
+```
+
+## Extends
+
+- [`PlayError`](../../../play/errors/classes/PlayError.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new ActorThrewNonErrorError(value): ActorThrewNonErrorError;
+```
+
+Defined in: [packages/play-xstate/src/errors.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L296)
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+#### Returns
+
+`ActorThrewNonErrorError`
+
+#### 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/v4.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-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/v4.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)