@xmachines/docs 3.0.0 → 4.0.0

package/api/@xmachines/play-xstate/index/classes/PlayerActor.md

@@ -0,0 +1,584 @@
+[API](../../../../README.md) / [@xmachines/play-xstate](../../README.md) / [index](../README.md) / PlayerActor
+
+# Class: PlayerActor\<TMachine\>
+
+Defined in: [packages/play-xstate/src/player-actor.ts:160](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L160)
+
+The concrete XState actor. It implements the signal protocol of the Play Architecture
+
+The class extends the `Actor` class of XState directly, and it implements
+[@xmachines/play-actor!PlayActor](../../../play-actor/interfaces/PlayActor.md). It gives you the XState v5 integration, and it keeps the
+compatibility with the ecosystem, such as the XState inspection and the devtools.
+The constructor of the base class receives the machine. Therefore a `PlayerActor`
+**is** the XState actor, and it is no wrapper around one: every member of the
+XState `Actor` class works on the state of this instance, and this class adds the
+reactive state on the TC39 Signals for the observation by the infrastructure.
+
+**Capabilities:** the class implements both the
+[@xmachines/play-router!index.Routable](../../../play-router/index/interfaces/Routable.md) interface and the
+[@xmachines/play-view!index.Viewable](../../../play-view/index/interfaces/Viewable.md) interface. It therefore supports the
+routing and the view rendering.
+
+**Architectural context:** the class implements **Actor Authority (INV-01)**,
+because the guards of the XState machine control every decision of the
+navigation. The infrastructure observes the signals of the actor (`state`,
+`currentRoute`, and `currentView`), but it changes no state directly: every
+change goes through the event handlers of the state machine.
+
+## Examples
+
+The creation of an actor, and its lifecycle
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+
+const machine = setup({}).createMachine({
+	initial: "idle",
+	states: {
+		idle: {
+			meta: {
+				route: "/",
+				// A view spec needs `root` and `elements`. Every other shape derives null.
+				view: {
+					root: "home",
+					elements: { home: { type: "HomePage", props: {}, children: [] } },
+				},
+			},
+		},
+	},
+});
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
+// Observe the signals
+console.log(actor.currentRoute.get()); // '/'
+console.log(actor.currentView.get()?.root); // 'home'
+```
+
+The signal lifecycle with a watcher
+
+```typescript
+import { Signal } from "@xmachines/play-signals";
+
+const watcher = new Signal.subtle.Watcher(() => {
+	queueMicrotask(() => {
+		const pending = watcher.getPending();
+		console.log("State changed:", actor.state.get());
+	});
+});
+
+watcher.watch(actor.state);
+actor.send({ type: "play.route", to: "#about" });
+// The watcher schedules its own notification in a microtask
+```
+
+## See
+
+- [Play RFC](../../../../../rfc/play.md)
+- [definePlayer](../functions/definePlayer.md) for the creation through a factory
+- [@xmachines/play-actor!PlayActor](../../../play-actor/interfaces/PlayActor.md) for the signal protocol
+- [@xmachines/play-router!index.Routable](../../../play-router/index/interfaces/Routable.md) for the routing capability
+- [@xmachines/play-view!index.Viewable](../../../play-view/index/interfaces/Viewable.md) for the view rendering capability
+
+## Remarks
+
+**The routing:** this actor supports the `route: {}` config pattern of XState and
+also a `play.route` event with parameters. The `deriveRoute()` function reads
+`meta.route`, which is the Stately pattern, for a URL template, and it substitutes
+each parameter.
+
+**The pattern of the view signal:** the `currentView` signal is a direct
+`Signal.State`, and not a `Signal.Computed`. The propagation to a watcher in
+PlayRenderer is therefore correct. The class derives each view at the entry of a
+state and keeps it, and it computes no view on a read.
+
+## Extends
+
+- [`Actor`](https://www.jsdocs.io/package/xstate#Actor)\<`TMachine`\>
+
+## Type Parameters
+
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
+
+## Implements
+
+- [`PlayActor`](../../../play-actor/interfaces/PlayActor.md)\<`ReturnType`\<`TMachine`\[`"transition"`\]\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\>\>
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlayerActor<TMachine>(
+   machine,
+   options,
+   input?,
+   restoredSnapshot?
+): PlayerActor<TMachine>;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L258)
+
+#### Parameters
+
+| Parameter           | Type                                                                        |
+| ------------------- | --------------------------------------------------------------------------- |
+| `machine`           | `TMachine`                                                                  |
+| `options`           | [`PlayerOptions`](../interfaces/PlayerOptions.md)\<`TMachine`\>             |
+| `input?`            | [`InputFrom`](https://www.jsdocs.io/package/xstate#InputFrom)\<`TMachine`\> |
+| `restoredSnapshot?` | [`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>    |
+
+#### Returns
+
+`PlayerActor`\<`TMachine`\>
+
+#### Overrides
+
+```ts
+Actor<TMachine>.constructor
+```
+
+## Properties
+
+| Property                                    | Modifier | Type                                                                                                                                                                                                                                                                                                                     | Description                                                                                                                                                                                               | Inherited from    | Defined in                                                                                                                                             |
+| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-_parent"></a> `_parent?`    | `public` | [`AnyActorRef`](https://www.jsdocs.io/package/xstate#AnyActorRef)                                                                                                                                                                                                                                                        | -                                                                                                                                                                                                         | `Actor._parent`   | -                                                                                                                                                      |
+| <a id="property-clock"></a> `clock`         | `public` | [`Clock`](https://www.jsdocs.io/package/xstate#Clock)                                                                                                                                                                                                                                                                    | The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.                                                                                                  | `Actor.clock`     | -                                                                                                                                                      |
+| <a id="property-id"></a> `id`               | `public` | `string`                                                                                                                                                                                                                                                                                                                 | The unique identifier for this actor relative to its parent.                                                                                                                                              | `Actor.id`        | -                                                                                                                                                      |
+| <a id="property-logic"></a> `logic`         | `public` | `TMachine`                                                                                                                                                                                                                                                                                                               | -                                                                                                                                                                                                         | `Actor.logic`     | -                                                                                                                                                      |
+| <a id="property-options"></a> `options`     | `public` | `Readonly`\<[`ActorOptions`](https://www.jsdocs.io/package/xstate#ActorOptions)\<`TLogic`\>\>                                                                                                                                                                                                                            | -                                                                                                                                                                                                         | `Actor.options`   | -                                                                                                                                                      |
+| <a id="property-ref"></a> `ref`             | `public` | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TMachine`\>\> | -                                                                                                                                                                                                         | `Actor.ref`       | -                                                                                                                                                      |
+| <a id="property-sessionid"></a> `sessionId` | `public` | `string`                                                                                                                                                                                                                                                                                                                 | The globally unique process ID for this invocation.                                                                                                                                                       | `Actor.sessionId` | -                                                                                                                                                      |
+| <a id="property-src"></a> `src`             | `public` | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                                     | -                                                                                                                                                                                                         | `Actor.src`       | -                                                                                                                                                      |
+| <a id="property-state"></a> `state`         | `public` | [`State`](../../../play-signals/namespaces/Signal/classes/State.md)\<`ReturnType`\<`TMachine`\[`"transition"`\]\>\>                                                                                                                                                                                                      | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | -                 | [packages/play-xstate/src/player-actor.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L224) |
+| <a id="property-system"></a> `system`       | `public` | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                                  | The system to which this actor belongs.                                                                                                                                                                   | `Actor.system`    | -                                                                                                                                                      |
+| <a id="property-systemid"></a> `systemId`   | `public` | `string` \| `undefined`                                                                                                                                                                                                                                                                                                  | -                                                                                                                                                                                                         | `Actor.systemId`  | -                                                                                                                                                      |
+
+## Methods
+
+### \[dispose\]()
+
+```ts
+dispose: void;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:611](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L611)
+
+Stops the actor when the scope of a `using` declaration ends.
+
+The actor is a `Disposable`, so a scope that owns one writes no teardown:
+
+```ts
+{
+	using actor = definePlayer({ machine })();
+	actor.start();
+	actor.send({ type: "go" });
+	// stop() runs here, and it runs even when send() throws
+}
+```
+
+The release is [stop](#stop), which is synchronous and idempotent. `Disposable` and
+not `AsyncDisposable`: a `Disposable` serves `using` AND `await using`, while an
+`AsyncDisposable` raises a TypeError under a plain `using`.
+
+The key is `DISPOSE` of `@xmachines/play` and not a bare `Symbol.dispose`, so that
+the method still answers a `using` that a bundler downlevelled for a target without
+the well-known symbol.
+
+#### Returns
+
+`void`
+
+---
+
+### \[observable\]()
+
+```ts
+observable: InteropSubscribable<SnapshotFrom<TMachine>>;
+```
+
+Defined in: `xstate`
+
+#### Returns
+
+[`InteropSubscribable`](https://www.jsdocs.io/package/xstate#InteropSubscribable)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\>
+
+#### Inherited from
+
+```ts
+Actor.[observable]
+```
+
+---
+
+### can()
+
+```ts
+can(event): boolean;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L237)
+
+Tells you if the current state of the actor accepts the given event.
+
+The type is the event union of the machine. An unknown event type is therefore a
+compile error. The method evaluates the event against the snapshot signal.
+
+#### Parameters
+
+| Parameter | Type                                                                                  |
+| --------- | ------------------------------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> |
+
+#### Returns
+
+`boolean`
+
+#### Example
+
+```typescript
+if (actor.can({ type: "auth.logout" })) { ... }
+```
+
+---
+
+### getPersistedSnapshot()
+
+```ts
+getPersistedSnapshot(options?): Snapshot<unknown>;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:562](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L562)
+
+Returns the persisted snapshot of this actor.
+
+Use it to serialize the state, and to restore it later with the
+`restore.snapshot` option of the factory.
+
+#### Parameters
+
+| Parameter  | Type      |
+| ---------- | --------- |
+| `options?` | `unknown` |
+
+#### Returns
+
+[`Snapshot`](https://www.jsdocs.io/package/xstate#Snapshot)\<`unknown`\>
+
+#### Overrides
+
+```ts
+Actor.getPersistedSnapshot;
+```
+
+---
+
+### getSnapshot()
+
+```ts
+getSnapshot(): SnapshotFrom<TMachine>;
+```
+
+Defined in: `xstate`
+
+Read an actor’s snapshot synchronously.
+
+#### Returns
+
+[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>
+
+#### Remarks
+
+The snapshot represent an actor's last emitted value.
+
+When an actor receives an event, its internal state may change. An actor
+may emit a snapshot when a state transition occurs.
+
+Note that some actors, such as callback actors generated with
+`fromCallback`, will not emit snapshots.
+
+#### See
+
+- [Actor.subscribe](https://www.jsdocs.io/package/xstate#Actor.subscribe) to subscribe to an actor’s snapshot values.
+- [Actor.getPersistedSnapshot](https://www.jsdocs.io/package/xstate#Actor.getPersistedSnapshot) to persist the internal state of an actor (which is more than just a snapshot).
+
+#### Inherited from
+
+```ts
+Actor.getSnapshot;
+```
+
+---
+
+### on()
+
+```ts
+on<TType>(type, handler): Subscription;
+```
+
+Defined in: `xstate`
+
+#### Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `TType` _extends_ `any` |
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `type`    | `TType`               |
+| `handler` | (`emitted`) => `void` |
+
+#### Returns
+
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
+
+#### Inherited from
+
+```ts
+Actor.on;
+```
+
+---
+
+### select()
+
+```ts
+select<TSelected>(selector, equalityFn?): Readable<TSelected>;
+```
+
+Defined in: `xstate`
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TSelected`    |
+
+#### Parameters
+
+| Parameter     | Type                        |
+| ------------- | --------------------------- |
+| `selector`    | (`snapshot`) => `TSelected` |
+| `equalityFn?` | (`a`, `b`) => `boolean`     |
+
+#### Returns
+
+`Readable`\<`TSelected`\>
+
+#### Inherited from
+
+```ts
+Actor.select;
+```
+
+---
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L439)
+
+Sends an event to this actor.
+
+The guards of the state machine of the actor decide if the event causes a
+transition. Give any event of the event union of the machine: a domain event, a
+routing event, and so on.
+
+#### Parameters
+
+| Parameter | Type                                                                                  | Description                                                      |
+| --------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `event`   | [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TMachine`\> | An event of the `EventFromLogic<TMachine>` union of the machine. |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+When `event` is not a plain object, for example
+`null`, `undefined`, a string, or a number. Import the class from
+`@xmachines/play-xstate/errors`.
+
+#### Example
+
+```typescript
+// A domain event, with the type of the event union of the machine
+actor.send({ type: "auth.login", userId: "123" });
+
+// A routing event
+actor.send({ type: "play.route", to: "#home" });
+```
+
+#### Implementation of
+
+[`PlayActor`](../../../play-actor/interfaces/PlayActor.md).[`send`](../../../play-actor/interfaces/PlayActor.md#send)
+
+#### Overrides
+
+```ts
+Actor.send;
+```
+
+---
+
+### start()
+
+```ts
+start(): this;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:365](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L365)
+
+Starts the actor.
+
+The method fires `onStart` on each real start, which is every transition from
+"not running" to "running". A start after a stop is such a transition, and XState
+permits it: its own `start()` stops only while the actor RUNS already. A second
+call while the actor runs fires no hook. Therefore a defensive double mount runs
+the side effects of `onStart` one time for one real start.
+
+#### Returns
+
+`this`
+
+#### Overrides
+
+```ts
+Actor.start;
+```
+
+---
+
+### stop()
+
+```ts
+stop(): this;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L395)
+
+Stops the actor and cleans up.
+
+The method fires `onStop` only when the actor ran. This matches XState, where a
+stop of an actor that never started, or of an actor that stopped already, does
+nothing and tears nothing down. Therefore the paired cleanup runs never two
+times, and it runs never against a resource that `onStart` did not take. A stop
+does not close the actor for ever: a later `start()` is a new lifecycle, and it
+fires `onStart` again.
+
+#### Returns
+
+`this`
+
+#### Overrides
+
+```ts
+Actor.stop;
+```
+
+---
+
+### subscribe()
+
+#### Call Signature
+
+```ts
+subscribe(observer): Subscription;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:500](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L500)
+
+Subscribes to the snapshot updates of this actor.
+
+The method accepts an observer object, exactly like `Actor.subscribe` of XState.
+
+##### Parameters
+
+| Parameter  | Type                                                                                                                                             | Description                                                        |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `observer` | [`Observer`](https://www.jsdocs.io/package/xstate#Observer)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TMachine`\>\> | The observer, with a `next`, an `error`, and a `complete` handler. |
+
+##### Returns
+
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
+
+The subscription, with an `unsubscribe()` method.
+
+##### Overrides
+
+```ts
+Actor.subscribe;
+```
+
+#### Call Signature
+
+```ts
+subscribe(
+   nextListener?,
+   errorListener?,
+   completeListener?
+): Subscription;
+```
+
+Defined in: [packages/play-xstate/src/player-actor.ts:511](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/player-actor.ts#L511)
+
+Subscribes to the snapshot updates of this actor.
+
+The method accepts listener functions, exactly like `Actor.subscribe` of XState.
+
+##### Parameters
+
+| Parameter           | Type                   | Description                                                                      |
+| ------------------- | ---------------------- | -------------------------------------------------------------------------------- |
+| `nextListener?`     | (`snapshot`) => `void` | The listener function of each snapshot.                                          |
+| `errorListener?`    | (`error`) => `void`    | The actor calls it on an error.                                                  |
+| `completeListener?` | () => `void`           | The actor calls it when it completes, which means that it reaches a final state. |
+
+##### Returns
+
+[`Subscription`](https://www.jsdocs.io/package/xstate#Subscription)
+
+The subscription, with an `unsubscribe()` method.
+
+##### Overrides
+
+```ts
+Actor.subscribe;
+```
+
+---
+
+### toJSON()
+
+```ts
+toJSON(): object;
+```
+
+Defined in: `xstate`
+
+#### Returns
+
+`object`
+
+| Name           | Type     | Defined in |
+| -------------- | -------- | ---------- |
+| `id`           | `string` | -          |
+| `xstate$$type` | `number` | -          |
+
+#### Inherited from
+
+```ts
+Actor.toJSON;
+```