xstate 6.0.0-alpha.69 → 6.0.0-alpha.70

package/README.md

@@ -1,3 +1,73 @@
+# 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.
+
+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@alpha
+```
+
+```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,7 +76,7 @@
     <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>
@@ -22,7 +92,7 @@ It uses event-driven programming, state machines, statecharts, and the actor mod
 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](../../docs/system-transitions.md).
+actors. See [pure system transitions](https://github.com/statelyai/xstate/blob/next/docs/system-transitions.md).
 
 <!-- durable execution and checkpoint restoration from packages/core/src/durable/index.ts -->
 
@@ -31,18 +101,18 @@ For durable hosts, the experimental `xstate/durable` entry point provides
 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](../../docs/durable-execution.md).
+`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](../../docs/typestates.md), declare state-level `schemas.context`
+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](../../docs/invoke.md#typed-inline-invokes).
+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.
 
@@ -50,11 +120,11 @@ The helper requires input for actors whose input excludes `undefined`, and check
 
 <!-- graph traversal events from packages/core/src/graph/index.ts -->
 
-`getAllOwnEvents(snapshot)` from `xstate/graph` includes invoke completions, errors, and delayed events. Compose it with custom traversal payloads: supplied `events` replace the defaults. See [model-based testing](../../docs/model-based-testing.md).
+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](../../docs/serialization.md).
+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:
@@ -90,7 +160,7 @@ runtime schemas, serialization and inspection.
 
 ---
 
-📖 [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)
 
@@ -100,11 +170,11 @@ runtime schemas, serialization and inspection.
 
 <!-- public SCXML entry point from packages/xstate-scxml/src/index.ts -->
 
-Create machines from SCXML documents with the separate [`@xstate/scxml`](../xstate-scxml) package. See the [SCXML guide](../../docs/scxml.md).
+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
 
@@ -119,14 +189,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_
 
@@ -136,15 +206,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>
@@ -153,15 +223,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>
@@ -170,15 +240,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>
@@ -187,52 +257,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
@@ -261,10 +285,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
 
@@ -655,10 +679,10 @@ Most of the packages in the XState family declare a peer dependency on XState it
 Validate external input with `machine.eventSchema` 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](../../docs/internal-events.md#validating-public-input).
+`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](../../docs/actions.md).
+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](../../docs/snapshots.md) and [states](../../docs/states.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).