xstate 6.0.0-alpha.9 → 6.0.0-beta.1

package/README.md

@@ -1,3 +1,78 @@
+# XState v6
+
+This package contains **XState v6 alpha**. Its APIs differ from v5.
+
+<!-- bundled documentation generated by scripts/build-package-docs.mjs from docs/meta.json -->
+
+Before writing code with an installed package, read `docs/index.md` beside this
+README, usually `node_modules/xstate/docs/index.md`. These bundled docs match the
+installed package version.
+
+For coding agents, start with `docs/agents.md`. Run `npx xstate docs` to locate
+the installed documentation and read its machine-readable stability manifest.
+The data-only CLI also supports `inspect`, `validate`, `simulate`, `test`,
+`replay` and `diff`; see the agent guide for their contracts and limits.
+
+Online, start with the [quick start](https://github.com/statelyai/xstate/blob/next/docs/quick-start.md)
+or the [v5 to v6 migration guide](https://github.com/statelyai/xstate/blob/next/docs/xstate-v5-to-v6.md).
+
+<!-- v6 authoring replacements from src/index.ts, src/transitionActions.ts and src/types.ts -->
+
+| XState v5 | XState v6 |
+| --- | --- |
+| `assign(...)` | Return a shallow `{ context: { ... } }` patch from a transition, entry or exit function. |
+| `fromPromise(fn)` | `createAsyncLogic({ run: fn })` from `xstate`. |
+| `types: {} as { ... }` | `schemas` with `types<T>()` for type-only schemas or Standard Schema for runtime schemas. |
+| `{ target, guard, actions }` | A transition function that checks its condition and returns `{ target, context }`; queue effects with `enq`. |
+
+<!-- quick start using public createMachine and createActor exports from src/index.ts -->
+
+## Quick start
+
+```bash
+npm install xstate@beta
+```
+
+```ts
+import { createMachine, createActor } from 'xstate';
+
+// State machine
+const toggleMachine = createMachine({
+  id: 'toggle',
+  initial: 'inactive',
+  context: {
+    count: 0
+  },
+  states: {
+    inactive: {
+      on: {
+        TOGGLE: { target: 'active' }
+      }
+    },
+    active: {
+      entry: ({ context }) => ({
+        context: { count: context.count + 1 }
+      }),
+      on: {
+        TOGGLE: { target: 'inactive' }
+      }
+    }
+  }
+});
+
+// Actor (instance of the machine logic, like a store)
+const toggleActor = createActor(toggleMachine);
+toggleActor.subscribe((state) => console.log(state.value, state.context));
+toggleActor.start();
+// => logs 'inactive', { count: 0 }
+
+toggleActor.send({ type: 'TOGGLE' });
+// => logs 'active', { count: 1 }
+
+toggleActor.send({ type: 'TOGGLE' });
+// => logs 'inactive', { count: 1 }
+```
+
 <p align="center">
   <br />
 
@@ -6,20 +81,120 @@
     <img alt="XState logotype" src="https://raw.githubusercontent.com/statelyai/public-assets/main/logos/xstate-logo-black-nobg.svg" width="200">
   </picture>
   <br />
-    <strong>Actor-based state management & orchestration for complex app logic.</strong> <a href="https://stately.ai/docs">→ Documentation</a>
+    <strong>Actor-based state management & orchestration for complex app logic.</strong> <a href="https://github.com/statelyai/xstate/tree/next/docs">→ Documentation</a>
   <br />
   <br />
 </p>
 
-XState is a state management and orchestration solution for JavaScript and TypeScript apps. It has _zero_ dependencies, and is useful for frontend and backend application logic.
+<!-- runtime dependencies and public entry points from package.json -->
+
+XState is a state management and orchestration solution for JavaScript and TypeScript apps. The `xstate` package has _zero_ runtime dependencies. XState is useful for frontend and backend application logic.
 
 It uses event-driven programming, state machines, statecharts, and the actor model to handle complex logic in predictable, robust, and visual ways. XState provides a powerful and flexible way to manage application and workflow state by allowing developers to model logic as actors and state machines.
 
+<!-- system-wide emission observation from packages/core/src/setup.ts and packages/core/src/system.ts -->
+
+Observe emitted events from root and child actors with `createSystem({ onEmitted })`:
+
+```ts
+import { createMachine, createSystem } from 'xstate';
+
+const machine = createMachine({
+  entry: (_, enq) => enq.emit({ type: 'started' })
+});
+
+const system = createSystem({
+  onEmitted: ({ actorRef, event }) => {
+    console.log(actorRef.id, event);
+  }
+});
+
+const root = system.createActor(machine).start();
+```
+
+Use `system.onEmitted(listener)` for a removable subscription. `actor.on(...)`
+observes only that actor. See [actor systems](https://github.com/statelyai/xstate/blob/next/docs/systems.md#observe-emitted-events-across-a-system).
+
+<!-- experimental whole-system transitions from packages/core/src/systemTransition.ts -->
+
+For pure actor-system simulation, `initialSystemTransition`, `systemTransition`
+and `advanceSystemTime` return an immutable system snapshot and external effects
+as data. Branch or replay actors, messages and virtual timers without starting live
+actors. See [pure system transitions](https://github.com/statelyai/xstate/blob/next/docs/system-transitions.md).
+
+<!-- snapshot restoration from packages/core/src/persist/index.ts -->
+
+The `xstate/persist` entry point provides `restoreActor(logic, persistedSnapshot, options?)`
+to resume any actor from a persisted snapshot, and `snapshotSchema(machine)` for the
+persisted snapshot contract. See [persistence](https://github.com/statelyai/xstate/blob/next/docs/persistence.md).
+
+<!-- durable execution and checkpoint restoration from packages/core/src/durable/index.ts -->
+
+For durable hosts, the experimental `xstate/durable` entry point provides
+`createDurable`. Resume a checkpoint with `execution.restore(persistedSnapshot)`
+and execute the returned effects to restart active embedded children and pending
+timers without replaying entry actions. Await `executeEffects()` before persisting
+to retain accepted timer deadlines. The host handles root error snapshots;
+`run()` rejects with the root error. See [durable execution](https://github.com/statelyai/xstate/blob/next/docs/durable-execution.md).
+
+<!-- state context refinements from packages/core/src/setup.ts and packages/core/src/State.ts -->
+
+For [typestates](https://github.com/statelyai/xstate/blob/next/docs/typestates.md), declare state-level `schemas.context`
+in `setup({ states })`. State functions receive narrowed context, transitions
+check the target context requirements, and `snapshot.matches(...)` narrows
+context when reading snapshots.
+
+<!-- typed inline invocation from packages/core/src/setup.ts -->
+
+Use `s.createInvoke({ src, input, onDone })` inline in `s.createMachine(...)` for an actor used in one state. It infers the actor's input and output and the enclosing state's narrowed context without registering that actor in `setup.actors`. See [typed inline invokes](https://github.com/statelyai/xstate/blob/next/docs/invoke.md#typed-inline-invokes).
+
+Pass an async function directly as `src`, with `schemas.input`, `schemas.output`, and `schemas.error` on the same invoke. Output also infers from the async return when its schema is omitted. Existing logic values use their own schemas.
+
+The helper requires input for actors whose input excludes `undefined`, and checks child IDs and source compatibility against `schemas.children` declared in the setup or machine.
+
+<!-- graph traversal events from packages/core/src/graph/index.ts -->
+
+Graph traversal requires samples for known event types with required payloads. Pass an `events` map such as `{ ADD: [{ value: 1 }, { value: 0 }] }`; each entry also accepts a snapshot callback returning nonempty payload cases. Maps preserve payload-free defaults, invoke completions, errors, and delayed events. Event arrays and callbacks returning events replace all defaults. Coverage remains sample-based. See [model-based testing](https://github.com/statelyai/xstate/blob/next/docs/model-based-testing.md).
+
+<!-- JSON loading and runtime validation from packages/core/src/machineFromJSON.ts -->
+
+Revive JSON definitions with `machineFromJSON(json, { schemas, validator, ...sources })` to restore runtime validation. The loader validates config keys and references. See [serialization](https://github.com/statelyai/xstate/blob/next/docs/serialization.md).
+
+For flat finite state machines, `xstate/fsm` provides a tiny pure transition
+table with context and TypeScript support:
+
+<!-- public exports from packages/core/src/fsm/index.ts; exact capabilities documented in docs/fsm.md -->
+
+```ts
+import { createFSM } from 'xstate/fsm';
+
+const machine = createFSM({
+  initial: 'inactive',
+  states: {
+    inactive: { on: { toggle: 'active' } },
+    active: { on: { toggle: 'inactive' } }
+  }
+});
+
+let state = machine.initialState;
+[state] = machine.transition(state, { type: 'toggle' });
+```
+
+The FSM is also actor logic, so `createActor(machine)` from `xstate` runs it.
+
+For typed context, event payloads, or state-specific context snapshots, use
+`setup` and `types` from `xstate/fsm`. These schemas are type-only in this
+subpath; use root `xstate` for runtime schema validation.
+
+See the [exact supported surface](https://stately.ai/docs/fsm). Use the root `xstate`
+entry point for compound or parallel statecharts, invocation, named sources,
+runtime schemas, serialization and inspection.
+
 ### ✨ Create state machines visually in Stately Studio → [state.new](https://state.new)
 
 ---
 
-📖 [Read the documentation](https://stately.ai/docs)
+📖 [Read the documentation](https://github.com/statelyai/xstate/tree/next/docs)
 
 ➡️ [Create state machines with the Stately Editor](https://stately.ai/editor)
 
@@ -27,9 +202,13 @@ It uses event-driven programming, state machines, statecharts, and the actor mod
 
 📑 Inspired by the [SCXML specification](https://www.w3.org/TR/scxml/)
 
+<!-- public SCXML entry point from packages/xstate-scxml/src/index.ts -->
+
+Create machines from SCXML documents with the separate [`@xstate/scxml`](https://www.npmjs.com/package/@xstate/scxml) package. See the [SCXML guide](https://github.com/statelyai/xstate/blob/next/docs/scxml.md).
+
 💬 Chat on the [Stately Discord Community](https://discord.gg/xstate)
 
-✍️ Browse through the many [XState examples](https://github.com/statelyai/xstate/tree/main/examples)
+✍️ Browse through the many [XState examples](https://github.com/statelyai/xstate/tree/next/examples)
 
 ## Templates
 
@@ -44,14 +223,14 @@ Get started by forking one of these templates on CodeSandbox:
 <tr>
 <td>
 
-[🤖 XState Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/vanilla-ts)
+[🤖 XState Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/next/templates/vanilla-ts)
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/main/templates/vanilla-ts?file=%2Fsrc%2FfeedbackMachine.ts)
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/next/templates/vanilla-ts?file=%2Fsrc%2FfeedbackMachine.ts)
 
 </td>
 <td>
 
-- XState v5
+- XState v6 alpha
 - TypeScript
 - _No framework_
 
@@ -61,15 +240,15 @@ Get started by forking one of these templates on CodeSandbox:
 <tr>
 <td>
 
-[⚛️ XState + React Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/react-ts)
+[⚛️ XState + React Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/next/templates/react-ts)
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/main/templates/react-ts?file=%2Fsrc%2FfeedbackMachine.ts)
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/next/templates/react-ts?file=%2Fsrc%2FfeedbackMachine.ts)
 
 </td>
 <td>
 
 - [React](https://react.dev/)
-- XState v5
+- XState v6 alpha
 - TypeScript
 
 </td>
@@ -78,15 +257,15 @@ Get started by forking one of these templates on CodeSandbox:
 <tr>
 <td>
 
-[💚 XState + Vue Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/vue-ts)
+[💚 XState + Vue Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/next/templates/vue-ts)
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/main/templates/vue-ts?file=%2Fsrc%2FfeedbackMachine.ts)
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/next/templates/vue-ts?file=%2Fsrc%2FfeedbackMachine.ts)
 
 </td>
 <td>
 
 - [Vue](https://vuejs.org/)
-- XState v5
+- XState v6 alpha
 - TypeScript
 
 </td>
@@ -95,15 +274,15 @@ Get started by forking one of these templates on CodeSandbox:
 <tr>
 <td>
 
-[🧡 XState + Svelte Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/main/templates/svelte-ts)
+[🧡 XState + Svelte Template (CodeSandbox)](https://codesandbox.io/p/devbox/github/statelyai/xstate/tree/next/templates/svelte-ts)
 
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/main/templates/svelte-ts?file=%2Fsrc%2FfeedbackMachine.ts)
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/statelyai/xstate/tree/next/templates/svelte-ts?file=%2Fsrc%2FfeedbackMachine.ts)
 
 </td>
 <td>
 
 - [Svelte](https://svelte.dev/)
-- XState v5
+- XState v6 alpha
 - TypeScript
 
 </td>
@@ -112,52 +291,6 @@ Get started by forking one of these templates on CodeSandbox:
 </tbody>
 </table>
 
-## Super quick start
-
-```bash
-npm install xstate
-```
-
-```ts
-import { createMachine, createActor } from 'xstate';
-
-// State machine
-const toggleMachine = createMachine({
-  id: 'toggle',
-  initial: 'inactive',
-  context: {
-    count: 0
-  },
-  states: {
-    inactive: {
-      on: {
-        TOGGLE: { target: 'active' }
-      }
-    },
-    active: {
-      entry: ({ context }) => ({
-        context: { count: context.count + 1 }
-      }),
-      on: {
-        TOGGLE: { target: 'inactive' }
-      }
-    }
-  }
-});
-
-// Actor (instance of the machine logic, like a store)
-const toggleActor = createActor(toggleMachine);
-toggleActor.subscribe((state) => console.log(state.value, state.context));
-toggleActor.start();
-// => logs 'inactive', { count: 0 }
-
-toggleActor.send({ type: 'TOGGLE' });
-// => logs 'active', { count: 1 }
-
-toggleActor.send({ type: 'TOGGLE' });
-// => logs 'inactive', { count: 1 }
-```
-
 ## [Stately Studio](https://stately.ai)
 
 - Visually create, edit, and collaborate on state machines
@@ -166,7 +299,7 @@ toggleActor.send({ type: 'TOGGLE' });
 - Deploy to Stately Sky
 - Generate & modify machines with Stately AI
 
-<a href="stately.ai/registry/new?ref=github" title="Stately Studio">
+<a href="https://stately.ai/registry/new?ref=github" title="Stately Studio">
   <img src="https://github.com/statelyai/xstate/assets/1093738/74ed9cbc-b824-4ed7-a16d-f104947af8a7" alt="XState Viz" width="800" />
 </a>
 
@@ -186,10 +319,10 @@ Read [📽 the slides](http://slides.com/davidkhourshid/finite-state-machines) (
 | Package                                                                                     | Description                                                                  |
 | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | 🤖 `xstate`                                                                                 | Core finite state machine and statecharts library + interpreter              |
-| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react)   | React hooks and utilities for using XState in React applications             |
-| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/main/packages/xstate-vue)       | Vue composition functions and utilities for using XState in Vue applications |
-| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/main/packages/xstate-svelte) | Svelte utilities for using XState in Svelte applications                     |
-| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/main/packages/xstate-solid)   | Solid hooks and utilities for using XState in Solid applications             |
+| [⚛️ `@xstate/react`](https://github.com/statelyai/xstate/tree/next/packages/xstate-react)   | React hooks and utilities for using XState in React applications             |
+| [💚 `@xstate/vue`](https://github.com/statelyai/xstate/tree/next/packages/xstate-vue)       | Vue composition functions and utilities for using XState in Vue applications |
+| [🎷 `@xstate/svelte`](https://github.com/statelyai/xstate/tree/next/packages/xstate-svelte) | Svelte utilities for using XState in Svelte applications                     |
+| [🥏 `@xstate/solid`](https://github.com/statelyai/xstate/tree/next/packages/xstate-solid)   | Solid hooks and utilities for using XState in Solid applications             |
 
 ## Finite State Machines
 
@@ -208,17 +341,17 @@ const lightMachine = createMachine({
   states: {
     green: {
       on: {
-        TIMER: 'yellow'
+        TIMER: { target: 'yellow' }
       }
     },
     yellow: {
       on: {
-        TIMER: 'red'
+        TIMER: { target: 'red' }
       }
     },
     red: {
       on: {
-        TIMER: 'green'
+        TIMER: { target: 'green' }
       }
     }
   }
@@ -281,12 +414,12 @@ const pedestrianStates = {
   states: {
     walk: {
       on: {
-        PED_TIMER: 'wait'
+        PED_TIMER: { target: 'wait' }
       }
     },
     wait: {
       on: {
-        PED_TIMER: 'stop'
+        PED_TIMER: { target: 'stop' }
       }
     },
     stop: {}
@@ -299,17 +432,17 @@ const lightMachine = createMachine({
   states: {
     green: {
       on: {
-        TIMER: 'yellow'
+        TIMER: { target: 'yellow' }
       }
     },
     yellow: {
       on: {
-        TIMER: 'red'
+        TIMER: { target: 'red' }
       }
     },
     red: {
       on: {
-        TIMER: 'green'
+        TIMER: { target: 'green' }
       },
       ...pedestrianStates
     }
@@ -485,15 +618,15 @@ const paymentMachine = createMachine({
       states: {
         cash: {
           on: {
-            SWITCH_CHECK: 'check'
+            SWITCH_CHECK: { target: 'check' }
           }
         },
         check: {
           on: {
-            SWITCH_CASH: 'cash'
+            SWITCH_CASH: { target: 'cash' }
           }
         },
-        hist: { type: 'history' }
+        hist: { type: 'history', target: 'cash' }
       },
       on: { NEXT: { target: 'review' } }
     },
@@ -575,3 +708,15 @@ For these reasons, it is impractical for our team to be bound by decisions taken
 ### Packages
 
 Most of the packages in the XState family declare a peer dependency on XState itself. We’ll be cautious about maintaining compatibility with already-released packages when releasing a new version of XState, **but** each release of packages depending on XState will always adjust the declared peer dependency range to include the latest version of XState. For example, you should always be able to update `xstate` without `@xstate/react`. But when you update `@xstate/react`, we highly recommend updating `xstate` too.
+
+<!-- public input validation contract from src/StateMachine.ts -->
+Validate external input with `eventSchema(machine)` before `actor.send()`.
+It validates complete public events, excludes internal/runtime events, and allows
+explicitly configured routes. Payload checks require runtime schemas;
+`types<T>()` supplies types only. See [public input validation](https://github.com/statelyai/xstate/blob/next/docs/internal-events.md#validating-public-input).
+
+<!-- entry effects and terminal transition behavior from packages/core/src/stateUtils.ts and transitionActions.ts -->
+
+Use the `enq` argument in transition, entry and exit functions to queue effects. Return context or child patches from those functions; the return value of an enqueued effect is ignored, with a development warning. See [actions](https://github.com/statelyai/xstate/blob/next/docs/actions.md).
+
+For actors that are done, stopped or failed, pure transitions return the same snapshot and no effects, and `snapshot.can(...)` returns `false`. See [snapshots](https://github.com/statelyai/xstate/blob/next/docs/snapshots.md) and [states](https://github.com/statelyai/xstate/blob/next/docs/states.md).