@xmachines/play-xstate 6.1.0 → 7.0.0

package/README.md

@@ -2,13 +2,14 @@
 
 > XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with atom-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-6.1.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-7.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.
+> **Browser floor:** the table of the root README covers this package. Its own code calls
+> no ES2023 change-by-copy array method, and its routing capability imports only types from
+> [`@xmachines/play-router`](../play-router/README.md). A router bridge of play-router sets
+> the floor of the table.
 
 ## Installation
 
@@ -115,21 +116,36 @@ machine cannot be `undefined`, the first argument of the factory is necessary. A
 input is then a compile error, not an actor that stops in an error status.
 
 ```typescript
-type PlayerFactory<TMachine> =
+import type { AnyStateMachine, InputFrom } from "xstate";
+import type { PlayerActor, PlayerFactoryResumeOptions } from "@xmachines/play-xstate";
+
+type PlayerFactory<TMachine extends AnyStateMachine, TCapabilities extends object = object> =
 	undefined extends InputFrom<TMachine>
 		? (
 				input?: InputFrom<TMachine>,
 				options?: PlayerFactoryResumeOptions<TMachine>,
-			) => PlayerActor<TMachine>
+			) => PlayerActor<TMachine> & TCapabilities
 		: (
 				input: InputFrom<TMachine>,
 				options?: PlayerFactoryResumeOptions<TMachine>,
-			) => PlayerActor<TMachine>;
+			) => PlayerActor<TMachine> & TCapabilities;
 ```
 
