xstate 6.0.0-alpha.8 → 6.0.0-beta.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 (235) hide show
  1. package/README.md +223 -78
  2. package/bin/agent.js +347 -0
  3. package/bin/xstate.js +52 -0
  4. package/dist/createActor-25900f76.cjs.js +7015 -0
  5. package/dist/createActor-551369be.development.esm.js +7175 -0
  6. package/dist/createActor-a49ae0ce.development.cjs.js +7289 -0
  7. package/dist/createActor-cbe3abac.esm.js +6902 -0
  8. package/dist/declarations/src/SimulatedClock.d.ts +2 -1
  9. package/dist/declarations/src/State.d.ts +66 -5
  10. package/dist/declarations/src/StateMachine.d.ts +107 -32
  11. package/dist/declarations/src/StateNode.d.ts +21 -16
  12. package/dist/declarations/src/actions.d.ts +11 -6
  13. package/dist/declarations/src/actors/callback.d.ts +11 -2
  14. package/dist/declarations/src/actors/index.d.ts +6 -5
  15. package/dist/declarations/src/actors/listener.d.ts +8 -3
  16. package/dist/declarations/src/actors/logic.d.ts +42 -52
  17. package/dist/declarations/src/actors/observable.d.ts +15 -2
  18. package/dist/declarations/src/actors/promise.d.ts +90 -22
  19. package/dist/declarations/src/actors/subscription.d.ts +9 -3
  20. package/dist/declarations/src/assert.d.ts +1 -0
  21. package/dist/declarations/src/base.types.d.ts +102 -0
  22. package/dist/declarations/src/createActor.d.ts +101 -27
  23. package/dist/declarations/src/createMachine.d.ts +38 -17
  24. package/dist/declarations/src/delay.d.ts +8 -0
  25. package/dist/declarations/src/durable/index.d.ts +231 -0
  26. package/dist/declarations/src/effectDescriptor.d.ts +95 -0
  27. package/dist/declarations/src/eventTypes.d.ts +9 -0
  28. package/dist/declarations/src/fsm/index.d.ts +2 -0
  29. package/dist/declarations/src/fsm.d.ts +169 -0
  30. package/dist/declarations/src/graph/adjacency.d.ts +6 -3
  31. package/dist/declarations/src/graph/graph.d.ts +6 -3
  32. package/dist/declarations/src/graph/index.d.ts +2 -3
  33. package/dist/declarations/src/graph/pathFromEvents.d.ts +5 -2
  34. package/dist/declarations/src/graph/shortestPaths.d.ts +5 -3
  35. package/dist/declarations/src/graph/simplePaths.d.ts +5 -3
  36. package/dist/declarations/src/graph/types.d.ts +113 -59
  37. package/dist/declarations/src/hotSwap.d.ts +18 -0
  38. package/dist/declarations/src/index.d.ts +28 -19
  39. package/dist/declarations/src/inspection.d.ts +24 -1
  40. package/dist/declarations/src/machineFromJSON.d.ts +171 -0
  41. package/dist/declarations/src/machineSchemas.d.ts +27 -0
  42. package/dist/declarations/src/machineVersion.types.d.ts +53 -0
  43. package/dist/declarations/src/machineVersions.d.ts +103 -0
  44. package/dist/declarations/src/mapState.d.ts +2 -0
  45. package/dist/declarations/src/persist/index.d.ts +36 -0
  46. package/dist/declarations/src/persistedSnapshotValidation.d.ts +18 -0
  47. package/dist/declarations/src/runtimeHelpers.d.ts +43 -0
  48. package/dist/declarations/src/schema.types.d.ts +31 -4
  49. package/dist/declarations/src/serialize.d.ts +39 -28
  50. package/dist/declarations/src/setup.d.ts +1086 -147
  51. package/dist/declarations/src/spawn.d.ts +6 -4
  52. package/dist/declarations/src/stateUtils.d.ts +57 -14
  53. package/dist/declarations/src/system.d.ts +178 -17
  54. package/dist/declarations/src/systemTransition.d.ts +108 -0
  55. package/dist/declarations/src/toPromise.d.ts +1 -0
  56. package/dist/declarations/src/transition.d.ts +48 -10
  57. package/dist/declarations/src/transitionActions.d.ts +22 -4
  58. package/dist/declarations/src/typeUtils.d.ts +51 -0
  59. package/dist/declarations/src/types.d.ts +835 -318
  60. package/dist/declarations/src/types.v6.d.ts +547 -104
  61. package/dist/declarations/src/utils.d.ts +38 -8
  62. package/dist/declarations/src/validation/index.d.ts +49 -0
  63. package/dist/declarations/src/validation.types.d.ts +29 -0
  64. package/dist/declarations/src/waitFor.d.ts +1 -0
  65. package/dist/effectDescriptor-2fa27c54.cjs.js +351 -0
  66. package/dist/effectDescriptor-321a8ce9.development.esm.js +343 -0
  67. package/dist/effectDescriptor-d8b0f749.esm.js +343 -0
  68. package/dist/effectDescriptor-f73da4ec.development.cjs.js +351 -0
  69. package/dist/machineSchemas-45c21bc2.esm.js +1292 -0
  70. package/dist/machineSchemas-6d96bef4.development.cjs.js +1379 -0
  71. package/dist/machineSchemas-88d01821.cjs.js +1300 -0
  72. package/dist/machineSchemas-b5736804.development.esm.js +1371 -0
  73. package/dist/schema.types-0ecd17b8.esm.js +71 -0
  74. package/dist/schema.types-15a68ddc.cjs.js +74 -0
  75. package/dist/schema.types-1c16f035.development.cjs.js +74 -0
  76. package/dist/schema.types-1cd4652e.development.esm.js +71 -0
  77. package/dist/validation-05f1d517.esm.js +8 -0
  78. package/dist/validation-4561b43c.cjs.js +10 -0
  79. package/dist/validation-e69470ad.development.esm.js +8 -0
  80. package/dist/validation-f2714a35.development.cjs.js +10 -0
  81. package/dist/xstate-actors.cjs.js +1068 -12
  82. package/dist/xstate-actors.cjs.mjs +2 -4
  83. package/dist/xstate-actors.development.cjs.js +1068 -12
  84. package/dist/xstate-actors.development.cjs.mjs +2 -4
  85. package/dist/xstate-actors.development.esm.js +1064 -1
  86. package/dist/xstate-actors.esm.js +1064 -1
  87. package/dist/xstate-actors.umd.min.js +1 -1
  88. package/dist/xstate-actors.umd.min.js.map +1 -1
  89. package/dist/xstate-durable.cjs.d.mts +2 -0
  90. package/dist/xstate-durable.cjs.d.ts +2 -0
  91. package/dist/xstate-durable.cjs.js +513 -0
  92. package/dist/xstate-durable.cjs.mjs +5 -0
  93. package/dist/xstate-durable.development.cjs.js +513 -0
  94. package/dist/xstate-durable.development.cjs.mjs +5 -0
  95. package/dist/xstate-durable.development.esm.js +507 -0
  96. package/dist/xstate-durable.esm.js +507 -0
  97. package/dist/xstate-durable.umd.min.js +2 -0
  98. package/dist/xstate-durable.umd.min.js.map +1 -0
  99. package/dist/xstate-fsm.cjs.d.mts +2 -0
  100. package/dist/xstate-fsm.cjs.d.ts +2 -0
  101. package/dist/xstate-fsm.cjs.js +111 -0
  102. package/dist/xstate-fsm.cjs.mjs +5 -0
  103. package/dist/xstate-fsm.development.cjs.js +111 -0
  104. package/dist/xstate-fsm.development.cjs.mjs +5 -0
  105. package/dist/xstate-fsm.development.esm.js +105 -0
  106. package/dist/xstate-fsm.esm.js +105 -0
  107. package/dist/xstate-fsm.umd.min.js +2 -0
  108. package/dist/xstate-fsm.umd.min.js.map +1 -0
  109. package/dist/xstate-graph.cjs.js +173 -457
  110. package/dist/xstate-graph.cjs.mjs +2 -5
  111. package/dist/xstate-graph.development.cjs.js +173 -457
  112. package/dist/xstate-graph.development.cjs.mjs +2 -5
  113. package/dist/xstate-graph.development.esm.js +171 -451
  114. package/dist/xstate-graph.esm.js +171 -451
  115. package/dist/xstate-graph.umd.min.js +1 -1
  116. package/dist/xstate-graph.umd.min.js.map +1 -1
  117. package/dist/xstate-persist.cjs.d.mts +2 -0
  118. package/dist/xstate-persist.cjs.d.ts +2 -0
  119. package/dist/xstate-persist.cjs.js +314 -0
  120. package/dist/xstate-persist.cjs.mjs +6 -0
  121. package/dist/xstate-persist.development.cjs.js +325 -0
  122. package/dist/xstate-persist.development.cjs.mjs +6 -0
  123. package/dist/xstate-persist.development.esm.js +319 -0
  124. package/dist/xstate-persist.esm.js +308 -0
  125. package/dist/xstate-persist.umd.min.js +2 -0
  126. package/dist/xstate-persist.umd.min.js.map +1 -0
  127. package/dist/xstate-validation.cjs.d.mts +2 -0
  128. package/dist/xstate-validation.cjs.d.ts +2 -0
  129. package/dist/xstate-validation.cjs.js +330 -0
  130. package/dist/xstate-validation.cjs.mjs +5 -0
  131. package/dist/xstate-validation.development.cjs.js +330 -0
  132. package/dist/xstate-validation.development.cjs.mjs +5 -0
  133. package/dist/xstate-validation.development.esm.js +324 -0
  134. package/dist/xstate-validation.esm.js +324 -0
  135. package/dist/xstate-validation.umd.min.js +2 -0
  136. package/dist/xstate-validation.umd.min.js.map +1 -0
  137. package/dist/xstate.cjs.js +2486 -1430
  138. package/dist/xstate.cjs.mjs +23 -13
  139. package/dist/xstate.development.cjs.js +2486 -1430
  140. package/dist/xstate.development.cjs.mjs +23 -13
  141. package/dist/xstate.development.esm.js +2445 -1398
  142. package/dist/xstate.esm.js +2445 -1398
  143. package/dist/xstate.umd.min.js +1 -1
  144. package/dist/xstate.umd.min.js.map +1 -1
  145. package/docs/actions.md +75 -0
  146. package/docs/actor-logic.md +250 -0
  147. package/docs/actors.md +64 -0
  148. package/docs/agents.md +132 -0
  149. package/docs/api-stability.json +4287 -0
  150. package/docs/async-logic.md +75 -0
  151. package/docs/async-requests.md +157 -0
  152. package/docs/backend-workflows.md +124 -0
  153. package/docs/cancellation.md +42 -0
  154. package/docs/cheatsheet.md +563 -0
  155. package/docs/choice-states.md +109 -0
  156. package/docs/choose-xstate.md +47 -0
  157. package/docs/configuration.md +161 -0
  158. package/docs/context.md +67 -0
  159. package/docs/create-actor.md +159 -0
  160. package/docs/data-and-effects.md +48 -0
  161. package/docs/delays.md +81 -0
  162. package/docs/durable-execution.md +520 -0
  163. package/docs/emitted-events.md +146 -0
  164. package/docs/errors.md +812 -0
  165. package/docs/examples.md +75 -0
  166. package/docs/faq.md +60 -0
  167. package/docs/final-states.md +149 -0
  168. package/docs/forms-and-wizards.md +166 -0
  169. package/docs/frameworks.md +69 -0
  170. package/docs/fsm.md +164 -0
  171. package/docs/glossary.md +68 -0
  172. package/docs/guards.md +137 -0
  173. package/docs/history-states.md +161 -0
  174. package/docs/how-xstate-runs-machines.md +86 -0
  175. package/docs/index.md +74 -0
  176. package/docs/input-output.md +69 -0
  177. package/docs/inspect-actor-systems.md +118 -0
  178. package/docs/inspection.md +75 -0
  179. package/docs/internal-events.md +156 -0
  180. package/docs/invoke.md +371 -0
  181. package/docs/lifecycle-and-errors.md +48 -0
  182. package/docs/listen-and-subscribe.md +126 -0
  183. package/docs/model-based-testing.md +321 -0
  184. package/docs/modeling.md +40 -0
  185. package/docs/parallel-states.md +182 -0
  186. package/docs/persist-and-restore-actors.md +120 -0
  187. package/docs/persistence.md +312 -0
  188. package/docs/quick-start.md +55 -0
  189. package/docs/retries-and-timeouts.md +122 -0
  190. package/docs/route-states.md +104 -0
  191. package/docs/scxml.md +92 -0
  192. package/docs/selectors.md +99 -0
  193. package/docs/serialization.md +127 -0
  194. package/docs/setup-and-provide.md +273 -0
  195. package/docs/snapshots.md +134 -0
  196. package/docs/spawn.md +212 -0
  197. package/docs/state-input.md +162 -0
  198. package/docs/statecharts.md +54 -0
  199. package/docs/states-events-transitions.md +82 -0
  200. package/docs/states.md +168 -0
  201. package/docs/system-transitions.md +172 -0
  202. package/docs/systems.md +166 -0
  203. package/docs/testing.md +152 -0
  204. package/docs/timeouts.md +125 -0
  205. package/docs/transition-functions.md +89 -0
  206. package/docs/transitions.md +187 -0
  207. package/docs/troubleshooting.md +56 -0
  208. package/docs/tutorial.md +481 -0
  209. package/docs/typescript.md +213 -0
  210. package/docs/typestates.md +112 -0
  211. package/docs/utilities.md +39 -0
  212. package/docs/why-state-machines.md +59 -0
  213. package/docs/xstate-v5-to-v6.md +1923 -0
  214. package/docs/your-first-machine.md +79 -0
  215. package/durable/package.json +8 -0
  216. package/fsm/package.json +8 -0
  217. package/package.json +72 -10
  218. package/persist/package.json +8 -0
  219. package/validation/package.json +8 -0
  220. package/actions/package.json +0 -8
  221. package/dev/package.json +0 -8
  222. package/dist/StateMachine-0aa98f54.development.esm.js +0 -746
  223. package/dist/StateMachine-aef700df.cjs.js +0 -732
  224. package/dist/StateMachine-d4931336.esm.js +0 -729
  225. package/dist/StateMachine-da872dde.development.cjs.js +0 -749
  226. package/dist/declarations/src/createMachineFromConfig.d.ts +0 -177
  227. package/dist/declarations/src/getNextSnapshot.d.ts +0 -37
  228. package/dist/declarations/src/graph/TestModel.d.ts +0 -70
  229. package/dist/declarations/src/graph/pathGenerators.d.ts +0 -4
  230. package/dist/index-219cb621.development.cjs.js +0 -4476
  231. package/dist/index-2f2fbd9b.development.esm.js +0 -4421
  232. package/dist/index-559ceab3.cjs.js +0 -4437
  233. package/dist/index-8828376f.esm.js +0 -4382
  234. package/guards/package.json +0 -8
  235. package/invoke/package.json +0 -4
