@xmachines/play-actor 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +22 -10
  2. package/dist/abstract-actor.d.ts +16 -0
  3. package/dist/abstract-actor.d.ts.map +1 -1
  4. package/dist/abstract-actor.js +8 -0
  5. package/dist/abstract-actor.js.map +1 -1
  6. package/package.json +9 -11
package/README.md CHANGED
@@ -1,9 +1,10 @@
1
- <!-- generated-by: gsd-doc-writer -->
2
-
3
1
  # @xmachines/play-actor
4
2
 
5
3
  Abstract Actor base class for XMachines Play Architecture.
6
4
 
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
7
+
7
8
  Part of the [xmachines-js monorepo](../../README.md).
8
9
 
9
10
  ## Installation
@@ -45,19 +46,30 @@ Concrete implementations are created by adapters such as [`@xmachines/play-xstat
45
46
 
46
47
  Abstract base class extending XState `Actor<TLogic>`.
47
48
 
49
+ A subclass **is** the actor: hand the logic and its options to `super()` so one
50
+ instance holds the running machine, and reach XState's own `send` through the
51
+ prototype — `send` is declared abstract here only to narrow the event type, and
52
+ TypeScript forbids `super` calls to an abstract member.
53
+
48
54
  ```ts
49
55
  import { AbstractActor } from "@xmachines/play-actor";
50
56
  import { Signal } from "@xmachines/play-signals";
51
- import type { AnyActorLogic } from "xstate";
57
+ import { Actor, type ActorOptions, type AnyActorLogic } from "xstate";
52
58
 
53
59
  class MyActor extends AbstractActor<AnyActorLogic> {
54
60
  // Required: reactive state signal
55
- state = new Signal.State({});
61
+ state: Signal.State<unknown>;
62
+
63
+ constructor(logic: AnyActorLogic, options?: ActorOptions<AnyActorLogic>) {
64
+ super(logic, options);
65
+ this.state = new Signal.State(this.getSnapshot());
66
+ super.subscribe((snapshot) => this.state.set(snapshot));
67
+ }
56
68
 
57
69
  // Required: typed event dispatch
58
- send = (event: { type: string }) => {
59
- /* dispatch to XState */
60
- };
70
+ override send(event: { type: string }): void {
71
+ Actor.prototype.send.call(this, event);
72
+ }
61
73
  }
62
74
  ```
63
75
 
@@ -69,9 +81,9 @@ type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout
69
81
  class AuthActor extends AbstractActor<AnyActorLogic, AuthEvent> {
70
82
  state = new Signal.State({ isAuthenticated: false, username: null });
71
83
 
72
- send = (event: AuthEvent) => {
73
- /* dispatch */
74
- };
84
+ override send(event: AuthEvent): void {
85
+ Actor.prototype.send.call(this, event);
86
+ }
75
87
  }
76
88
  ```
77
89
 
package/dist/abstract-actor.d.ts CHANGED
@@ -163,6 +163,14 @@ export interface BaseActorProviderProps<TRegistry extends {
163
163
  * tooling (devtools, inspection) while exposing reactive signals for
164
164
  * Infrastructure layer communication.
165
165
  *
166
+ * **A subclass IS the actor.** Forward the logic *and* its options to
167
+ * `super(logic, options)`, then observe `this`. Holding a separately
168
+ * constructed actor alongside leaves this instance running as an empty second
169
+ * actor, and every inherited member — `system`, `sessionId`, `clock`, the
170
+ * internal `_send` that receives `sendTo()` traffic, and anything a future
171
+ * XState version adds — answers from that empty one until it is individually
172
+ * forwarded.
173
+ *
166
174
  * @typeParam TLogic - XState actor logic type
167
175
  * @typeParam TEvent - Event type constraint (defaults to EventObject)
168
176
  */
@@ -178,6 +186,14 @@ export declare abstract class AbstractActor<TLogic extends AnyActorLogic, TEvent
178
186
  * Send event to Actor.
179
187
  *
180
188
  * Constrained to TEvent for type safety in concrete implementations.
189
+ *
190
+ * Note for implementations that wrap `send` (validating the event, or
191
+ * notifying hooks around it): this declaration is abstract purely to narrow
192
+ * the event type, and TypeScript forbids `super` calls to an abstract
193
+ * member. Reach XState's own implementation with
194
+ * `Actor.prototype.send.call(this, event)` instead. Making this concrete
195
+ * would allow `super.send()` but would force every existing subclass to add
196
+ * an `override` modifier — a breaking change for adapters outside this repo.
181
197
  */
182
198
  abstract send(event: TEvent): void;
183
199
  }
package/dist/abstract-actor.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,QAAQ,SAAS,MAAM,EAChD,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,GAAG;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7D,GACC,QAAQ,CAEV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,uDAAuD;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,gHAAgH;IAChH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,6EAA6E;IAC7E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uGAAuG;IACvG,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;OAIG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}
1
+ {"version":3,"file":"abstract-actor.d.ts","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EACX,IAAI,EACJ,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,MAAM,6BAA6B,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,QAAQ,SAAS,MAAM,EAChD,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,GAAG;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7D,GACC,QAAQ,CAEV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,MAAM;IAC7D,sCAAsC;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,uDAAuD;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,gHAAgH;IAChH,KAAK,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAA;CAAE;IAE/E,6EAA6E;IAC7E,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC;IAC/C,uGAAuG;IACvG,cAAc,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,aAAa,CAClC,MAAM,SAAS,aAAa,EAC5B,MAAM,SAAS,WAAW,GAAG,WAAW,CACvC,SAAQ,KAAK,CAAC,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAgB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;OAYG;aACsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAClD"}
package/dist/abstract-actor.js CHANGED
@@ -56,6 +56,14 @@ export function typedSpec(spec) {
56
56
  * tooling (devtools, inspection) while exposing reactive signals for
57
57
  * Infrastructure layer communication.
58
58
  *
59
+ * **A subclass IS the actor.** Forward the logic *and* its options to
60
+ * `super(logic, options)`, then observe `this`. Holding a separately
61
+ * constructed actor alongside leaves this instance running as an empty second
62
+ * actor, and every inherited member — `system`, `sessionId`, `clock`, the
63
+ * internal `_send` that receives `sendTo()` traffic, and anything a future
64
+ * XState version adds — answers from that empty one until it is individually
65
+ * forwarded.
66
+ *
59
67
  * @typeParam TLogic - XState actor logic type
60
68
  * @typeParam TEvent - Event type constraint (defaults to EventObject)
61
69
  */
package/dist/abstract-actor.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAuCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAiFD;;;;;;;;;GASG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAetB"}
1
+ {"version":3,"file":"abstract-actor.js","sourceRoot":"","sources":["../src/abstract-actor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,EAAwC,MAAM,QAAQ,CAAC;AAuCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,SAAS,CACxB,IAEC;IAED,OAAO,IAAgB,CAAC;AACzB,CAAC;AAiFD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,aAGpB,SAAQ,KAAa;CAuBtB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xmachines/play-actor",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "private": false,
5
5
  "description": "Abstract Actor base class for XMachines Play Architecture",
6
6
  "keywords": [
@@ -23,9 +23,9 @@
23
23
  "LICENSE"
24
24
  ],
25
25
  "type": "module",
26
+ "sideEffects": false,
26
27
  "exports": {
27
28
  ".": {
28
- "source": "./src/index.ts",
29
29
  "types": "./dist/index.d.ts",
30
30
  "import": "./dist/index.js"
31
31
  }
@@ -40,24 +40,22 @@
40
40
  "lint": "oxlint .",
41
41
  "lint:fix": "oxlint --fix .",
42
42
  "format": "oxfmt .",
43
- "format:check": "oxfmt --check .",
44
- "prepublishOnly": "npm run build"
43
+ "format:check": "oxfmt --check ."
45
44
  },
46
45
  "dependencies": {
47
46
  "@xmachines/json-render-core": "^0.19.0-xm.2"
48
47
  },
49
48
  "devDependencies": {
50
49
  "@testing-library/jest-dom": "^6.9.1",
51
- "@types/node": "^26.1.1",
52
- "@xmachines/shared": "1.0.0",
53
- "oxfmt": "^0.58.0",
54
- "oxlint": "^1.73.0",
55
- "vitest": "^4.1.10",
50
+ "@types/node": "^26.2.0",
51
+ "oxfmt": "^0.64.0",
52
+ "oxlint": "^1.79.0",
53
+ "vitest": "^4.1.11",
56
54
  "xstate": "^5.31.0"
57
55
  },
58
56
  "peerDependencies": {
59
- "@xmachines/play": "1.0.0",
60
- "@xmachines/play-signals": "1.0.0",
57
+ "@xmachines/play": "1.1.0",
58
+ "@xmachines/play-signals": "1.1.0",
61
59
  "xstate": "^5.31.0"
62
60
  },
63
61
  "engines": {