+`TCapabilities` is what `compose` adds, for example `Routable` of [`@xmachines/play-router`](../play-router/README.md).
+
 #### Restoring from a snapshot
 
 ```typescript
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine, with an input and routed states
+
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
+const actor = createPlayer({ userId: "alice" });
+actor.start();
+
 const snapshot = actor.getPersistedSnapshot();
 actor.stop();
 
@@ -182,6 +198,9 @@ carries the route utilities — `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl
 import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
 import { withRouting } from "@xmachines/play-xstate/routing";
 import { withView } from "@xmachines/play-xstate/view";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
 
 // Both capabilities
 const createPlayer = definePlayer({
@@ -201,6 +220,15 @@ const createBare = definePlayer({ machine });
 **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
+import { definePlayer, PlayerActor, compose } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import type { Routable } from "@xmachines/play-router";
+import type { Viewable } from "@xmachines/play-view";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
 let composed: PlayerActor<typeof machine> & Routable & Viewable;
 
 const actor = definePlayer({
@@ -254,6 +282,11 @@ the path yourself, when you run work that belongs to a change of the route alone
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { Routable } from "@xmachines/play-router";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine> & Routable; // composed with withRouting
 
 const stop = watchAtom(actor.currentRoute, (route) => {
 	console.log("Route changed:", route);
@@ -275,22 +308,32 @@ This package gives no guard utility. Compose a guard with the `and()`, `or()` an
 import { and, not, setup } from "xstate";
 
 const machine = setup({
+	types: {
+		context: {} as { userId: string; role: string },
+		events: {} as { type: "accessAdmin" } | { type: "accessLogin" },
+	},
 	guards: {
 		isLoggedIn: ({ context }) => context.userId !== "",
 		hasAdminRole: ({ context }) => context.role === "admin",
 	},
 }).createMachine({
+	context: { userId: "", role: "guest" },
+	initial: "home",
 	on: {
 		accessAdmin: {
 			guard: and(["isLoggedIn", "hasAdminRole"]),
-			target: "adminPanel",
+			target: ".adminPanel",
 		},
 		accessLogin: {
 			guard: not("isLoggedIn"),
-			target: "login",
+			target: ".login",
 		},
 	},
-	// ...
+	states: {
+		home: {},
+		adminPanel: {},
+		login: {},
+	},
 });
 ```
 
@@ -314,6 +357,7 @@ import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 const config = formatPlayRouteTransitions({
 	id: "app",
+	initial: "home",
 	states: {
 		home: {
 			id: "home",
@@ -348,6 +392,10 @@ with `asDisposable` of [`@xmachines/core/utils`](../core/README.md):
 
 ```typescript
 import { asDisposable } from "@xmachines/core/utils";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
 
 {
 	const actor = definePlayer({ machine })();
@@ -368,6 +416,10 @@ includes [`@statelyai/inspect`](https://stately.ai/docs/inspector):
 
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
 
 const { inspect } = createBrowserInspector();
 const createPlayer = definePlayer({ machine, options: { inspect } });
@@ -429,7 +481,7 @@ every consumer, including one that composes no routing.
 The string form declares the path only. The object form declares the path and the
 behaviour of the generated `play.route` transition:
 
-```typescript
+```typescript fragment
 meta: {
 	route: {
 		path: "/doc/:docId",
@@ -467,7 +519,7 @@ An unknown `handler` value throws `InvalidRouteHandlerError` at the format time.
 The `data` field follows the `WithDynamicParams` shape of XState, so the function form
 reads the context and the event:
 
-```typescript
+```typescript fragment
 data: ({ context, event }) => ({ title: `Document ${event.params?.docId}` });
 ```
 

package/dist/capabilities.js

@@ -1,4 +1,8 @@
-export function compose(Base, ...capabilities) {
-    return capabilities.reduce((actor, capability) => capability(actor), Base);
+//#region packages/play-xstate/src/capabilities.ts
+function compose(Base, ...capabilities) {
+	return capabilities.reduce((actor, capability) => capability(actor), Base);
 }
+//#endregion
+export { compose };
+
 //# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AA6HA,MAAM,UAAU,OAAO,CACtB,IAAiC,EACjC,GAAG,YAEF;IAED,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"capabilities.js","names":[],"sources":["../src/capabilities.ts"],"sourcesContent":["/**\n * The composition of the optional capabilities of an actor.\n *\n * `PlayerActor` gives the protocol of `PlayActor` and nothing else: `state` and\n * `send`. Routing and the view are capabilities, each one a MIXIN in a module that the\n * core imports never. An application that renders no view therefore loads no view code,\n * and an application that declares no route loads no routing code.\n *\n * {@link compose} applies each capability from left to right, so the LAST one is the\n * outermost class. The ORDER decides no value: a capability that publishes one derives it\n * with a computed atom over `state`, and the engine evaluates every derivation from the\n * one write of a transition, in topological order. A capability that must run an EFFECT\n * overrides `onSnapshot`, and the override calls `super.onSnapshot()` first.\n *\n * ## Why the types read this way\n *\n * A capability is typed by the INSTANCE that it extends, and not by a type parameter for\n * the class. That one decision removes three problems at once:\n *\n * - A class that extends a TYPE PARAMETER must constrain it to `new (...args: any[])`, and\n *   TypeScript reports TS2545 for every other spelling. A concrete constructor type needs\n *   no `any`.\n * - A mixin that INFERS its return type emits no declaration: `Actor` of XState carries\n *   private members such as `_actorScope`, and an anonymous class that holds one is not\n *   nameable (TS4094).\n * - A conditional return type cannot be checked against the class that a mixin builds, so\n *   it forces `as unknown as` at the return. Nothing here asserts anything.\n *\n * `TCapabilities` carries what the base already added, so a composed constructor names\n * every capability on its instance. {@link compose} is what accumulates them:\n * `compose(PlayerActor, withRouting, withView)` answers an actor that is `Routable` AND\n * `Viewable`. Each capability declares a FIXED return type, so the nested form\n * `withView(withRouting(PlayerActor))` answers `Viewable` alone.\n */\nimport type { ActorOptions, AnyStateMachine, InputFrom } from \"xstate\";\n\nimport type { PlayerActor } from \"./player-actor.js\";\nimport type { PlayerOptions } from \"./types.js\";\n\n/**\n * The constructor of a `PlayerActor`, with every capability that it carries already.\n *\n * The argument list is the one that `PlayerActor` declares, so `definePlayer` builds an\n * actor with the arguments checked, whatever the composition added to the instance.\n *\n * @typeParam TMachine - The machine of the actor.\n * @typeParam TCapabilities - What the capabilities added, for example `Routable & Viewable`.\n */\nexport type PlayerConstructor<\n\tTMachine extends AnyStateMachine,\n\tTCapabilities extends object = object,\n> = new (\n\tmachine: TMachine,\n\toptions: PlayerOptions<TMachine>,\n\tinput?: InputFrom<TMachine>,\n\trestoredSnapshot?: ActorOptions<TMachine>[\"snapshot\"],\n) => PlayerActor<TMachine> & TCapabilities;\n\n/**\n * One capability of an actor: a function that takes an actor class and answers the same\n * class with `TAdded` on the instance.\n *\n * `withRouting` of `@xmachines/play-xstate/routing` and `withView` of\n * `@xmachines/play-xstate/view` are the two that this package ships. Write your own with\n * the same shape, and {@link compose} takes it beside them.\n *\n * @typeParam TMachine - The machine of the actor.\n * @typeParam TAdded - What the capability adds to the instance, for example `Routable`.\n */\nexport type Capability<TMachine extends AnyStateMachine, TAdded extends object> = (\n\tBase: PlayerConstructor<TMachine>,\n) => PlayerConstructor<TMachine, TAdded>;\n\n/**\n * Builds an actor class from a base and a list of capabilities.\n *\n * It applies each capability from left to right, so the LAST one is the outermost class,\n * and the return type accumulates what each one adds:\n * `compose(PlayerActor, withRouting, withView)` is `Routable` AND `Viewable`.\n *\n * Use this form, and not the nested one. Each capability declares a FIXED return type, so\n * `withView(withRouting(PlayerActor))` builds the same class at run time and answers\n * `Viewable` alone at the type level — a router bridge then refuses the actor with\n * TS2739. The overloads below are what carries `Routable` through.\n *\n * @example\n * ```typescript\n * import { definePlayer, PlayerActor, compose } from \"@xmachines/play-xstate\";\n * import { withRouting } from \"@xmachines/play-xstate/routing\";\n * import { withView } from \"@xmachines/play-xstate/view\";\n *\n * const createPlayer = definePlayer({\n *   machine,\n *   actor: compose(PlayerActor, withRouting, withView),\n * });\n * ```\n *\n * Each overload takes the capabilities as separate arguments, `c1` to `c3`, and it\n * applies them from left to right.\n *\n * @param Base - The actor class to build on, normally `PlayerActor`.\n */\nexport function compose<TMachine extends AnyStateMachine>(\n\tBase: PlayerConstructor<TMachine>,\n): PlayerConstructor<TMachine>;\nexport function compose<TMachine extends AnyStateMachine, TC1 extends object>(\n\tBase: PlayerConstructor<TMachine>,\n\tc1: Capability<TMachine, TC1>,\n): PlayerConstructor<TMachine, TC1>;\nexport function compose<TMachine extends AnyStateMachine, TC1 extends object, TC2 extends object>(\n\tBase: PlayerConstructor<TMachine>,\n\tc1: Capability<TMachine, TC1>,\n\tc2: Capability<TMachine, TC2>,\n): PlayerConstructor<TMachine, TC1 & TC2>;\nexport function compose<\n\tTMachine extends AnyStateMachine,\n\tTC1 extends object,\n\tTC2 extends object,\n\tTC3 extends object,\n>(\n\tBase: PlayerConstructor<TMachine>,\n\tc1: Capability<TMachine, TC1>,\n\tc2: Capability<TMachine, TC2>,\n\tc3: Capability<TMachine, TC3>,\n): PlayerConstructor<TMachine, TC1 & TC2 & TC3>;\nexport function compose<TMachine extends AnyStateMachine>(\n\tBase: PlayerConstructor<TMachine>,\n\t...capabilities: ReadonlyArray<\n\t\t(Base: PlayerConstructor<TMachine>) => PlayerConstructor<TMachine>\n\t>\n): PlayerConstructor<TMachine> {\n\treturn capabilities.reduce((actor, capability) => capability(actor), Base);\n}\n"],"mappings":";AA6HA,SAAgB,QACf,MACA,GAAG,cAG2B;CAC9B,OAAO,aAAa,QAAQ,OAAO,eAAe,WAAW,KAAK,GAAG,IAAI;AAC1E"}

package/dist/define-player.js

@@ -1,11 +1,11 @@
 import { PlayerActor } from "./player-actor.js";
-export function definePlayer(config) {
-    const { machine, options, actor } = config;
-    // `PlayerActor` is the default, and it carries no capability. A consumer that routes or
-    // renders passes a composed class, and this module imports neither capability. The two
-    // overloads above are what keeps the answer exact: the default one answers a bare
-    // player, and the other answers the player with everything that the composition added.
-    const ActorClass = actor ?? PlayerActor;
-    return (input, restore) => new ActorClass(machine, options ?? {}, input, restore?.snapshot);
+//#region packages/play-xstate/src/define-player.ts
+function definePlayer(config) {
+	const { machine, options, actor } = config;
+	const ActorClass = actor ?? PlayerActor;
+	return (input, restore) => new ActorClass(machine, options ?? {}, input, restore?.snapshot);
 }
+//#endregion
+export { definePlayer };
+
 //# sourceMappingURL=define-player.js.map

package/dist/define-player.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-player.js","sourceRoot":"","sources":["../src/define-player.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkEhD,MAAM,UAAU,YAAY,CAC3B,MAA6C;IAE7C,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC3C,wFAAwF;IACxF,uFAAuF;IACvF,kFAAkF;IAClF,uFAAuF;IACvF,MAAM,UAAU,GAAG,KAAK,IAAI,WAAW,CAAC;IAExC,OAAO,CAAC,KAA2B,EAAE,OAA8C,EAAE,EAAE,CACtF,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"define-player.js","names":[],"sources":["../src/define-player.ts"],"sourcesContent":["import type { AnyStateMachine, InputFrom } from \"xstate\";\nimport type { PlayerConfig, PlayerFactory, PlayerFactoryResumeOptions } from \"./types.js\";\nimport type { PlayerConstructor } from \"./capabilities.js\";\nimport { PlayerActor } from \"./player-actor.js\";\n\n/**\n * Creates a player factory from an XState machine\n *\n * This factory function accepts an XState v5 machine. It returns a function that\n * makes {@link PlayerActor} instances. One configuration can therefore make more\n * than one actor instance, and this helps with a test, with an application of\n * several instances, and with a render on the server.\n *\n * @typeParam TMachine - The type of the XState v5 state machine\n *\n * @param config - The configuration object of the player\n * @param config.machine - The XState v5 state machine\n * @param config.options - The optional lifecycle hooks: onStart, onTransition, and the others\n *\n * @returns The factory function. It makes an actor instance, with an optional input context\n *\n * @example\n * A basic player factory\n * ```typescript\n * import { setup } from \"xstate\";\n * import { definePlayer } from \"@xmachines/play-xstate\";\n *\n * const machine = setup({}).createMachine({\n *   initial: 'idle',\n *   states: {\n *     idle: { meta: { route: '/' } },\n *     active: { meta: { route: '/active' } }\n *   }\n * });\n *\n * const createPlayer = definePlayer({ machine });\n * const actor = createPlayer();\n * actor.start();\n * ```\n *\n * @example\n * More than one actor instance from one factory\n * ```typescript\n * const createPlayer = definePlayer({ machine });\n *\n * // Create an actor for each user\n * const alice = createPlayer({ userId: 'alice' });\n * const bob = createPlayer({ userId: 'bob' });\n *\n * alice.start();\n * bob.start();\n *\n * // The two state machines are independent\n * console.log(alice.state.get() !== bob.state.get());\n * ```\n *\n * @see [Play RFC](../../docs/rfc/play.md)\n * @see {@link PlayerActor} for the concrete actor implementation\n * @see {@link PlayerConfig} for the configuration options\n * @see {@link PlayerFactory} for the signature of the factory function\n */\nexport function definePlayer<TMachine extends AnyStateMachine>(\n\tconfig: PlayerConfig<TMachine> & { actor?: undefined },\n): PlayerFactory<TMachine>;\nexport function definePlayer<TMachine extends AnyStateMachine, TCapabilities extends object>(\n\tconfig: PlayerConfig<TMachine, TCapabilities> & {\n\t\tactor: PlayerConstructor<TMachine, TCapabilities>;\n\t},\n): PlayerFactory<TMachine, TCapabilities>;\nexport function definePlayer<TMachine extends AnyStateMachine, TCapabilities extends object>(\n\tconfig: PlayerConfig<TMachine, TCapabilities>,\n): PlayerFactory<TMachine, TCapabilities> | PlayerFactory<TMachine> {\n\tconst { machine, options, actor } = config;\n\t// `PlayerActor` is the default, and it carries no capability. A consumer that routes or\n\t// renders passes a composed class, and this module imports neither capability. The two\n\t// overloads above are what keeps the answer exact: the default one answers a bare\n\t// player, and the other answers the player with everything that the composition added.\n\tconst ActorClass = actor ?? PlayerActor;\n\n\treturn (input?: InputFrom<TMachine>, restore?: PlayerFactoryResumeOptions<TMachine>) =>\n\t\tnew ActorClass(machine, options ?? {}, input, restore?.snapshot);\n}\n"],"mappings":";;AAqEA,SAAgB,aACf,QACmE;CACnE,MAAM,EAAE,SAAS,SAAS,UAAU;CAKpC,MAAM,aAAa,SAAS;CAE5B,QAAQ,OAA6B,YACpC,IAAI,WAAW,SAAS,WAAW,CAAC,GAAG,OAAO,SAAS,QAAQ;AACjE"}