@@ -0,0 +1,112 @@
1
+ ---
2
+ title: Typestates
3
+ description: Narrow context according to the active state.
4
+ ---
5
+
6
+ Typestates describe which context values are valid in each state. For example,
7
+ a request can have `user: null` while idle and `user: string` after loading.
8
+ XState v6 derives these types from state-level `schemas.context` declarations,
9
+ instead of the manually declared `Typestate` generic used in v4.
10
+
11
+ ## Declare context per state
12
+
13
+ <!-- state context refinements and target patches from packages/core/test/stateInput.test.ts -->
14
+
15
+ Declare the root context and each state's refinements in `setup(...)`:
16
+
17
+ ```ts
18
+ import { createActor, setup, types } from 'xstate';
19
+
20
+ const machine = setup({
21
+ schemas: {
22
+ context: types<{ requestId: string; user: string | null }>(),
23
+ events: { load: types<{ name: string }>() }
24
+ },
25
+ states: {
26
+ idle: { schemas: { context: types<{ user: null }>() } },
27
+ loaded: { schemas: { context: types<{ user: string }>() } }
28
+ }
29
+ }).createMachine({
30
+ context: { requestId: 'request-1', user: null },
31
+ initial: 'idle',
32
+ states: {
33
+ idle: {
34
+ on: {
35
+ load: ({ event }) => ({
36
+ target: 'loaded',
37
+ context: { user: event.name }
38
+ })
39
+ }
40
+ },
41
+ loaded: {
42
+ entry: ({ context }, enq) => {
43
+ enq(() => console.log(context.user.toUpperCase()));
44
+ }
45
+ }
46
+ }
47
+ });
48
+
49
+ const actor = createActor(machine).start();
50
+ const snapshot = actor.getSnapshot();
51
+ snapshot.context.user; // string | null
52
+
53
+ if (snapshot.matches('loaded')) {
54
+ snapshot.context.user; // string
55
+ snapshot.context.requestId; // string
56
+ }
57
+ ```
58
+
59
+ State schemas refine the root context type by intersection. They only need to
60
+ declare the fields they narrow; other root fields remain available. A state
61
+ schema cannot widen a root field or give it an incompatible type.
62
+
63
+ `types<T>()` declares a TypeScript contract without runtime validation. Use Zod
64
+ or another Standard Schema library when you also need runtime checks.
65
+
66
+ ## Enter a state with valid context
67
+
68
+ Actions and transition functions declared on a state receive that state's
69
+ narrowed context. When a transition's target requires a refinement the source
70
+ context does not already satisfy, the transition must provide a matching
71
+ `context` patch. In the example, entering `loaded` from `idle` requires
72
+ `user: string`; omitting the patch or supplying `user: null` is a type error.
73
+
74
+ Context patches merge at the top level. The transition only changes `user`;
75
+ `requestId` keeps its current value. See [context updates](context.md#update-context).
76
+
77
+ ## Narrow a snapshot
78
+
79
+ Use `snapshot.matches(...)` to narrow context when reading an actor snapshot.
80
+ For a checkout machine with a nested `reviewing` state, pass a nested state value:
81
+
82
+ ```ts
83
+ if (checkoutSnapshot.matches({ checkout: 'reviewing' })) {
84
+ // Context includes the checkout and reviewing state refinements.
85
+ }
86
+ ```
87
+
88
+ Nested states retain refinements from active ancestors. For parallel states,
89
+ `matches(...)` combines refinements for the regions named in the matched value.
90
+ An omitted region does not gain a refinement from that check.
91
+
92
+ Typestates refine context; they do not identify the event that entered a state.
93
+ An `entry` or `exit` function can receive multiple event types. Use
94
+ `assertEvent(...)` when it needs one particular event.
95
+ An `on.load` transition already receives the narrowed `load` event.
96
+
97
+ ## Runtime validation
98
+
99
+ > **Experimental:** `standardSchemaValidator()`, `ActorValidationError` and the other `xstate/validation` exports may change in a minor release.
100
+
101
+ Schemas infer types by default. To check values at runtime, install
102
+ `standardSchemaValidator()` from `xstate/validation` on the setup. XState then
103
+ validates stable context against the root schema and every active state schema
104
+ before running effects. Nested state refinements are checked alongside their
105
+ ancestor schemas.
106
+
107
+ Validation is opt-in and assertion-only. `types<T>()` cannot validate values,
108
+ and runtime schemas that transform values or validate asynchronously are
109
+ unsupported. See [runtime validation](typescript.md#runtime-validation).
110
+
111
+ Typestates do not validate a persisted snapshot during restoration. Validate
112
+ stored data before restoring it; see [persistence](persistence.md).
@@ -0,0 +1,39 @@
1
+ ---
2
+ title: Utilities
3
+ description: Work with actors, snapshots and state values.
4
+ ---
5
+
6
+ | Utility | Purpose |
7
+ | --- | --- |
8
+ | `waitFor(actor, predicate)` | Wait for a matching snapshot. |
9
+ | `toPromise(actor)` | Resolve with an actor's output. |
10
+ | `initialTransition(logic, input?)` | Get `[snapshot, actions]` for the initial transition without starting an actor. |
11
+ | `transition(logic, snapshot, event)` | Calculate `[nextSnapshot, actions]` for an event. |
12
+ | `initialSystemTransition(systemLogic, options?)` | Initialize a pure system snapshot; experimental. |
13
+ | `systemTransition(systemLogic, snapshot, actorPath, event)` | Settle macrosteps and messages in a system snapshot; experimental. |
14
+ | `advanceSystemTime(systemLogic, snapshot, { time })` | Process system timers through an absolute deadline; experimental. |
15
+ | `mapState(...)` | Map one state value to another value. |
16
+ | `SimulatedClock` | Control time in tests. |
17
+
18
+ ```ts
19
+ const finalSnapshot = await waitFor(actor, (snapshot) =>
20
+ snapshot.matches('complete')
21
+ );
22
+ ```
23
+
24
+ Use `initialTransition(...)` and `transition(...)` for pure calculations. They do not start actors or run effects; the returned actions describe the effects that an actor would execute. Use `SimulatedClock` to test delays without waiting for real time.
25
+
26
+ For pure calculations across children, messages and timers, use the experimental
27
+ [system transition APIs](system-transitions.md). Each returns `[snapshot, externalEffects]`
28
+ and completes macrosteps without running external effects.
29
+
30
+ For example, a route loader can calculate an initial view without starting a long-lived actor. A timeout test can advance a simulated clock to the retry state.
31
+
32
+ ## Utilities cheatsheet
33
+
34
+ ```ts
35
+ await waitFor(actor, predicate);
36
+ await toPromise(actor);
37
+ const [initialSnapshot, initialActions] = initialTransition(logic, input);
38
+ const [nextSnapshot, actions] = transition(logic, snapshot, event);
39
+ ```
@@ -0,0 +1,59 @@
1
+ ---
2
+ title: Why state machines?
3
+ description: Learn how explicit states make application behavior easier to understand.
4
+ ---
5
+
6
+ Application logic is often described with values that can contradict each other.
7
+
8
+ ```ts
9
+ const request = {
10
+ isLoading: false,
11
+ hasData: true,
12
+ hasError: true
13
+ };
14
+ ```
15
+
16
+ Is this request successful or failed? The object allows both at the same time. Every consumer has to decide what the combination means.
17
+
18
+ A state machine makes the status explicit:
19
+
20
+ ```ts
21
+ const requestMachine = createMachine({
22
+ initial: 'idle',
23
+ states: {
24
+ idle: { on: { load: { target: 'loading' } } },
25
+ loading: {
26
+ on: {
27
+ succeed: { target: 'success' },
28
+ fail: { target: 'failure' }
29
+ }
30
+ },
31
+ success: {},
32
+ failure: { on: { retry: { target: 'loading' } } }
33
+ }
34
+ });
35
+ ```
36
+
37
+ The request is in one state at a time. A `retry` event only has meaning in the `failure` state. The model documents the allowed behavior and rejects behavior you did not define.
38
+
39
+ ## Benefits of explicit states
40
+
41
+ - **No contradictory states.** The request cannot be both successful and failed.
42
+ - **Events have local meaning.** You can see which events each state accepts.
43
+ - **Changes are easier to review.** New behavior appears as a new state or transition.
44
+ - **Tests follow the model.** Test states and transitions instead of combinations of flags.
45
+ - **Behavior can be visualized.** States and transitions form a statechart.
46
+
47
+ A state machine does not reduce the complexity of the behavior. It describes that complexity as states and transitions.
48
+
49
+ ## Real examples
50
+
51
+ An online payment may be `idle`, `authorizing`, `confirmed` or `declined`. While it is `authorizing`, a second `submit` event can be ignored. A `retry` event only applies after the payment is declined.
52
+
53
+ A video call may be `joining`, `connected`, `reconnecting` or `ended`. The UI, timers and network effects can follow the current state instead of checking several connection flags.
54
+
55
+ Each model describes what can happen in the current state and which state comes next, in one place.
56
+
57
+ ## When not to use a state machine
58
+
59
+ Do not add a state machine only to replace a value. A counter, an open menu and a single text field may be clearer as ordinary state. Use a machine when the rules between states are the important part of the problem.